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
PUT /incoming-call-actionUpsert the inbound-call configuration for an agent identity.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
incoming_call_action | string | Yes | "auto_accept", "auto_reject", "webhook", or "hosted_agent" |
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) |
"hosted_agent" — answer with Inkbox Voice AI — is the only answering action with zero prerequisites: it requires neither URL. URL fields sent alongside it are stored but ignored while the action is "hosted_agent". Note this endpoint replaces the whole config on every call: an omitted URL field is cleared, so include the URLs you want to keep, and re-supply the relevant one when switching back to "auto_accept" or "webhook".
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" |
Code examples
cURLGet incoming call action GET
GET /incoming-call-actionRead 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", or "hosted_agent" |
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" |
- Inkbox Voice AI — what answers the call when the action is
"hosted_agent" - 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
