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

# 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.

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

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

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

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.

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

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

class Message<TRaw = unknown> {
  id: string;
  threadId: string;
  text: string;
  isMention: boolean;
  raw: TRaw;

  toJSON(): SerializedMessage;
  static fromJSON(data: SerializedMessage): Message;
}

SentMessage

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');

const sent = await thread.post("Done");
await sent.addReaction("thumbsup");

Channel

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)

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

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

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:

Plain markdown tables (without Table()) also pass through the same adapter conversion pipeline.

<Table>
  <TableRow>
    <TableCell>Region</TableCell>
    <TableCell>us-east-1</TableCell>
  </TableRow>
  <TableRow>
    <TableCell>Latency</TableCell>
    <TableCell>128ms</TableCell>
  </TableRow>
</Table>

Modals

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

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

import { createTelegramAdapter } from "@chat-adapter/telegram";

const telegram = createTelegramAdapter();
// Env: TELEGRAM_BOT_TOKEN, TELEGRAM_WEBHOOK_SECRET

Microsoft Teams

import { createTeamsAdapter } from "@chat-adapter/teams";

const teams = createTeamsAdapter({
  appType: "singleTenant",
});
// Env: TEAMS_APP_ID, TEAMS_APP_PASSWORD, TEAMS_APP_TENANT_ID

Discord

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

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

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

GitHub

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

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)

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

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

ioredis (cluster/sentinel)

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

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

Memory (dev/test only)

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

const state = new MemoryState();

Webhook Setup

Next.js App Router

// 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),
  });
}

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

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

Pages Router

// 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()

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()

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

// 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
• GitHub: vercel/chat