| name | chat-sdk |
| description | Build multi-platform chat bots with Chat SDK (`chat` npm package). Use when developers want to scaffold a bot with create-chat-sdk, build a Slack, Teams, Google Chat, Discord, Telegram, GitHub, Linear, or WhatsApp bot, handle mentions, direct messages, subscribed threads, reactions, slash commands, cards, modals, files, or AI streaming, set up webhook routes or multi-adapter bots, send rich cards or streamed AI responses to chat platforms, or build a custom adapter or state adapter. |
Chat SDK
Unified TypeScript SDK for building chat bots across Slack, Teams, Google Chat, Discord, Telegram, GitHub, Linear, and WhatsApp. Write bot logic once, deploy everywhere.
Scaffold a new project
Use create-chat-sdk with explicit adapters so coding agents can scaffold a webhook-only Next.js bot project without prompts:
npm create chat-sdk@latest -- my-bot --adapter slack memory -y
Non-interactive example:
npm create chat-sdk@latest -- my-bot --adapter slack redis -d "My bot" --pm pnpm -y
With npm, the -- separator is required — npm consumes the flags itself instead of forwarding them to the CLI. pnpm create and yarn create forward flags without it.
Key flags:
--adapter <values...> — platform or state adapters from chat/adapters-d, --description <text> — project description--pm <manager> — package manager (npm, yarn, pnpm, 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
When create-chat-sdk detects a coding agent environment, it automatically uses non-interactive defaults. Pass at least one platform adapter with --adapter; the state adapter defaults to memory. If no project name is provided, it uses my-bot.
Generated projects include src/lib/bot.ts, src/app/api/webhooks/[platform]/route.ts, .env.example, next.config.ts, and adapter dependencies. If the Web adapter is selected, the CLI also creates src/app/api/chat/route.ts and src/lib/auth-stub.ts.
Start with published sources
When Chat SDK is installed in a user project, inspect the published files that ship in node_modules:
node_modules/chat/docs/ # bundled docs
node_modules/chat/dist/index.d.ts # core API types
node_modules/chat/dist/adapters/index.d.ts # static adapter catalog types
node_modules/chat/dist/jsx-runtime.d.ts # JSX runtime types
node_modules/chat/docs/contributing/ # adapter-authoring docs
node_modules/chat/resources/guides/ # framework/platform guides (markdown)
node_modules/chat/resources/templates.json # starter templates (title, description, href)
If one of the paths below does not exist, that package is not installed in the project yet.
Read these before writing code:
node_modules/chat/docs/getting-started.mdx — install and setupnode_modules/chat/docs/usage.mdx — Chat config and lifecyclenode_modules/chat/docs/handling-events.mdx — event routing and handlersnode_modules/chat/docs/threads-messages-channels.mdx — thread/channel/message modelnode_modules/chat/docs/posting-messages.mdx — post, edit, delete, schedulenode_modules/chat/docs/streaming.mdx — AI SDK integration and streaming semanticsnode_modules/chat/docs/cards.mdx — JSX cardsnode_modules/chat/docs/actions.mdx — button/select interactionsnode_modules/chat/docs/modals.mdx — modal submit/close flowsnode_modules/chat/docs/slash-commands.mdx — slash command routingnode_modules/chat/docs/direct-messages.mdx — DM behavior and openDM()node_modules/chat/docs/files.mdx — attachments/uploadsnode_modules/chat/docs/state-adapters.mdx — persistence, locking, dedupenode_modules/chat/docs/adapters.mdx — cross-platform feature matrixnode_modules/chat/docs/api/chat.mdx — exact Chat APInode_modules/chat/docs/api/thread.mdx — exact Thread APInode_modules/chat/docs/api/message.mdx — exact Message APInode_modules/chat/docs/api/modals.mdx — modal element and event details
For the specific adapter or state package you are using, inspect that installed package's dist/index.d.ts export surface in node_modules.
Adapter catalog subpath
Chat SDK exposes a zero-dependency static catalog at chat/adapters. Agents can import ADAPTERS, ADAPTER_NAMES, getAdapter, isAdapterSlug, listEnvVars, getSecretEnvVars, and metadata types like CatalogAdapter and AdapterSlug from this subpath without importing any adapter implementation package.
Use it for:
- Listing official and vendor-official adapter slugs, names, npm packages, groups, and platform vs state types.
- Building setup or onboarding flows that need package names, peer dependencies, and install guidance before any adapter is installed.
- Discovering required, optional, and credential-mode environment variables for an adapter, including which variables are secrets.
- Keeping vendor-official adapter docs and metadata aligned with the catalog when adding or updating a listed adapter.
Available resources
Guides
node_modules/chat/resources/guides/how-to-build-an-ai-agent-for-slack-with-chat-sdk-and-ai-sdk.md — Build a Slack AI agent using Chat SDK, AI SDK's ToolLoopAgent, and Vercel AI Gateway. Covers project setup, tool definitions, streaming responses, deployment to Vercel, and scaling tool selection with toolpick.node_modules/chat/resources/guides/human-in-the-loop-with-chat-sdk-and-workflow-sdk.md — Pause durable workflows on Slack approval cards using Chat SDK and Workflow SDK. Uses createWebhook to suspend workflows until a button click, with patterns for multi-stage approvals, timeouts via durable sleep, and approver validation.node_modules/chat/resources/guides/liveblocks-chat-sdk-ai-sdk.md — Build an AI agent that replies to @-mentions in Liveblocks comment threads with streamed responses and tool calling. Uses Chat SDK, the Liveblocks adapter, AI SDK's ToolLoopAgent, and Redis for thread subscriptions and distributed locking.node_modules/chat/resources/guides/slack-bot-vercel-blob.md — Build a Slack bot that lists, reads, uploads, and deletes files in Vercel Blob through tool calls. Uses Chat SDK, AI SDK's ToolLoopAgent, and Files SDK's createFileTools factory with approval-gated write tools and a read-only mode.node_modules/chat/resources/guides/run-and-track-deploys-from-slack.md — Build a Slack deploy bot with Chat SDK and Vercel Workflow. Dispatch GitHub Actions from a slash command, gate production behind approval, poll for completion, and notify Linear and GitHub when the run finishes.node_modules/chat/resources/guides/triage-form-submissions-with-chat-sdk.md — Build a Slack bot that triages form submissions with interactive cards. Forward, edit, or mark as spam without leaving Slack. Built with Chat SDK, Hono, and Resend.node_modules/chat/resources/guides/how-to-build-a-slack-bot-with-next-js-and-redis.md — This guide walks through building a Slack bot with Next.js, covering project setup, Slack app configuration, event handling, interactive features, and deployment.node_modules/chat/resources/guides/create-a-discord-support-bot-with-nuxt-and-redis.md — This guide walks through building a Discord support bot with Nuxt, covering project setup, Discord app configuration, Gateway forwarding, AI-powered responses, and deployment.node_modules/chat/resources/guides/ship-a-github-code-review-bot-with-hono-and-redis.md — This guide walks through building a GitHub bot that reviews pull requests on demand. When a user @mentions the bot on a PR, Chat SDK picks up the mention, spins up a Vercel Sandbox with the repo cloned, and uses AI SDK to analyze the diff.node_modules/chat/resources/guides/build-a-slack-bot-with-vercel-connect.md — Learn how to build your very own Slackbot with Chat SDK and AI SDK. Vercel Connect supplies runtime Slack tokens and forwards triggers, so you never store a long-lived bot token.
Templates
Listed in node_modules/chat/resources/templates.json:
Quick start
import { Chat } from "chat";
import { createSlackAdapter } from "@chat-adapter/slack";
import { createRedisState } from "@chat-adapter/state-redis";
const bot = new Chat({
userName: "mybot",
adapters: {
slack: createSlackAdapter(),
},
state: createRedisState(),
dedupeTtlMs: 600_000,
});
bot.onNewMention(async (thread) => {
await thread.subscribe();
await thread.post("Hello! I'm listening to this thread.");
});
bot.onSubscribedMessage(async (thread, message) => {
await thread.post(`You said: ${message.text}`);
});
Core concepts
- Chat — main entry point; coordinates adapters, routing, locks, and state
- Adapters — platform-specific integrations for Slack, Teams, Google Chat, Discord, Telegram, GitHub, Linear, and WhatsApp
- State adapters — persistence for subscriptions, locks, dedupe, and thread state
- Thread — conversation context with
post(), stream(), subscribe(), setState(), startTyping()
- Message — normalized content with
text, formatted, attachments, author info, and platform raw
- Channel — container for threads and top-level posts
Event handlers
| Handler | Trigger |
|---|
onNewMention | Bot @-mentioned in an unsubscribed thread |
onDirectMessage | New DM in an unsubscribed DM thread |
onSubscribedMessage | Any message in a subscribed thread |
onNewMessage(regex) | Regex match in an unsubscribed thread |
onReaction(emojis?) | Emoji added or removed |
onAction(actionIds?) | Button clicks and select/radio interactions |
onModalSubmit(callbackId?) | Modal form submitted |
onModalClose(callbackId?) | Modal dismissed/cancelled |
onSlashCommand(commands?) | Slash command invocation |
onAssistantThreadStarted | Slack assistant thread opened |
onAssistantContextChanged | Slack assistant context changed |
onAppHomeOpened | Slack App Home opened |
onMemberJoinedChannel | Slack member joined channel event |
Read node_modules/chat/docs/handling-events.mdx, node_modules/chat/docs/actions.mdx, node_modules/chat/docs/modals.mdx, and node_modules/chat/docs/slash-commands.mdx before wiring handlers. onDirectMessage behavior is documented in node_modules/chat/docs/direct-messages.mdx.
Streaming
Pass any AsyncIterable<string> to thread.post(). For AI SDK, prefer result.fullStream over result.textStream when available so step boundaries are preserved.
import { ToolLoopAgent } from "ai";
const agent = new ToolLoopAgent({ model: "anthropic/claude-4.5-sonnet" });
bot.onNewMention(async (thread, message) => {
const result = await agent.stream({ prompt: message.text });
await thread.post(result.fullStream);
});
Key details:
streamingUpdateIntervalMs controls post+edit fallback cadencefallbackStreamingPlaceholderText defaults to "..."; set null to disable- Structured
StreamChunk support is Slack-only; other adapters ignore non-text chunks
Cards and modals (JSX)
Set jsxImportSource: "chat" in tsconfig.json.
Card components:
Card, CardText, Section, Fields, Field, Button, CardLink, LinkButton, Actions, Select, SelectOption, RadioSelect, Table, Image, Divider
Modal components:
Modal, TextInput, Select, SelectOption, RadioSelect
Button and Modal accept a callbackUrl prop — when triggered, the SDK POSTs the action payload to that URL in addition to firing any onAction / onModalSubmit handler. Use this for webhook-based workflow flows. See node_modules/chat/docs/actions.mdx and node_modules/chat/docs/modals.mdx.
await thread.post(
<Card title="Order #1234">
<CardText>Your order has been received.</CardText>
<Actions>
<Button id="approve" style="primary">Approve</Button>
<Button id="reject" style="danger">Reject</Button>
</Actions>
</Card>
);
Adapter inventory
See chat-sdk.dev/adapters for the current list of official, vendor-official, and community adapters, including package names and authors. For the exact factory function and config types of an installed adapter, inspect its dist/index.d.ts in node_modules.
Building a custom adapter
Read these published docs first:
node_modules/chat/docs/contributing/building.mdxnode_modules/chat/docs/contributing/testing.mdxnode_modules/chat/docs/contributing/publishing.mdx
Also inspect:
node_modules/chat/dist/index.d.ts — Adapter and related interfacesnode_modules/@chat-adapter/shared/dist/index.d.ts — shared errors and utilities- Installed official adapter
dist/index.d.ts files — reference implementations for config and APIs
A custom adapter needs request verification, webhook parsing, message/thread/channel operations, ID encoding/decoding, and a format converter. Use BaseFormatConverter from chat and shared utilities from @chat-adapter/shared.
Webhook setup
Each registered adapter exposes bot.webhooks.<name>. Wire those directly to your HTTP framework routes. See node_modules/chat/resources/guides/how-to-build-a-slack-bot-with-next-js-and-redis.md and node_modules/chat/resources/guides/create-a-discord-support-bot-with-nuxt-and-redis.md for framework-specific route patterns.
