Configure how inbound calls are handled for an agent identity. This config is keyed on the agent identity, so it governs inbound handling for both dedicated numbers and shared iMessage lines that route to that identity.
Requires an admin API key, an identity-scoped API key, or you can manage this from the Inkbox Console.
Set incoming call action PUT
PUT /incoming-call-action
Upsert the inbound-call configuration for an agent identity.
Request body
Field
Type
Required
Description
incoming_call_action
string
Yes
"auto_accept", "auto_reject", or "webhook"
agent_identity_id
UUID | null
Conditional
The agent identity to configure. Required with an admin API key or the Console (omitting returns 422); identity-scoped keys use their own and cannot name another (403)
client_websocket_url
string | null
Conditional
WebSocket URL (wss://) used when the call is answered. Required when incoming_call_action is "auto_accept" (omitting returns 422)
incoming_call_webhook_url
string | null
Conditional
HTTPS endpoint that receives the incoming-call webhook. Required when incoming_call_action is "webhook" (omitting returns 422)
Request example
JSON
Response (200)
JSON
Error responses
Status
Description
404
Agent identity not found
422
agent_identity_id is required
422
client_websocket_url is required when incoming_call_action is "auto_accept"
422
incoming_call_webhook_url is required when incoming_call_action is "webhook"
Code examples
cURL
Get incoming call action GET
GET /incoming-call-action
Read the inbound-call configuration for an agent identity.
Query parameters
Parameter
Type
Required
Description
agent_identity_id
UUID
Conditional
The agent identity to read. Required with an admin API key or the Console (omitting returns 422); identity-scoped keys use their own and cannot name another (403)
Response (200)
JSON
Error responses
Status
Description
404
Agent identity not found
404
No inbound-call config set for this identity
422
agent_identity_id is required
Code examples
cURL
Incoming call action object
Field
Type
Description
agent_identity_id
UUID
The agent identity this configuration applies to
incoming_call_action
string
"auto_accept", "auto_reject", or "webhook"
client_websocket_url
string | null
WebSocket URL used when the call is answered
incoming_call_webhook_url
string | null
HTTPS endpoint that receives the incoming-call webhook when the action is "webhook"
Related
Calls — place outbound calls and retrieve call records
Webhooks — when the action is "webhook", the webhook responds with {action, client_websocket_url} to accept or reject the call (see the phone Webhooks page)
Media Stream — how audio and text flow over the WebSocket once a call is answered
JSON
cURL