Calls - Inkbox

Place outbound calls with bidirectional audio streaming, and retrieve call records. Calls are scoped to your agent identity and span dedicated phone numbers plus shared and dedicated iMessage lines. When you place a call, Inkbox dials the to_number and opens a WebSocket media stream to the client_websocket_url you provide. Your agent connects to that URL to send and receive audio (or text, depending on the pipeline mode). See Media Stream for details on pipeline modes. Alternatively, place the call with mode="hosted_agent" and Inkbox runs Inkbox Voice AI on the call — no WebSocket required.

Place call

POST /place-call

Initiate an outbound call. Inkbox dials the to_number and opens a bidirectional media stream to your client_websocket_url.

Request body

Field	Type	Required	Description
`origination`	string	No	`"dedicated_number"` (default), `"shared_imessage_number"`, or `"dedicated_imessage_number"`. Selects the phone or iMessage line used for the call
`from_number`	string \| null	Conditional	Caller ID in E.164 — REQUIRED for `dedicated_number` origination and must be an active number in your org. Omit for either iMessage origination; Inkbox resolves the line from the identity
`to_number`	string	Yes	Destination number in E.164 format
`agent_identity_id`	UUID \| null	Conditional	The agent identity placing the call. Required for either iMessage origination when using an admin API key or the Inkbox Console; identity-scoped API keys resolve their own identity automatically (naming a different one returns `403`)
`client_websocket_url`	string \| null	No	WebSocket URL (`wss://`) your agent listens on. Can carry text or audio, depending on how the connection is configured. Falls back to the identity’s configured `client_websocket_url` (see Incoming calls) if omitted (`400` if none is set). Must be absent when `mode` is `"hosted_agent"` (`422`)
`mode`	string	No	Who drives the call: `"client_websocket"` (default — your agent, over the media stream) or `"hosted_agent"` (Inkbox Voice AI)
`hosted_agent_authority_mode`	string \| null	No	Optional data-scope override for a Voice AI call: `"contact_scoped"` or `"yolo"`. Omit or send `null` to inherit the identity’s saved mode, or `"yolo"` if the identity has no saved Voice AI configuration. Explicit `"contact_scoped"` can always narrow one call; explicit `"yolo"` requires an admin API key or the Inkbox Console only when the saved mode is `"contact_scoped"`
`reason`	string \| null	Conditional	The voice agent’s task brief — what this call is for, in plain language. REQUIRED with `mode="hosted_agent"` (non-empty, max 2,000 characters); invalid with `mode="client_websocket"` (`422`)
`on_voicemail`	string	No	What to do when the call reaches voicemail: `"leave_message"` (default with `mode="hosted_agent"`) has Voice AI wait for the beep, leave a message, then end the call; `"hang_up"` (default otherwise) ends the call once a voicemail beep is detected; `"ignore"` turns detection off and treats whatever answers as a person. `"leave_message"` requires `mode="hosted_agent"` (`422`)
`voicemail_message`	string \| null	No	What Voice AI should say when leaving a voicemail, up to 1,000 characters; the agent delivers it naturally rather than reading it verbatim. Only valid with `on_voicemail="leave_message"` (`422` otherwise). When omitted, the agent composes a short message from `reason`
`voicemail_detection`	string	No	Deprecated — use `on_voicemail`. `"enabled"` means `on_voicemail="hang_up"` and `"disabled"` means `on_voicemail="ignore"`. Still accepted; sending both fields with conflicting values returns `422`

Request example

JSON

{
  "origination": "dedicated_number",
  "from_number": "+14155550100",
  "to_number": "+12125550199",
  "client_websocket_url": "wss://your-agent.example.com/stream"
}

To place the call from your agent identity’s shared iMessage line, omit from_number — the outbound line is resolved automatically:

JSON

{
  "origination": "shared_imessage_number",
  "to_number": "+12125550199",
  "agent_identity_id": "d4e5f6a7-b8c9-0123-def0-456789012345"
}

To have Inkbox Voice AI run the call, pass mode and a reason instead of a WebSocket URL:

JSON

{
  "origination": "dedicated_number",
  "from_number": "+14155550100",
  "to_number": "+12125550199",
  "mode": "hosted_agent",
  "reason": "Call the dental office and book a cleaning next week, mornings preferred."
}

A Voice AI call leaves a voicemail by default: when the call reaches voicemail, the agent waits for the beep, leaves a message, and ends the call with hangup_reason "voicemail". Pass voicemail_message to control what it says; omit it and the agent composes a short message from reason:

JSON

{
  "origination": "dedicated_number",
  "from_number": "+14155550100",
  "to_number": "+12125550199",
  "mode": "hosted_agent",
  "reason": "Confirm tomorrow's 9:30am appointment.",
  "on_voicemail": "leave_message",
  "voicemail_message": "Hi, this is Ink from Blue Harbor Dental confirming your 9:30am appointment tomorrow. Call us back if you need to reschedule."
}

Set on_voicemail to "hang_up" when the call should end instead — it hangs up as soon as a voicemail beep is detected, so automated greetings and phone menus are left alone. On Voice AI calls the agent stays silent from the machine report until the no-beep verdict (roughly 25–30 seconds) while keypad presses keep working. That is the default for client_websocket calls. Set "ignore" to skip detection entirely and treat whatever answers as a person. voicemail_detection remains accepted as a deprecated alias: "enabled" is "hang_up" and "disabled" is "ignore". The MCP call tool offers the same on_voicemail and voicemail_message fields; a call placed through MCP that omits both on_voicemail and voicemail_detection leaves a message. Voice AI inherits the identity’s saved authority when hosted_agent_authority_mode is omitted or null. An identity with no saved Voice AI configuration uses yolo. Set contact_scoped to narrow one call. Set yolo when the call needs identity-wide access to contacts, email, SMS, iMessage, or historical calls:

JSON

{
  "origination": "dedicated_number",
  "from_number": "+15555550100",
  "to_number": "+15555550123",
  "mode": "hosted_agent",
  "hosted_agent_authority_mode": "yolo",
  "reason": "Review today's open conversations and summarize anything urgent."
}

Response (200)

JSON

{
  "id": "c1d2e3f4-a5b6-7890-cdef-012345678901",
  "origin": "dedicated_number",
  "local_phone_number": "+14155550100",
  "remote_phone_number": "+12125550199",
  "direction": "outbound",
  "status": "ringing",
  "client_websocket_url": "wss://your-agent.example.com/stream",
  "mode": "client_websocket",
  "hosted_agent_authority_mode": "contact_scoped",
  "on_voicemail": "hang_up",
  "voicemail_detection": "enabled",
  "reason": null,
  "post_call_action_items": [],
  "connections": [],
  "forwardings": [],
  "use_inkbox_tts": null,
  "use_inkbox_stt": null,
  "hangup_reason": null,
  "started_at": null,
  "ended_at": null,
  "is_blocked": false,
  "created_at": "2026-03-10T12:00:00Z",
  "updated_at": "2026-03-10T12:00:00Z",
  "rate_limit": {
    "calls_used": 1,
    "calls_remaining": 99,
    "calls_limit": 100,
    "minutes_used": 0.0,
    "minutes_remaining": 100.0,
    "minutes_limit": 100
  }
}

The place call response includes a rate_limit object with your organization’s rolling 24-hour usage snapshot (calls_used, calls_remaining, calls_limit, minutes_used, minutes_remaining, minutes_limit). Active calls, including initiated calls, count provisionally toward the daily call quota. Canceled outbound calls still count when dialing reached the phone network. Failed placements, pre-dial outbound cancellations, and inbound calls that end unanswered are excluded. These quota and call-admission rules are server-side behavior. They apply even when you use an older SDK or CLI version. For shared_imessage_number origination, local_phone_number is null because the shared line is never surfaced. A dedicated_imessage_number call surfaces its dedicated iMessage line as local_phone_number.

Error responses

Status	Description
400	`from_number` is not active, or no WebSocket URL is available
402	`free_call_minutes_exhausted`: the organization has used all call minutes included with its plan. Upgrade in the Inkbox Console; `detail.upgrade_url` links to the billing page. `overage_cap_reached`: the organization’s overage spending limit is reached.
403	Recipient rejected for policy reasons, an identity-scoped key names a different identity, or `yolo` would widen a saved `contact_scoped` mode without an admin API key or the Inkbox Console
404	`from_number` not found
409	For iMessage-line originations: no active shared connection, no dedicated iMessage line, an inactive agent identity, or an identity that is not iMessage-enabled
422	Cannot call the number itself; for iMessage-line originations, also returned when the line is not voice-enabled or not verified. Also returned for Voice AI shape violations: `mode="hosted_agent"` without a `reason` (or with a `client_websocket_url`), a `reason` with `mode="client_websocket"`, or `hosted_agent_authority_mode="yolo"` without `mode="hosted_agent"`. Voicemail shape violations: `on_voicemail="leave_message"` without `mode="hosted_agent"`, a `voicemail_message` without `on_voicemail="leave_message"` (or blank, or over 1,000 characters), or `on_voicemail` and `voicemail_detection` sent together with conflicting values
429	Rolling 24-hour call or minute quota exceeded, or `concurrent_calls_limit`: the live outbound-call limit is reached (default: 3 across the organization’s phone numbers, or on one dedicated iMessage line). Concurrent-call rejections include `Retry-After` (seconds), `X-RateLimit-Limit`, and `X-RateLimit-Remaining`. Daily-call rejections also include `X-RateLimit-Reset`.
502	Upstream dial failed
503	`call_capacity_busy`: call capacity is temporarily busy; retry after the `Retry-After` interval (seconds). In `hosted_agent` mode, `hosted_agent_at_capacity` means Voice AI capacity is momentarily saturated, and `hosted_agent_unavailable` means the selected voice is currently unavailable.

For iMessage-line originations, actionable placement rejections use these structured 422 details:

`detail.error`	`detail.code`	`detail.message`
`destination_country_not_enabled`	`D13`	Dialed number is not enabled for this voice line. Contact Inkbox support to enable this destination country.
`invalid_destination_number`	`D11`	Dialed number is invalid.

Code examples

curl -X POST "https://inkbox.ai/api/v1/phone/place-call" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+14155550100",
    "to_number": "+12125550199",
    "client_websocket_url": "wss://your-agent.example.com/stream"
  }'

const response = await fetch(
  "https://inkbox.ai/api/v1/phone/place-call",
  {
      method: "POST",
      headers: {
          "X-API-Key": "YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      body: JSON.stringify({
          from_number: "+14155550100",
          to_number: "+12125550199",
          client_websocket_url: "wss://your-agent.example.com/stream",
      }),
  }
);
const call = await response.json();

import requests

response = requests.post(
"https://inkbox.ai/api/v1/phone/place-call",
headers={"X-API-Key": "YOUR_API_KEY"},
json={
"from_number": "+14155550100",
"to_number": "+12125550199",
"client_websocket_url": "wss://your-agent.example.com/stream",
},
)
call = response.json()

List calls

GET /calls

List calls for an agent identity, newest first — spans dedicated phone numbers plus shared and dedicated iMessage lines.

Query parameters

Parameter	Type	Default	Description
`agent_identity_id`	UUID	—	The agent identity whose calls to list. Required for admin API keys and Console sessions (omitting it returns `422`); identity-scoped keys resolve their own automatically and cannot name another (`403`)
`limit`	integer	50	Number of results to return (1–200)
`offset`	integer	0	Pagination offset
`is_blocked`	boolean	—	Filter by blocked state. `true` returns only blocked rows, `false` returns only non-blocked rows, and omitting it applies the caller’s default visibility
`start_datetime`	string	—	Only calls created on or after this date/time
`end_datetime`	string	—	Only calls created on or before this date/time; a bare date includes the whole day
`tz`	string	UTC	IANA zone for interpreting zone-less `start_datetime`/`end_datetime` values. Defaults to UTC

Identity-scoped API keys never see contact-rule-blocked calls, regardless of is_blocked. Admin API keys and human sessions see blocked and non-blocked calls by default; use is_blocked=true for an admin-side blocked listing. start_datetime, end_datetime, and tz filter on created_at. Both bounds are optional and non-breaking — omit them for unchanged behavior. See Filtering by date.

Response (200)

JSON

[
  {
    "id": "c1d2e3f4-a5b6-7890-cdef-012345678901",
    "origin": "dedicated_number",
    "local_phone_number": "+14155550100",
    "remote_phone_number": "+12125550199",
    "direction": "outbound",
    "status": "completed",
    "client_websocket_url": "wss://your-agent.example.com/stream",
    "mode": "client_websocket",
    "hosted_agent_authority_mode": "contact_scoped",
    "on_voicemail": "hang_up",
    "voicemail_detection": "enabled",
    "reason": null,
    "post_call_action_items": [],
    "connections": [],
    "forwardings": [],
    "use_inkbox_tts": true,
    "use_inkbox_stt": true,
    "hangup_reason": "remote",
    "started_at": "2026-03-10T12:00:05Z",
    "ended_at": "2026-03-10T12:03:42Z",
    "is_blocked": false,
    "created_at": "2026-03-10T12:00:00Z",
    "updated_at": "2026-03-10T12:03:42Z"
  },
  {
    "id": "d2e3f4a5-b6c7-8901-def0-123456789012",
    "origin": "shared_imessage_number",
    "local_phone_number": null,
    "remote_phone_number": "+12125550188",
    "direction": "outbound",
    "status": "completed",
    "client_websocket_url": "wss://your-agent.example.com/stream",
    "mode": "client_websocket",
    "hosted_agent_authority_mode": "contact_scoped",
    "on_voicemail": "hang_up",
    "voicemail_detection": "enabled",
    "reason": null,
    "post_call_action_items": [],
    "connections": [],
    "forwardings": [],
    "use_inkbox_tts": true,
    "use_inkbox_stt": true,
    "hangup_reason": "remote",
    "started_at": "2026-03-11T09:15:02Z",
    "ended_at": "2026-03-11T09:18:20Z",
    "is_blocked": false,
    "created_at": "2026-03-11T09:15:00Z",
    "updated_at": "2026-03-11T09:18:20Z"
  }
]

Code examples

curl -X GET "https://inkbox.ai/api/v1/phone/calls?agent_identity_id=AGENT_IDENTITY_ID&limit=50" \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch(
  `https://inkbox.ai/api/v1/phone/calls?agent_identity_id=${agentIdentityId}&limit=50`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const calls = await response.json();

import requests

response = requests.get(
"https://inkbox.ai/api/v1/phone/calls",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"agent_identity_id": AGENT_IDENTITY_ID, "limit": 50},
)
calls = response.json()

The number-scoped listing is deprecated. GET /numbers/{phone_number_id}/calls only returns calls on that dedicated phone number and omits iMessage-line calls. It accepts the same start_datetime/end_datetime/tz date filters for parity. Use GET /calls instead.

Get call

GET /calls/{call_id}

Get a single call by ID across all three call origins.

Path parameters

Parameter	Type	Description
`call_id`	UUID	Unique identifier of the call

Response (200)

Returns a call object.

Error responses

Status	Description
404	Call not found (for identity-scoped keys, cross-identity reads are masked as `404`)

Code examples

curl -X GET "https://inkbox.ai/api/v1/phone/calls/CALL_ID" \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch(
  `https://inkbox.ai/api/v1/phone/calls/${callId}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const call = await response.json();

import requests

response = requests.get(
f"https://inkbox.ai/api/v1/phone/calls/{call_id}",
headers={"X-API-Key": "YOUR_API_KEY"},
)
call = response.json()

The number-scoped route is deprecated. GET /numbers/{phone_number_id}/calls/{call_id} cannot address iMessage-line calls. Use GET /calls/{call_id}.

List Voice AI tool activity

GET /calls/{call_id}/tool-invocations

List a call’s built-in and remote MCP tool activity in execution order. Activity is recorded for both contact_scoped and yolo Voice AI calls. Calls without recorded activity, including older calls and calls driven by your own WebSocket, return an empty page. The response includes the tool name, execution status, timestamps, and a small result summary for built-in tools. source is builtin or external_mcp. MCP records also include connection_id, config_version, connection_label, and server_url. Full arguments and results are retained when supplied by the provider, but are not returned by this endpoint; arguments_available and result_available indicate whether an external payload was captured. Credentials are never returned.

Path parameters

Parameter	Type	Description
`call_id`	UUID	Unique identifier of the call

Query parameters

Parameter	Type	Default	Description
`limit`	integer	50	Number of results to return (1–200)
`offset`	integer	0	Pagination offset (0–10,000)

Response (200)

JSON

{
  "items": [
    {
      "id": "e3f4a5b6-c7d8-9012-ef01-234567890123",
      "call_id": "c1d2e3f4-a5b6-7890-cdef-012345678901",
      "tool_name": "send_email",
      "status": "succeeded",
      "result": {
        "status": "sent"
      },
      "started_at": "2026-07-29T12:00:05Z",
      "completed_at": "2026-07-29T12:00:06Z"
    }
  ],
  "limit": 50,
  "offset": 0,
  "has_more": false
}

status is "started", "succeeded", "failed", or "unknown". For MCP calls, unknown means the outcome could not be confirmed; check the external service before repeating an action. started_at can be null when only a completion was observed; observed_at records when Inkbox first observed it. Page-level incomplete: true indicates missing external observations, including when no individual tool record is available. On yolo calls, an accepted write can remain "started" after the call ends while Inkbox finishes it. Poll this endpoint until it reaches a terminal status when completion matters.

Error responses

Status	Description
404	Call not found (for identity-scoped keys, cross-identity reads are masked as `404`)
422	Invalid pagination value

Code example

curl -X GET "https://inkbox.ai/api/v1/phone/calls/CALL_ID/tool-invocations?limit=50&offset=0" \
  -H "X-API-Key: YOUR_API_KEY"

const page = await inkbox.calls.toolInvocations(callId, {
  limit: 50,
  offset: 0,
});

page = inkbox.calls.tool_invocations(
    call_id,
    limit=50,
    offset=0,
)

let page = inkbox
    .calls()
    .tool_invocations(call_id, 50, 0)?;

Hang up call

POST /calls/{call_id}/hangup

End a live call from outside it. The agent on the call can always end it in-band over the media WebSocket; this endpoint is the lever for everything else — tests, operator tooling, or any process that only holds the call ID. It works identically on Inkbox Voice AI calls, where it’s the operator kill switch. The carrier confirms the teardown asynchronously, so the returned call may still show its live status for a moment; the final status, ended_at, and transcript land through the normal call lifecycle (including the call.ended webhook).

Path parameters

Parameter	Type	Description
`call_id`	UUID	Unique identifier of the call

Response (200)

Returns the call object as of the hangup request, normally with hangup_reason set to "local". If the call ended on its own at the same moment — the carrier reports it already over before the hangup lands — the request still returns 200, but the call closes with hangup_reason "remote". Don’t branch on hangup_reason to confirm the hangup took effect.

Error responses

Status	Description
404	Call not found (for identity-scoped keys, cross-identity calls are masked as `404`)
409	`call_already_ended` — the call already finished; or `call_not_active` — the call has no active carrier leg yet

Code examples

curl -X POST "https://inkbox.ai/api/v1/phone/calls/CALL_ID/hangup" \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch(
  `https://inkbox.ai/api/v1/phone/calls/${callId}/hangup`,
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const call = await response.json();

import requests

response = requests.post(
f"https://inkbox.ai/api/v1/phone/calls/{call_id}/hangup",
headers={"X-API-Key": "YOUR_API_KEY"},
)
call = response.json()

Call object

Field	Type	Description
`id`	UUID	Unique call identifier
`origin`	string	`"dedicated_number"`, `"shared_imessage_number"`, or `"dedicated_imessage_number"`
`local_phone_number`	string \| null	Your number (E.164) for dedicated phone and dedicated iMessage calls. `null` for `shared_imessage_number` calls — the shared line is never surfaced.
`remote_phone_number`	string	The other party’s number (E.164)
`direction`	string	`"outbound"` or `"inbound"`
`status`	string	Call status (see below)
`client_websocket_url`	string \| null	WebSocket URL the call was streamed to
`mode`	string	Who drove the call: `"client_websocket"` or `"hosted_agent"`
`hosted_agent_authority_mode`	string	Authority snapshot for the call: `"contact_scoped"` or `"yolo"`. Always present
`on_voicemail`	string	What the call does when it reaches voicemail: `"leave_message"`, `"hang_up"`, or `"ignore"`. Always present; older calls derive it from `voicemail_detection`: `"hang_up"` for `"enabled"`, `"ignore"` for `"disabled"`
`voicemail_detection`	string	Deprecated view of `on_voicemail`: `"enabled"` for `"leave_message"` and `"hang_up"`, `"disabled"` for `"ignore"`. Always present; legacy calls default to `"enabled"`
`reason`	string \| null	The voice agent’s task brief on outbound `hosted_agent` calls; `null` otherwise
`post_call_action_items`	array	Open action items Inkbox Voice AI recorded, ordered by `seq` — each `{ id, seq, action, details, status }`, the same shape the `call.ended` webhook delivers. Always present; empty for `client_websocket` calls and Voice AI calls with none
`connections`	array	Ordered handoff and conference attempts. Empty when none were requested. See Connection history
`forwardings`	array	Automatic incoming-call forwarding only. Live transfers and conference guests appear in `connections`. See Forwarding history
`use_inkbox_tts`	boolean \| null	Whether Inkbox handles text-to-speech (`null` until negotiated via WebSocket)
`use_inkbox_stt`	boolean \| null	Whether Inkbox handles speech-to-text (`null` until negotiated via WebSocket)
`hangup_reason`	string \| null	Why the call ended: `"local"`, `"remote"`, `"max_duration"`, `"voicemail"`, `"rejected"`, `"failed"`, `"no_answer"`, `"missed"`, `"busy"`, or `"dropped"`
`started_at`	string \| null	When the call was answered (ISO 8601)
`ended_at`	string \| null	When the call ended (ISO 8601)
`is_blocked`	boolean	Whether the call was rejected by a contact rule or by default-block in whitelist mode. Identity-scoped API keys never receive rows where this is `true`
`created_at`	string	Creation timestamp (ISO 8601)
`updated_at`	string	Last updated timestamp (ISO 8601)

Call statuses

Status	Description
`initiated`	Call created, dialing in progress
`ringing`	Remote party is ringing
`answered`	Call connected and active
`completed`	Call ended normally
`canceled`	Call ended before being answered
`failed`	Call could not be connected

An outbound call rings for up to 60 seconds. If nobody answers in that window, Inkbox stops the dial and the call ends unanswered — a Voice AI call reports it as the no_answer outcome on call.ended. A call that reaches voicemail counts as answered: its hangup_reason is "voicemail" when on_voicemail ended it, whether after leaving a message or at the beep. A destination connection does not replace the original call’s status. For example, a call can be completed while a successful connection retains status: "connected" and has an ended_at timestamp.

Connection history

Each item in connections records one attempt to connect another destination. Records are ordered from oldest to newest.

Field	Type	Description
`id`	UUID	Unique connection-attempt identifier
`kind`	string	`"handoff"` routes the caller to another destination without keeping the agent; `"conference"` adds a guest while the agent stays
`trigger`	string	`"incoming_action"` for automatic inbound forwarding or `"agent_tool"` for a transfer or conference requested during a Voice AI call
`status`	string	`"requested"`, `"dialing"`, `"connected"`, or `"failed"`
`target_type`	string	`"phone"` or `"sip"`
`target`	string	The E.164 phone number or complete SIP URI used for this attempt
`requested_at`	string	When the connection was requested (ISO 8601)
`dialing_at`	string \| null	When dialing the destination began
`connected_at`	string \| null	When the destination was connected to the conversation
`ended_at`	string \| null	When the destination connection ended
`failure_code`	string \| null	Optional outcome or termination reason; may also be present after a successful connection

The listed kind, trigger, and status values can grow. Preserve unfamiliar strings and display an unknown value neutrally rather than assuming a handoff or a successful connection. "requested" and "dialing" do not mean the destination is connected. For a conference, answering the destination phone is not enough: the guest must join the conversation. A successful connection remains "connected" after it ends; ended_at records that later event. A failed attempt does not necessarily end the original call. A later termination reason can set failure_code without changing a successfully connected attempt to "failed". Read it alongside status and ended_at, and treat unfamiliar reason strings as opaque values; the set of reasons is not exhaustive. Automatic forwarding is kind: "handoff" with trigger: "incoming_action". A live transfer is kind: "handoff" with trigger: "agent_tool". A group call is kind: "conference" with trigger: "agent_tool". Transfers and conferences are actions the Voice AI agent takes during a conversation. This history is read-only; it does not add SDK or CLI transfer or conference commands.

Forwarding history

forwardings contains only automatic incoming-call forwarding attempts with trigger: "incoming_action". Live transfers and conference guests appear only in connections, so existing clients can continue reading calls and typed webhooks without accepting new forwarding trigger values. For an automatic forwarding attempt, both lists use the same id, destination, and request, dialing, ending, and failure fields, with this legacy field mapping:

Connection fields	Compatibility fields
`kind: "handoff"`, `trigger: "incoming_action"`	`trigger: "incoming_action"`
`status: "connected"`	`status: "forwarded"`
`connected_at`	`forwarded_at`

Use status, not the presence of failure_code, to determine whether forwarding succeeded. A "forwarded" record can also carry a later termination reason. Other status values are unchanged. Read connections when the field is present, even if it is empty. Fall back to forwardings only for older responses that omit connections; do not combine the two lists or count each attempt twice.

​Place call

​Request body

​Request example

​Response (200)

​Error responses

​Code examples

​List calls

​Query parameters

​Response (200)

​Code examples

​Get call

​Path parameters

​Response (200)

​Error responses

​Code examples

​List Voice AI tool activity

​Path parameters

​Query parameters

​Response (200)

​Error responses

​Code example

​Hang up call

​Path parameters

​Response (200)

​Error responses

​Code examples

​Call object

​Call statuses

​Connection history

​Forwarding history

Place call

Request body

Request example

Response (200)

Error responses

Code examples

List calls

Query parameters

Response (200)

Code examples

Get call

Path parameters

Response (200)

Error responses

Code examples

List Voice AI tool activity

Path parameters

Query parameters

Response (200)

Error responses

Code example

Hang up call

Path parameters

Response (200)

Error responses

Code examples

Call object

Call statuses

Connection history

Forwarding history