Skip to navigation

Start outbound call

Makes one of your agents call a phone number now and returns the outbound call, which you can follow with GET /outbound-calls/{outbound_call_id}. Only Italian landline, mobile and toll-free (800, 803) numbers can be called, only from an agent with an Italian line, within the calling hours of the organization, and never a number on the do-not-call list. You must declare in contact_origin where the right to call this person comes from. With a test key nothing is dialed: the response has status: simulated and simulated: true. Required scope: calls:start. This operation consumes usage (minutes, SMS or model calls) and is billed to the organization. With a test key (vx_test_) it is simulated: nothing real happens and nothing is billed. Requires an Idempotency-Key header. NOT retriable: when the operation itself fails with a 429, a 5xx or a temporary 409, the outcome is uncertain and the key becomes “unknown” (the same key gives 409 idempotency_outcome_unknown); with no response at all, the same key returns the first outcome or that same 409. After idempotency_outcome_unknown, read the state of the resource and retry with a new key only if the operation did not happen. A 429 rate_limited from the request limit and 409 request_in_progress come before the operation and leave the key as it is: retry with the same key.

Authentication

AuthorizationBearer
API key created by an Owner or Admin of the organization. Never in the query string.

Headers

VoxAI-VersionenumOptional

API version for this request; defaults to the version the key is pinned to.

Allowed values:
Idempotency-KeystringRequiredformat: "^[A-Za-z0-9_-]{16,64}$"

A unique value you generate for each new operation (16 to 64 letters, digits, hyphen or underscore; a UUID works). Repeating the same request with the same key within 24 hours returns the first response and does nothing again, when that response was a success or a 4xx error the same request would always get again (not 429, and not the temporary 409 codes request_in_progress, caller_has_active_call and caller_request_in_progress: for those, and for a 5xx, see the note on retrying in the operation); the same key with a different request is refused with idempotency_key_reused.

Request

This endpoint expects an object.
agent_idstringRequiredformat: "^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"

The agent that makes the call, as returned by GET /agents. It needs an Italian phone line and must not be suspended.

tostringRequiredformat: "^\+[1-9][0-9]{6,14}$"

The number to call, in E.164 format, for example +393331234567. Only Italian landline, mobile and toll-free (800, 803) numbers; never a number on the do-not-call list of the organization.

variablesobjectOptional

Values for the variables of the agent, by name (GET /agents/{agent_id}/variables): text, number or boolean, at most 30. The agent uses them in the conversation, for example a name or a date. A required variable that is missing gives 422 missing_variables.

contact_originobjectOptional

Required (without it the answer is 422 contact_origin_required): your declaration of where the right to call comes from. VoxAI records it with the key and the time, so you can show it if asked; it does not verify it and does not check the Register of Oppositions for you. basis and purpose are required inside it.

Response

The call was accepted: status is dialing (or simulated with a test key).

object"outbound_call"

Always outbound_call.

idstringformat: "uuid"

Id of the outbound call: use it with GET /outbound-calls/{outbound_call_id}.

statusenum

dialing: the number is being called. answered: a person answered. voicemail_left: an answering machine answered and the agent left a message. no_answer: nobody answered, or an automatic message or menu answered (it may be retried). invalid_number: the number does not exist or is a fax. completed: the call ended normally. failed: the call could not be made. missing_variables: the agent needed a variable that was not given. simulated: only with a test key, nothing was dialed. uncertain (HTTP 202): the telephone network did not answer clearly, the call may have started and is NOT repeated; read the call again (it keeps saying uncertain until the call is closed or marked failed) before deciding anything.

agent_idstring
The agent that makes the call.
call_idstring or null

Id of the call in GET /calls, once the call has started; null before.

simulatedboolean

true with a test key: nothing was dialed and the id does not exist (reading it gives 404).

goal_achievedboolean or null

Whether the agent reached the goal of the call, from its report card. null until the call has been evaluated.

created_atdatetime
When the call was requested, ISO 8601 UTC.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
502
Bad Gateway Error
503
Service Unavailable Error