chat-sdk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Chat SDK

Unified TypeScript SDK for building chat bots across Slack, Teams, Google Chat, Discord, GitHub, and Linear. Write bot logic once, deploy everywhere.

一款统一的TypeScript SDK，用于跨Slack、Teams、Google Chat、Discord、GitHub和Linear平台构建聊天机器人。只需编写一次机器人逻辑，即可部署到所有平台。

Critical: Read the bundled docs

重要提示：阅读捆绑文档

The

chat

package ships with full documentation in

node_modules/chat/docs/

and TypeScript source types. Always read these before writing code:

node_modules/chat/docs/           # Full documentation (MDX files)
node_modules/chat/dist/           # Built types (.d.ts files)

Key docs to read based on task:

```
docs/getting-started.mdx
```
— setup guides
```
docs/usage.mdx
```
— event handlers, threads, messages, channels
```
docs/streaming.mdx
```
— AI streaming with AI SDK
```
docs/cards.mdx
```
— JSX interactive cards
```
docs/actions.mdx
```
— button/dropdown handlers
```
docs/modals.mdx
```
— form dialogs (Slack only)
```
docs/adapters/*.mdx
```
— platform-specific adapter setup
```
docs/state/*.mdx
```
— state adapter config (Redis, ioredis, memory)

Quick start

快速开始

typescript

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({
      botToken: process.env.SLACK_BOT_TOKEN!,
      signingSecret: process.env.SLACK_SIGNING_SECRET!,
    }),
  },
  state: createRedisState({ url: process.env.REDIS_URL! }),
});

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}`);
});

typescript

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({
      botToken: process.env.SLACK_BOT_TOKEN!,
      signingSecret: process.env.SLACK_SIGNING_SECRET!,
    }),
  },
  state: createRedisState({ url: process.env.REDIS_URL! }),
});

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 and routes events
Adapters — platform-specific (Slack, Teams, GChat, Discord, GitHub, Linear)
State — pluggable persistence (Redis for prod, memory for dev)
Thread — conversation thread with
```
post()
```
,
```
subscribe()
```
,
```
startTyping()
```
Message — normalized format with
```
text
```
,
```
formatted
```
(mdast AST),
```
raw
```
Channel — container for threads, supports listing and posting

Chat — 主入口，负责协调适配器并路由事件
Adapters — 各平台专属适配器（Slack、Teams、GChat、Discord、GitHub、Linear）
State — 可插拔的持久化组件（生产环境用Redis，开发环境用内存）
Thread — 对话线程，支持
```
post()
```
、
```
subscribe()
```
、
```
startTyping()
```
方法
Message — 标准化消息格式，包含
```
text
```
、
```
formatted
```
（mdast语法树）、
```
raw
```
字段
Channel — 线程的容器，支持线程列表查看和消息发布

Event handlers

事件处理器

Handler	Trigger
`onNewMention`	Bot @-mentioned in unsubscribed thread
`onSubscribedMessage`	Any message in subscribed thread
`onNewMessage(regex)`	Messages matching pattern in unsubscribed threads
`onSlashCommand("/cmd")`	Slash command invocations
`onReaction(emojis)`	Emoji reactions added/removed
`onAction(actionId)`	Button clicks and dropdown selections
`onAssistantThreadStarted`	Slack Assistants API thread opened
`onAppHomeOpened`	Slack App Home tab opened

处理器	触发条件
`onNewMention`	机器人在未订阅的线程中被@提及
`onSubscribedMessage`	已订阅线程中的任何消息
`onNewMessage(regex)`	未订阅线程中匹配指定模式的消息
`onSlashCommand("/cmd")`	斜杠命令被调用
`onReaction(emojis)`	表情反应被添加/移除
`onAction(actionId)`	按钮点击或下拉菜单选择
`onAssistantThreadStarted`	Slack Assistants API线程开启
`onAppHomeOpened`	Slack应用主页标签被打开

Streaming

流式响应

Pass any

AsyncIterable<string>

thread.post()

. Works with AI SDK's

textStream

typescript

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.textStream);
});

将任意

AsyncIterable<string>

传入

thread.post()

即可实现流式响应。可与AI SDK的

textStream

配合使用：

typescript

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.textStream);
});

Cards (JSX)

卡片（JSX）

Set

jsxImportSource: "chat"

in tsconfig. Components:

Card

CardText

Button

Actions

Fields

Field

Select

SelectOption

Image

Divider

LinkButton

Section

RadioSelect

tsx

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

在tsconfig中设置

jsxImportSource: "chat"

。可用组件包括：

Card

、

CardText

、

Button

、

Actions

、

Fields

、

Field

、

Select

、

SelectOption

、

Image

、

Divider

、

LinkButton

、

Section

、

RadioSelect

。

tsx

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

Packages

Package	Purpose
`chat`	Core SDK
`@chat-adapter/slack`	Slack
`@chat-adapter/teams`	Microsoft Teams
`@chat-adapter/gchat`	Google Chat
`@chat-adapter/discord`	Discord
`@chat-adapter/github`	GitHub Issues
`@chat-adapter/linear`	Linear Issues
`@chat-adapter/state-redis`	Redis state (production)
`@chat-adapter/state-ioredis`	ioredis state (alternative)
`@chat-adapter/state-memory`	In-memory state (development)

包	用途
`chat`	核心SDK
`@chat-adapter/slack`	Slack平台适配
`@chat-adapter/teams`	Microsoft Teams平台适配
`@chat-adapter/gchat`	Google Chat平台适配
`@chat-adapter/discord`	Discord平台适配
`@chat-adapter/github`	GitHub Issues适配
`@chat-adapter/linear`	Linear Issues适配
`@chat-adapter/state-redis`	Redis状态存储（生产环境）
`@chat-adapter/state-ioredis`	ioredis状态存储（替代方案）
`@chat-adapter/state-memory`	内存状态存储（开发环境）

Webhook setup

Webhook设置

Each adapter exposes a webhook handler via

bot.webhooks.{platform}

. Wire these to your HTTP framework's routes (e.g. Next.js API routes, Hono, Express).

每个适配器都通过

bot.webhooks.{platform}

暴露Webhook处理器。可将其接入你的HTTP框架路由中（例如Next.js API路由、Hono、Express）。

chat-sdk

Original

Translation

Chat SDK

Chat SDK

Critical: Read the bundled docs

重要提示：阅读捆绑文档

Quick start

快速开始

Core concepts

核心概念

Event handlers

事件处理器

Streaming

流式响应

Cards (JSX)

卡片（JSX）

Packages

相关包

Webhook setup

Webhook设置