> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ada.cx/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server. # Start a conversation from a Proactive POST https://example.ada.support/api/v2/conversations/proactive/ Content-Type: application/json Ask Ada to contact a person with one of your Proactives. For a voice Proactive, Ada places an outbound call to `recipient.phone_number`; when a person answers, the Proactive's Playbook opens the conversation. The request is accepted asynchronously. The response is the queued **Proactive Attempt**, not a conversation: the conversation exists only once the recipient answers. This endpoint does not report the attempt's outcome; subscribe to the `v1.proactive_call.*` webhooks to follow the attempt from `queued` to its verdict. - `channel` must be the Proactive's channel. Only `voice` Proactives can be placed. - `language` must be a language enabled for your AI Agent that voice supports. When omitted, the Proactive's default language is used, then the AI Agent's language. - `metadata` keys are set as metavariables on the conversation when the recipient answers and the Proactive's Playbook opens it, so the Playbook can use them. Values must be strings, numbers or booleans, and the object must not exceed 4 KB. - Send an `Idempotency-Key` header to retry safely. A reused key returns the attempt the first request created, with the `Idempotent-Replayed: true` response header, instead of contacting the recipient again. Keys stay reserved for 90 days. Reference: https://docs.ada.cx/reference/conversations/create-proactive-conversation ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Headers - `Idempotency-Key` (string, optional) — A unique key of your choice for this request. Retrying with the same key returns the Proactive Attempt the first request created instead of contacting the recipient again. ### Body (application/json) This endpoint expects a ProactiveConversationCreateRequest. - `proactive_id` (string, required) — The ID of the Proactive to contact the recipient with - `channel` (enum, required) — The Proactive's channel. Only voice Proactives can be placed. - Allowed values: `voice` - `recipient` (ProactiveRecipient, required) - `language` (string, optional, nullable) — The language to hold the conversation in, as a language code enabled for your AI Agent that voice supports. When omitted or null, the Proactive's default language is used, then the AI Agent's language. - `metadata` (map from string to ProactiveConversationCreateRequestMetadata, optional) — Key-value pairs for this conversation. Each key is set as a metavariable when the recipient answers and the Proactive's Playbook opens the conversation, so the Playbook can use it. - at most 20 keys, each 1 to 64 letters, digits or underscores, and not a 24-character hexadecimal string (Ada reads those as variable ids) - keys that name a metavariable Ada sets itself (for example `language`, `phone_number`, `email`) are rejected - values may only be of type `string`, `boolean`, `integer`, or `number` (a finite float), and are stored as strings on the metavariable the way End Users API metadata is: `true` becomes `True`, `false` becomes `False`, `12.5` becomes `12.5` - the object must not exceed 4 KB when serialized as JSON ## Response ### 202 The Proactive Attempt is queued. Its `id` identifies the attempt; the conversation is created when the recipient answers. - `id` (string, required) — The ID of the Proactive Attempt - `state` (enum, required) — Where the attempt is in its lifecycle. A new attempt is `queued`; this endpoint does not report the later states. - Allowed values: `queued`, `initiated`, `answered`, `machine_detected`, `failed` - `proactive_id` (string, required) — The ID of the Proactive - `channel` (string, required) — The Proactive's channel - `recipient` (ProactiveRecipient, required) - `language` (string, required, nullable) — The language the conversation is held in - `metadata` (map from string to ProactiveAttemptMetadata, required) — The `metadata` the attempt was created with - `created_at` (string, required) — The date and time the attempt was created ## Errors ### 400 Bad Request Error Bad Request: an unknown field, a `recipient.phone_number` that is not a valid E.164 number, a `language` the AI Agent does not support on voice, or `metadata` that is too large or has a non-scalar value. - `errors` (list of ErrorsErrorsItems, required) — A list of errors ### 401 Unauthorized Error Unauthorized - `errors` (list of ErrorsErrorsItems, required) — A list of errors ### 404 Not Found Error No Proactive with this `proactive_id` exists for your AI Agent - `errors` (list of ErrorsErrorsItems, required) — A list of errors ### 409 Conflict Error Another request with the same `Idempotency-Key` is still being processed. Retry the request. - `errors` (list of ErrorsErrorsItems, required) — A list of errors ### 422 Unprocessable Entity Error The Proactive is not active, it has no compliance attestation, it is not on the requested `channel`, or the language the call would be held in is no longer one your AI Agent supports on voice - `errors` (list of ErrorsErrorsItems, required) — A list of errors ### 429 Too Many Requests Error Too Many Requests - `errors` (list of ErrorsErrorsItems, required) — A list of errors ### 500 Internal Server Error Internal Server Error - `errors` (list of ErrorsErrorsItems, required) — A list of errors ## Types ### ProactiveRecipient - `phone_number` (string, required) — The recipient's phone number in E.164 format (for example +14155550123). ### ProactiveConversationCreateRequestMetadata ### ProactiveAttemptMetadata ### ErrorsErrorsItems - `type` (string, required) — The error type - `message` (string, required) — The error message - `details` (string, optional, nullable) — Extra information about the error ## Examples **Request** ```json { "proactive_id": "5df263b7db5a7e6ea03fae9b", "channel": "voice", "recipient": { "phone_number": "+14155550123" } } ``` **Response** ```json { "id": "5df263b7db5a7e6ea03fae9b", "state": "queued", "proactive_id": "5df263b7db5a7e6ea03fae9b", "channel": "voice", "recipient": { "phone_number": "+14155550123" }, "language": "en", "metadata": { "order_id": "ORD-1042", "is_priority": true }, "created_at": "2026-09-11T16:00:00+00:00" } ``` **SDK Code** ```python import requests url = "https://example.ada.support/api/v2/conversations/proactive/" payload = { "proactive_id": "5df263b7db5a7e6ea03fae9b", "channel": "voice", "recipient": { "phone_number": "+14155550123" } } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://example.ada.support/api/v2/conversations/proactive/'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"proactive_id":"5df263b7db5a7e6ea03fae9b","channel":"voice","recipient":{"phone_number":"+14155550123"}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://example.ada.support/api/v2/conversations/proactive/" payload := strings.NewReader("{\n \"proactive_id\": \"5df263b7db5a7e6ea03fae9b\",\n \"channel\": \"voice\",\n \"recipient\": {\n \"phone_number\": \"+14155550123\"\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://example.ada.support/api/v2/conversations/proactive/") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"proactive_id\": \"5df263b7db5a7e6ea03fae9b\",\n \"channel\": \"voice\",\n \"recipient\": {\n \"phone_number\": \"+14155550123\"\n }\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://example.ada.support/api/v2/conversations/proactive/") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"proactive_id\": \"5df263b7db5a7e6ea03fae9b\",\n \"channel\": \"voice\",\n \"recipient\": {\n \"phone_number\": \"+14155550123\"\n }\n}") .asString(); ``` ```php request('POST', 'https://example.ada.support/api/v2/conversations/proactive/', [ 'body' => '{ "proactive_id": "5df263b7db5a7e6ea03fae9b", "channel": "voice", "recipient": { "phone_number": "+14155550123" } }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://example.ada.support/api/v2/conversations/proactive/"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"proactive_id\": \"5df263b7db5a7e6ea03fae9b\",\n \"channel\": \"voice\",\n \"recipient\": {\n \"phone_number\": \"+14155550123\"\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "proactive_id": "5df263b7db5a7e6ea03fae9b", "channel": "voice", "recipient": ["phone_number": "+14155550123"] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://example.ada.support/api/v2/conversations/proactive/")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```