Inkbox

> # Documentation index
> Fetch the complete documentation index at: https://inkbox.ai/sitemap.xml
> Use this file to discover all available pages before exploring further.

---

# Incoming calls
description: Configure how inbound calls are handled for an agent identity — across dedicated numbers and shared iMessage lines

---


# 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"`, 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
{
    "agent_identity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "incoming_call_action": "webhook",
    "client_websocket_url": "wss://your-agent.example.com/stream",
    "incoming_call_webhook_url": "https://your-agent.example.com/incoming-call"
}
```

### Response (200)

```json
{
    "agent_identity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "incoming_call_action": "webhook",
    "client_websocket_url": "wss://your-agent.example.com/stream",
    "incoming_call_webhook_url": "https://your-agent.example.com/incoming-call"
}
```

### 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**

```bash
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": "webhook",
      "client_websocket_url": "wss://your-agent.example.com/stream",
      "incoming_call_webhook_url": "https://your-agent.example.com/incoming-call"
    }'
```

**JavaScript**

```javascript
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: "webhook",
            client_websocket_url: "wss://your-agent.example.com/stream",
            incoming_call_webhook_url: "https://your-agent.example.com/incoming-call",
        }),
    }
);
const config = await response.json();
```

**Python**

```python
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": "webhook",
        "client_websocket_url": "wss://your-agent.example.com/stream",
        "incoming_call_webhook_url": "https://your-agent.example.com/incoming-call",
    },
)
config = response.json()
```

---

## Get 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)

```json
{
    "agent_identity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "incoming_call_action": "webhook",
    "client_websocket_url": "wss://your-agent.example.com/stream",
    "incoming_call_webhook_url": "https://your-agent.example.com/incoming-call"
}
```

### 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**

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

**JavaScript**

```javascript
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();
```

**Python**

```python
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"`, 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](/docs/api/phone/calls) — place outbound calls and retrieve call records
- [Webhooks](/docs/api/phone/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](/docs/api/phone/media-stream) — how audio and text flow over the WebSocket once a call is answered