Calls API

The agent associated with the call. It does not need to be dialable; this endpoint only logs the record.

Call direction. One of inbound or outbound. Defaults to outbound when omitted, but always send an explicit value; the default may be removed in a future release.

E.164 phone number of the callee, e.g. +14155551234. Validated against ^\+[1-9]\d{1,14}$.

E.164 phone number of the caller. Example: +14155559876. Validated against the regex ^\+[1-9]\d{1,14}$. This endpoint only logs the record, so from_number is optional here. POST /calls/trigger and per-recipient entries in POST /calls/batch both reject a missing from_number with 422 from_number_required.

Arbitrary JSON stored on the call for your own bookkeeping (campaign tags, lead IDs, etc.). Returned verbatim on GET /calls/{id}. Defaults to {'}.

The agent that should handle this call.

Recipient phone number in E.164 format, e.g. +14155551234. Must match ^\+[1-9]\d{1,14}$.

Caller ID in E.164 format. Example: +14155559876. Validated against the regex ^\+[1-9]\d{1,14}$. Must be a phone number registered to this account with outbound enabled (see Phone Numbers). Required — omitting it returns 422 from_number_required.

Per-call values for {{ variable_name }} placeholders defined on the agent. Values stored on the agent act as defaults; pass keys here to override them per call and to fill any placeholder that has no default. A placeholder with no value does not refuse the call: the model reads [name: not provided] in its place, and the agent's webhook gets agent.prompt_variables.unfilled (at most once a day). Values must be strings, numbers, or booleans. Keys using the reserved system__ prefix are rejected because supported system placeholders are filled by Aethex.

Arbitrary JSON stored on the call for your own bookkeeping (campaign tags, lead IDs, etc.). Returned verbatim on GET /calls/{id}. Defaults to {'}.

The agent that should handle every call in the batch.

Array of recipient objects. Minimum 1, maximum 10,000. Each entry may use phone_number (compatibility shape) or to_number (legacy), plus optional id, from_number, variables, and conversation_initiation_client_data.dynamic_variables. On a WhatsApp batch, whatsapp_user_id (the person's WhatsApp number, digits) may stand in for phone_number, and from_number does not apply. If agent_phone_number_id is omitted, every phone recipient must provide a tenant-owned outbound-capable from_number. A recipient may also carry transfer_number: where that call transfers to, overriding the agent's own destination for that call alone. One E.164 number, or an array of up to five tried in order when a leg is not answered. Omit it to keep the agent's own setting. Batch recipients are stored durably, so variables cannot include secret__* keys; use POST /calls/trigger for per-call secret dynamic variables.

Compatibility batch label. name is accepted as a legacy alias.

Optional human-readable batch label, max 255 characters.

Optional description, max 2000 characters. Omitting it returns as "" in responses.

Defer the first dial until this timestamp. Must include a timezone offset. When in the future the batch starts as scheduled; otherwise the field is ignored and the batch starts as queued.

Hard deadline. The dialer abandons any recipients still un-started past this timestamp. Must include a timezone offset, must be in the future, and must be strictly after start_at if both are set.

Unix timestamp for scheduled dispatch. Accepted as an alias for start_at; if both are supplied they must represent the same instant.

Tenant phone-number UUID to use as the default sender for recipients that omit from_number.

Call the batch on WhatsApp. whatsapp_phone_number_id names the connected number (its id or Meta's phone-number id; optional when the workspace has one), and whatsapp_call_permission_request_template_name with whatsapp_call_permission_request_template_language_code name an approved template with a call-permission request and no variables — every recipient receives it as written. Each person may appear once, and a recipient given both phone_number and whatsapp_user_id must be the same person. Needs the whatsapp_messages:write scope and counts against the WhatsApp send budget. agent_phone_number_id and from_number do not apply.

Optional telephony settings. ringing_timeout_secs controls how long Twilio or SIP rings before giving up; default is 60 seconds.

Maximum simultaneous calls for this batch. The worker also remains subject to tenant and cluster admission limits.

Optional IANA timezone label returned with the batch for UI/reporting; scheduling is still driven by absolute timestamps.

UUID of the batch returned from POST /calls/batch.

UUID of the batch returned from POST /calls/batch.

UUID of the batch returned from POST /calls/batch.

UUID of the batch returned from POST /calls/batch.

UUID of the call to hang up.