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

> Send WhatsApp messages, quoted replies, and reactions on an approved dedicated number

WhatsApp is available by approval for an agent that already has a dedicated personal iMessage number. The approved WhatsApp channel uses that same number. Shared WhatsApp numbers are not supported.

Open the [Inkbox Console](https://inkbox.ai/console), select your agent, and open **Phone → WhatsApp**. If the agent does not have access, choose **Request Access**. A dedicated iMessage number establishes eligibility; it does not automatically enable WhatsApp. Creating an identity, editing its fields, or subscribing to events does not enable the channel.

## Check current availability

Read fresh channel status before sending. `enabled` describes approved access, while `status` describes current availability. An enabled channel can be temporarily unavailable. Do not treat an old identity snapshot as the final answer after access changes.

```python Python theme={null}
identity = inkbox.get_identity("my-agent")
status = identity.get_whatsapp_status()
if status is not None and status.enabled and status.status == "ready":
    message = identity.send_whatsapp(
        to="+15555550123",
        text="I received your project brief.",
        idempotency_key="project-brief-acknowledgment",
    )
    print(message.id, message.status)
```

```typescript TypeScript theme={null}
const identity = await inkbox.getIdentity("my-agent");
const status = await identity.getWhatsAppStatus();
if (status?.enabled && status.status === "ready") {
  const message = await identity.sendWhatsApp({
    to: "+15555550123",
    text: "I received your project brief.",
    idempotencyKey: "project-brief-acknowledgment",
  });
  console.log(message.id, message.status);
}
```

```bash CLI theme={null}
inkbox whatsapp status --identity my-agent
inkbox whatsapp send --identity my-agent \
  --to +15555550123 --text "I received your project brief." \
  --idempotency-key project-brief-acknowledgment
```

Basic direct-message SDK and CLI helpers require version `0.7.26` or later. Group metadata, Companion, and message-link/QR onboarding helpers require version `0.7.29` or later. SDK status helpers return `None` in Python or `null` in TypeScript when an older API does not expose WhatsApp status.

## Invite someone to message your agent

Share a [WhatsApp message link or QR code](https://inkbox.ai/docs/api/whatsapp/onboarding.md) for your agent's enabled number. It opens WhatsApp with `Hello!` prefilled; the person must tap **Send**. No `connect` message is needed. Opening the link does not send a message or enable access.

## Messages and attachments

Send `to` as one E.164 string for a direct message, or use an existing direct-message or group `conversation_id`. All arrays, including singleton arrays, and comma-separated lists are rejected for `to`. There is no fanout. Each message can contain text, one attachment, or both, within the current [WhatsApp limits](https://inkbox.ai/docs/api/whatsapp/limits.md). The initial attachment fallback is 5 MiB. Transport ceilings are 4,000 Unicode code points and 20 MiB; opening-message and organization policies can be lower.

In a direct conversation, before that recipient's first WhatsApp reply, the initial policy allows three short text messages of at most 159 Unicode code points each. Do not include links, phone numbers, media, or email addresses in those opening messages. Read the current limits before sending; each content permission is independently configurable.

[Upload the attachment](https://inkbox.ai/docs/api/whatsapp/media.md) first, then send its returned media ID. Keep that ID and the logical-send key when a request times out. Do not re-upload or generate another key to retry the same intended message. Attachment URLs expire; retrieve a fresh authorized URL by media ID.

A queued message is accepted, not delivered. Read its current `status` separately from `delivery_state`. A confirmed sent message with unknown delivery is not a failed send. An uncertain send is not proof that nothing was sent. Check the original message rather than automatically sending another copy.

## Existing groups

Have another participant add the agent’s WhatsApp number to a group. Inkbox does not create groups or manage membership. Another participant must send a message that the agent receives before the agent can send text, attachments, quoted replies, or reactions there. Joining, a reaction, or the agent’s own message does not meet this requirement.

Groups appear in authorized conversation history with `is_group` and `group_name`. Use the stable `conversation_id` to reply; names are display labels and can change or be duplicated. Current contact permissions still apply. SDK and CLI group support requires `0.7.29` or later. See [existing group conversations](https://inkbox.ai/docs/api/whatsapp/groups.md).

## Receive events

Create an identity-owned [webhook subscription](https://inkbox.ai/docs/api/whatsapp/webhooks.md) for `whatsapp.received` and any delivery events you need. Verify webhook signatures and deduplicate retries by the event ID. Only a received-message event represents new incoming content; delivery events should update tracking without starting another reply.

You can select WhatsApp events before approval. Matching deliveries begin when the channel becomes available. Subscribing does not grant access or import earlier account history.

## History and local unread state

Browse [conversations and messages](https://inkbox.ai/docs/api/whatsapp/conversations.md) in the Console or API. Disabling access prevents new sends while retained history remains available to its original authorized owner. Replacing or detaching the qualifying dedicated iMessage number disables WhatsApp access; an old conversation does not transfer to a different agent.

[Marking a conversation read](https://inkbox.ai/docs/api/whatsapp/conversations.md#mark-local-history-read) updates Inkbox's local unread state through an exact message boundary. It does not send a remote read receipt.

Request WhatsApp explicitly in [contact correspondence](https://inkbox.ai/docs/api/contacts/memory.md#whatsapp-correspondence). Existing default channel selections do not include it.

## Supported scope

This version supports direct messages and replies in existing groups, including text, attachments, native quoted replies, and whole-message reactions. The Console can read attachments but does not upload files. Phone contact rules apply to the remote recipient for direct messages and to every participant for groups. Groups with unavailable participant numbers remain unusable until a later incoming message reports every participant’s number and those numbers pass the current directional contact rules; changing contact rules alone does not resolve missing numbers. Native quotes never silently fall back to an unquoted message.

Read [threads](https://inkbox.ai/docs/api/whatsapp/threads.md) for chronological quoted context. [Reactions](https://inkbox.ai/docs/api/whatsapp/reactions.md) return versioned receipts; a pending or uncertain receipt is not an applied reaction. The Console keeps these states distinct and lets you remove your own selected reaction version.

Typing indicators, remote read receipts, and WhatsApp calls are not supported. WhatsApp groups can use [Companion mode](https://inkbox.ai/docs/capabilities/companion-mode.md) with the identity’s existing enabled preference and an eligible sponsor. Automatic contact-memory extraction is not enabled by joining a group.

## Reference

* [WhatsApp API](https://inkbox.ai/docs/api/whatsapp.md)
* [Message link and QR code](https://inkbox.ai/docs/api/whatsapp/onboarding.md)
* [Messages and delivery state](https://inkbox.ai/docs/api/whatsapp/messages.md)
* [Media](https://inkbox.ai/docs/api/whatsapp/media.md)
* [Conversations](https://inkbox.ai/docs/api/whatsapp/conversations.md)
* [Webhooks](https://inkbox.ai/docs/api/whatsapp/webhooks.md)
* [Limits and usage](https://inkbox.ai/docs/api/whatsapp/limits.md)


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