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

# WhatsApp API

> Identity-scoped WhatsApp messages, existing groups, quoted replies, and reactions

Use the WhatsApp API for an agent with approved access on its dedicated personal iMessage number. The WhatsApp number is the same E.164 number. There is no shared-number mode or public provisioning endpoint.

All endpoints use the production base URL `https://inkbox.ai/api/v1/whatsapp` and your normal API key. Use the `agent_identity_id` query parameter to select the agent for an organization-wide credential. An identity-scoped credential remains restricted to its own identity; an explicit different identity does not switch its authority.

## Resources

| Resource | Purpose |
| :- | :- |
| [Onboarding](https://inkbox.ai/docs/api/whatsapp/onboarding.md) | Get a shareable message link and QR code |
| [Messages](https://inkbox.ai/docs/api/whatsapp/messages.md) | Send text or one owned attachment; read message status and history |
| [Media](https://inkbox.ai/docs/api/whatsapp/media.md) | Upload a file and retrieve current authorized attachment access |
| [Conversations](https://inkbox.ai/docs/api/whatsapp/conversations.md) | Browse direct and existing group conversations and update local unread state |
| [Existing groups](https://inkbox.ai/docs/api/whatsapp/groups.md) | Reply after receiving a participant’s message; no group creation |
| [Threads](https://inkbox.ai/docs/api/whatsapp/threads.md) | Read authorized chronological quote chains |
| [Reactions](https://inkbox.ai/docs/api/whatsapp/reactions.md) | Submit and remove whole-message reactions with versioned receipts |
| [Webhooks](https://inkbox.ai/docs/api/whatsapp/webhooks.md) | Receive incoming messages and outbound delivery updates |
| [Limits and usage](https://inkbox.ai/docs/api/whatsapp/limits.md) | Read current independent WhatsApp safeguards and usage |

## Read channel status

```text theme={null}
GET /api/v1/identities/{agent_handle}/channel-status
```

The response includes a `whatsapp` object:

```json theme={null}
{
  "enabled": true,
  "number": "+15555550100",
  "status": "ready"
}
```

| Field | Type | Description |
| :- | :- | :- |
| `enabled` | boolean | Whether the agent currently has approved access and remains eligible |
| `number` | string or null | The dedicated E.164 number when available |
| `status` | string | `not_eligible`, `access_required`, `disabled`, `unavailable`, or `ready` |

Send only when access is enabled and status is `ready`. Availability can change after a status read; the send endpoint checks it again. A ready channel can still reject a quoted reply, reaction, group send, or `gif_playback` send with `409 whatsapp_capability_not_ready` when that operation is unavailable. That rejection admits nothing; ordinary direct messages can remain available. Do not replace a rejected quote with an unquoted send. Reading status never enables access. Identity responses also expose read-only `whatsapp_enabled`, `whatsapp_configured`, and nullable `whatsapp_number`; these are not fields you can set when creating or updating an identity. `whatsapp_configured` remains true after access is disabled so past conversations stay discoverable; it does not grant sending access.

## Common conventions

* Requests use `text`; stored messages and webhooks use `content`.
* Send returns `201` with `{ "message": ... }`. Message, conversation, and media single reads return flat objects. Reaction POST, GET, and DELETE return `{ "reaction": ... }`.
* Message and conversation lists return bare arrays with `offset` and `limit`. Thread reads use an opaque cursor envelope.
* Message and conversation participants contain remote numbers only. The local number is a separate field.
* Use owned `media_ids`, not arbitrary URLs, filesystem paths, or identifiers from another channel.
* Preserve the same [idempotency key](https://inkbox.ai/docs/api/message-sends.md) for retries of one intended send.

See [WhatsApp availability and supported scope](https://inkbox.ai/docs/capabilities/whatsapp.md) before integrating.


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