Calls

Place outbound calls with bidirectional audio streaming, and retrieve call records. Calls are scoped to your agent identity and span both origins — the dedicated phone numbers your organization owns (past and present) and your agent identity's shared iMessage line.

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.

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

Request example

JSON

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

JSON

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

JSON

Response (200)

JSON

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 the response has "origin": "shared_imessage_number" and local_phone_number is null — the shared line is internal routing detail and is never surfaced.

Error responses

Code examples

cURL

cURL

JavaScript

Python

GET /calls

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

Query parameters

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

Code examples

cURL

cURL

JavaScript

Python

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

GET /calls/{call_id}

Get a single call by ID. Addresses calls of either origin — dedicated numbers or shared iMessage lines.

Path parameters

Response (200)

Returns a call object.

Error responses

Code examples

cURL

cURL

JavaScript

Python

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

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

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

Code examples

cURL

cURL

JavaScript

Python

Call statuses