@chat-adapter/whatsapp 4.20.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Vercel, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# @chat-adapter/whatsapp
+
+[![npm version](https://img.shields.io/npm/v/@chat-adapter/whatsapp)](https://www.npmjs.com/package/@chat-adapter/whatsapp)
+[![npm downloads](https://img.shields.io/npm/dm/@chat-adapter/whatsapp)](https://www.npmjs.com/package/@chat-adapter/whatsapp)
+
+WhatsApp adapter for [Chat SDK](https://chat-sdk.dev/docs), using the [WhatsApp Business Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api).
+
+## Installation
+
+```bash
+npm install chat @chat-adapter/whatsapp
+```
+
+## Usage
+
+```typescript
+import { Chat } from "chat";
+import { createWhatsAppAdapter } from "@chat-adapter/whatsapp";
+
+const bot = new Chat({
+  userName: "mybot",
+  adapters: {
+    whatsapp: createWhatsAppAdapter(),
+  },
+});
+```
+
+When using `createWhatsAppAdapter()` without arguments, credentials are auto-detected from environment variables.
+
+## Environment variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `WHATSAPP_ACCESS_TOKEN` | Yes | Meta access token (permanent or system user token) |
+| `WHATSAPP_APP_SECRET` | Yes | App secret for X-Hub-Signature-256 verification |
+| `WHATSAPP_PHONE_NUMBER_ID` | Yes | Bot's phone number ID from Meta dashboard |
+| `WHATSAPP_VERIFY_TOKEN` | Yes | User-defined secret for webhook verification handshake |
+
+## 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`.
+
+```typescript
+// Next.js App Router example
+import { 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);
+}
+```
+
+## Interactive messages
+
+Card elements are automatically converted to WhatsApp interactive messages:
+
+- **3 or fewer buttons** — rendered as WhatsApp reply buttons
+- **More than 3 buttons** — falls back to formatted text
+
+## Limitations
+
+- **No message editing** — `editMessage()` throws (WhatsApp limitation)
+- **No message deletion** — `deleteMessage()` throws (WhatsApp limitation)
+- **No message history API** — `fetchMessages()` returns empty results
+
+## Thread ID format
+
+```
+whatsapp:{phoneNumberId}:{userWaId}
+```
+
+Example: `whatsapp:1234567890:15551234567`
+
+## Documentation
+
+Full setup instructions at [chat-sdk.dev/docs/adapters/whatsapp](https://chat-sdk.dev/docs/adapters/whatsapp).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,441 @@
+import { Logger, Adapter, ChatInstance, WebhookOptions, AdapterPostableMessage, RawMessage, StreamChunk, StreamOptions, EmojiValue, FetchOptions, FetchResult, ThreadInfo, Message, FormattedContent } from 'chat';
+
+/**
+ * Type definitions for the WhatsApp adapter.
+ *
+ * Based on the WhatsApp Business Cloud API (Meta Graph API).
+ * @see https://developers.facebook.com/docs/whatsapp/cloud-api
+ */
+
+/**
+ * WhatsApp adapter configuration.
+ *
+ * Requires a System User access token for API calls and an App Secret
+ * for webhook signature verification.
+ *
+ * @see https://developers.facebook.com/docs/whatsapp/cloud-api/get-started
+ */
+interface WhatsAppAdapterConfig {
+    /** Access token (System User token) for WhatsApp Cloud API calls */
+    accessToken: string;
+    /** Meta Graph API version (default: "v21.0") */
+    apiVersion?: string;
+    /** Meta App Secret for webhook HMAC-SHA256 signature verification */
+    appSecret: string;
+    /** Logger instance for error reporting */
+    logger: Logger;
+    /** WhatsApp Business phone number ID (not the phone number itself) */
+    phoneNumberId: string;
+    /** Bot display name used for identification */
+    userName: string;
+    /** Verify token for webhook challenge-response verification */
+    verifyToken: string;
+}
+/**
+ * Decoded thread ID for WhatsApp.
+ *
+ * WhatsApp conversations are always 1:1 between a business phone number
+ * and a user. There is no concept of threads or channels.
+ *
+ * Format: whatsapp:{phoneNumberId}:{userWaId}
+ */
+interface WhatsAppThreadId {
+    /** Business phone number ID */
+    phoneNumberId: string;
+    /** User's WhatsApp ID (their phone number) */
+    userWaId: string;
+}
+/**
+ * Contact information from an inbound message.
+ */
+interface WhatsAppContact {
+    profile: {
+        name: string;
+    };
+    wa_id: string;
+}
+/**
+ * Inbound message from a user.
+ *
+ * @see https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/payload-examples
+ */
+interface WhatsAppInboundMessage {
+    /** Audio message content */
+    audio?: {
+        id: string;
+        mime_type: string;
+        sha256: string;
+        voice?: boolean;
+    };
+    /** Legacy button response (from template quick replies) */
+    button?: {
+        payload: string;
+        text: string;
+    };
+    /** Context for quoted replies */
+    context?: {
+        from: string;
+        id: string;
+    };
+    /** Document message content */
+    document?: {
+        caption?: string;
+        filename?: string;
+        id: string;
+        mime_type: string;
+        sha256: string;
+    };
+    /** Sender's WhatsApp ID */
+    from: string;
+    /** Unique message ID */
+    id: string;
+    /** Image message content */
+    image?: {
+        caption?: string;
+        id: string;
+        mime_type: string;
+        sha256: string;
+    };
+    /** Interactive message reply */
+    interactive?: {
+        button_reply?: {
+            id: string;
+            title: string;
+        };
+        list_reply?: {
+            description?: string;
+            id: string;
+            title: string;
+        };
+        type: "button_reply" | "list_reply";
+    };
+    /** Location message content */
+    location?: {
+        address?: string;
+        latitude: number;
+        longitude: number;
+        name?: string;
+        url?: string;
+    };
+    /** Reaction to a message */
+    reaction?: {
+        emoji: string;
+        message_id: string;
+    };
+    /** Sticker message content */
+    sticker?: {
+        animated: boolean;
+        id: string;
+        mime_type: string;
+        sha256: string;
+    };
+    /** Text message content */
+    text?: {
+        body: string;
+    };
+    /** Unix timestamp string */
+    timestamp: string;
+    /** Message type */
+    type: "text" | "image" | "document" | "audio" | "video" | "voice" | "sticker" | "location" | "contacts" | "interactive" | "button" | "reaction" | "order" | "system";
+    /** Video message content */
+    video?: {
+        caption?: string;
+        id: string;
+        mime_type: string;
+        sha256: string;
+    };
+    /** Voice message content */
+    voice?: {
+        id: string;
+        mime_type: string;
+        sha256: string;
+    };
+}
+/**
+ * Response from the media URL endpoint.
+ *
+ * @see https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media#get-media-url
+ */
+interface WhatsAppMediaResponse {
+    file_size: number;
+    id: string;
+    messaging_product: "whatsapp";
+    mime_type: string;
+    sha256: string;
+    url: string;
+}
+/**
+ * Platform-specific raw message type for WhatsApp.
+ */
+interface WhatsAppRawMessage {
+    /** Contact info from the webhook */
+    contact?: WhatsAppContact;
+    /** The raw inbound message data */
+    message: WhatsAppInboundMessage;
+    /** Phone number ID that received the message */
+    phoneNumberId: string;
+}
+
+/**
+ * Split text into chunks that fit within WhatsApp's message limit,
+ * breaking on paragraph boundaries (\n\n) when possible, then line
+ * boundaries (\n), and finally at the character limit as a last resort.
+ */
+declare function splitMessage(text: string): string[];
+
+/**
+ * WhatsApp adapter for chat SDK.
+ *
+ * Supports messaging via the WhatsApp Business Cloud API (Meta Graph API).
+ * All conversations are 1:1 DMs between the business phone number and users.
+ *
+ * @example
+ * ```typescript
+ * import { Chat } from "chat";
+ * import { createWhatsAppAdapter } from "@chat-adapter/whatsapp";
+ * import { MemoryState } from "@chat-adapter/state-memory";
+ *
+ * const chat = new Chat({
+ *   userName: "my-bot",
+ *   adapters: {
+ *     whatsapp: createWhatsAppAdapter(),
+ *   },
+ *   state: new MemoryState(),
+ * });
+ * ```
+ */
+declare class WhatsAppAdapter implements Adapter<WhatsAppThreadId, WhatsAppRawMessage> {
+    readonly name = "whatsapp";
+    readonly persistMessageHistory = true;
+    readonly userName: string;
+    private readonly accessToken;
+    private readonly appSecret;
+    private readonly phoneNumberId;
+    private readonly verifyToken;
+    private readonly graphApiUrl;
+    private chat;
+    private readonly logger;
+    private _botUserId;
+    private readonly formatConverter;
+    /** Bot user ID used for self-message detection */
+    get botUserId(): string | undefined;
+    constructor(config: WhatsAppAdapterConfig);
+    /**
+     * Initialize the adapter and fetch business profile info.
+     */
+    initialize(chat: ChatInstance): Promise<void>;
+    /**
+     * Handle incoming webhook from WhatsApp.
+     *
+     * Handles both the GET verification challenge and POST event notifications.
+     *
+     * @see https://developers.facebook.com/docs/whatsapp/cloud-api/guides/set-up-webhooks
+     */
+    handleWebhook(request: Request, options?: WebhookOptions): Promise<Response>;
+    /**
+     * Handle the webhook verification challenge from Meta.
+     *
+     * @see https://developers.facebook.com/docs/whatsapp/cloud-api/guides/set-up-webhooks
+     */
+    private handleVerificationChallenge;
+    /**
+     * Verify webhook signature using HMAC-SHA256 with the App Secret.
+     *
+     * @see https://developers.facebook.com/docs/graph-api/webhooks/getting-started#verification-requests
+     */
+    private verifySignature;
+    /**
+     * Handle an inbound message from a user.
+     */
+    private handleInboundMessage;
+    /**
+     * Handle reaction events.
+     */
+    private handleReaction;
+    /**
+     * Handle interactive message replies (button/list selection).
+     */
+    private handleInteractiveReply;
+    /**
+     * Handle legacy button responses (from template quick replies).
+     */
+    private handleButtonResponse;
+    /**
+     * Extract text content from an inbound message.
+     * Returns null for unsupported message types.
+     */
+    private extractTextContent;
+    /**
+     * Build a Message from a WhatsApp inbound message.
+     */
+    private buildMessage;
+    /**
+     * Build attachments from an inbound message.
+     */
+    private buildAttachments;
+    /**
+     * Build a single media attachment with a lazy fetchData function.
+     */
+    private buildMediaAttachment;
+    /**
+     * Download media from WhatsApp.
+     *
+     * WhatsApp media is fetched in two steps:
+     * 1. GET the media metadata to obtain the download URL
+     * 2. GET the actual binary data from the download URL
+     *
+     * @param mediaId - The media ID from the inbound message
+     * @returns The media data as a Buffer
+     *
+     * @see https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media#download-media
+     */
+    downloadMedia(mediaId: string): Promise<Buffer>;
+    /**
+     * Send a message to a WhatsApp user.
+     *
+     * @see https://developers.facebook.com/docs/whatsapp/cloud-api/messages
+     */
+    postMessage(threadId: string, message: AdapterPostableMessage): Promise<RawMessage<WhatsAppRawMessage>>;
+    /**
+     * Split text into chunks that fit within WhatsApp's message limit,
+     * breaking on paragraph boundaries (\n\n) when possible, then line
+     * boundaries (\n), and finally at the character limit as a last resort.
+     */
+    splitMessage(text: string): string[];
+    /**
+     * Send a single text message via the Cloud API (must be within the
+     * 4096-character limit).
+     */
+    private sendSingleTextMessage;
+    /**
+     * Send a text message, splitting into multiple messages if it exceeds
+     * WhatsApp's 4096-character limit. Returns the last message sent.
+     */
+    private sendTextMessage;
+    /**
+     * Send an interactive message (buttons or list) via the Cloud API.
+     */
+    private sendInteractiveMessage;
+    /**
+     * Edit a message. Not supported by WhatsApp Cloud API — throws an error.
+     *
+     * Callers should use postMessage directly if they want to send a follow-up.
+     */
+    editMessage(_threadId: string, _messageId: string, _message: AdapterPostableMessage): Promise<RawMessage<WhatsAppRawMessage>>;
+    /**
+     * Stream a message by buffering all chunks and sending as a single message.
+     * WhatsApp doesn't support message editing, so we can't do incremental updates.
+     */
+    stream(threadId: string, textStream: AsyncIterable<string | StreamChunk>, _options?: StreamOptions): Promise<RawMessage<WhatsAppRawMessage>>;
+    /**
+     * Delete a message. Not supported by WhatsApp Cloud API — throws an error.
+     */
+    deleteMessage(_threadId: string, _messageId: string): Promise<void>;
+    /**
+     * Add a reaction to a message.
+     *
+     * @see https://developers.facebook.com/docs/whatsapp/cloud-api/messages/reaction-messages
+     */
+    addReaction(threadId: string, messageId: string, emoji: EmojiValue | string): Promise<void>;
+    /**
+     * Remove a reaction from a message.
+     *
+     * @see https://developers.facebook.com/docs/whatsapp/cloud-api/messages/reaction-messages
+     */
+    removeReaction(threadId: string, messageId: string, _emoji: EmojiValue | string): Promise<void>;
+    /**
+     * Start typing indicator.
+     *
+     * WhatsApp supports typing indicators via the messages endpoint.
+     * The indicator displays for up to 25 seconds or until the next message.
+     *
+     * @see https://developers.facebook.com/docs/whatsapp/cloud-api/messages/mark-messages-as-read
+     */
+    startTyping(_threadId: string, _status?: string): Promise<void>;
+    /**
+     * Fetch messages. Not supported by WhatsApp Cloud API.
+     *
+     * WhatsApp does not provide an API to retrieve message history.
+     */
+    fetchMessages(_threadId: string, _options?: FetchOptions): Promise<FetchResult<WhatsAppRawMessage>>;
+    /**
+     * Fetch thread info.
+     */
+    fetchThread(threadId: string): Promise<ThreadInfo>;
+    /**
+     * Encode a WhatsApp thread ID.
+     *
+     * Format: whatsapp:{phoneNumberId}:{userWaId}
+     */
+    encodeThreadId(platformData: WhatsAppThreadId): string;
+    /**
+     * Decode a WhatsApp thread ID.
+     *
+     * Format: whatsapp:{phoneNumberId}:{userWaId}
+     */
+    decodeThreadId(threadId: string): WhatsAppThreadId;
+    /**
+     * Derive channel ID from a WhatsApp thread ID.
+     * On WhatsApp every conversation is a 1:1 DM, so channel === thread.
+     */
+    channelIdFromThreadId(threadId: string): string;
+    /**
+     * All WhatsApp conversations are DMs.
+     */
+    isDM(_threadId: string): boolean;
+    /**
+     * Open a DM with a user. Returns the thread ID for the conversation.
+     *
+     * For WhatsApp, this simply constructs the thread ID since all
+     * conversations are inherently DMs. Note: you can only message users
+     * who have messaged you first (within the 24-hour window) or
+     * via approved template messages.
+     */
+    openDM(userId: string): Promise<string>;
+    /**
+     * Parse platform message format to normalized format.
+     */
+    parseMessage(raw: WhatsAppRawMessage): Message<WhatsAppRawMessage>;
+    /**
+     * Render formatted content to WhatsApp markdown.
+     */
+    renderFormatted(content: FormattedContent): string;
+    /**
+     * Mark an inbound message as read.
+     *
+     * @see https://developers.facebook.com/docs/whatsapp/cloud-api/messages/mark-messages-as-read
+     */
+    markAsRead(messageId: string): Promise<void>;
+    /**
+     * Make a request to the Meta Graph API.
+     */
+    private graphApiRequest;
+    /**
+     * Resolve an emoji value to a unicode string.
+     */
+    private resolveEmoji;
+}
+/**
+ * Factory function to create a WhatsApp adapter.
+ *
+ * @example
+ * ```typescript
+ * const adapter = createWhatsAppAdapter({
+ *   accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
+ *   appSecret: process.env.WHATSAPP_APP_SECRET!,
+ *   phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID!,
+ *   verifyToken: process.env.WHATSAPP_VERIFY_TOKEN!,
+ * });
+ * ```
+ */
+declare function createWhatsAppAdapter(config?: {
+    accessToken?: string;
+    apiVersion?: string;
+    appSecret?: string;
+    logger?: Logger;
+    phoneNumberId?: string;
+    userName?: string;
+    verifyToken?: string;
+}): WhatsAppAdapter;
+
+export { WhatsAppAdapter, type WhatsAppAdapterConfig, type WhatsAppMediaResponse, type WhatsAppRawMessage, type WhatsAppThreadId, createWhatsAppAdapter, splitMessage };