@chat-adapter/whatsapp

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

Installation

pnpm add @chat-adapter/whatsapp

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.

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.

*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 verificationWHATSAPP_PHONE_NUMBER_ID=...       # Bot's phone number ID from Meta dashboardWHATSAPP_VERIFY_TOKEN=...          # User-defined secret for webhook verificationWHATSAPP_BOT_USERNAME=...          # Optional, defaults to "whatsapp-bot"

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 exampleimport { bot } from "@/lib/bot";export async function GET(request: Request) {  return bot.adapters.whatsapp.handleWebhook(request);}export async function POST(request: Request) {  return bot.adapters.whatsapp.handleWebhook(request);}

Features

Messaging

Rich content

Conversations

Incoming message types

Message history

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

Thread ID format

whatsapp:{phoneNumberId}:{userWaId}

Example: whatsapp:1234567890:15551234567

Troubleshooting

Webhook verification failing

• Confirm WHATSAPP_VERIFY_TOKEN matches the value you entered in the Meta dashboard
• Ensure your endpoint returns the hub.challenge value for GET requests

Messages not arriving

• Check that you subscribed to the messages webhook field in Meta app settings
• Verify WHATSAPP_APP_SECRET is correct — signature verification silently rejects invalid payloads
• Ensure your phone number is registered and verified in the WhatsApp Business dashboard

"Invalid signature" errors

• Double-check WHATSAPP_APP_SECRET matches the value under App Settings > Basic
• The adapter uses HMAC-SHA256 to verify the X-Hub-Signature-256 header

Token expired

• Temporary tokens from the API Setup page expire after 24 hours
• For production, create a System User in Meta Business Suite and generate a permanent token

License

MIT