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. 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`)
`voicemail_detection`	string	No	`"enabled"` (default) ends the call when voicemail is detected. `"disabled"` keeps the call connected so the caller can leave a message

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

Voicemail detection is enabled by default. Set voicemail_detection to "disabled" when your agent should stay connected and leave a message:

JSON

{
  "origination": "dedicated_number",
  "from_number": "+14155550100",
  "to_number": "+12125550199",
  "mode": "hosted_agent",
  "reason": "Confirm the appointment, and leave the details in a voicemail if needed.",
  "voicemail_detection": "disabled"
}

Voice AI inherits the identity’s saved authority when hosted_agent_authority_mode is omitted or null. 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",
  "voicemail_detection": "enabled",
  "reason": null,
  "post_call_action_items": [],
  "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). 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
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"`
429	Organization has exceeded 100 calls or 100 minutes in the last 24 hours. Response includes `Retry-After` (seconds), `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers
502	Upstream dial failed
503	`hosted_agent_at_capacity`: Voice AI capacity is momentarily saturated; retry shortly. `hosted_agent_unavailable`: the selected voice is currently unavailable for calls. Applies to `hosted_agent` mode.

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",
    "voicemail_detection": "enabled",
    "reason": null,
    "post_call_action_items": [],
    "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",
    "voicemail_detection": "enabled",
    "reason": null,
    "post_call_action_items": [],
    "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 Voice AI 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 is intentionally safe to display or log. It includes the tool name, execution status, timestamps, and a small result summary. Tool arguments and delivery-system details are not 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", or "failed". 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
`voicemail_detection`	string	Whether voicemail detection was `"enabled"` or `"disabled"` for this call. 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
`forwardings`	array	Ordered forwarding history for this call. Always present; empty when the call was not forwarded. 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"`, or `"failed"`
`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

Forwarding does not replace the call status. For example, a successfully forwarded call is answered while connected and completed after it ends; its forwarding record retains status: "forwarded".

Forwarding history

Each item in forwardings records one attempt to send the call to another phone or SIP destination. Records are ordered from oldest to newest.

Field	Type	Description
`id`	UUID	Unique forwarding-attempt identifier
`trigger`	string	`"incoming_action"` for automatic inbound forwarding
`status`	string	`"requested"`, `"dialing"`, `"forwarded"`, 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 forwarding was requested (ISO 8601)
`dialing_at`	string \| null	When dialing the destination began
`forwarded_at`	string \| null	When the destination connected
`ended_at`	string \| null	When the forwarded connection ended
`failure_code`	string \| null	Stable failure code when the attempt failed

"forwarded" is a successful, terminal forwarding outcome. The record remains "forwarded" after the conversation ends; ended_at captures that later event.

​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

​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

Forwarding history