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 /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"`, `"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

JSON

{
  "agent_identity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "incoming_call_action": "forward",
  "forwarding_target_type": "sip",
  "forwarding_phone_number": null,
  "forwarding_sip_uri": "sip:+14155550100@voice.example.com"
}

Response (200)

JSON

{
  "agent_identity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "incoming_call_action": "forward",
  "client_websocket_url": null,
  "incoming_call_webhook_url": null,
  "forwarding_target_type": "sip",
  "forwarding_phone_number": null,
  "forwarding_sip_uri": "sip:+14155550100@voice.example.com"
}

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"`
422	A valid phone number or complete SIP URI is required when `incoming_call_action` is `"forward"`

Code examples

curl -X PUT "https://inkbox.ai/api/v1/phone/incoming-call-action" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_identity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "incoming_call_action": "forward",
    "forwarding_target_type": "sip",
    "forwarding_sip_uri": "sip:+14155550100@voice.example.com"
  }'

const response = await fetch(
  "https://inkbox.ai/api/v1/phone/incoming-call-action",
  {
      method: "PUT",
      headers: {
          "X-API-Key": "YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      body: JSON.stringify({
          agent_identity_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          incoming_call_action: "forward",
          forwarding_target_type: "sip",
          forwarding_sip_uri: "sip:+14155550100@voice.example.com",
      }),
  }
);
const config = await response.json();

import requests

response = requests.put(
    "https://inkbox.ai/api/v1/phone/incoming-call-action",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "agent_identity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "incoming_call_action": "forward",
        "forwarding_target_type": "sip",
        "forwarding_sip_uri": "sip:+14155550100@voice.example.com",
    },
)
config = response.json()

Get incoming call action

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

{
  "agent_identity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "incoming_call_action": "forward",
  "client_websocket_url": null,
  "incoming_call_webhook_url": null,
  "forwarding_target_type": "sip",
  "forwarding_phone_number": null,
  "forwarding_sip_uri": "sip:+14155550100@voice.example.com"
}

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 -X GET "https://inkbox.ai/api/v1/phone/incoming-call-action?agent_identity_id=AGENT_IDENTITY_ID" \
  -H "X-API-Key: YOUR_API_KEY"

const params = new URLSearchParams({ agent_identity_id: agentIdentityId });
const response = await fetch(
  `https://inkbox.ai/api/v1/phone/incoming-call-action?${params}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const config = await response.json();

import requests

response = requests.get(
    "https://inkbox.ai/api/v1/phone/incoming-call-action",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"agent_identity_id": agent_identity_id},
)
config = response.json()

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"`, `"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

Agent signup API

Agent identity API

Agent2Agent API

Message retries

Mail API

Phone API

iMessage API

Slack API

Webhooks API

Tunnels API

Contacts API

Notes API

Vault API

Billing API

Incoming calls

Set incoming call action

Request body

Request example

Response (200)

Error responses

Code examples

Get incoming call action

Query parameters

Response (200)

Error responses

Code examples

Incoming call action object

​Set incoming call action

​Request body

​Request example

​Response (200)

​Error responses

​Code examples

​Get incoming call action

​Query parameters

​Response (200)

​Error responses

​Code examples

​Incoming call action object

​Related

Set incoming call action

Request body

Request example

Response (200)

Error responses

Code examples

Get incoming call action

Query parameters

Response (200)

Error responses

Code examples

Incoming call action object

Related