chat 4.25.0 → 4.26.0

package/dist/index.d.ts

@@ -2881,6 +2881,21 @@ declare class Chat<TAdapters extends Record<string, Adapter> = Record<string, Ad
  */
 declare function fromFullStream(stream: AsyncIterable<unknown>): AsyncIterable<string | StreamChunk>;
 
+/**
+ * Standalone JSON reviver for Chat SDK objects.
+ *
+ * Restores serialized Thread, Channel, and Message instances during
+ * JSON.parse() without requiring a Chat instance. This is useful in
+ * environments like Vercel Workflow functions where importing the full
+ * Chat instance (with its adapter dependencies) is not possible.
+ *
+ * Thread instances created this way use lazy adapter resolution —
+ * the adapter is looked up from the Chat singleton when first accessed,
+ * so `chat.registerSingleton()` must be called before using thread
+ * methods like `post()` (typically inside a "use step" function).
+ */
+declare function reviver(_key: string, value: unknown): unknown;
+
 interface StreamingMarkdownRendererOptions {
     /**
      * Wrap confirmed table blocks in code fences for append-only consumers that
@@ -3381,4 +3396,4 @@ declare const Select: SelectComponent;
 declare const SelectOption: SelectOptionComponent;
 declare const TextInput: TextInputComponent;
 
-export { type ActionEvent, type ActionHandler, Actions, ActionsComponent, type Adapter, type AdapterPostableMessage, type AddTaskOptions, type AiAssistantMessage, type AiFilePart, type AiImagePart, type AiMessage, type AiMessagePart, type AiTextPart, type AiUserMessage, type AppHomeOpenedEvent, type AppHomeOpenedHandler, type AssistantContextChangedEvent, type AssistantContextChangedHandler, type AssistantThreadStartedEvent, type AssistantThreadStartedHandler, type Attachment, type Author, BaseFormatConverter, Button, ButtonComponent, Card, CardChild, CardComponent, CardElement, CardLink, CardLinkComponent, CardText, type Channel, ChannelImpl, type ChannelInfo, type ChannelVisibility, Chat, type ChatConfig, ChatElement, ChatError, type ChatInstance, type CompletePlanOptions, type ConcurrencyConfig, type ConcurrencyStrategy, ConsoleLogger, type CustomEmojiMap, DEFAULT_EMOJI_MAP, type DirectMessageHandler, Divider, DividerComponent, type Emoji, type EmojiFormats, type EmojiMapConfig, EmojiResolver, type EmojiValue, type EphemeralMessage, type FetchDirection, type FetchOptions, type FetchResult, Field, FieldComponent, Fields, FieldsComponent, type FileUpload, type FormatConverter, type FormattedContent, Image, ImageComponent, LinkButton, LinkButtonComponent, type LinkPreview, type ListThreadsOptions, type ListThreadsResult, type Lock, LockError, type LockScope, type LockScopeContext, type LogLevel, type Logger, type MarkdownConverter, type MarkdownTextChunk, type MemberJoinedChannelEvent, type MemberJoinedChannelHandler, type MentionHandler, Message, type MessageContext, type MessageData, type MessageHandler, MessageHistoryCache, type MessageHistoryConfig, type MessageMetadata, Modal, type ModalCloseEvent, type ModalCloseHandler, type ModalCloseResponse, ModalComponent, ModalElement, type ModalErrorsResponse, type ModalPushResponse, type ModalResponse, type ModalSubmitEvent, type ModalSubmitHandler, type ModalUpdateResponse, NotImplementedError, Plan, type PlanContent, type PlanModel, type PlanModelTask, type PlanTask, type PlanTaskStatus, type PlanUpdateChunk, type PostEphemeralOptions, type Postable, type PostableAst, type PostableCard, type PostableMarkdown, type PostableMessage, type PostableObject, type PostableObjectContext, type PostableRaw, type QueueEntry, RadioSelect, RadioSelectComponent, RateLimitError, type RawMessage, type ReactionEvent, type ReactionHandler, type ScheduledMessage, Section, SectionComponent, Select, SelectComponent, SelectOption, SelectOptionComponent, type SentMessage, type SerializedChannel, type SerializedMessage, type SerializedThread, type SlashCommandEvent, type SlashCommandHandler, type StartPlanOptions, type StateAdapter, type StreamChunk, type StreamEvent, type StreamOptions, StreamingMarkdownRenderer, type SubscribedMessageHandler, THREAD_STATE_TTL_MS, Table, type TaskUpdateChunk, TextComponent, TextInput, TextInputComponent, type Thread, ThreadImpl, type ThreadInfo, type ThreadSummary, type UpdateTaskInput, type WebhookOptions, type WellKnownEmoji, blockquote, cardChildToFallbackText, codeBlock, convertEmojiPlaceholders, createEmoji, defaultEmojiResolver, deriveChannelId, emoji, emphasis, fromFullStream, fromReactElement, fromReactModalElement, getEmoji, getNodeChildren, getNodeValue, inlineCode, isBlockquoteNode, isCardElement, isCodeNode, isDeleteNode, isEmphasisNode, isInlineCodeNode, isJSX, isLinkNode, isListItemNode, isListNode, isModalElement, isParagraphNode, isPostableObject, isStrongNode, isTableCellNode, isTableNode, isTableRowNode, isTextNode, link, markdownToPlainText, paragraph, parseMarkdown, root, strikethrough, stringifyMarkdown, strong, tableElementToAscii, tableToAscii, text, toAiMessages, toCardElement, toModalElement, toPlainText, walkAst };
+export { type ActionEvent, type ActionHandler, Actions, ActionsComponent, type Adapter, type AdapterPostableMessage, type AddTaskOptions, type AiAssistantMessage, type AiFilePart, type AiImagePart, type AiMessage, type AiMessagePart, type AiTextPart, type AiUserMessage, type AppHomeOpenedEvent, type AppHomeOpenedHandler, type AssistantContextChangedEvent, type AssistantContextChangedHandler, type AssistantThreadStartedEvent, type AssistantThreadStartedHandler, type Attachment, type Author, BaseFormatConverter, Button, ButtonComponent, Card, CardChild, CardComponent, CardElement, CardLink, CardLinkComponent, CardText, type Channel, ChannelImpl, type ChannelInfo, type ChannelVisibility, Chat, type ChatConfig, ChatElement, ChatError, type ChatInstance, type CompletePlanOptions, type ConcurrencyConfig, type ConcurrencyStrategy, ConsoleLogger, type CustomEmojiMap, DEFAULT_EMOJI_MAP, type DirectMessageHandler, Divider, DividerComponent, type Emoji, type EmojiFormats, type EmojiMapConfig, EmojiResolver, type EmojiValue, type EphemeralMessage, type FetchDirection, type FetchOptions, type FetchResult, Field, FieldComponent, Fields, FieldsComponent, type FileUpload, type FormatConverter, type FormattedContent, Image, ImageComponent, LinkButton, LinkButtonComponent, type LinkPreview, type ListThreadsOptions, type ListThreadsResult, type Lock, LockError, type LockScope, type LockScopeContext, type LogLevel, type Logger, type MarkdownConverter, type MarkdownTextChunk, type MemberJoinedChannelEvent, type MemberJoinedChannelHandler, type MentionHandler, Message, type MessageContext, type MessageData, type MessageHandler, MessageHistoryCache, type MessageHistoryConfig, type MessageMetadata, Modal, type ModalCloseEvent, type ModalCloseHandler, type ModalCloseResponse, ModalComponent, ModalElement, type ModalErrorsResponse, type ModalPushResponse, type ModalResponse, type ModalSubmitEvent, type ModalSubmitHandler, type ModalUpdateResponse, NotImplementedError, Plan, type PlanContent, type PlanModel, type PlanModelTask, type PlanTask, type PlanTaskStatus, type PlanUpdateChunk, type PostEphemeralOptions, type Postable, type PostableAst, type PostableCard, type PostableMarkdown, type PostableMessage, type PostableObject, type PostableObjectContext, type PostableRaw, type QueueEntry, RadioSelect, RadioSelectComponent, RateLimitError, type RawMessage, type ReactionEvent, type ReactionHandler, type ScheduledMessage, Section, SectionComponent, Select, SelectComponent, SelectOption, SelectOptionComponent, type SentMessage, type SerializedChannel, type SerializedMessage, type SerializedThread, type SlashCommandEvent, type SlashCommandHandler, type StartPlanOptions, type StateAdapter, type StreamChunk, type StreamEvent, type StreamOptions, StreamingMarkdownRenderer, type SubscribedMessageHandler, THREAD_STATE_TTL_MS, Table, type TaskUpdateChunk, TextComponent, TextInput, TextInputComponent, type Thread, ThreadImpl, type ThreadInfo, type ThreadSummary, type UpdateTaskInput, type WebhookOptions, type WellKnownEmoji, blockquote, cardChildToFallbackText, codeBlock, convertEmojiPlaceholders, createEmoji, defaultEmojiResolver, deriveChannelId, emoji, emphasis, fromFullStream, fromReactElement, fromReactModalElement, getEmoji, getNodeChildren, getNodeValue, inlineCode, isBlockquoteNode, isCardElement, isCodeNode, isDeleteNode, isEmphasisNode, isInlineCodeNode, isJSX, isLinkNode, isListItemNode, isListNode, isModalElement, isParagraphNode, isPostableObject, isStrongNode, isTableCellNode, isTableNode, isTableRowNode, isTextNode, link, markdownToPlainText, paragraph, parseMarkdown, reviver, root, strikethrough, stringifyMarkdown, strong, tableElementToAscii, tableToAscii, text, toAiMessages, toCardElement, toModalElement, toPlainText, walkAst };

package/dist/index.js

@@ -729,7 +729,7 @@ var ChannelImpl = class _ChannelImpl {
     return {
       _type: "chat:Channel",
       id: this.id,
-      adapterName: this.adapter.name,
+      adapterName: this._adapterName ?? this.adapter.name,
       channelVisibility: this.channelVisibility,
       isDM: this.isDM
     };
@@ -1541,7 +1541,7 @@ var ThreadImpl = class _ThreadImpl {
         return;
       }
       const content = renderer.render();
-      if (content !== lastEditContent) {
+      if (content.trim() && content !== lastEditContent) {
         try {
           await this.adapter.editMessage(threadIdForEdits, msg.id, {
             markdown: content
@@ -1563,12 +1563,14 @@ var ThreadImpl = class _ThreadImpl {
         renderer.push(chunk);
         if (!msg) {
           const content = renderer.render();
-          msg = await this.adapter.postMessage(this.id, {
-            markdown: content
-          });
-          threadIdForEdits = msg.threadId || this.id;
-          lastEditContent = content;
-          scheduleNextEdit();
+          if (content.trim()) {
+            msg = await this.adapter.postMessage(this.id, {
+              markdown: content
+            });
+            threadIdForEdits = msg.threadId || this.id;
+            lastEditContent = content;
+            scheduleNextEdit();
+          }
         }
       }
     } finally {
@@ -1585,12 +1587,12 @@ var ThreadImpl = class _ThreadImpl {
     const finalContent = renderer.finish();
     if (!msg) {
       msg = await this.adapter.postMessage(this.id, {
-        markdown: accumulated
+        markdown: accumulated.trim() ? accumulated : " "
       });
       threadIdForEdits = msg.threadId || this.id;
       lastEditContent = accumulated;
     }
-    if (finalContent !== lastEditContent) {
+    if (finalContent.trim() && finalContent !== lastEditContent) {
       await this.adapter.editMessage(threadIdForEdits, msg.id, {
         markdown: accumulated
       });
@@ -1642,7 +1644,7 @@ var ThreadImpl = class _ThreadImpl {
       channelVisibility: this.channelVisibility,
       currentMessage: this._currentMessage?.toJSON(),
       isDM: this.isDM,
-      adapterName: this.adapter.name
+      adapterName: this._adapterName ?? this.adapter.name
     };
   }
   /**
@@ -1832,6 +1834,23 @@ function extractMessageContent2(message) {
   throw new Error("Invalid PostableMessage format");
 }
 
+// src/reviver.ts
+function reviver(_key, value) {
+  if (value && typeof value === "object" && "_type" in value) {
+    const typed = value;
+    if (typed._type === "chat:Thread") {
+      return ThreadImpl.fromJSON(value);
+    }
+    if (typed._type === "chat:Channel") {
+      return ChannelImpl.fromJSON(value);
+    }
+    if (typed._type === "chat:Message") {
+      return Message.fromJSON(value);
+    }
+  }
+  return value;
+}
+
 // src/chat.ts
 var DEFAULT_LOCK_TTL_MS = 3e4;
 function sleep(ms) {
@@ -2248,21 +2267,7 @@ var Chat = class {
    */
   reviver() {
     this.registerSingleton();
-    return function reviver(_key, value) {
-      if (value && typeof value === "object" && "_type" in value) {
-        const typed = value;
-        if (typed._type === "chat:Thread") {
-          return ThreadImpl.fromJSON(value);
-        }
-        if (typed._type === "chat:Channel") {
-          return ChannelImpl.fromJSON(value);
-        }
-        if (typed._type === "chat:Message") {
-          return Message.fromJSON(value);
-        }
-      }
-      return value;
-    };
+    return reviver;
   }
   // ChatInstance interface implementations
   /**
@@ -4071,6 +4076,7 @@ export {
   markdownToPlainText,
   paragraph,
   parseMarkdown,
+  reviver,
   root,
   strikethrough,
   stringifyMarkdown,

package/docs/adapters.mdx

@@ -34,7 +34,7 @@ Ready to build your own? Follow the [building](/docs/contributing/building) guid
 | Tables | ✅ Block Kit | ✅ GFM | ⚠️ ASCII | ✅ GFM | ⚠️ ASCII | ✅ GFM | ✅ GFM | ❌ |
 | Fields | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⚠️ Template variables |
 | Images in cards | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ | ✅ |
-| Modals | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Modals | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
 
 ### Conversations
 
@@ -64,7 +64,7 @@ Ready to build your own? Follow the [building](/docs/contributing/building) guid
 ⚠️ indicates partial support — the feature works with limitations. See individual adapter pages for details.
 </Callout>
 
-## How [adapters](/adapters) work
+## How adapters work
 
 Each adapter implements a standard interface that the `Chat` class uses to route events and send messages. When a webhook arrives:
 
@@ -73,7 +73,7 @@ Each adapter implements a standard interface that the `Chat` class uses to route
 3. Routes to your handlers via the `Chat` class
 4. Converts outgoing messages from markdown/AST/cards to the platform's native format
 
-## Using multiple [adapters](/adapters)
+## Using multiple adapters
 
 Register multiple [adapters](/adapters) and your event handlers work across all of them:
 

package/docs/api/cards.mdx

@@ -95,6 +95,11 @@ Button({ id: "delete", label: "Delete", style: "danger", value: "item-123" })
       description: 'Optional payload sent with the action callback.',
       type: 'string',
     },
+    actionType: {
+      description: 'Hints to adapters like Teams that this button will open a modal via event.openModal().',
+      type: '"action" | "modal"',
+      default: '"action"',
+    },
   }}
 />
 

package/docs/api/chat.mdx

@@ -475,3 +475,13 @@ Get a `JSON.parse` reviver that deserializes `Thread` and `Message` objects from
 const data = JSON.parse(payload, bot.reviver());
 await data.thread.post("Hello from workflow!");
 ```
+
+There is also a standalone `reviver` export that works without a `Chat` instance. This is useful in Vercel Workflow functions where importing the full Chat instance (with its adapter dependencies) is not possible:
+
+```typescript
+import { reviver } from "chat";
+
+const data = JSON.parse(payload, reviver) as { thread: Thread; message: Message };
+```
+
+The standalone reviver uses lazy adapter resolution - the adapter is looked up from the Chat singleton when first accessed. Call `chat.registerSingleton()` before using thread methods like `post()` (typically inside a `"use step"` function).

package/docs/api/modals.mdx

@@ -4,7 +4,7 @@ description: Modal form components for collecting user input.
 type: reference
 ---
 
-Modals display form dialogs that collect structured user input. Currently supported on Slack.
+Modals display form dialogs that collect structured user input. Currently supported on Slack and Teams.
 
 ```typescript
 import { Modal, TextInput, Select, RadioSelect, SelectOption } from "chat";

package/docs/cards.mdx

@@ -109,6 +109,12 @@ The `id` maps to your `onAction` handler. Optional `value` passes extra data:
 <Button id="report" value="bug">Report Bug</Button>
 ```
 
+Set `actionType="modal"` to indicate the button opens a [modal](/docs/modals). The button still triggers your `onAction` handler, where you call `event.openModal()` — this prop tells adapters like Teams to wire up the button for dialog opening:
+
+```tsx title="lib/bot.tsx"
+<Button id="open-feedback" actionType="modal">Give Feedback</Button>
+```
+
 ### CardLink
 
 Inline hyperlink rendered as text. Unlike `LinkButton` (which must be inside `Actions`), `CardLink` can be placed directly in a card alongside other content.

package/docs/getting-started.mdx

@@ -14,7 +14,7 @@ Learn the core patterns for handling incoming events and posting messages back t
   <Card title="Posting Messages" description="Different ways to render and send messages with thread.post()." href="/docs/posting-messages" />
 </Cards>
 
-## [Adapters](/adapters)
+## Adapters
 
 Connect your bot to chat platforms and persist state across restarts.
 

package/docs/guides/durable-chat-sessions-nextjs.mdx

@@ -98,14 +98,14 @@ export type ChatTurnPayload = {
 
 ## Create the durable session workflow
 
-The workflow receives the serialized thread and first message, restores them with `bot.reviver()`, and then keeps waiting for more turns through the hook.
+The workflow receives the serialized thread and first message, restores them with `reviver`, and then keeps waiting for more turns through the hook.
 
 The important detail is that the workflow only orchestrates. Chat SDK side effects such as `post()`, `unsubscribe()`, and `setState()` stay inside step helpers:
 
 ```typescript title="workflows/durable-chat-session.ts" lineNumbers
-import { Message, type Thread } from "chat";
+import { Message, reviver, type Thread } from "chat";
 import { createHook, getWorkflowMetadata } from "workflow";
-import { bot, type ThreadState } from "@/lib/bot";
+import type { ThreadState } from "@/lib/bot";
 import type { ChatTurnPayload } from "@/workflows/chat-turn-hook";
 
 async function postAssistantMessage(
@@ -114,6 +114,7 @@ async function postAssistantMessage(
 ) {
   "use step";
 
+  const { bot } = await import("@/lib/bot");
   await bot.initialize();
   await thread.post(text);
 }
@@ -121,6 +122,7 @@ async function postAssistantMessage(
 async function closeSession(thread: Thread<ThreadState>) {
   "use step";
 
+  const { bot } = await import("@/lib/bot");
   await bot.initialize();
   await thread.post("Session closed.");
   await thread.unsubscribe();
@@ -154,7 +156,7 @@ export async function durableChatSession(payload: string) {
   "use workflow";
 
   const { workflowRunId } = getWorkflowMetadata();
-  const { thread, message } = JSON.parse(payload, bot.reviver()) as {
+  const { thread, message } = JSON.parse(payload, reviver) as {
     thread: Thread<ThreadState>;
     message: Message;
   };
@@ -186,11 +188,15 @@ export async function durableChatSession(payload: string) {
   The `using` keyword requires TypeScript 5.2+ with `"lib": ["esnext.disposable"]` in your `tsconfig.json`. If you are on an older version, call `hook.dispose()` manually when the session ends.
 </Callout>
 
+<Callout type="warn">
+  Do not import `bot` at the top level of a workflow file. Adapter packages depend on Node.js modules that are not available in the workflow sandbox. Use the standalone `reviver` for deserialization and import `bot` dynamically inside `"use step"` functions where Node.js modules are available.
+</Callout>
+
 This is the core integration:
 
 - `thread.toJSON()` and `message.toJSON()` cross the workflow boundary safely
-- `bot.reviver()` restores real Chat SDK objects inside the workflow
-- `bot.registerSingleton()` lets Workflow deserialize `Thread` objects again inside step functions
+- `reviver` restores real Chat SDK objects inside the workflow without pulling in adapter dependencies
+- `registerSingleton()` is called in `lib/bot.ts` and the singleton is available inside step functions when `bot` is dynamically imported
 - `createHook<ChatTurnPayload>({ token: workflowRunId })` makes the workflow run itself the session identifier
 - `runTurn()`, `postAssistantMessage()`, and `closeSession()` are steps, so adapter and state side effects stay outside the workflow sandbox
 
@@ -328,4 +334,4 @@ From here you can add:
 - [Handling Events](/docs/handling-events) — Mentions, subscribed messages, and routing behavior
 - [Streaming](/docs/streaming) — Stream AI SDK responses directly to chat platforms
 - [Thread API](/docs/api/thread) — `thread.toJSON()`, `thread.setState()`, and other thread primitives
-- [Chat API](/docs/api/chat) — `bot.reviver()`, initialization, and webhook access
+- [Chat API](/docs/api/chat) — `reviver`, initialization, and webhook access

package/docs/modals.mdx

@@ -6,7 +6,7 @@ prerequisites:
   - /docs/actions
 ---
 
-Modals open form dialogs in response to button clicks or [slash commands](/docs/slash-commands). They support text inputs, dropdowns, radio buttons, and server-side validation. Currently supported on Slack.
+Modals open form dialogs in response to button clicks or [slash commands](/docs/slash-commands). They support text inputs, dropdowns, radio buttons, and server-side validation. Currently supported on Slack and Teams.
 
 ## Open a modal
 

package/docs/state.mdx

@@ -8,7 +8,7 @@ prerequisites:
 
 State adapters handle persistent storage for thread subscriptions, distributed locks (to prevent duplicate processing), and caching. You must provide a state adapter when creating a `Chat` instance. Browse all available state adapters on the [Adapters](/adapters) page.
 
-## What state [adapters](/adapters) manage
+## What state adapters manage
 
 ### Thread subscriptions
 

package/docs/usage.mdx

@@ -39,7 +39,7 @@ bot.onNewMention(async (thread) => {
 
 Each adapter factory auto-detects credentials from environment variables (`SLACK_BOT_TOKEN`, `SLACK_SIGNING_SECRET`, `REDIS_URL`, etc.), so you can get started with zero config. Pass explicit values to override.
 
-## Multiple [adapters](/adapters)
+## Multiple adapters
 
 Register multiple [adapters](/adapters) to deploy your bot across platforms simultaneously:
 
@@ -76,7 +76,7 @@ Your event handlers work identically across all registered adapters — the SDK
 | `fallbackStreamingPlaceholderText` | `string \| null` | `"..."` | Placeholder text while streaming starts. Set to `null` to skip |
 | `onLockConflict` | `'drop' \| 'force' \| (threadId, message) => 'drop' \| 'force'` | `"drop"` | Behavior when a thread lock is already held. `'force'` releases the existing lock and re-acquires it, enabling interrupt/steerability for long-running handlers |
 
-## Accessing [adapters](/adapters)
+## Accessing adapters
 
 Use `getAdapter` to access platform-specific APIs when you need functionality beyond the unified interface:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chat",
-  "version": "4.25.0",
+  "version": "4.26.0",
   "description": "Unified chat abstraction for Slack, Teams, Google Chat, and Discord",
   "type": "module",
   "main": "./dist/index.js",

package/docs/adapters/whatsapp.mdx

@@ -1,222 +0,0 @@
----
-title: WhatsApp
-description: Configure the WhatsApp adapter for the WhatsApp Business Cloud API.
-type: integration
-prerequisites:
-  - /docs/getting-started
----
-
-## Installation
-
-```sh title="Terminal"
-pnpm add @chat-adapter/whatsapp
-```
-
-## Usage
-
-The adapter auto-detects `WHATSAPP_ACCESS_TOKEN`, `WHATSAPP_APP_SECRET`, `WHATSAPP_PHONE_NUMBER_ID`, and `WHATSAPP_VERIFY_TOKEN` from environment variables:
-
-```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(`You said: ${message.text}`);
-});
-```
-
-Since all WhatsApp conversations are 1:1 DMs, every incoming message is treated as a mention.
-
-## Webhook route
-
-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`.
-
-Both are handled by the same `handleWebhook` method:
-
-```typescript title="app/api/webhooks/whatsapp/route.ts" lineNumbers
-import { bot } from "@/lib/bot";
-
-export async function GET(request: Request): Promise<Response> {
-  return bot.webhooks.whatsapp(request);
-}
-
-export async function POST(request: Request): Promise<Response> {
-  return bot.webhooks.whatsapp(request);
-}
-```
-
-## Meta app setup
-
-### 1. Create a Meta app
-
-1. Go to [developers.facebook.com/apps](https://developers.facebook.com/apps)
-2. Click **Create App** and select **Business** type
-3. Give it a name and click **Create App**
-
-### 2. Add WhatsApp product
-
-1. In the app dashboard, find **WhatsApp** and click **Set Up**
-2. This creates a test phone number and sandbox environment
-
-### 3. Get credentials
-
-From the app dashboard:
-
-| Credential | Where to find it |
-|---|---|
-| **Access Token** | WhatsApp > API Setup > Temporary access token (or create a System User token for production) |
-| **Phone Number ID** | WhatsApp > API Setup > Phone number ID |
-| **App Secret** | Settings > Basic > App Secret |
-| **Verify Token** | You define this — any secret string you choose |
-
-### 4. Configure webhooks
-
-1. Go to **WhatsApp** > **Configuration** in your app dashboard
-2. Click **Edit** next to Webhook URL
-3. Set **Callback URL** to `https://your-domain.com/api/webhooks/whatsapp`
-4. Set **Verify token** to the same value as your `WHATSAPP_VERIFY_TOKEN`
-5. Click **Verify and Save**
-6. Subscribe to the **messages** webhook field
-
-### 5. Production access
-
-For production use:
-
-1. Add a real phone number under **WhatsApp** > **API Setup**
-2. Create a **System User** in Meta Business Suite for a permanent access token
-3. Complete Meta's **App Review** process for the `whatsapp_business_messaging` permission
-
-## Interactive messages
-
-Card elements are automatically converted to WhatsApp interactive messages:
-
-- **3 or fewer buttons** — rendered as WhatsApp reply buttons (title max 20 characters)
-- **More than 3 buttons** — falls back to formatted text
-
-```typescript title="lib/bot.ts" lineNumbers
-import { Card, Actions, Button, Body, BodyText } from "chat";
-
-bot.onNewMention(async (thread) => {
-  await thread.post(
-    <Card>
-      <Body>
-        <BodyText>How can I help?</BodyText>
-      </Body>
-      <Actions>
-        <Button id="help" value="help">Get Help</Button>
-        <Button id="status" value="status">Check Status</Button>
-      </Actions>
-    </Card>
-  );
-});
-```
-
-## Media attachments
-
-Incoming media messages (images, documents, audio, video, voice, stickers) are exposed as attachments with a lazy `fetchData()` function. Media is downloaded in two steps via the Graph API — first fetching the media URL, then downloading the binary data.
-
-```typescript title="lib/bot.ts" lineNumbers
-bot.onNewMention(async (thread, message) => {
-  for (const attachment of message.attachments) {
-    if (attachment.fetchData) {
-      const data = await attachment.fetchData();
-      // Process the media buffer...
-    }
-  }
-});
-```
-
-## 24-hour messaging window
-
-WhatsApp enforces a [24-hour customer service window](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-messages#customer-service-windows). You can only send free-form messages to a user within 24 hours of their last message. After that, you must use approved **message templates**.
-
-## Configuration
-
-All options are auto-detected from environment variables when not provided.
-
-| Option | Required | Description |
-|--------|----------|-------------|
-| `accessToken` | No* | Meta access token. Auto-detected from `WHATSAPP_ACCESS_TOKEN` |
-| `appSecret` | No* | App secret for webhook signature verification. Auto-detected from `WHATSAPP_APP_SECRET` |
-| `phoneNumberId` | No* | Bot's phone number ID. Auto-detected from `WHATSAPP_PHONE_NUMBER_ID` |
-| `verifyToken` | No* | Secret for webhook verification handshake. Auto-detected from `WHATSAPP_VERIFY_TOKEN` |
-| `apiVersion` | No | Graph API version (defaults to `v21.0`) |
-| `userName` | No | Bot username. Auto-detected from `WHATSAPP_BOT_USERNAME` or defaults to `whatsapp-bot` |
-| `logger` | No | Logger instance (defaults to `ConsoleLogger("info")`) |
-
-*All four credentials are required — either via config or environment variables.
-
-## Environment variables
-
-```bash title=".env.local"
-WHATSAPP_ACCESS_TOKEN=EAAx...         # Meta access token
-WHATSAPP_APP_SECRET=abc123...         # App secret for signature verification
-WHATSAPP_PHONE_NUMBER_ID=1234567890   # Phone number ID from Meta dashboard
-WHATSAPP_VERIFY_TOKEN=my-secret       # Your chosen webhook verify token
-```
-
-## Features
-
-| Feature | Supported |
-|---------|-----------|
-| Mentions | N/A (all messages are DMs) |
-| Reactions (add/remove) | Yes |
-| Cards | Interactive messages (max 3 buttons) / text fallback |
-| Modals | No |
-| Streaming | No |
-| DMs | Yes (all conversations) |
-| Ephemeral messages | No |
-| File uploads | Receive only |
-| Typing indicator | Yes |
-| Message history | No |
-| Edit message | No (throws) |
-| Delete message | No (throws) |
-
-## Thread ID format
-
-```
-whatsapp:{phoneNumberId}:{userWaId}
-```
-
-Example: `whatsapp:1234567890:15551234567`
-
-## Notes
-
-- All WhatsApp conversations are 1:1 DMs between the business phone number and the user, so every message sets `isMention: true`.
-- `editMessage()` and `deleteMessage()` throw errors — WhatsApp does not support these operations.
-- `fetchMessages()` returns empty results — WhatsApp does not provide a message history API.
-- Messages exceeding 4096 characters are automatically split at paragraph or line boundaries.
-- Webhook signatures are verified using HMAC-SHA256 with `timingSafeEqual` for timing-attack resistance.
-
-## Troubleshooting
-
-### Webhook verification failing
-
-- Verify `WHATSAPP_VERIFY_TOKEN` matches what you set in the Meta dashboard
-- Ensure both GET and POST routes are configured for the webhook URL
-
-### "Invalid signature" error
-
-- Check that `WHATSAPP_APP_SECRET` is correct (find it under Settings > Basic in your Meta app)
-- Ensure the raw request body is not parsed before verification
-
-### Bot not responding
-
-- Confirm the **messages** webhook field is subscribed in Meta dashboard
-- Check that you're within the 24-hour messaging window (or using template messages)
-- Verify the phone number ID matches your configured `WHATSAPP_PHONE_NUMBER_ID`
-
-### Media downloads failing
-
-- Ensure your access token has the required permissions
-- Check that the media hasn't expired (WhatsApp media URLs are temporary)