Skip to main content
POST
Dispatch a call from this assistant

Authorizations

Authorization
string
header
required

Project API key (sk_api_…).

Headers

Idempotency-Key
string

Caller-chosen key that fixes the call id, so a retried request cannot dial twice. Scoped to this assistant.

Maximum string length: 256

Path Parameters

realtimeAssistantId
string<uuid>
required

Body

application/json
toNumber
string
required

Number to dial, either E.164 (+923001234567) or a local leading-zero number (03001234567).

Pattern: ^(\+[1-9]\d{1,14}|0\d{8,14})$
Example:

"+923001234567"

fromNumber
string

Caller ID to dial from, E.164. Only the format is checked, so a number your organization doesn't own dispatches and then fails at the carrier. Omit to let the platform allocate one.

Pattern: ^\+[1-9]\d{1,14}$
Example:

"+924232175000"

variables
object

Facts about this caller, like crop: cotton. They reach the model as a caller record after the prompt, and come back verbatim on every session read. String, number and boolean values go to the model. A nested object stays on the record only. Keys up to 64 characters, and the serialized object must stay under 3000 characters.

additionalInstructions
string

Appended to the assistant's instructions for this call only.

Maximum string length: 2000
assistantVersion
default:prod

Which version of the assistant runs. prod is the published version, or the draft before the first publish. draft tries unpublished edits on a real conversation. A number runs that exact published version, and one never published is a 404. Send a number as a JSON number, not a string.

Available options:
prod,
draft
Example:

"draft"

Response

The call is dialing.

callId
string<uuid>

Id of this call, and the sessionId in every session and call record.

externalRef
string

Telephony-provider dispatch reference, useful when raising support tickets.

status
string
Allowed value: "dispatched"