chat 4.29.0 → 4.31.0

package/docs/concurrency.mdx

@@ -5,7 +5,7 @@ type: guide
 prerequisites:
   - /docs/handling-events
 related:
-  - /docs/state
+  - /docs/state-adapters
   - /docs/streaming
 ---
 

package/docs/contributing/building.mdx

@@ -36,6 +36,10 @@ Chat SDK ships with Vercel-maintained adapters for Slack, Teams, Google Chat, Di
 - Documentation of the adapter in primary vendor docs.
 - Announcement of the adapter in blog post or changelog and social media.
 
+<Callout type="info">
+  Vendor-official adapters should include a Chat SDK docs PR that adds the adapter to the vendor-official listing and the [`chat/adapters` catalog](/docs/adapters#adapter-catalog-chatadapters). Include the package name, peer dependencies, environment variables, credential modes, and any constructor-only config so setup UIs and onboarding tools can discover the adapter without importing its package.
+</Callout>
+
 ## Project setup
 
 This guide uses a hypothetical **Matrix** adapter as a running example. Replace "matrix" with your platform name throughout.
@@ -339,6 +343,8 @@ async handleWebhook(
 
 Convert the raw platform message into a normalized `Message` instance. The `author` fields use `userId` and `userName`, and `isBot` accepts `boolean | "unknown"`. Include a `metadata` object with `dateSent` and `edited` instead of a top-level `createdAt`.
 
+Set `author.isMe` only when the message was sent by this adapter runtime and should be ignored by Chat SDK's handler dispatch. Do not map a platform "sent from my account" flag directly to `isMe` unless that account is the bot identity. For user-owned account adapters, keep user-authored messages as `isMe: false` and track message IDs returned by `postMessage`; if the platform echoes one of those IDs through the webhook, mark that echo as `isMe: true` and `isBot: true`.
+
 ```typescript title="src/adapter.ts" lineNumbers
 parseMessage(raw: unknown): Message<unknown> {
   const payload = raw as Record<string, unknown>;

package/docs/conversation-history.mdx

@@ -3,7 +3,7 @@ title: Conversation History
 description: Persist messages per user across every platform — for LLM context, audit, or compliance.
 type: guide
 prerequisites:
-  - /docs/state
+  - /docs/state-adapters
 related:
   - /docs/handling-events
   - /docs/api/transcripts

package/docs/create-chat-sdk.mdx

@@ -0,0 +1,143 @@
+---
+title: CLI
+description: Scaffold a Chat SDK bot app with a single command.
+---
+
+`create-chat-sdk` creates a minimal Next.js app for Chat SDK bots.
+
+The CLI will generate your `Chat` configuration, webhook route, `.env.example` file, dependencies, and optional Web adapter route from the adapter catalog.
+
+## Quick start
+
+<CodeBlockTabs defaultValue="npm">
+  <CodeBlockTabsList>
+    <CodeBlockTabsTrigger value="npm">npm</CodeBlockTabsTrigger>
+    <CodeBlockTabsTrigger value="pnpm">pnpm</CodeBlockTabsTrigger>
+    <CodeBlockTabsTrigger value="yarn">yarn</CodeBlockTabsTrigger>
+    <CodeBlockTabsTrigger value="bun">bun</CodeBlockTabsTrigger>
+  </CodeBlockTabsList>
+  <CodeBlockTab value="npm">
+```bash
+npm create chat-sdk@latest my-bot
+```
+  </CodeBlockTab>
+  <CodeBlockTab value="pnpm">
+```bash
+pnpm create chat-sdk@latest my-bot
+```
+  </CodeBlockTab>
+  <CodeBlockTab value="yarn">
+```bash
+yarn create chat-sdk my-bot
+```
+  </CodeBlockTab>
+  <CodeBlockTab value="bun">
+```bash
+bunx create-chat-sdk@latest my-bot
+```
+  </CodeBlockTab>
+</CodeBlockTabs>
+
+<Callout type="info">
+  `create-chat-sdk` automatically detects when it is being run by Cursor, Claude Code, or another coding agent. In agent environments, pass at least one platform adapter with `--adapter`; the state adapter defaults to `memory`. The CLI runs non-interactively and uses `my-bot` when no project name is provided. Pass `--interactive` to force prompts.
+</Callout>
+
+## Non-interactive usage
+
+Pass platform and state adapters with `--adapter`:
+
+```bash
+npm create chat-sdk@latest -- my-bot --adapter slack redis -y
+```
+
+<Callout type="warn">
+  With npm, the `--` separator is required because npm consumes flags before it (`-y` is npm's own `--yes`) instead of forwarding them to the CLI. `pnpm create` and `yarn create` forward flags without it.
+</Callout>
+
+The interactive prompt lists official adapters by default. Pass `--vendor` to list only vendor-official adapters instead. Automation and coding agents can install any CLI-supported official or vendor adapter directly with `--adapter`.
+
+Adapters that require a long-running process, including Matrix and Lark, cannot run on the webhook-only serverless runtime and are not available through the CLI. Add them to an existing project manually instead.
+
+<AdapterSlugList />
+
+Examples:
+
+```bash
+npm create chat-sdk@latest -- slack-bot --adapter slack memory -y --skip-install
+npm create chat-sdk@latest -- gchat-bot --adapter gchat redis -y --pm pnpm
+npm create chat-sdk@latest -- email-bot --adapter resend postgres -y --no-git
+npm create chat-sdk@latest -- my-bot --adapter slack memory -y --force
+```
+
+## What gets generated
+
+The scaffolded app is webhook-only. It does not include pages, layouts, or a client UI.
+
+```txt
+src/
+  lib/bot.ts                              Bot configuration and handlers
+  app/api/webhooks/[platform]/route.ts    Dynamic platform webhook route
+  app/api/chat/route.ts                   Web adapter route, only when selected
+  app/api/discord/gateway/route.ts        Discord Gateway listener, only when selected
+.env.example                              Required environment variables
+next.config.ts                            Next.js server config
+vercel.json                               Cron schedules, only when needed
+.chat-sdk.json                            Generated file ownership for safe reruns
+package.json                              Adapter dependencies
+```
+
+Webhook endpoints use the selected adapter slug:
+
+```txt
+/api/webhooks/slack
+/api/webhooks/gchat
+/api/webhooks/discord
+```
+
+When the [Web adapter](/adapters/official/web) is selected, the CLI also creates `/api/chat` for browser chat requests and a small `getUser` auth stub. Replace the stub with your app's real authentication logic so each web conversation can be associated with the correct user.
+
+When the [Discord adapter](/adapters/official/discord) is selected, the CLI also creates a Gateway listener at `/api/discord/gateway` and a `vercel.json` cron that calls it. Discord delivers slash commands and button clicks to the webhook route, but regular messages and reactions only arrive over the Gateway WebSocket, so the cron keeps that connection alive and forwards events to `/api/webhooks/discord`. Set a `CRON_SECRET` environment variable to authenticate the cron requests. The generated serverless Gateway cron requires [Vercel Pro or Enterprise](https://vercel.com/docs/cron-jobs/usage-and-pricing) because it runs every nine minutes.
+
+## Reference
+
+| Option | Description |
+| --- | --- |
+| `[name]` | Name of the project. |
+| `-d, --description <text>` | Project description. |
+| `--adapter <values...>` | Platform or state adapters to include. |
+| `--vendor` | List only vendor-official adapters in the interactive prompt. |
+| `--pm <manager>` | Package manager to use: `npm`, `yarn`, `pnpm`, or `bun`. |
+| `-y, --yes` | Skip prompts and accept defaults. |
+| `--interactive` | Always prompt, even when a coding agent environment is detected. |
+| `-f, --force` | Overwrite generated files in an existing directory. |
+| `-s, --skip-install` | Skip dependency installation. |
+| `--no-git` | Skip git repository initialization. |
+| `-q, --quiet` | Suppress non-essential output. |
+
+Color output follows the [NO_COLOR standard](https://no-color.org/) — set `NO_COLOR=1` to disable colors.
+
+## Customize your bot
+
+Most bot behavior lives in `src/lib/bot.ts`. Start there when you want to:
+
+- Add or change handlers like `onNewMention`, `onSubscribedMessage`, `onNewMessage`, reactions, actions, or slash commands.
+- Adjust adapter configuration, for example passing explicit credentials or platform-specific options instead of relying only on environment variables.
+- If you selected the memory state adapter, switch to Redis, ioredis, or PostgreSQL before deploying to production.
+
+The generated file includes starter handlers for mentions and subscribed thread replies.
+
+## Next steps
+
+After scaffolding:
+
+```bash
+cd my-bot
+cp .env.example .env.local
+npm run dev
+```
+
+Fill in the generated environment variables, expose your local server, and configure each selected platform to call its `/api/webhooks/{adapter}` endpoint.
+
+## Resources
+
+See guides, templates, and examples on the [resources](/resources) page.

package/docs/error-handling.mdx

@@ -105,7 +105,7 @@ try {
   }}
 />
 
-See the [feature matrix](/docs/adapters) for which features are supported on each platform.
+See the [feature matrix](/docs/platform-adapters) for which features are supported on each platform.
 
 ### LockError
 

package/docs/getting-started.mdx

@@ -19,10 +19,14 @@ Learn the core patterns for handling incoming events and posting messages back t
 Connect your bot to chat platforms and persist state across restarts.
 
 <Cards>
-  <Card title="Platform Adapters" description="Platform-specific adapters for Slack, Teams, Google Chat, Discord, Telegram, GitHub, and Linear." href="/docs/adapters" />
-  <Card title="State Adapters" description="Pluggable state adapters for thread subscriptions, distributed locking, and caching." href="/docs/state" />
+  <Card title="Platform Adapters" description="Platform-specific adapters for Slack, Teams, Google Chat, Discord, Telegram, GitHub, and Linear." href="/docs/platform-adapters" />
+  <Card title="State Adapters" description="Pluggable state adapters for thread subscriptions, distributed locking, and caching." href="/docs/state-adapters" />
 </Cards>
 
 Browse all official and community adapters on the [Adapters](/adapters) page.
 
-Step-by-step guides and starter templates are available on the [Resources](/resources) page.
+## Resources
+
+- [The Complete Guide to Chat SDK](https://vercel.com/kb/guide/the-complete-guide-to-chat-sdk?utm_source=chat-sdk_site&utm_medium=docs&utm_campaign=getting-started&utm_content=the-complete-guide-to-chat-sdk) — End-to-end walkthrough that takes you from zero to a deployed multi-platform bot, covering adapters, state, handlers, cards, and streaming.
+
+See all guides and templates on the [resources](/resources?utm_source=chat-sdk_site&utm_medium=docs&utm_campaign=getting-started&utm_content=resources) page.

package/docs/index.mdx

@@ -55,10 +55,11 @@ Each adapter factory auto-detects credentials from environment variables (`SLACK
 | Microsoft Teams | `@chat-adapter/teams` | Yes | Read-only | Yes | Yes | Native (DMs) / Buffered | Yes |
 | Google Chat | `@chat-adapter/gchat` | Yes | Yes | Yes | No | Post+Edit | Yes |
 | Discord | `@chat-adapter/discord` | Yes | Yes | Yes | No | Post+Edit | Yes |
-| Telegram | `@chat-adapter/telegram` | Yes | Yes | Partial | No | Post+Edit | Yes |
+| Telegram | `@chat-adapter/telegram` | Yes | Yes | Partial | No | Rich drafts / Post+Edit | Yes |
 | GitHub | `@chat-adapter/github` | Yes | Yes | No | No | Buffered | No |
 | Linear | `@chat-adapter/linear` | Yes | Yes | No | No | Agent sessions / Post+Edit | No |
 | WhatsApp | `@chat-adapter/whatsapp` | N/A | Yes | Partial | No | Buffered | Yes |
+| Twilio | `@chat-adapter/twilio` | N/A | No | Fallback | No | Buffered | Yes |
 | Messenger | `@chat-adapter/messenger` | Yes | Receive-only | Partial | No | Buffered | Yes |
 
 ## AI coding agent support
@@ -87,6 +88,7 @@ The SDK is distributed as a set of packages you install based on your needs:
 | `@chat-adapter/github` | GitHub Issues adapter |
 | `@chat-adapter/linear` | Linear Issues adapter |
 | `@chat-adapter/whatsapp` | WhatsApp Business adapter |
+| `@chat-adapter/twilio` | Twilio SMS and MMS adapter |
 | `@chat-adapter/messenger` | Facebook Messenger adapter |
 | `@chat-adapter/state-redis` | Redis state adapter (production) |
 | `@chat-adapter/state-ioredis` | ioredis state adapter (alternative) |

package/docs/meta.json

@@ -3,6 +3,7 @@
   "pages": [
     "index",
     "getting-started",
+    "create-chat-sdk",
     "---Usage---",
     "usage",
     "threads-messages-channels",
@@ -14,7 +15,10 @@
     "...ai",
     "---Adapters---",
     "adapters",
-    "state",
+    "platform-adapters",
+    "slack-primitives",
+    "teams-primitives",
+    "state-adapters",
     "---Messaging---",
     "streaming",
     "direct-messages",

package/docs/platform-adapters.mdx

@@ -0,0 +1,148 @@
+---
+title: Platform Adapters
+description: Platform-specific adapters that connect your bot to any messaging platform.
+type: overview
+prerequisites:
+  - /docs/getting-started
+  - /docs/adapters
+---
+
+Platform adapters handle webhook verification, message parsing, and API calls for each messaging platform. Install only the adapters you need. Browse all available adapters, including community-built ones, on the [Adapters](/adapters) page.
+
+Need a browser chat UI? See the [Web adapter](/adapters/official/web). It speaks the AI SDK UI stream protocol and works with React (`@ai-sdk/react`), Vue (`@ai-sdk/vue`), and Svelte (`@ai-sdk/svelte`), so the same bot serves Slack, Teams, and any browser framework out of the box.
+
+Ready to build your own? Follow the [building](/docs/contributing/building) guide.
+
+## Feature matrix
+
+<GlobalFeatureMatrix type="platform" />
+
+### Messaging
+
+| Feature | [Slack](/adapters/slack) | [Teams](/adapters/teams) | [Google Chat](/adapters/gchat) | [Discord](/adapters/discord) | [Telegram](/adapters/telegram) | [GitHub](/adapters/github) | [Linear](/adapters/linear) | [WhatsApp](/adapters/whatsapp) | [Messenger](/adapters/messenger) |
+|---------|-------|-------|-------------|---------|---------|--------|--------|-----------|-----------|
+| Post message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> |
+| Edit message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Partial | <Cross /> | <Cross /> |
+| Delete message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Partial | <Cross /> | <Cross /> |
+| File uploads | <Check /> | <Check /> | <Cross /> | <Check /> | <Warn /> Single file/media | <Cross /> | <Cross /> | <Check /> Images, audio, docs | <Cross /> |
+| Streaming | <Check /> Native | <Warn /> Native (DMs) / Buffered | <Warn /> Post+Edit | <Warn /> Post+Edit | <Warn /> Rich drafts / Post+Edit | <Warn /> Buffered | <Warn /> Agent sessions / Post+Edit | <Warn /> Buffered | <Warn /> Buffered |
+| Scheduled messages | <Check /> Native | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
+
+### Rich content
+
+| Feature | Slack | Teams | Google Chat | Discord | Telegram | GitHub | Linear | WhatsApp | Messenger |
+|---------|-------|-------|-------------|---------|----------|--------|--------|-----------|-----------|
+| Card format | Block Kit | Adaptive Cards | Google Chat Cards | Embeds | Markdown + inline keyboard buttons | GFM Markdown | Markdown | WhatsApp templates | Generic/Button Templates |
+| Buttons | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Inline keyboard callbacks | <Cross /> | <Cross /> | <Check /> Interactive replies | <Warn /> Max 3, postback |
+| Link buttons | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Inline keyboard URLs | <Cross /> | <Cross /> | <Cross /> | <Check /> |
+| Select menus | <Check /> | <Cross /> | <Check /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
+| Tables | <Check /> Block Kit | <Check /> GFM | <Warn /> ASCII | <Check /> GFM | <Warn /> Native messages / ASCII cards | <Check /> GFM | <Check /> GFM | <Cross /> | <Warn /> ASCII |
+| Fields | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Template variables | <Warn /> ASCII |
+| Images in cards | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Check /> | <Cross /> | <Check /> | <Check /> |
+| Modals | <Check /> | <Check /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
+
+### Conversations
+
+| Feature | Slack | Teams | Google Chat | Discord | Telegram | GitHub | Linear | WhatsApp | Messenger |
+|---------|-------|-------|-------------|---------|----------|--------|--------|-----------|-----------|
+| Slash commands | <Check /> | <Cross /> | <Cross /> | <Check /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
+| Mentions | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Check /> |
+| Add reactions | <Check /> | <Cross /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> |
+| Remove reactions | <Check /> | <Cross /> | <Check /> | <Check /> | <Check /> | <Warn /> | <Warn /> | <Check /> | <Cross /> |
+| Typing indicator | <Check /> | <Check /> | <Cross /> | <Check /> | <Check /> | <Cross /> | <Warn /> Agent sessions | <Warn /> | <Check /> |
+| DMs | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Cross /> | <Check /> | <Check /> |
+| Ephemeral messages | <Check /> Native | <Cross /> | <Check /> Native | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
+| User lookup ([`getUser`](/docs/api/chat#getuser)) | <Check /> | <Warn /> Cached | <Warn /> Cached | <Check /> | <Warn /> Seen users | <Check /> | <Check /> | <Cross /> | <Cross /> |
+| Parent subject ([`message.subject`](/docs/subject)) | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Check /> | <Check /> | <Cross /> | <Cross /> |
+| Native client ([`.webClient` / `.octokit` / `.linearClient`](/docs/api/chat#getadapter)) | <Check /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Check /> | <Check /> | <Cross /> | <Cross /> |
+| Custom API endpoint (`apiUrl`) | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> |
+
+### Message history
+
+| Feature | Slack | Teams | Google Chat | Discord | Telegram | GitHub | Linear | WhatsApp | Messenger |
+|---------|-------|-------|-------------|---------|----------|--------|--------|-----------|-----------|
+| Fetch messages | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Cached | <Check /> | <Check /> | <Warn /> Cached sent messages only | <Warn /> Cached sent messages only |
+| Fetch single message | <Check /> | <Cross /> | <Cross /> | <Cross /> | <Warn /> Cached | <Cross /> | <Cross /> | <Cross /> | <Warn /> Cached |
+| Fetch thread info | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> |
+| Fetch channel messages | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Cached | <Check /> | <Cross /> | <Cross /> | <Warn /> Cached |
+| List threads | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Check /> | <Cross /> | <Cross /> | <Cross /> |
+| Fetch channel info | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Cross /> | <Check /> |
+| Post channel message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Cross /> | <Check /> | <Check /> |
+
+<Callout type="info">
+<Warn /> 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:
+
+1. The adapter verifies the request signature
+2. Parses the platform-specific payload into a normalized `Message`
+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
+
+Register multiple [adapters](/adapters) and your event handlers work across all of them:
+
+```typescript title="lib/bot.ts" lineNumbers
+import { Chat } from "chat";
+import { createSlackAdapter } from "@chat-adapter/slack";
+import { createTeamsAdapter } from "@chat-adapter/teams";
+import { createGoogleChatAdapter } from "@chat-adapter/gchat";
+import { createRedisState } from "@chat-adapter/state-redis";
+
+const bot = new Chat({
+  userName: "mybot",
+  adapters: {
+    slack: createSlackAdapter(),
+    teams: createTeamsAdapter(),
+    gchat: createGoogleChatAdapter(),
+  },
+  state: createRedisState(),
+});
+
+// This handler fires for mentions on any platform
+bot.onNewMention(async (thread) => {
+  await thread.subscribe();
+  await thread.post("Hello!");
+});
+```
+
+Each adapter auto-detects credentials from environment variables, so you only need to pass config when overriding defaults.
+
+<Callout type="info">
+  The examples above use Redis for state. See [State Adapters](/docs/state-adapters) for all available options.
+</Callout>
+
+Each adapter creates a webhook handler accessible via `bot.webhooks.<name>`.
+
+## Customizing an adapter via subclassing
+
+Each official adapter exposes its extension surface as `protected` members so you can subclass it to override or extend platform-specific behavior without forking the package. Use this when you need to handle a payload type the built-in adapter doesn't cover, intercept verification, or wrap an existing handler.
+
+```typescript title="lib/custom-telegram.ts" lineNumbers
+import { TelegramAdapter, type TelegramUpdate } from "@chat-adapter/telegram";
+import type { WebhookOptions } from "chat";
+
+export class CustomTelegramAdapter extends TelegramAdapter {
+  protected override processUpdate(
+    update: TelegramUpdate,
+    options?: WebhookOptions
+  ): void {
+    // Handle a payload type the base adapter doesn't, e.g. chat_join_request.
+    if ("chat_join_request" in update) {
+      this.logger.info("Received chat_join_request", { update });
+      return;
+    }
+    super.processUpdate(update, options);
+  }
+}
+```
+
+Construct your subclass anywhere you'd construct the base adapter, for example, `adapters: { telegram: new CustomTelegramAdapter({ ... }) }`. Members marked `private` intentionally remain inaccessible. If you find a hook you need that isn't `protected`, please open an issue.
+
+<Callout type="warn">
+  The `protected` extension surface is intentionally broader than the public API but is not yet considered fully stable. Method signatures may evolve in minor releases as we learn from real-world subclasses. Pin the adapter version you build against, watch the changelog for the affected adapter, and prefer overriding the smallest hook that solves your problem so upgrades stay easy. If you rely on a particular hook, please open an issue so we can promote it to a stable, documented extension point.
+</Callout>