Incoming calls
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
Upsert the inbound-call configuration for an agent identity.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
incoming_call_action | string | Yes | "auto_accept", "auto_reject", "webhook", "hosted_agent", or "forward" |
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) |
forwarding_target_type | string | null | Conditional | "phone" or "sip". Required when incoming_call_action is "forward" |
forwarding_phone_number | string | null | Conditional | Destination in E.164 format. Required for a "phone" forwarding target |
forwarding_sip_uri | string | null | Conditional | Complete sip:user@public-dns-host[:port] URI. Required for a "sip" forwarding target |
"hosted_agent" — answer with Inkbox Voice AI — requires neither URL. URL fields sent alongside it are stored but ignored while the action is "hosted_agent".
"forward" sends the call to one phone number or SIP URI without opening an Inkbox media WebSocket. Connected forwarded calls use inbound and outbound call minutes simultaneously. SIP targets must use the exact sip:user@public-dns-host[:port] form; sips:, IP or private/single-label hosts, credentials, parameters, and URI headers are not accepted. Inkbox does not substitute the number that was called. SIP username/password authentication and custom SIP headers are not supported. Secure signaling and media settings are managed by Inkbox.
Omitted forwarding fields preserve their saved values. To clear a saved target, set forwarding_target_type to null; this clears both forwarding destinations. Sending only the active destination field as null while preserving its target type returns 422. Because the forward action requires a destination, switch incoming_call_action away from forward in the same request when clearing its target. Existing WebSocket and webhook URL fields retain their replacement behavior, so include the URLs you want to keep when changing those actions.
Request example
JSONResponse (200)
JSONError 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" |
| 422 | A valid phone number or complete SIP URI is required when incoming_call_action is "forward" |
Code examples
cURLGet incoming call action GET
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)
JSONError 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
cURLIncoming 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", "webhook", "hosted_agent", or "forward" |
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" |
forwarding_target_type | string | null | "phone", "sip", or null when no forwarding target is saved |
forwarding_phone_number | string | null | Saved E.164 forwarding destination |
forwarding_sip_uri | string | null | Saved complete SIP forwarding destination |
- Inkbox Voice AI — what answers the call when the action is
"hosted_agent" - Calls — place outbound calls and inspect where inbound calls were forwarded
- 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