@chat-adapter/whatsapp weekly downloads statistics

@chat-adapter/whatsapp

npm package: @chat-adapter/whatsapp

WhatsApp Business Cloud adapter for Chat SDK, using the WhatsApp Business Cloud API.

Documentation: chat-sdk.dev/adapters/official/whatsapp · Guides: vercel.com/kb/chat-sdk

Installation

pnpm add @chat-adapter/whatsapp

Scaffold with the CLI

To scaffold a new WhatsApp bot with this adapter preselected:

npx create-chat-sdk@latest my-bot --adapter whatsapp memory

Visit the adapters directory to see other available official and vendor-official adapters.

Usage

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!");
});

When using createWhatsAppAdapter() without arguments, credentials are auto-detected from environment variables.

WhatsApp Business setup

1. Create a Meta app

1. Go to developers.facebook.com/apps
2. Click Create App, select Business type
3. Add the WhatsApp product to your app
4. Go to WhatsApp > API Setup and note your Phone Number ID and Access Token

2. Configure webhooks

1. Go to WhatsApp > Configuration in your Meta app
2. Set Callback URL to https://your-domain.com/api/webhooks/whatsapp
3. Set Verify Token to a secret string of your choice (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 > Basic) as WHATSAPP_APP_SECRET
• Access Token (under WhatsApp > API Setup) as WHATSAPP_ACCESS_TOKEN
• Phone Number ID (under WhatsApp > API Setup) as WHATSAPP_PHONE_NUMBER_ID

For production, generate a permanent System User Token instead of the temporary access token.

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.

Configuration

All options are auto-detected from environment variables when not provided. You can call createWhatsAppAdapter() with no arguments if the env vars are set.

Option	Required	Description
accessToken	No*	Meta access token. Auto-detected from WHATSAPP_ACCESS_TOKEN
appSecret	No*	App secret for webhook verification. Auto-detected from WHATSAPP_APP_SECRET
phoneNumberId	No*	Bot's phone number ID. Auto-detected from WHATSAPP_PHONE_NUMBER_ID
verifyToken	No*	Webhook verification secret. Auto-detected from WHATSAPP_VERIFY_TOKEN
apiVersion	No	Graph API version (defaults to v25.0)
userName	No	Bot username for self-message detection. Auto-detected from WHATSAPP_BOT_USERNAME (defaults to whatsapp-bot)
apiUrl	No	Override the Meta Graph API base URL. Auto-detected from WHATSAPP_API_URL
logger	No	Logger instance (defaults to ConsoleLogger("info"))

*Required at runtime — either via config or environment variable.

Environment variables

WHATSAPP_ACCESS_TOKEN=...          # Meta access token (permanent or system user token)
WHATSAPP_APP_SECRET=...            # App secret for X-Hub-Signature-256 verification
WHATSAPP_PHONE_NUMBER_ID=...       # Bot's phone number ID from Meta dashboard
WHATSAPP_VERIFY_TOKEN=...          # User-defined secret for webhook verification
WHATSAPP_BOT_USERNAME=...          # Optional, defaults to "whatsapp-bot"
WHATSAPP_API_URL=...               # Optional, override the Meta Graph API base URL

Webhook setup

WhatsApp uses two webhook mechanisms:

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

// Next.js App Router example
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);
}

Features

Messaging

Feature	Supported
Post message	Yes
Edit message	No (WhatsApp limitation)
Delete message	No (WhatsApp limitation)
Streaming	Buffered (accumulates then sends)
Mark as read	Yes
Auto-chunking	Yes (splits at 4096 chars)
Template messages	Yes (via sendTemplate)

Rich content…