Start an outbound call

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 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.

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

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