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();
// Env: DISCORD_BOT_TOKEN, DISCORD_PUBLIC_KEY, DISCORD_APPLICATION_ID, CRON_SECRET
```

For message content handlers, enable both Gateway intent and Message Content Intent in the Discord developer portal.

### Google Chat

```ts
import { createGoogleChatAdapter } from "@chat-adapter/gchat";

const gchat = createGoogleChatAdapter();
// Env: GOOGLE_CHAT_CREDENTIALS, GOOGLE_CHAT_USE_ADC
```

### GitHub

```ts
import { createGitHubAdapter } from "@chat-adapter/github";

const github = createGitHubAdapter({
  botUserId: process.env.GITHUB_BOT_USER_ID,
});
// Env: GITHUB_TOKEN or (GITHUB_APP_ID + GITHUB_PRIVATE_KEY),
//      GITHUB_WEBHOOK_SECRET, GITHUB_INSTALLATION_ID
```

### Linear

```ts
import { createLinearAdapter } from "@chat-adapter/linear";

const linear = createLinearAdapter({
  clientId: process.env.LINEAR_CLIENT_ID,
  clientSecret: process.env.LINEAR_CLIENT_SECRET,
  accessToken: process.env.LINEAR_ACCESS_TOKEN,
});
```

## State Adapters

### Redis (recommended)

```ts
import { createRedisState } from "@chat-adapter/state-redis";

const state = createRedisState();
// Env: REDIS_URL (or REDIS_HOST/REDIS_PORT/REDIS_PASSWORD)
```

### ioredis (cluster/sentinel)

```ts
import { createIoRedisState } from "@chat-adapter/state-ioredis";

const state = createIoRedisState({
  // cluster/sentinel options
});
```

### Memory (dev/test only)

```ts
import { MemoryState } from "@chat-adapter/state-memory";

const state = new MemoryState();
```

## Webhook Setup

### Next.js App Router

```ts
// app/api/webhooks/slack/route.ts
import { bot } from "@/lib/bot";
import { after } from "next/server";

export async function POST(req: Request) {
  return bot.webhooks.slack(req, {
    waitUntil: (p) => after(() => p),
  });
}
```

```ts
// app/api/webhooks/telegram/route.ts
import { bot } from "@/lib/bot";

export async function POST(req: Request) {
  return bot.webhooks.telegram(req);
}
```

### Pages Router

```ts
// pages/api/bot.ts
export default async function handler(req, res) {
  const response = await bot.webhooks.slack(req);
  res.status(response.status).send(await response.text());
}
```

## Integration Patterns

### Out-of-thread routing with `openDM()` and `channel()`

```ts
bot.onAction("handoff", async (event) => {
  const dm = await bot.openDM(event.user.id);
  await dm.post("A human will follow up shortly.");

  const ops = bot.channel("ops-alerts");
  await ops.post(`Escalated by ${event.user.fullName}`);
});
```

### Workflow-safe serialization with `registerSingleton()` and `reviver()`

```ts
bot.registerSingleton();

const serialized = JSON.stringify({ thread });
const revived = JSON.parse(serialized, bot.reviver());
await revived.thread.post("Resumed workflow step");
```

### Slack OAuth callback handling

```ts
// app/api/webhooks/slack/oauth/callback/route.ts
import { bot } from "@/lib/bot";

export async function GET(req: Request) {
  return bot.oauth.slack.callback(req);
}
```

## Gotchas

### Routing

1. `onNewMention` only fires for unsubscribed threads; call `thread.subscribe()` to receive follow-ups.
2. DMs are treated as direct intent and set `message.isMention = true`.
3. `onNewMessage(pattern, handler)` only applies before subscription; use `onSubscribedMessage` after subscribe.
4. Catch-all and filtered handlers can both run; registration order determines execution order.
5. Out-of-thread routing via `openDM()` / `channel()` needs platform permissions for DM/channel posting.

### Streaming

6. Slack supports native streaming with real-time bold, italic, list, and other formatting rendered as the response arrives. Teams/Discord/Google Chat/Telegram use post+edit fallback.
7. Fallback adapters now convert markdown to each platform's native format at every intermediate edit — users no longer see raw `**bold**` syntax during streaming.
8. `fallbackStreamingPlaceholderText: null` disables placeholder messages on fallback adapters.
9. `streamingUpdateIntervalMs` too low can trigger rate limits on post+edit adapters.
10. `dedupeTtlMs` should cover webhook retry windows to avoid duplicate responses.
11. `startTyping()` is adapter-dependent and may no-op on platforms without typing indicators.

### Adapter-specific

11. Google Chat auth uses `GOOGLE_CHAT_CREDENTIALS` + `GOOGLE_CHAT_USE_ADC`; domain-wide delegation/impersonation is required for some org posting scenarios.
12. Teams requires `appType` plus `TEAMS_APP_TENANT_ID`; reactions/history/typing features are limited compared with Slack.
13. Discord content-based handlers require Message Content Intent enabled in addition to Gateway connectivity.
14. GitHub and Linear adapters do not support interactive card actions/modals; design around comments/status updates instead.
15. GitHub App installs need `GITHUB_INSTALLATION_ID` and often adapter `botUserId`; Linear OAuth setups need `clientId`, `clientSecret`, and `LINEAR_ACCESS_TOKEN`.

## Official Docs

- [Chat SDK documentation](https://chat-sdk.dev)
- [GitHub: vercel/chat](https://github.com/vercel/chat)