Initiates an outbound telephony call with a specified agent and phone number.
## Caller-ID resolution
When `fromProductId` is omitted **and** the agent has no telephony
product attached, the call dispatches from a Smallest-managed Plivo
trunk using a default caller-ID number (chosen by destination
country). The call still places and the response is still
`200 + conversationId`, but the recipient sees the default Smallest
number rather than your own. For production traffic, either:
- pass `fromProductId` explicitly (look up your owned numbers via
`GET /product/phone-numbers`), or
- attach a phone-number product to the agent.
## Resolved-config check
The call uses the agent's currently-active version. If your most
recent prompt change went through `PATCH /workflow/{workflowId}` and
the agent has versioning enabled, that change may not have
propagated to the active version — and the call will play the
platform-default greeting instead of your prompt. Before placing a
production call, fetch `GET /agent/{agentId}` and confirm
`_resolvedConfig.firstMessage` (and related fields) match what you
intended. The
[Versioning Lifecycle](/atoms/developer-guide/build/agents/versioning-lifecycle)
guide covers the correct edit flow.
**400 is returned for:**
- Invalid `agentId` format (`"Invalid agent id"`)
- Invalid `phoneNumber` format (`"Invalid phone number"`)
- Invalid `fromProductId` format (`"Invalid product id"`)
- Agent not found or not in the caller's org (`"Agent not found"`)
- Agent is archived (`"Agent is archived and cannot initiate calls"`)
- `workflow_graph` agent has no workflow configured (`"Workflow not found"`)
- Workflow has validation errors (`"Invalid workflow, please fix the errors..."`)
**403** is returned for `workflow_graph` agents when the org lacks conversational agents access.
**Test calls:** set the `x-test-call: true` header to mark the resulting call log as a test call
(`isTest: true`). Test calls are subject to concurrent slot limits.
Request
This endpoint expects an object.
agentIdstringRequired
MongoDB ObjectId of the agent initiating the conversation
phoneNumberstringRequired
The E.164 phone number to call
variablesmap from strings to strings or doubles or booleansOptional
Variables to inject into the agent’s prompt at call time.
Values must be string, number, or boolean — nested objects are not supported.
fromProductIdstringOptional
ID of the telephony product (phone number) to call from. Get this from GET /product/phone-numbers.
versionIdstringOptional
ID of a specific published agent version to use for this call.
Useful for test calls — attributes the call log to that version so you can track
which version was tested.
operatorIdstringOptional
Integration operator identifier. Pass "webengage" to trigger the WebEngage
integration flow.
operatorDatamap from strings to anyOptional
Arbitrary data passed to the operator (e.g. userId, journeyId for WebEngage).
Response
Successfully started the outbound conversation
