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.
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/jsx-runtime.d.ts # JSX runtime types
node_modules/chat/docs/contributing/ # adapter-authoring docs
node_modules/chat/docs/guides/ # framework/platform guides
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 setup
node_modules/chat/docs/usage.mdx — Chat config and lifecycle
node_modules/chat/docs/handling-events.mdx — event routing and handlers
node_modules/chat/docs/threads-messages-channels.mdx — thread/channel/message model
node_modules/chat/docs/posting-messages.mdx — post, edit, delete, schedule
node_modules/chat/docs/streaming.mdx — AI SDK integration and streaming semantics
node_modules/chat/docs/cards.mdx — JSX cards
node_modules/chat/docs/actions.mdx — button/select interactions
node_modules/chat/docs/modals.mdx — modal submit/close flows
node_modules/chat/docs/slash-commands.mdx — slash command routing
node_modules/chat/docs/direct-messages.mdx — DM behavior and openDM()
node_modules/chat/docs/files.mdx — attachments/uploads
node_modules/chat/docs/state.mdx — persistence, locking, dedupe
node_modules/chat/docs/adapters.mdx — cross-platform feature matrix
node_modules/chat/docs/api/chat.mdx — exact Chat API
node_modules/chat/docs/api/thread.mdx — exact Thread API
node_modules/chat/docs/api/message.mdx — exact Message API
node_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.
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() or thread.stream(). 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 cadence
fallbackStreamingPlaceholderText 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
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
Official platform adapters
| Platform |
Package |
Factory |
| Slack |
@chat-adapter/slack |
createSlackAdapter |
| Microsoft Teams |
@chat-adapter/teams |
createTeamsAdapter |
| Google Chat |
@chat-adapter/gchat |
createGoogleChatAdapter |
| Discord |
@chat-adapter/discord |
createDiscordAdapter |
| GitHub |
@chat-adapter/github |
createGitHubAdapter |
| Linear |
@chat-adapter/linear |
createLinearAdapter |
| Telegram |
@chat-adapter/telegram |
createTelegramAdapter |
| WhatsApp Business Cloud |
@chat-adapter/whatsapp |
createWhatsAppAdapter |
Official state adapters
| State backend |
Package |
Factory |
| Redis |
@chat-adapter/state-redis |
createRedisState |
| ioredis |
@chat-adapter/state-ioredis |
createIoRedisState |
| PostgreSQL |
@chat-adapter/state-pg |
createPostgresState |
| Memory |
@chat-adapter/state-memory |
createMemoryState |
Community adapters
chat-state-cloudflare-do
@beeper/chat-adapter-matrix
chat-adapter-imessage
@bitbasti/chat-adapter-webex
@resend/chat-sdk-adapter
chat-adapter-baileys
Coming-soon platform entries
- Instagram
- Signal
- X
- Messenger
Building a custom adapter
Read these published docs first:
node_modules/chat/docs/contributing/building.mdx
node_modules/chat/docs/contributing/testing.mdx
node_modules/chat/docs/contributing/publishing.mdx
Also inspect:
node_modules/chat/dist/index.d.ts — Adapter and related interfaces
node_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/docs/guides/slack-nextjs.mdx and node_modules/chat/docs/guides/discord-nuxt.mdx for framework-specific route patterns.
1---
2name: chat-sdk
3description: >
4 Build multi-platform chat bots with Chat SDK (`chat` npm package). Use when developers want to
5 (1) Build a Slack, Teams, Google Chat, Discord, Telegram, GitHub, Linear, or WhatsApp bot,
6 (2) Use Chat SDK to handle mentions, direct messages, subscribed threads, reactions, slash
7 commands, cards, modals, files, or AI streaming,
8 (3) Set up webhook routes or multi-adapter bots,
9 (4) Send rich cards or streamed AI responses to chat platforms,
10 (5) Build or maintain a custom adapter or state adapter.
11 Triggers on "chat sdk", "chat bot", "slack bot", "teams bot", "google chat bot", "discord bot",
12 "telegram bot", "whatsapp bot", "@chat-adapter", "@chat-adapter/state-", "custom adapter",
13 "state adapter", "build adapter", and building bots that work across multiple chat platforms.
14metadata:
15 source: https://skillmd.com/skills/vercel-labs/chat-sdk
16---
17
18# Chat SDK
19
20Unified TypeScript SDK for building chat bots across Slack, Teams, Google Chat, Discord, Telegram, GitHub, Linear, and WhatsApp. Write bot logic once, deploy everywhere.
21
22## Start with published sources
23
24When Chat SDK is installed in a user project, inspect the published files that ship in `node_modules`:
25
26```
27node_modules/chat/docs/ # bundled docs
28node_modules/chat/dist/index.d.ts # core API types
29node_modules/chat/dist/jsx-runtime.d.ts # JSX runtime types
30node_modules/chat/docs/contributing/ # adapter-authoring docs
31node_modules/chat/docs/guides/ # framework/platform guides
32```
33
34If one of the paths below does not exist, that package is not installed in the project yet.
35
36Read these before writing code:
37- `node_modules/chat/docs/getting-started.mdx` — install and setup
38- `node_modules/chat/docs/usage.mdx` — `Chat` config and lifecycle
39- `node_modules/chat/docs/handling-events.mdx` — event routing and handlers
40- `node_modules/chat/docs/threads-messages-channels.mdx` — thread/channel/message model
41- `node_modules/chat/docs/posting-messages.mdx` — post, edit, delete, schedule
42- `node_modules/chat/docs/streaming.mdx` — AI SDK integration and streaming semantics
43- `node_modules/chat/docs/cards.mdx` — JSX cards
44- `node_modules/chat/docs/actions.mdx` — button/select interactions
45- `node_modules/chat/docs/modals.mdx` — modal submit/close flows
46- `node_modules/chat/docs/slash-commands.mdx` — slash command routing
47- `node_modules/chat/docs/direct-messages.mdx` — DM behavior and `openDM()`
48- `node_modules/chat/docs/files.mdx` — attachments/uploads
49- `node_modules/chat/docs/state.mdx` — persistence, locking, dedupe
50- `node_modules/chat/docs/adapters.mdx` — cross-platform feature matrix
51- `node_modules/chat/docs/api/chat.mdx` — exact `Chat` API
52- `node_modules/chat/docs/api/thread.mdx` — exact `Thread` API
53- `node_modules/chat/docs/api/message.mdx` — exact `Message` API
54- `node_modules/chat/docs/api/modals.mdx` — modal element and event details
55
56For the specific adapter or state package you are using, inspect that installed package's `dist/index.d.ts` export surface in `node_modules`.
57
58## Quick start
59
60```typescript
61import { Chat } from "chat";
62import { createSlackAdapter } from "@chat-adapter/slack";
63import { createRedisState } from "@chat-adapter/state-redis";
64
65const bot = new Chat({
66 userName: "mybot",
67 adapters: {
68 slack: createSlackAdapter(),
69 },
70 state: createRedisState(),
71 dedupeTtlMs: 600_000,
72});
73
74bot.onNewMention(async (thread) => {
75 await thread.subscribe();
76 await thread.post("Hello! I'm listening to this thread.");
77});
78
79bot.onSubscribedMessage(async (thread, message) => {
80 await thread.post(`You said: ${message.text}`);
81});
82```
83
84## Core concepts
85
86- **Chat** — main entry point; coordinates adapters, routing, locks, and state
87- **Adapters** — platform-specific integrations for Slack, Teams, Google Chat, Discord, Telegram, GitHub, Linear, and WhatsApp
88- **State adapters** — persistence for subscriptions, locks, dedupe, and thread state
89- **Thread** — conversation context with `post()`, `stream()`, `subscribe()`, `setState()`, `startTyping()`
90- **Message** — normalized content with `text`, `formatted`, attachments, author info, and platform `raw`
91- **Channel** — container for threads and top-level posts
92
93## Event handlers
94
95| Handler | Trigger |
96|---------|---------|
97| `onNewMention` | Bot @-mentioned in an unsubscribed thread |
98| `onDirectMessage` | New DM in an unsubscribed DM thread |
99| `onSubscribedMessage` | Any message in a subscribed thread |
100| `onNewMessage(regex)` | Regex match in an unsubscribed thread |
101| `onReaction(emojis?)` | Emoji added or removed |
102| `onAction(actionIds?)` | Button clicks and select/radio interactions |
103| `onModalSubmit(callbackId?)` | Modal form submitted |
104| `onModalClose(callbackId?)` | Modal dismissed/cancelled |
105| `onSlashCommand(commands?)` | Slash command invocation |
106| `onAssistantThreadStarted` | Slack assistant thread opened |
107| `onAssistantContextChanged` | Slack assistant context changed |
108| `onAppHomeOpened` | Slack App Home opened |
109| `onMemberJoinedChannel` | Slack member joined channel event |
110
111Read `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`.
112
113## Streaming
114
115Pass any `AsyncIterable<string>` to `thread.post()` or `thread.stream()`. For AI SDK, prefer `result.fullStream` over `result.textStream` when available so step boundaries are preserved.
116
117```typescript
118import { ToolLoopAgent } from "ai";
119
120const agent = new ToolLoopAgent({ model: "anthropic/claude-4.5-sonnet" });
121
122bot.onNewMention(async (thread, message) => {
123 const result = await agent.stream({ prompt: message.text });
124 await thread.post(result.fullStream);
125});
126```
127
128Key details:
129- `streamingUpdateIntervalMs` controls post+edit fallback cadence
130- `fallbackStreamingPlaceholderText` defaults to `"..."`; set `null` to disable
131- Structured `StreamChunk` support is Slack-only; other adapters ignore non-text chunks
132
133## Cards and modals (JSX)
134
135Set `jsxImportSource: "chat"` in `tsconfig.json`.
136
137Card components:
138- `Card`, `CardText`, `Section`, `Fields`, `Field`, `Button`, `CardLink`, `LinkButton`, `Actions`, `Select`, `SelectOption`, `RadioSelect`, `Table`, `Image`, `Divider`
139
140Modal components:
141- `Modal`, `TextInput`, `Select`, `SelectOption`, `RadioSelect`
142
143```tsx
144await thread.post(
145 <Card title="Order #1234">
146 <CardText>Your order has been received.</CardText>
147 <Actions>
148 <Button id="approve" style="primary">Approve</Button>
149 <Button id="reject" style="danger">Reject</Button>
150 </Actions>
151 </Card>
152);
153```
154
155## Adapter inventory
156
157### Official platform adapters
158
159| Platform | Package | Factory |
160|---------|---------|---------|
161| Slack | `@chat-adapter/slack` | `createSlackAdapter` |
162| Microsoft Teams | `@chat-adapter/teams` | `createTeamsAdapter` |
163| Google Chat | `@chat-adapter/gchat` | `createGoogleChatAdapter` |
164| Discord | `@chat-adapter/discord` | `createDiscordAdapter` |
165| GitHub | `@chat-adapter/github` | `createGitHubAdapter` |
166| Linear | `@chat-adapter/linear` | `createLinearAdapter` |
167| Telegram | `@chat-adapter/telegram` | `createTelegramAdapter` |
168| WhatsApp Business Cloud | `@chat-adapter/whatsapp` | `createWhatsAppAdapter` |
169
170### Official state adapters
171
172| State backend | Package | Factory |
173|--------------|---------|---------|
174| Redis | `@chat-adapter/state-redis` | `createRedisState` |
175| ioredis | `@chat-adapter/state-ioredis` | `createIoRedisState` |
176| PostgreSQL | `@chat-adapter/state-pg` | `createPostgresState` |
177| Memory | `@chat-adapter/state-memory` | `createMemoryState` |
178
179### Community adapters
180
181- `chat-state-cloudflare-do`
182- `@beeper/chat-adapter-matrix`
183- `chat-adapter-imessage`
184- `@bitbasti/chat-adapter-webex`
185- `@resend/chat-sdk-adapter`
186- `chat-adapter-baileys`
187
188### Coming-soon platform entries
189
190- Instagram
191- Signal
192- X
193- Messenger
194
195## Building a custom adapter
196
197Read these published docs first:
198- `node_modules/chat/docs/contributing/building.mdx`
199- `node_modules/chat/docs/contributing/testing.mdx`
200- `node_modules/chat/docs/contributing/publishing.mdx`
201
202Also inspect:
203- `node_modules/chat/dist/index.d.ts` — `Adapter` and related interfaces
204- `node_modules/@chat-adapter/shared/dist/index.d.ts` — shared errors and utilities
205- Installed official adapter `dist/index.d.ts` files — reference implementations for config and APIs
206
207A 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`.
208
209## Webhook setup
210
211Each registered adapter exposes `bot.webhooks.<name>`. Wire those directly to your HTTP framework routes. See `node_modules/chat/docs/guides/slack-nextjs.mdx` and `node_modules/chat/docs/guides/discord-nuxt.mdx` for framework-specific route patterns.