conversations

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.
post/v2/conversations/proactive/

Request

  • Base URL: https://example.ada.support/api
  • URL: https://example.ada.support/api/v2/conversations/proactive/
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

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 body

proactive_idstring id required

The ID of the Proactive to contact the recipient with

channel'voice' required

The Proactive's channel. Only voice Proactives can be placed.

languagestring 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.

metadataobject

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.

idstring id required

The ID of the Proactive Attempt

state'queued' | 'initiated' | 'answered' | 'machine_detected' | 'failed' required

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

proactive_idstring id required

The ID of the Proactive

channelstring required

The Proactive's channel

languagestring nullable required

The language the conversation is held in

metadataobject required

The metadata the attempt was created with

created_atstring date-time required

The date and time the attempt was created

Changes

No recorded changes to this operation across all 1 revision of this API.