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

# Manage numbers and routers

> Assign already-owned WhatsApp numbers and manage your organization's dedicated router

These endpoints require an admin-scoped API key or an authenticated Inkbox Console session. Paths are relative to `https://inkbox.ai/api/v1/whatsapp`. They manage resources your organization already owns; they do not purchase or provision numbers, shared pools, or routers. Contact [support@inkbox.ai](mailto:support@inkbox.ai) to request those resources.

The SDK and CLI methods below require version `0.7.38` or later and an API supporting these management endpoints.

## List dedicated numbers

```text theme={null}
GET /numbers?offset=0
```

Returns `{ "numbers": [...], "has_more": false }`. Each page contains up to 100 numbers; add 100 to `offset` while `has_more` is true. Each number has:

| Field | Type | Description |
| :- | :- | :- |
| `id` | UUID | Number resource ID |
| `number` | string | E.164 phone number |
| `agent_identity_id` | UUID or null | Attached agent, if any |
| `revision` | integer | Current revision required when assigning or detaching |
| `state` | string | `enabled`, `disabled`, or `revoked` |
| `binding_state` | string or null | Current setup state, when available |
| `assignable` | boolean | Whether the number is ready for assignment |
| `unavailable_reason` | string or null | Explanation when assignment is unavailable |

## Assign or detach a number

```text theme={null}
PATCH /numbers/{account_id}
```

```json theme={null}
{
  "agent_identity_id": "11111111-1111-4111-8111-111111111111",
  "expected_revision": 2
}
```

Pass an agent in your organization to attach the number. Pass `agent_identity_id: null` to detach it. The response is the updated number object. Refresh the number before retrying a `409` conflict; the request must use its current revision.

If the number differs from the agent's iMessage number, explicitly confirm that difference before submitting `confirmed_imessage_number` with the current iMessage number. Do not populate confirmation automatically. Detaching a number can require setup assistance before it can be attached again. A successful assignment does not permit unsolicited messages.

## Read and edit your dedicated router

```text theme={null}
GET /router
PATCH /router
```

The read returns `{ "router": null }` when your organization has no enabled dedicated router. Otherwise, `router` contains `id`, `number`, `revision`, `state`, nullable `profile_display_name`, and `accepting_new_connections`. This endpoint does not allocate a global router; use [Get router number](https://inkbox.ai/docs/api/whatsapp/router.md#get-router-number) for recipient connection instructions.

To edit, submit the ID and revision you read:

```json theme={null}
{
  "expected_router_id": "22222222-2222-4222-8222-222222222222",
  "expected_revision": 2,
  "accepting_new_connections": false
}
```

Both values identify the router configuration you intend to change. A replacement router or stale revision returns `409`; refresh and review the new router before retrying. Omit `profile_display_name` to preserve it, or pass null to clear it. Omit `accepting_new_connections` to preserve admission. Disabling new connections does not disconnect existing recipients. The response uses the same `router` envelope as the read.

```python Python theme={null}
router = inkbox.whatsapp.get_router()
if router is not None:
    updated = inkbox.whatsapp.update_router(
        expected_router_id=router.id,
        expected_revision=router.revision,
        accepting_new_connections=False,
    )
```

```typescript TypeScript theme={null}
const router = await inkbox.whatsapp.getRouter();
if (router !== null) {
  const updated = await inkbox.whatsapp.updateRouter({
    expectedRouterId: router.id,
    expectedRevision: router.revision,
    acceptingNewConnections: false,
  });
}
```

```rust Rust theme={null}
if let Some(router) = inkbox.whatsapp().get_router()? {
    inkbox.whatsapp().update_router(&router.id, router.revision, None, Some(false))?;
}
```

```bash CLI theme={null}
inkbox whatsapp numbers --offset 0
inkbox whatsapp assign-number NUMBER_ID --identity my-agent --revision 2
inkbox whatsapp router
inkbox whatsapp update-router ROUTER_ID --revision 2 --accepting false
```

## Read dedicated-router conversations

```text theme={null}
GET /router/conversations?offset=0&limit=50
GET /router/conversations/{remote_number}/messages?offset=0&limit=50
```

Use an E.164 `remote_number`. Both endpoints return `{ "items": [...], "has_more": false }`, newest first. `limit` is 1–100, defaults to 50, and `offset` defaults to zero. Increase `offset` by `limit` to continue.

Thread items contain `remote_number`, `last_message_at`, `latest_text`, and `message_count`. Message items contain `id`, `direction` (`inbound` or `outbound`), `content`, `status`, and `created_at`. Router messages are separate from your agent's conversations.

| Operation | Python | TypeScript | Rust | CLI |
| :- | :- | :- | :- | :- |
| List owned numbers | `list_numbers(offset=0)` | `listNumbers({ offset: 0 })` | `list_numbers(0)` | `whatsapp numbers` |
| Assign/detach | `assign_number(account_id, agent_identity_id=identity_id, expected_revision=revision)` | `assignNumber(accountId, { agentIdentityId, expectedRevision })` | `assign_number(&account_id, Some(&identity_id), revision, None)` | `whatsapp assign-number NUMBER_ID --identity my-agent --revision 2` |
| List threads | `list_router_threads(limit=50, offset=0)` | `listRouterThreads({ limit: 50, offset: 0 })` | `list_router_threads(50, 0)` | `whatsapp router-threads` |
| Read messages | `list_router_messages("+15555550101")` | `listRouterMessages("+15555550101")` | `list_router_messages("+15555550101", 50, 0)` | `whatsapp router-messages +15555550101` |

Methods are on `inkbox.whatsapp` in Python/TypeScript and `inkbox.whatsapp()` in Rust. CLI examples use the `inkbox` executable. Pass null/None instead of the agent ID to detach; use `--detach` in the CLI.

## Errors

| Status | Meaning |
| :- | :- |
| 402 | Enabling the selected agent requires WhatsApp access or a higher identity allowance. |
| 403 | The credential cannot manage organization resources. |
| 404 | The number, agent, or dedicated router is unavailable to your organization. |
| 409 | The resource changed or requires setup. Refresh before retrying; contact support if setup is required. |
| 422 | A request field is invalid or required confirmation is missing. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.