vercel__chat/apps/docs/content/adapters/official/whatsapp.mdx

---
title: WhatsApp Business Cloud
description: WhatsApp Business Cloud adapter for Chat SDK.
packageName: "@chat-adapter/whatsapp"
slug: whatsapp
type: platform
logo: whatsapp
tagline: Connect to WhatsApp Business Cloud for customer messaging and automated conversations.
beta: true
features:
  postMessage: yes
  messageReplies:
    status: partial
    label: Outbound only
  editMessage: no
  deleteMessage: no
  fileUploads:
    status: yes
    label: Images, audio, docs
  streaming:
    status: partial
    label: Buffered
  scheduledMessages: no
  cardFormat:
    status: partial
    label: Interactive messages
  buttons:
    status: yes
    label: Interactive replies
  linkButtons:
    status: partial
    label: Single CTA URL
  selectMenus: no
  tables: no
  fields:
    status: partial
    label: Formatted text
  imagesInCards: yes
  modals: no
  slashCommands: no
  mentions: no
  addReactions: yes
  removeReactions: yes
  typingIndicator: yes
  markAsRead: yes
  messageUpdatedEvents: no
  messageDeletedEvents: no
  directMessages: yes
  ephemeralMessages: no
  customApiEndpoint: yes
  fetchMessages:
    status: partial
    label: Cached sent only
  fetchSingleMessage: no
  fetchThreadInfo: yes
  fetchChannelMessages: no
  listThreads: no
  fetchChannelInfo: no
  postChannelMessage: yes
---

## Install

<PackageInstall package="@chat-adapter/whatsapp" />

## Quick start

<Callout type="info">
The adapter auto-detects `WHATSAPP_ACCESS_TOKEN`, `WHATSAPP_APP_SECRET`, `WHATSAPP_PHONE_NUMBER_ID`, and `WHATSAPP_VERIFY_TOKEN` from the environment.
</Callout>

```typescript title="lib/bot.ts" lineNumbers
import { Chat } from "chat";
import { createWhatsAppAdapter } from "@chat-adapter/whatsapp";

const bot = new Chat({
  userName: "mybot",
  adapters: {
    whatsapp: createWhatsAppAdapter(),
  },
});

bot.onNewMention(async (thread, message) => {
  await thread.post("Hello from WhatsApp!");
});
```

```typescript title="app/api/webhooks/whatsapp/route.ts" lineNumbers
import { bot } from "@/lib/bot";

export async function GET(request: Request) {
  return bot.webhooks.whatsapp(request);
}

export async function POST(request: Request) {
  return bot.webhooks.whatsapp(request);
}
```

## Configuration

<TypeTable
  type={{
    accessToken: {
      type: "string",
      description: "Meta access token. Auto-detected from `WHATSAPP_ACCESS_TOKEN`.",
    },
    appSecret: {
      type: "string",
      description:
        "App secret for webhook verification. Auto-detected from `WHATSAPP_APP_SECRET`.",
    },
    phoneNumberId: {
      type: "string",
      description:
        "Bot's phone number ID. Auto-detected from `WHATSAPP_PHONE_NUMBER_ID`.",
    },
    verifyToken: {
      type: "string",
      description:
        "Webhook verification secret. Auto-detected from `WHATSAPP_VERIFY_TOKEN`.",
    },
    apiVersion: {
      type: "string",
      default: '"v21.0"',
      description: "Graph API version.",
    },
    userName: {
      type: "string",
      default: '"whatsapp-bot"',
      description: "Bot username for self-message detection.",
    },
    apiUrl: {
      type: "string",
      description: "Override the Meta Graph API base URL.",
    },
  }}
/>

## Authentication

### 1. Create a Meta app

1. Go to [developers.facebook.com/apps](https://developers.facebook.com/apps) and create a **Business** app.
2. Add the **WhatsApp** product to your app.
3. Open **WhatsApp** then **API Setup** to find your **Phone Number ID** and a temporary **Access Token**.

### 2. Configure webhooks

1. Open **WhatsApp** then **Configuration**.
2. Set the callback URL to `https://your-domain.com/api/webhooks/whatsapp`.
3. Set a **Verify Token** of your choosing — this becomes `WHATSAPP_VERIFY_TOKEN`.
4. Subscribe to the `messages` webhook field.

### 3. Get credentials

From your Meta app dashboard, copy:

- **App Secret** (under **App Settings** then **Basic**) → `WHATSAPP_APP_SECRET`.
- **Access Token** (under **WhatsApp** then **API Setup**) → `WHATSAPP_ACCESS_TOKEN`. For production, generate a permanent **System User Token** instead.
- **Phone Number ID** (under **WhatsApp** then **API Setup**) → `WHATSAPP_PHONE_NUMBER_ID`.

## Advanced

### Inbound attachments

Incoming media attachments expose a lazy `fetchData()`. Media is downloaded only from Meta's `fbcdn.net` and `fbsbx.com` hosts or the configured Graph origin. Downloads refuse private and internal addresses, are limited to 25 MB, and time out after 30 seconds, and the access token never follows a redirect off those hosts. Pass a custom transport to `downloadMedia()` to route downloads through a proxy.

### Webhook flow

WhatsApp uses two webhook mechanisms:

- **Verification handshake** (GET) — Meta sends a `hub.verify_token` challenge that must match your `WHATSAPP_VERIFY_TOKEN`.
- **Event delivery** (POST) — incoming messages, reactions, and interactive responses, verified via `X-Hub-Signature-256`.

### Interactive messages

Card elements are automatically converted to WhatsApp interactive messages:

- **3 or fewer buttons** — rendered as WhatsApp reply buttons (max 20 chars per title).
- **More than 3 buttons** — falls back to formatted text.
- **Max body text** — 1024 characters.

When a card with reply buttons also contains link buttons, each link button is appended to the interactive message body as a `Label: url` line, since WhatsApp reply buttons cannot open URLs.

### Contextual replies

Use `thread.reply()` to quote a specific message in WhatsApp:

```typescript
bot.onNewMessage(async (thread, message) => {
  await thread.reply(message, {
    markdown: "I can help with that.",
  });
});
```

You can pass either a `Message` or a message ID as the target. Text, cards, files, and buffered streams are supported. When one logical reply produces multiple WhatsApp messages, only the first message includes the contextual reference.

Replies are outbound only. When a user quote-replies to one of your messages, the adapter does not yet surface what they quoted, so `message.replyTo` is `undefined` on inbound WhatsApp messages.

WhatsApp does not display the quoted bubble when the target was deleted or moved to long-term storage, when the reply is a template message, or for some media replies on KaiOS. Reaction messages cannot be contextual replies. See [Meta's contextual replies documentation](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/contextual-replies/).

### Link buttons (CTA URL)

A card whose only interactive element is a single `LinkButton` is sent as a native WhatsApp CTA URL message with a tappable link button. The card is promoted only when all of these hold:

- The `LinkButton` is the card's only action across every actions row, including rows nested in sections. Reply buttons, selects, radio selects, or a second populated actions row keep the text fallback.
- The URL starts with `http://` or `https://` and the label is non-empty. Other schemes (`mailto:`, `tel:`, relative paths) keep the text fallback because the Cloud API rejects them.
- The card has no header `imageUrl` and no image, table, chart, or inline link children. The interactive body cannot carry those, so such cards keep the text fallback to avoid losing content. Text, fields, sections, and dividers are fine.
- The post has no `files` or `attachments`. When media accompanies the card, the adapter keeps the single captioned media send.

The button label is truncated to 20 characters, the header (card title) to 60, and the body to 1024. Cards that do not match these rules fall back to formatted text, where link buttons render as `Label: url`.

### Template messages

Outside the 24-hour customer service window, WhatsApp only accepts pre-approved [template messages](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-message-templates). Use `sendTemplate` to start business-initiated conversations:

```typescript
const threadId = await adapter.openDM("15551234567");

await adapter.sendTemplate(threadId, {
  name: "appointment_reminder",
  language: "en",
  components: [
    {
      type: "body",
      parameters: [{ type: "text", text: "Tomorrow at 2pm" }],
    },
  ],
});
```

Templates must be created and approved in [WhatsApp Manager](https://business.facebook.com/wa/manage/message-templates/) before they can be sent. Quick reply button taps on a template arrive as button responses and are dispatched to your `onAction` handlers.

### Typing indicators

WhatsApp supports typing indicators through `thread.startTyping()` or `adapter.startTyping(threadId)`.

Use it when the bot is about to respond and may take a few seconds. The adapter sends Meta's read-plus-typing payload using the latest inbound message in the thread, so the indicator only works after the bot has received a message.

```typescript
bot.onNewMessage(async (thread, message) => {
  await thread.startTyping();

  await thread.post({
    markdown: "Thanks, I am checking that now.",
  });
});
```

WhatsApp-specific behavior:

- The adapter uses the most recent inbound message ID from thread history.
- If there is no inbound message context, `startTyping()` no-ops.
- The typing indicator is dismissed when the bot sends its reply, or after the WhatsApp platform timeout.

### Read receipts

Mark the current inbound message as read before starting work:

```typescript
bot.onDirectMessage(async (thread) => {
  await thread.markAsRead();
  await thread.post("Thanks, I am checking that now.");
});
```

You can also pass an inbound `Message` or its ID to `thread.markAsRead()`. WhatsApp marks that message and earlier messages in the conversation as read. It does not allow outgoing message IDs to be marked as read and recommends acknowledging inbound messages within 30 days.

### User identity

WhatsApp messages include a [business-scoped user ID](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids/) in `from_user_id` and `contacts[].user_id`. Users with a username may omit the phone-based `from` and `wa_id` fields.

The adapter accepts either identifier. When both are available, it preserves an existing phone-based thread ID and stores the BSUID as an alias. Replies include both `to` and `recipient`, with the phone number taking precedence according to Meta's API. BSUID-only threads send through `recipient`.

Meta does not support BSUID recipients for one-tap, zero-tap, or copy-code authentication templates. Those templates require the user's phone number.

Use a persistent state adapter in production so identity aliases survive restarts. The adapter preserves the canonical thread when Meta rotates a BSUID by consuming `user_changed_number` and `user_changed_user_id` system messages plus the `user_id_update` webhook, which carries the previous and current BSUID. Subscribe your Meta app to the `user_id_update` webhook field so rotations reach the adapter. Current phone, BSUID, parent BSUID, and username fields remain available through `message.raw`.

### Thread ID format

```
whatsapp:{phoneNumberId}:{userWaId}
```

Example: `whatsapp:1234567890:15551234567`.

The final segment is the adapter's canonical user identifier. It may contain a phone number, a BSUID such as `US.13491208655302741918`, or a previously observed identifier retained for thread continuity.

### Auto-chunking

Outgoing messages longer than 4096 characters are automatically chunked.

### File uploads

`postMessage` accepts both `files` and `attachments` (typed media with optional `data`, `fetchData`, or a public URL). See the [file uploads guide](/docs/files) for the shared API.

WhatsApp-specific behavior:

- **One media per message** — multiple `files` or `attachments` in a single `post()` are sent as sequential messages (the last message ID is returned).
- **Captions** — markdown (or card fallback text) is attached as a caption on the first media message when supported (max 1024 characters). Text is sent as a separate message first when the caption is too long or when the first media is audio (audio does not support captions).
- **Binary vs link** — buffers are uploaded via the Cloud API `/media` endpoint; `attachments` with only an `url` use HTTPS link passthrough (no upload). URLs must use `https://`.
- **Cards + files** — when the card renders as an interactive message (reply buttons or a list), media is sent first without a caption and the interactive message that follows carries the title, body, and buttons. When the card falls back to plain text, the fallback text captions the first media, and the caption includes a `Label: url` line for each link button. A card with only a link button is not promoted to a CTA URL message when media is attached, so it takes this captioned path too. To send a photo with buttons, pass the image via `files` or `attachments` — card-embedded images (`imageUrl` or `<Image>` children) are not sent as native media.

```typescript title="lib/bot.ts" lineNumbers
await thread.post({
  markdown: "Here's the report:",
  files: [
    {
      data: reportBuffer,
      filename: "report.pdf",
      mimeType: "application/pdf",
    },
  ],
});
```

## API errors

A non-2xx Graph API response throws `WhatsAppApiError`, exported from `@chat-adapter/whatsapp`. It extends `AdapterError`, so existing `instanceof AdapterError` checks continue to work.

```typescript
import { WhatsAppApiError } from "@chat-adapter/whatsapp";

try {
  await thread.post("Hello");
} catch (error) {
  if (error instanceof WhatsAppApiError) {
    console.error(error.code, error.errorCode, error.details, error.status);
  }
  throw error;
}
```

- `code`: the shared `AdapterError` code when the failure maps onto one: `RATE_LIMITED` (HTTP 429, or Meta throttling codes such as `130429` and `80007`), `AUTH_FAILED` (HTTP 401, or Meta codes `0` and `190`), `PERMISSION_DENIED` (HTTP 403, or Meta codes `3`, `10`, and `200` to `299`), `NOT_FOUND` (HTTP 404). Otherwise `undefined`.
- `errorCode`: Meta's numeric error code, such as `130429`
- `providerMessage` and `type`: Meta's `error.message` and `error.type`, when present
- `details`: Meta's `error_data.details`, when present
- `status`: HTTP response status
- `subcode` and `traceId`: Meta's `error_subcode` and `fbtrace_id`, when present
- `raw`: the full parsed response body (see the `WhatsAppGraphErrorBody` type), or the original text if it is not valid JSON

Meta recommends using [error codes and details](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes/) for error handling. Subcodes are optional and deprecated in the Cloud API. Missing or malformed provider fields stay `undefined`, and numeric codes that a proxy serializes as strings are accepted. The error message combines the operation, the HTTP status, and Meta's `error.message`, or a bounded excerpt of a non-JSON body.

This covers non-2xx responses from message sends, templates, reactions, read receipts, typing requests, media uploads, and media metadata requests. Transport failures and unparseable response bodies throw `NetworkError`, as do binary media download failures. A 2xx response that reports `success: false` for a typing request or read receipt throws a plain `AdapterError`. A successful API response can still be followed by an asynchronous delivery failure; those webhook errors are not thrown as `WhatsAppApiError`.

## Feature support

<FeatureSupport />