Skip to main content
POST
Initiate VoiceAgent call

Authorizations

Authorization
string
header
required

HTTP Basic Authentication. Use your API Access Key ID as the username and your API Access Key Secret as the password. Generate keys in the CloudTalk Dashboard under Account -> Settings -> API Keys (https://dashboard.cloudtalk.io/menu/account/settings/API-keys).

Body

application/json
call_number
string
required

The phone number to call

Example:

"+421000000000"

voice_agent_id
string
required

ID of the VoiceAgent to use for the call

Example:

"681b0639876543cfbc3d6b55"

contact_id

Optional. ID of the CloudTalk contact (or lead) being called, as a string of digits or as an integer; "123" and 123 are the same contact. The call then uses exactly this contact instead of the one matched by call_number, and goes ahead even when the contact's phone numbers do not include call_number.

The contact fills the {{contact.*}} variables and appears in the post-call analysis as ct_call_context.contact; its e-mails are where the calendar invite goes by default. A non-empty value you send for a contact.* variable in call_properties.system_prompt.variables wins over the contact's value for that variable in what the agent is told, in what it sends to custom tools and, for the variable the booking skill takes the invite e-mail from (contact.emails by default), in where the calendar invite goes. ct_call_context.contact stays this contact's.

A contact that does not exist in your company, belongs to another company or was deleted is refused with 422 contact_not_found, and no call is queued. Fractional numbers (for example 1.5), zero, negative numbers, null, integers above 9223372036854775807, and strings that are empty, start with a zero, contain anything but digits or are longer than 19 digits (for example "012" or "1.0") are refused with 422. A whole number written as 123.0 or 1.23e2 is the same contact as 123.

Pattern: ^[1-9][0-9]{0,18}$
Example:

"123456"

call_properties
object

Additional properties for configuring the VoiceAgent call

Response

The call was queued.

session_id
string
required

ID of the queued call session. Quote it when you contact CloudTalk support about this call.

Example:

"6640f1a2c3d4e5f60718293a"