Sign in
Calls

Start an outbound call

Initiates an outbound telephony call with a specified agent and phone number.

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.

post/conversation/outbound

Headers

x-test-call'true'

Set to "true" to mark this as a test call. The call log will have isTest=true and counts against concurrent test-call slot limits.

Request body

agentIdstring required

MongoDB ObjectId of the agent initiating the conversation

phoneNumberstring required

The E.164 phone number to call

variablesobject

Variables to inject into the agent's prompt at call time. Values must be string, number, or boolean — nested objects are not supported.

fromProductIdstring

ID of the telephony product (phone number) to call from. Get this from GET /product/phone-numbers.

versionIdstring

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.

operatorIdstring

Integration operator identifier. Pass "webengage" to trigger the WebEngage integration flow.

operatorDataobject

Arbitrary data passed to the operator (e.g. userId, journeyId for WebEngage).

Example request

{
  "agentId": "60d0fe4f5311236168a109ca",
  "phoneNumber": "+1234567890",
  "variables": {
    "name": "John",
    "age": 30,
    "vip": true
  },
  "fromProductId": "60d0fe4f5311236168a109ca"
}

Response

Successfully started the outbound conversation

statusboolean

Example response

{
  "status": true,
  "data": {
    "conversationId": "CALL-1737000000000-abc123"
  }
}

Changes