chat 4.19.0 → 4.20.0

package/dist/jsx-runtime.d.ts

@@ -1 +1 @@
-export { A as ActionsComponent, B as ButtonComponent, V as ButtonProps, c as CardComponent, W as CardJSXElement, X as CardJSXProps, e as CardLinkComponent, Y as CardLinkProps, Z as CardProps, a as ChatElement, _ as ContainerProps, D as DividerComponent, $ as DividerProps, F as FieldComponent, a0 as FieldProps, f as FieldsComponent, an as Fragment, I as ImageComponent, a1 as ImageProps, ao as JSX, L as LinkButtonComponent, a2 as LinkButtonProps, n as ModalComponent, a3 as ModalProps, R as RadioSelectComponent, S as SectionComponent, o as SelectComponent, p as SelectOptionComponent, a4 as SelectOptionProps, a5 as SelectProps, ai as TableComponent, ah as TableProps, T as TextComponent, q as TextInputComponent, a6 as TextInputProps, a7 as TextProps, aj as isCardLinkProps, h as isJSX, ak as jsx, am as jsxDEV, al as jsxs, t as toCardElement, k as toModalElement } from './jsx-runtime-BYavlUk9.js';
+export { A as ActionsComponent, B as ButtonComponent, V as ButtonProps, c as CardComponent, W as CardJSXElement, X as CardJSXProps, e as CardLinkComponent, Y as CardLinkProps, Z as CardProps, a as ChatElement, _ as ContainerProps, D as DividerComponent, $ as DividerProps, F as FieldComponent, a0 as FieldProps, f as FieldsComponent, an as Fragment, I as ImageComponent, a1 as ImageProps, ao as JSX, L as LinkButtonComponent, a2 as LinkButtonProps, n as ModalComponent, a3 as ModalProps, R as RadioSelectComponent, S as SectionComponent, o as SelectComponent, p as SelectOptionComponent, a4 as SelectOptionProps, a5 as SelectProps, ai as TableComponent, ah as TableProps, T as TextComponent, q as TextInputComponent, a6 as TextInputProps, a7 as TextProps, aj as isCardLinkProps, h as isJSX, ak as jsx, am as jsxDEV, al as jsxs, t as toCardElement, k as toModalElement } from './jsx-runtime-C2ATKxHQ.js';

package/dist/jsx-runtime.js

@@ -7,7 +7,7 @@ import {
   jsxs,
   toCardElement,
   toModalElement
-} from "./chunk-WAB7KMH4.js";
+} from "./chunk-JW7GYSMH.js";
 export {
   Fragment,
   isCardLinkProps,

package/docs/adapters/whatsapp.mdx

@@ -0,0 +1,222 @@
+---
+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)

package/docs/adapters.mdx

@@ -10,6 +10,60 @@ Adapters handle webhook verification, message parsing, and API calls for each pl
 
 Ready to build your own? Follow the [building](/docs/contributing/building) guide.
 
+## Feature matrix
+
+### Messaging
+
+| Feature | [Slack](/adapters/slack) | [Teams](/adapters/teams) | [Google Chat](/adapters/google-chat) | [Discord](/adapters/discord) | [Telegram](/adapters/telegram) | [GitHub](/adapters/github) | [Linear](/adapters/linear) | [WhatsApp](/adapters/whatsapp) |
+|---------|-------|-------|-------------|---------|---------|--------|--------|-----------|
+| Post message | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Edit message | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Delete message | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
+| File uploads | ✅ | ✅ | ❌ | ✅ | ⚠️ Single file | ❌ | ❌ | ✅ Images, audio, docs |
+| Streaming | ✅ Native | ⚠️ Post+Edit | ⚠️ Post+Edit | ⚠️ Post+Edit | ⚠️ Post+Edit | ❌ | ❌ | ❌ |
+| Scheduled messages | ✅ Native | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
+
+### Rich content
+
+| Feature | Slack | Teams | Google Chat | Discord | Telegram | GitHub | Linear | WhatsApp |
+|---------|-------|-------|-------------|---------|----------|--------|--------|-----------|
+| Card format | Block Kit | Adaptive Cards | Google Chat Cards | Embeds | Markdown + inline keyboard buttons | GFM Markdown | Markdown | WhatsApp templates |
+| Buttons | ✅ | ✅ | ✅ | ✅ | ⚠️ Inline keyboard callbacks | ❌ | ❌ | ✅ Interactive replies |
+| Link buttons | ✅ | ✅ | ✅ | ✅ | ⚠️ Inline keyboard URLs | ❌ | ❌ | ❌ |
+| Select menus | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Tables | ✅ Block Kit | ✅ GFM | ⚠️ ASCII | ✅ GFM | ⚠️ ASCII | ✅ GFM | ✅ GFM | ❌ |
+| Fields | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⚠️ Template variables |
+| Images in cards | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ | ✅ |
+| Modals | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
+
+### Conversations
+
+| Feature | Slack | Teams | Google Chat | Discord | Telegram | GitHub | Linear | WhatsApp |
+|---------|-------|-------|-------------|---------|----------|--------|--------|-----------|
+| Slash commands | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
+| Mentions | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
+| Add reactions | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
+| Remove reactions | ✅ | ❌ | ✅ | ✅ | ✅ | ⚠️ | ⚠️ | ❌ |
+| Typing indicator | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ |
+| DMs | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ |
+| Ephemeral messages | ✅ Native | ❌ | ✅ Native | ❌ | ❌ | ❌ | ❌ | ❌ |
+
+### Message history
+
+| Feature | Slack | Teams | Google Chat | Discord | Telegram | GitHub | Linear | WhatsApp |
+|---------|-------|-------|-------------|---------|----------|--------|--------|-----------|
+| Fetch messages | ✅ | ✅ | ✅ | ✅ | ⚠️ Cached | ✅ | ✅ | ⚠️ Cached sent messages only |
+| Fetch single message | ✅ | ❌ | ❌ | ❌ | ⚠️ Cached | ❌ | ❌ | ⚠️ Cached sent messages only |
+| Fetch thread info | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
+| Fetch channel messages | ✅ | ✅ | ✅ | ✅ | ⚠️ Cached | ✅ | ❌ | ⚠️ Cached sent messages only |
+| List threads | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ |
+| Fetch channel info | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
+| Post channel message | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ |
+
+<Callout type="info">
+⚠️ indicates partial support — the feature works with limitations. See individual adapter pages for details.
+</Callout>
+
 ## How adapters work
 
 Each adapter implements a standard interface that the `Chat` class uses to route events and send messages. When a webhook arrives:

package/docs/api/channel.mdx

@@ -104,6 +104,21 @@ await channel.post({ markdown: "**Announcement**: New release!" });
 
 Accepts the same message formats as `thread.post()` — see [PostableMessage](/docs/api/postable-message).
 
+## schedule
+
+Schedule a message for future delivery to the channel top-level. Currently only supported by the Slack adapter — other adapters throw `NotImplementedError`.
+
+```typescript
+const scheduled = await channel.schedule("Weekly reminder: update your status!", {
+  postAt: new Date("2026-03-10T09:00:00Z"),
+});
+
+// Cancel before it's sent
+await scheduled.cancel();
+```
+
+Accepts the same message formats as `channel.post()` (except streaming). See [ScheduledMessage](/docs/api/thread#scheduledmessage) for the return type.
+
 ## fetchMetadata
 
 Fetch channel metadata from the platform.

package/docs/api/index.mdx

@@ -18,6 +18,7 @@ import { Chat, root, paragraph, text, Card, Button, emoji } from "chat";
 | [`Thread`](/docs/api/thread) | Conversation thread with methods for posting, subscribing, and state |
 | [`Channel`](/docs/api/channel) | Channel/conversation container that holds threads |
 | [`Message`](/docs/api/message) | Normalized message with text, AST, author, and metadata |
+| [`ScheduledMessage`](/docs/api/thread#scheduledmessage) | Returned by `thread.schedule()` / `channel.schedule()` with `cancel()` |
 
 ## Message formats
 

package/docs/api/thread.mdx

@@ -93,6 +93,27 @@ await thread.postEphemeral(userId, "Only you can see this", {
 
 **Returns:** `Promise<EphemeralMessage | null>`
 
+## schedule
+
+Schedule a message for future delivery. Currently only supported by the Slack adapter — other adapters throw `NotImplementedError`.
+
+```typescript
+const scheduled = await thread.schedule("Reminder: standup in 5 minutes!", {
+  postAt: new Date("2026-03-09T09:00:00Z"),
+});
+
+// Cancel before it's sent
+await scheduled.cancel();
+```
+
+**Parameters:** `message: string | PostableMessage | CardJSXElement`, `options: { postAt: Date }`
+
+**Returns:** `Promise<ScheduledMessage>`
+
+<Callout type="warn">
+Streaming and file uploads are not supported in scheduled messages.
+</Callout>
+
 ## subscribe / unsubscribe
 
 Manage thread subscriptions. Subscribed threads route all messages to `onSubscribedMessage` handlers.
@@ -190,6 +211,35 @@ await data.thread.post("Hello from workflow!");
 
 Under the hood, the reviver calls `ThreadImpl.fromJSON()` and `Message.fromJSON()` for any serialized objects it encounters.
 
+## ScheduledMessage
+
+Returned by `thread.schedule()` and `channel.schedule()`.
+
+<TypeTable
+  type={{
+    scheduledMessageId: {
+      description: 'Platform-specific scheduled message ID.',
+      type: 'string',
+    },
+    channelId: {
+      description: 'Channel ID where the message will be posted.',
+      type: 'string',
+    },
+    postAt: {
+      description: 'When the message will be sent.',
+      type: 'Date',
+    },
+    raw: {
+      description: 'Platform-specific raw response.',
+      type: 'unknown',
+    },
+    'cancel()': {
+      description: 'Cancel the scheduled message before it is sent.',
+      type: '() => Promise<void>',
+    },
+  }}
+/>
+
 ## SentMessage
 
 Returned by `thread.post()`. Extends `Message` with mutation methods.

package/docs/contributing/building.mdx

@@ -542,6 +542,7 @@ These methods are not required but extend your adapter's capabilities:
 | `fetchMessage(threadId, messageId)` | Fetch a single message by ID |
 | `fetchChannelMessages(channelId)` | Fetch top-level channel messages |
 | `channelIdFromThreadId(threadId)` | Extract channel ID from a thread ID |
+| `scheduleMessage(threadId, message, options)` | Schedule a message for future delivery; return a `ScheduledMessage` with `cancel()` |
 
 Implement only the methods your platform supports. The SDK gracefully handles missing optional methods.
 

package/docs/error-handling.mdx

@@ -66,7 +66,7 @@ try {
 
 ### NotImplementedError
 
-Thrown when you call a feature that a platform doesn't support. For example, calling `addReaction()` on Teams.
+Thrown when you call a feature that a platform doesn't support. For example, calling `addReaction()` on Teams or `schedule()` on adapters without native scheduling support.
 
 ```typescript title="lib/bot.ts" lineNumbers
 import { NotImplementedError } from "chat";

package/docs/getting-started.mdx

@@ -29,6 +29,8 @@ Step-by-step tutorials to get up and running on your platform of choice.
 
 <Cards>
   <Card title="Slack bot with Next.js and Redis" description="Build a Slack bot from scratch using Chat SDK, Next.js, and Redis." href="/docs/guides/slack-nextjs" />
+  <Card title="Durable chat sessions with Next.js, Workflow, and Redis" description="Build a bot whose thread sessions survive restarts by combining Chat SDK with Workflow." href="/docs/guides/durable-chat-sessions-nextjs" />
+  <Card title="Schedule Slack posts with Next.js, Workflow, and Neon" description="Build durable scheduled posts backed by Neon and Workflow timers." href="/docs/guides/scheduled-posts-neon" />
   <Card title="Code review GitHub bot with Hono and Redis" description="Build a GitHub bot that reviews pull requests using AI SDK, Vercel Sandbox, and Chat SDK." href="/docs/guides/code-review-hono" />
   <Card title="Discord support bot with Nuxt and Redis" description="Build a Discord support bot using Chat SDK, Nuxt, and AI SDK." href="/docs/guides/discord-nuxt" />
 </Cards>