Jump to

Calls

Place outbound calls with bidirectional audio streaming, and retrieve call records for your phone numbers.

When you place a call, Inkbox dials via Telnyx 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.

Place call POST

POST /place-call

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

Request body

Field	Type	Required	Description
`from_number`	string	Yes	Caller ID in E.164 format — must be an active number in your organization
`to_number`	string	Yes	Destination number in E.164 format
`client_websocket_url`	string	No	WebSocket URL (`wss://`) your agent listens on. Can carry text or audio, depending on how the connection is configured. Falls back to the phone number's configured `client_websocket_url` if omitted
`webhook_url`	string	No	URL to receive call status events. Defaults to the Inkbox telephony event handler

Request example

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).

Error responses

Status	Description
400	`from_number` is not active
403	`from_number` does not belong to your organization
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	Telnyx dial failed

Code examples

List calls GET

GET /numbers/{phone_number_id}/calls

List calls for a phone number, newest first.

Path parameters

Parameter	Type	Description
`phone_number_id`	UUID	Unique identifier of the phone number

Query parameters

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

Response (200)

JSON

Code examples

Get call GET

GET /numbers/{phone_number_id}/calls/{call_id}

Get a single call by ID.

Path parameters

Parameter	Type	Description
`phone_number_id`	UUID	Unique identifier of the phone number
`call_id`	UUID	Unique identifier of the call

Response (200)

Returns a call object.

Error responses

Status	Description
403	Call does not belong to your organization
404	Call not found

Code examples

Call object

Field	Type	Description
`id`	UUID	Unique call identifier
`local_phone_number`	string	Your phone number (E.164)
`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
`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"`, or `"rejected"`
`started_at`	string \| null	When the call was answered (ISO 8601)
`ended_at`	string \| null	When the call ended (ISO 8601)
`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