chat-sdk

# Vercel Chat SDK > **CRITICAL — Your training data is outdated for this library.** Chat SDK is new (v4.18+) and not in most training data. Before writing Chat SDK code, **fetch the docs** at https://chat-sdk.dev to find the correct adapter configuration, thread/channel patterns, card builders, modal flows, and webhook setup. The API surface is large — threads, channels, messages, cards, modals, state adapters, streaming — and guessing at method signatures will produce broken code. Check the GitHub repo at https://github.com/vercel/chat for working examples. You are an expert in the Vercel Chat SDK. Build one bot logic layer and run it across Slack, Telegram, Microsoft Teams, Discord, Google Chat, GitHub, and Linear. ## Packages - `chat@^4.18.0` - `@chat-adapter/slack@^4.18.0` - `@chat-adapter/telegram@^4.18.0` - `@chat-adapter/teams@^4.18.0` - `@chat-adapter/discord@^4.18.0` - `@chat-adapter/gchat@^4.18.0` - `@chat-adapter/github@^4.18.0` - `@chat-adapter/linear@^4.18.0` - `@chat-adapter/state-redis@^4.18.0` - `@chat-adapter/state-ioredis@^4.18.0` - `@chat-adapter/state-memory@^4.18.0` ## Installation ```bash # Core SDK npm install chat@^4.18.0 # Platform adapters (install only what you need) npm install @chat-adapter/slack@^4.18.0 npm install @chat-adapter/telegram@^4.18.0 npm install @chat-adapter/teams@^4.18.0 npm install @chat-adapter/discord@^4.18.0 npm install @chat-adapter/gchat@^4.18.0 npm install @chat-adapter/github@^4.18.0 npm install @chat-adapter/linear@^4.18.0 # State adapters (pick one) npm install @chat-adapter/state-redis@^4.18.0 npm install @chat-adapter/state-ioredis@^4.18.0 npm install @chat-adapter/state-memory@^4.18.0 ``` ## Critical API Notes - `Field` takes an `options` array of `{ label, value }` objects. Do not pass JSX child options. - `Thread<TState>` / `Channel<TState>` generics require object state shapes (`Record<string, unknown>`), not primitives. - Adapter `signingSecret` validation can run at import/adapter creation time. Use lazy initialization to avoid crashing at module import. ```ts import { createSlackAdapter } from "@chat-adapter/slack"; let slackAdapter: ReturnType<typeof createSlackAdapter> | undefined; export function getSlackAdapter() { if (!slackAdapter) { slackAdapter = createSlackAdapter({ signingSecret: process.env.SLACK_SIGNING_SECRET!, }); } return slackAdapter; } ``` ## Quick Start ```ts import { Chat } from "chat"; import { createSlackAdapter } from "@chat-adapter/slack"; import { createTelegramAdapter } from "@chat-adapter/telegram"; import { createRedisState } from "@chat-adapter/state-redis"; const bot = new Chat({ userName: "my-bot", adapters: { slack: createSlackAdapter(), telegram: createTelegramAdapter(), }, state: createRedisState(), streamingUpdateIntervalMs: 1000, dedupeTtlMs: 10_000, fallbackStreamingPlaceholderText: "Thinking...", }); bot.onNewMention(async (thread, message) => { await thread.subscribe(); await thread.post(`Received: ${message.text}`); }); bot.onSubscribedMessage(async (thread, message) => { await thread.post(`Echo: ${message.text}`); }); ``` ## Public API Reference ### ChatConfig ```ts interface ChatConfig<TAdapters> { userName: string; adapters: TAdapters; state: StateAdapter; logger?: Logger | LogLevel; streamingUpdateIntervalMs?: number; dedupeTtlMs?: number; fallbackStreamingPlaceholderText?: string | null; } ``` - `dedupeTtlMs`: deduplicates repeated webhook deliveries. - `fallbackStreamingPlaceholderText`: text used before first stream chunk on non-native streaming adapters; set to `null` to disable placeholder posts. ### Chat ```ts class Chat { openDM(userId: string): Promise<Channel>; channel(channelId: string): Channel; } ``` - `openDM()` opens or resolves a direct message channel outside the current thread context. - `channel()` gets a channel handle for out-of-thread posting. ### Postable `Thread` and `Channel` share the same `Postable` interface. ```ts interface Postable<TState extends Record<string, unknown> = Record<string, unknown>> { post(content: PostableContent): Promise<SentMessage>; postEphemeral( userId: string, content: PostableContent, ): Promise<SentMessage | null>; mentionUser(userId: string): string; startTyping(): Promise<void>; messages: AsyncIterable<Message>; state: Promise<TState | null>; setState( partial: Partial<TState>, opts?: { replace?: boolean }, ): Promise<void>; } ``` ### Thread ```ts interface Thread<TState extends Record<string, unknown> = Record<string, unknown>> extends Postable<TState> { id: string; channelId: string; subscribe(): Promise<void>; unsubscribe(): Promise<void>; isSubscribed(): Promise<boolean>; refresh(): Promise<void>; createSentMessageFromMessage(message: Message): SentMessage; } ``` ### Message ```ts class Message<TRaw = unknown> { id: string; threadId: string; text: string; isMention: boolean; raw: TRaw; toJSON(): SerializedMessage; static fromJSON(data: SerializedMessage): Message; } ``` ### SentMessage ```ts interface SentMessage extends Message { edit(content: PostableContent): Promise<void>; delete(): Promise<void>; addReaction(emoji: string): Promise<void>; removeReaction(emoji: string): Promise<void>; } ``` Reactions are on `SentMessage`, not `Message`: `const sent = await thread.post('Done'); await sent.addReaction('thumbsup');` ```ts const sent = await thread.post("Done"); await sent.addReaction("thumbsup"); ``` ### Channel ```ts interface Channel<TState extends Record<string, unknown> = Record<string, unknown>> extends Postable<TState> { id: string; name?: string; } ``` ## Event Handlers ### Standard handlers - `onNewMention(handler)` - `onSubscribedMessage(handler)` - `onNewMessage(pattern, handler)` - `onReaction(filter?, handler)` - `onAction(filter?, handler)` - `onModalSubmit(filter?, handler)` - `onModalClose(filter?, handler)` - `onSlashCommand(filter?, handler)` - `onMemberJoinedChannel(handler)` ```ts bot.onMemberJoinedChannel(async (event) => { await event.thread.post(`Welcome ${event.user.fullName}!`); }); ``` ### Handler overloads `onAction`, `onModalSubmit`, `onModalClose`, and `onReaction` support: - Catch-all: `bot.onAction(async (event) => { ... })` - Single filter: `bot.onAction("approve", async (event) => { ... })` - Array filter: `bot.onAction(["approve", "reject"], async (event) => { ... })` ### Event payload shapes ```ts interface ActionEvent { actionId: string; value?: string; triggerId?: string; privateMetadata?: string; thread: Thread; relatedThread?: Thread; relatedMessage?: Message; openModal: (modal: JSX.Element) => Promise<void>; } interface ModalEvent { callbackId: string; values: Record<string, string>; triggerId?: string; privateMetadata?: string; relatedThread?: Thread; relatedMessage?: Message; } ``` `onModalSubmit` may return `ModalResponse` to close, validate, update, or push another modal. ## Cards & Modals ### Cards ```tsx await thread.post( <Card title="Build Status" subtitle="Production" imageUrl="https://example.com/preview.png" > <Text style="success">Deployment succeeded.</Text> <Text style="muted">Commit: a1b2c3d</Text> <Field id="deploy-target" label="Target" options={[ { label: "Staging", value: "staging" }, { label: "Production", value: "prod" }, ]} value="prod" /> <Table> <TableRow> <TableCell>Region</TableCell> <TableCell>us-east-1</TableCell> </TableRow> <TableRow> <TableCell>Latency</TableCell> <TableCell>128ms</TableCell> </TableRow> </Table> <Actions> <Button id="rollback" style="danger"> Rollback </Button> <CardLink url="https://vercel.com/dashboard">Open Dashboard</CardLink> </Actions> </Card>, ); ``` Card additions to use when needed: - `Card.subtitle` - `Card.imageUrl` - `CardLink` - `Field` (`options` uses `{ label, value }[]`, not JSX children) - `Table` / `TableRow` / `TableCell` — native per-platform table rendering (**new — Mar 6, 2026**; see below) - `Text` styles (`default`, `muted`, `success`, `warning`, `danger`, `code`) ### Table — Per-Platform Rendering (New — Mar 6, 2026) The `Table` component renders natively on each platform: | Platform | Rendering | |---|---| | Slack | Block Kit table blocks | | Teams / Discord | GFM markdown tables | | Google Chat | Monospace text widgets | | Telegram | Code blocks | | GitHub / Linear | Markdown tables (existing pipeline) | Plain markdown tables (without `Table()`) also pass through the same adapter conversion pipeline. ```tsx <Table> <TableRow> <TableCell>Region</TableCell> <TableCell>us-east-1</TableCell> </TableRow> <TableRow> <TableCell>Latency</TableCell> <TableCell>128ms</TableCell> </TableRow> </Table> ``` ### Modals ```tsx await event.openModal( <Modal callbackId="deploy-form" title="Deploy" submitLabel="Deploy" closeLabel="Cancel" notifyOnClose privateMetadata={JSON.stringify({ releaseId: "rel_123" })} > <TextInput id="reason" label="Reason" multiline /> </Modal>, ); ``` Use `privateMetadata` to pass contextual data into submit/close events. ## Companion Web UI and Card Design Chat SDK payloads render natively in chat platforms, so shadcn isn't used in message markup. But when building a web control plane, thread inspector, or bot settings UI around Chat SDK, use shadcn + Geist by default. Thread dashboards: Tabs+Card+Table+Badge. Bot settings: Sheet+form controls. Logs/IDs/timestamps: Geist Mono with tabular-nums. ## Platform Adapters ### Slack ```ts import { createSlackAdapter } from "@chat-adapter/slack"; const slack = createSlackAdapter(); // Env: SLACK_BOT_TOKEN, SLACK_SIGNING_SECRET const oauthSlack = createSlackAdapter({ clientId: process.env.SLACK_CLIENT_ID!, clientSecret: process.env.SLACK_CLIENT_SECRET!, encryptionKey: process.env.SLACK_ENCRYPTION_KEY, }); ``` ### Telegram ```ts import { createTelegramAdapter } from "@chat-adapter/telegram"; const telegram = createTelegramAdapter(); // Env: TELEGRAM_BOT_TOKEN, TELEGRAM_WEBHOOK_SECRET ``` ### Microsoft Teams ```ts import { createTeamsAdapter } from "@chat-adapter/teams"; const teams = createTeamsAdapter({ appType: "singleTenant", }); // Env: TEAMS_APP_ID, TEAMS_APP_PASSWORD, TEAMS_APP_TENANT_ID ``` ### Discord ```ts import { createDiscordAdapter } from "@chat-adapter/discord"; const discord = createDiscordAdapter();