Back to Details

chat-sdk

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Chat SDK

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)
Also read the TypeScript types from 
node_modules/chat/dist/
to understand the full API surface.
chat
包在
node_modules/chat/docs/
目录中附带了完整文档，同时提供TypeScript源类型定义。编写代码前请务必阅读这些内容：
node_modules/chat/docs/           # 完整文档（MDX文件）
node_modules/chat/dist/           # 编译后的类型文件（.d.ts格式）
按任务选择核心文档：
  • docs/getting-started.mdx
    — 入门设置指南
  • docs/usage.mdx
    — 事件处理器、线程、消息、频道
  • docs/streaming.mdx
    — 结合AI SDK实现AI流式响应
  • docs/cards.mdx
    — JSX交互式卡片
  • docs/actions.mdx
    — 按钮/下拉菜单处理器
  • docs/modals.mdx
    — 表单对话框（仅支持Slack）
  • docs/adapters/*.mdx
    — 各平台适配工具的设置说明
  • docs/state/*.mdx
    — 状态适配器配置（Redis、ioredis、内存）
同时请阅读
node_modules/chat/dist/
中的TypeScript类型定义，以全面了解API的功能范围。

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

事件处理器

HandlerTrigger
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>
to 
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

相关包

PackagePurpose
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）。