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
cURL
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
cURL
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
cURL
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"
JSON
cURL