Outbound calls

Queue one call with POST /outbound/calls — by saved flow, by workspace default, or with a one-off flow defined inline.

POST /api/external/v1/outbound/calls queues a single outbound call session. It returns once the call is queued, not once the conversation has finished.

Choosing the flow

There are three ways to say what the agent should do, and they are mutually exclusive.

By saved flow

The normal case. Reference a flow from your library by its apiId.

{
  "flowApiId": "f_sales_voice",
  "customerNumber": "+15551234567",
  "fromPhoneNumber": "+15557654321",
  "contactName": "Taylor Reed",
  "contactEmail": "[email protected]",
  "rowData": {
    "company": "Acme",
    "pipeline": "sales"
  },
  "contextData": {
    "crmLeadId": "lead_123",
    "source": "zapier"
  }
}

By workspace default

Omit flowId, flowApiId and flow entirely and the call runs on your workspace's default manual-call flow.

{
  "customerNumber": "+15551234567",
  "contactName": "Taylor Reed",
  "rowData": {
    "campaign": "reactivation_q2"
  }
}

Inline, without saving

Pass a whole flow definition in the request. Nothing is written to the flow library — this is for conversations your own system composes per call.

{
  "flow": {
    "name": "One-off reactivation call",
    "masterPrompt": "You are Alex from Acme, calling to check in on the contact's account.",
    "firstMessage": "Hi there, this is Alex from Acme — got a minute?",
    "voiceId": "en-US-female-1",
    "language": "en",
    "localVariables": [
      { "variableName": "accountTier", "type": "string" }
    ]
  },
  "customerNumber": "+15551234567",
  "contactName": "Taylor Reed",
  "rowData": {
    "campaign": "reactivation_q2"
  }
}

Fields

customerNumberstringRequired

The number to call, in E.164 form.

fromPhoneNumberstring

Which of your provisioned numbers to call from. Falls back to the workspace default when omitted.

flowApiIdstring

The apiId of a saved flow. Prefer this over the numeric flowId — it is stable across environments.

flowobject

A complete inline flow definition, used instead of flowApiId. Not saved.

contactNamestring

The contact's name, available to the conversation and stored on the resulting row.

rowDataobject

Arbitrary key/value data merged into the conversation as variables the flow can reference. This is what the agent is allowed to know.

contextDataobject

Arbitrary metadata that travels with the call and comes back on the result, untouched. This is where your own identifiers belong — a CRM record id, the campaign that triggered it, the system that asked.

rowData or contextData?

If the agent should be able to say it out loud, it is rowData. If it only exists so your system can match the result back to a record, it is contextData.

Getting the result

Calls are asynchronous. Poll GET /call-history, or fetch the specific row with GET /call-rows/{rowId}, and the record carries the transcript, the recording, the structured fields the flow extracted, and the contextData you sent in.

For anything volume-shaped, an automation that pushes each finished call to your own endpoint is better than polling — see Core concepts.

Chat works the same way

POST /outbound/chats takes the same three flow-selection shapes for WhatsApp and API-managed chat sessions. The full request and response schemas are in the API reference.