Skip to content
Voicebot

Create communication (agent-dialed, or a scenario test call)

POST
/v1/communication/-/dispatch
curl --request POST \
  --url https://example.com/v1/communication/-/dispatch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "recipient": "example", "agent_sid": "example", "strategy_sid": "example", "scheduled_at": "2026-04-15T12:00:00Z", "data": {}, "schedule": {}, "scenario_sid": "example", "draft": true }'

Agent_sid dials through a configured agent (today’s behavior). scenario_sid is a test call: dispatched immediately, no strategy/number/campaign pre-creation needed. Exactly one of the two is required.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
X-Account-Sid
string

Target account for account-scoped resources. Principals without an account scope (superuser, tenant API key) MUST send it to declare which account to operate in. Account-scoped principals may omit it; if sent it must match their own account or the request is rejected with scope_conflict. For tenant API keys the account must belong to the key’s tenant.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Exactly one of agent_sid / scenario_sid is required; the other is a 422. agent_sid dials through a configured agent (dispatch timing is the server’s decision, not the caller’s). scenario_sid is a test call: draft selects the axis (omit for the current published version). Either variant may set scheduled_at to defer the dispatch; strategy_sid / schedule / data are agent-path only and ignored with scenario_sid. The from-number is the scenario’s agent number for a published run through an agent, otherwise a free account number. timezone is never accepted here — it is always derived server-side (the bound agent’s, or the account’s).

object
recipient
required
string
/^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/
agent_sid
string
strategy_sid
string
scheduled_at
string format: date-time
data

Flat map of scalar values (string/number/boolean); nested objects and arrays are rejected with 422.

object
key
additional properties
any
schedule
object
key
additional properties
any
scenario_sid

Test call: the scenario to dial directly.

string
draft

Test call only: true runs the current draft (frozen on first use); omit for the current published version.

boolean
Examplegenerated
{
  "recipient": "example",
  "agent_sid": "example",
  "strategy_sid": "example",
  "scheduled_at": "2026-04-15T12:00:00Z",
  "data": {},
  "schedule": {},
  "scenario_sid": "example",
  "draft": true
}

Responses

Section titled “Responses”

201

Section titled “201”

Created

Media typeapplication/json
object
id
required
string
account_sid
required
string
agent_sid
required
string
scenario_sid
required

Scenario the communication runs; empty on legacy rows created before the scenario binding was recorded.

string
strategy_sid
required
string
nullable
version
required

Published scenario version; null when the run used a draft.

integer
nullable
draft_version
required

Draft scenario version; null when the run used a published version. Exactly one of version / draft_version is set.

integer
nullable
strategy_attempt_sid
required
string
nullable
strategy_attempt_number
required
integer
recipient
required
string
direction
required
string
Allowed values: inbound outbound
communication_status
required
string
Allowed values: new ready dialing in_progress bounced done failed drifted
call_status
required
string
Allowed values: busy rejected no_answer voicemail incomplete completed failed tech_canceled
reason
required
string
data
required
object
key
additional properties
any
variables
required
object
key
additional properties
any
status_history
required
Array<object>
nullable
object
from
required
string
to
required
string
reason
string
call_sid
string
at
required
string format: date-time
scheduled_at
required
string format: date-time
nullable
schedule
required
object
key
additional properties
any
timezone
required
string
next_call_at
required
string format: date-time
call_attempt_number
required
integer
executor_id
required
string
nullable
call_sid
required
string
nullable
duration
required

Call duration in seconds, measured by the execution layer; 0 until the call completes.

integer
is_test
required

Whether this is a test communication.

boolean
consent_granted
required

Whether personal-data recording consent was granted for the call.

boolean
has_recording
required

Whether a stored call recording exists for this communication.

boolean
has_call_history
required

Whether a saved call execution history exists for this communication.

boolean
created_at
required
string format: date-time
updated_at
required
string format: date-time
Example
{
  "direction": "inbound",
  "communication_status": "new",
  "call_status": "busy"
}

400

Section titled “400”

Invalid request body or parameters

Media typeapplication/json
object
error
required

Stable lower_snake_case usecase code (e.g. scenario_not_found)

string
code
required

Registered machine code — generic ERRxxx by status class (ERR001–ERR020 reserved); entity-prefixed codes (SCN1xx) appear only inside validation details; registry in docs/specifications/error-envelope-design.md, append-only, never renumbered

string
message
required
string
data

Structured details, present only where there is structure to carry: validation failures (topic validation, per-entity errors) and delete conflicts (topic conflict, referencing agents)

object
topic
string
errors

Validation errors keyed by entity

object
scenario
Array<object>
object
code

SCN1xx constructor validation code

string
message
string
summary
string
tree_id
string
node_id
string
output_type
string
duplicate_tree_index
string
duplicate_node_index
string
property
string
invalid_value
string
agents

Ids of the agents referencing the resource a delete was rejected for; first 20 — message carries the total count

Array<string>
Examplegenerated
{
  "error": "example",
  "code": "example",
  "message": "example",
  "data": {
    "topic": "example",
    "errors": {
      "scenario": [
        {
          "code": "example",
          "message": "example",
          "summary": "example",
          "tree_id": "example",
          "node_id": "example",
          "output_type": "example",
          "duplicate_tree_index": "example",
          "duplicate_node_index": "example",
          "property": "example",
          "invalid_value": "example"
        }
      ]
    },
    "agents": [
      "example"
    ]
  }
}

401

Section titled “401”

Missing or invalid credentials

Media typeapplication/json
object
error
required

Stable lower_snake_case usecase code (e.g. scenario_not_found)

string
code
required

Registered machine code — generic ERRxxx by status class (ERR001–ERR020 reserved); entity-prefixed codes (SCN1xx) appear only inside validation details; registry in docs/specifications/error-envelope-design.md, append-only, never renumbered

string
message
required
string
data

Structured details, present only where there is structure to carry: validation failures (topic validation, per-entity errors) and delete conflicts (topic conflict, referencing agents)

object
topic
string
errors

Validation errors keyed by entity

object
scenario
Array<object>
object
code

SCN1xx constructor validation code

string
message
string
summary
string
tree_id
string
node_id
string
output_type
string
duplicate_tree_index
string
duplicate_node_index
string
property
string
invalid_value
string
agents

Ids of the agents referencing the resource a delete was rejected for; first 20 — message carries the total count

Array<string>
Examplegenerated
{
  "error": "example",
  "code": "example",
  "message": "example",
  "data": {
    "topic": "example",
    "errors": {
      "scenario": [
        {
          "code": "example",
          "message": "example",
          "summary": "example",
          "tree_id": "example",
          "node_id": "example",
          "output_type": "example",
          "duplicate_tree_index": "example",
          "duplicate_node_index": "example",
          "property": "example",
          "invalid_value": "example"
        }
      ]
    },
    "agents": [
      "example"
    ]
  }
}

422

Section titled “422”

Semantic validation failure

Media typeapplication/json
object
error
required

Stable lower_snake_case usecase code (e.g. scenario_not_found)

string
code
required

Registered machine code — generic ERRxxx by status class (ERR001–ERR020 reserved); entity-prefixed codes (SCN1xx) appear only inside validation details; registry in docs/specifications/error-envelope-design.md, append-only, never renumbered

string
message
required
string
data

Structured details, present only where there is structure to carry: validation failures (topic validation, per-entity errors) and delete conflicts (topic conflict, referencing agents)

object
topic
string
errors

Validation errors keyed by entity

object
scenario
Array<object>
object
code

SCN1xx constructor validation code

string
message
string
summary
string
tree_id
string
node_id
string
output_type
string
duplicate_tree_index
string
duplicate_node_index
string
property
string
invalid_value
string
agents

Ids of the agents referencing the resource a delete was rejected for; first 20 — message carries the total count

Array<string>
Examplegenerated
{
  "error": "example",
  "code": "example",
  "message": "example",
  "data": {
    "topic": "example",
    "errors": {
      "scenario": [
        {
          "code": "example",
          "message": "example",
          "summary": "example",
          "tree_id": "example",
          "node_id": "example",
          "output_type": "example",
          "duplicate_tree_index": "example",
          "duplicate_node_index": "example",
          "property": "example",
          "invalid_value": "example"
        }
      ]
    },
    "agents": [
      "example"
    ]
  }
}

500

Section titled “500”

Internal server error

Media typeapplication/json
object
error
required

Stable lower_snake_case usecase code (e.g. scenario_not_found)

string
code
required

Registered machine code — generic ERRxxx by status class (ERR001–ERR020 reserved); entity-prefixed codes (SCN1xx) appear only inside validation details; registry in docs/specifications/error-envelope-design.md, append-only, never renumbered

string
message
required
string
data

Structured details, present only where there is structure to carry: validation failures (topic validation, per-entity errors) and delete conflicts (topic conflict, referencing agents)

object
topic
string
errors

Validation errors keyed by entity

object
scenario
Array<object>
object
code

SCN1xx constructor validation code

string
message
string
summary
string
tree_id
string
node_id
string
output_type
string
duplicate_tree_index
string
duplicate_node_index
string
property
string
invalid_value
string
agents

Ids of the agents referencing the resource a delete was rejected for; first 20 — message carries the total count

Array<string>
Examplegenerated
{
  "error": "example",
  "code": "example",
  "message": "example",
  "data": {
    "topic": "example",
    "errors": {
      "scenario": [
        {
          "code": "example",
          "message": "example",
          "summary": "example",
          "tree_id": "example",
          "node_id": "example",
          "output_type": "example",
          "duplicate_tree_index": "example",
          "duplicate_node_index": "example",
          "property": "example",
          "invalid_value": "example"
        }
      ]
    },
    "agents": [
      "example"
    ]
  }
}