Start an outbound call

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

Caller-ID resolution

Every call names the number it dials from:

1. fromNumber present: resolved against the numbers your organization owns (rented numbers and outbound SIP trunk caller IDs). Must match exactly as stored, E.164 with the leading + and no spaces (+14155552671). An unowned or unmatched number returns 400 (”… is not one of your outbound numbers”).
2. fromNumber omitted (deprecated fallback): the call dials from the agent’s attached caller IDs (see POST /agent/{agentId}/caller-ids), first attached wins. This fallback is the compatibility bridge and sunsets with the migration window, after which fromNumber is required; calls that used it respond with a Deprecation: true header so you can find them in your logs. With no caller IDs attached, the call is refused with 400 (“No caller ID for this call — pass a number to dial from, or attach a caller ID to the agent”). Calls to numbers on the Do Not Call list are refused with 403 (“Call blocked: number is on Do Not Call list”).

There is no silent fallback to a platform-owned number (dashboard test calls are the only exception). fromProductId is still accepted as a legacy alias and is resolved to its phone number first.

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")
• fromNumber that is not one of your rented numbers or outbound-trunk caller IDs ("...is not one of your outbound numbers")
• fromProductId that does not resolve to an active number in your organization ("Phone number not found or not active for your organization")
• No number to dial from: fromNumber omitted and the agent has no caller ID attached ("No caller ID for this call — pass a number to dial from, or attach a caller ID to the agent")
• 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.