Skip to navigation
ConversationsConversations

Start a conversation from a Proactive

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.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Headers

Idempotency-KeystringOptional1-255 characters
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.

Request

This endpoint expects an object.
proactive_idstringRequiredformat: "id"
The ID of the Proactive to contact the recipient with
channelenumRequired
The Proactive's channel. Only voice Proactives can be placed.
Allowed values:
recipientobjectRequired
languagestring or nullOptional2-16 characters
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.
metadatamap from strings to strings or booleans or integers or doublesOptional

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

The Proactive Attempt is queued. Its id identifies the attempt; the conversation is created when the recipient answers.

idstringRead-onlyformat: "id"
The ID of the Proactive Attempt
stateenumRead-only

Where the attempt is in its lifecycle. A new attempt is queued; this endpoint does not report the later states.

Allowed values:
proactive_idstringformat: "id"
The ID of the Proactive
channelstring
The Proactive's channel
recipientobject
languagestring or null
The language the conversation is held in
metadatamap from strings to strings or booleans or integers or doubles

The metadata the attempt was created with

created_atstringRead-onlyformat: "date-time"
The date and time the attempt was created

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error