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

# Assignments

> Connect a recipient to an agent through your organization's shared WhatsApp pool, list assignments, and disconnect

A connection links one recipient to one agent. Shared-number connections reserve a number from your organization's shared pool when created through the API. Dedicated-number connections are recorded when the recipient connects through the router or sends their first direct message. The connect API below is for shared numbers and returns the reserved number. Nothing is sent. Your agent can reply after the recipient messages that number.

> [!NOTE]
>
> Connecting through the API requires an organization shared pool, available by request. Contact [support@inkbox.ai](mailto:support@inkbox.ai). Without one, recipients can connect by texting the [router](https://inkbox.ai/docs/api/whatsapp/router.md).

Paths are relative to `https://inkbox.ai/api/v1/whatsapp`.

Unlike [iMessage connect](https://inkbox.ai/docs/api/imessage/connections.md#connect-a-recipient), WhatsApp connect has no `first_message` field. Shared WhatsApp numbers never start a conversation.

## Request headers and retries

Connect and disconnect accept an [admin API key](https://inkbox.ai/docs/api-keys.md) or an authenticated [Inkbox Console](https://inkbox.ai/console) session. Identity-scoped API keys cannot connect or disconnect recipients.

| Header | Required | Description |
| :- | :- | :- |
| `X-API-Key` | Yes | Your organization's admin API key |
| `Content-Type` | Yes | `application/json` |
| `Idempotency-Key` | Yes | A client-generated key for this logical action, sent on the first attempt and every retry |

Reuse the same key and body when retrying the same action, including after a timeout. A completed request replays its original status and response. Use a new key for each new connect or disconnect action.

## Connect a recipient

```text theme={null}
POST /connect
```

The identity must belong to your organization and must not have its own dedicated WhatsApp number. Its [phone contact rules](https://inkbox.ai/docs/api/phone/contact-rules.md) must allow this recipient. Each pool number serves at most one agent per recipient.

| Field | Type | Required | Description |
| :- | :- | :- | :- |
| `agent_identity_id` | UUID | Yes | The agent to connect |
| `recipient_number` | string | Yes | The recipient's E.164 phone number |

Unsupported request fields are rejected.

```python Python theme={null}
from uuid import uuid4

result = inkbox.whatsapp.connect(
    agent_identity_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    recipient_number="+15555550123",
    idempotency_key=str(uuid4()),
)
print(result.assigned_number, result.awaiting_inbound)
```

```typescript TypeScript theme={null}
const result = await inkbox.whatsapp.connect({
  agentIdentityId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  recipientNumber: "+15555550123",
  idempotencyKey: crypto.randomUUID(),
});
console.log(result.assignedNumber, result.awaitingInbound);
```

```bash CLI theme={null}
inkbox whatsapp connect -i my-agent --recipient +15555550123 \
  --idempotency-key 5f0c2a8e-6d1b-4c3e-9a7f-2b8d4e6f1a90
```

```bash cURL theme={null}
curl -X POST "https://inkbox.ai/api/v1/whatsapp/connect" \
  -H "X-API-Key: YOUR_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f0c2a8e-6d1b-4c3e-9a7f-2b8d4e6f1a90" \
  -d '{
    "agent_identity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "recipient_number": "+15555550123"
  }'
```

### Response

* **201:** A new connection was created.
* **200:** The agent and recipient are already connected. `already_connected` is `true`.

```json JSON theme={null}
{
  "assignment": {
    "id": "9b2e4a68-8cb1-4f18-b97d-a2324c8b4d1f",
    "agent_identity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "remote_number": "+15555550123",
    "organization_id": "org_example",
    "status": "active",
    "released_at": null,
    "created_at": "2026-11-14T12:00:00Z",
    "updated_at": "2026-11-14T12:00:00Z"
  },
  "conversation_id": "20000000-0000-4000-8000-000000000002",
  "assigned_number": "+15555550100",
  "already_connected": false,
  "awaiting_inbound": true
}
```

| Field | Type | Description |
| :- | :- | :- |
| `assignment` | object | The [assignment object](#assignment-object) |
| `conversation_id` | UUID | The connected conversation |
| `assigned_number` | string or null | The organization-owned number the recipient should message; null for global shared numbers |
| `already_connected` | boolean | Whether the request reused an existing connection |
| `awaiting_inbound` | boolean | `true` until the recipient messages this number; replies are rejected until then |

Share `assigned_number`, when present, with this recipient only, for example as a `https://wa.me/` link. Routing depends on the sender's number, so other people who message it may reach a different agent or none.

### Errors

| Status | `detail.error` | Meaning |
| :- | :- | :- |
| 400 | | WhatsApp is disabled for the agent. `detail` is `"Agent identity is not enabled for WhatsApp"`. Enable WhatsApp before connecting. |
| 403 | `recipient_blocked` | The agent's contact rules do not allow this recipient. |
| 404 | | The identity is not found in your organization. |
| 409 | `whatsapp_identity_has_dedicated_line` | The agent has its own dedicated number. Share that number instead. |
| 409 | `whatsapp_recipient_connections_full` | This recipient already uses every available number in your organization’s pool. Disconnect an existing assignment before connecting another agent. |
| 409 | `whatsapp_pool_unavailable` | No number in your organization's shared pool is available for this recipient. |
| 409 | `whatsapp_connection_busy` | Another connection change for this recipient is in progress. Honor `Retry-After` and retry with the same key. |
| 422 | | A required field is missing or invalid. |

Connect and disconnect also return these retry errors:

| Status | `detail.error` | What to do |
| :- | :- | :- |
| 409 | `idempotency_key_reused` | Restore the original request body, or use a new key for a new action. |
| 409 | `idempotency_in_progress` | The original request is still running. Honor `Retry-After` and retry with the same key and body. |
| 409 | `result_unavailable` | The original result can no longer be replayed. Check current connections before starting a new action. |
| 422 | `invalid_idempotency_key` | Send a non-empty key of at most 255 printable ASCII characters. |

## Disconnect a recipient

```text theme={null}
POST /disconnect
```

The request body has the same `agent_identity_id` and `recipient_number` fields. Disconnecting ends the current shared or dedicated connection. Conversation history is kept, and the recipient is not notified. A recipient can reconnect through the router. For a dedicated number, a new direct message from that recipient also reconnects them.

```json JSON theme={null}
{
  "assignment_id": "9b2e4a68-8cb1-4f18-b97d-a2324c8b4d1f",
  "disconnected": true
}
```

`assignment_id` is `null` when there was no connection; that is a successful no-op.

```python Python theme={null}
inkbox.whatsapp.disconnect(
    agent_identity_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    recipient_number="+15555550123",
    idempotency_key=str(uuid4()),
)
```

```typescript TypeScript theme={null}
await inkbox.whatsapp.disconnect({
  agentIdentityId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  recipientNumber: "+15555550123",
  idempotencyKey: crypto.randomUUID(),
});
```

```bash CLI theme={null}
inkbox whatsapp disconnect -i my-agent --recipient +15555550123 \
  --idempotency-key 0c6f1e2a-3b4d-4e5f-8a9b-1c2d3e4f5a6b
```

## List assignments

```text theme={null}
GET /assignments?agent_identity_id={agent_identity_id}
```

Returns the agent's current shared- and dedicated-number connections, newest first. Any API key or Console session for the organization can read them; an identity-scoped key reads only its own identity.

```python Python theme={null}
for connection in inkbox.whatsapp.list_assignments(agent_identity_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890"):
    print(connection.remote_number, connection.status)
```

```typescript TypeScript theme={null}
const connections = await inkbox.whatsapp.listAssignments({
  agentIdentityId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
});
```

```bash CLI theme={null}
inkbox whatsapp assignments -i my-agent
```

The response is a JSON array of assignments, not an object containing `items`.
Use `limit` (default 50, maximum 200) and `offset` (default 0) for pagination.

### Assignment object

| Field | Type | Description |
| :- | :- | :- |
| `id` | UUID | Assignment ID |
| `agent_identity_id` | UUID | The connected agent |
| `organization_id` | string | The owning organization |
| `remote_number` | string | The recipient's E.164 number |
| `status` | string | `active` or `released` |
| `released_at` | string or null | When the assignment was released |
| `created_at` | string | When the assignment was created |
| `updated_at` | string | When the assignment last changed |

Assignments do not expose the shared WhatsApp number. Global shared numbers are
also absent from message and conversation `local_number` fields.

## Release an assignment

```text theme={null}
DELETE /assignments/{assignment_id}
```

Requires an admin API key. Returns `204` with no body. Conversation history stays
with the agent, and the recipient is not notified.

```python Python theme={null}
inkbox.whatsapp.delete_assignment("9b2e4a68-8cb1-4f18-b97d-a2324c8b4d1f")
```

```typescript TypeScript theme={null}
await inkbox.whatsapp.deleteAssignment("9b2e4a68-8cb1-4f18-b97d-a2324c8b4d1f");
```

```bash CLI theme={null}
inkbox whatsapp delete-assignment 9b2e4a68-8cb1-4f18-b97d-a2324c8b4d1f
```

## Reply through a shared number

Send with [`POST /messages`](https://inkbox.ai/docs/api/whatsapp/messages#send-a-message) as usual. For an agent without a dedicated number, the recipient in `to`, or the conversation's participant, selects the connection. Before the recipient's first message on that number, sends return `409`:

```json JSON theme={null}
{
  "detail": {
    "error": "whatsapp_awaiting_inbound",
    "message": "This recipient has not messaged this WhatsApp number yet. You can reply once they send a message.",
    "retry_condition": "recipient_message"
  }
}
```

Nothing is admitted. Wait for a [`whatsapp.received`](https://inkbox.ai/docs/api/whatsapp/webhooks) event from that recipient before retrying. To attach a file, pass `recipient_number` when you [upload the media](https://inkbox.ai/docs/api/whatsapp/media.md#upload-an-attachment).

| Status | `detail.error` | Meaning |
| :- | :- | :- |
| 403 | `whatsapp_access_required` | The agent has no dedicated number and is not connected to this recipient. [Connect the recipient](#connect-a-recipient) first. Sends and media uploads both return this. |
| 409 | `whatsapp_awaiting_inbound` | The recipient has not messaged this number yet. |
| 409 | `whatsapp_connection_released` | The dedicated connection was disconnected. Wait for the recipient to reconnect through the router or send a new direct message before retrying. |

Connection methods are available in the SDKs and CLI from version `0.7.38`.


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