|
| 1 | +--- |
| 2 | +name: chat-sdk |
| 3 | +description: > |
| 4 | + Build multi-platform chat bots with Chat SDK (`chat` npm package). Use when developers want to |
| 5 | + (1) Build a Slack, Teams, Google Chat, Discord, GitHub, or Linear bot, |
| 6 | + (2) Use the Chat SDK to handle mentions, messages, reactions, slash commands, cards, modals, or streaming, |
| 7 | + (3) Set up webhook handlers for chat platforms, |
| 8 | + (4) Send interactive cards or stream AI responses to chat platforms, |
| 9 | + (5) Build a custom adapter for a new chat platform. |
| 10 | + Triggers on "chat sdk", "chat bot", "slack bot", "teams bot", "discord bot", "@chat-adapter", |
| 11 | + "custom adapter", "build adapter", building bots that work across multiple chat platforms. |
| 12 | +--- |
| 13 | + |
| 14 | +# Chat SDK |
| 15 | + |
| 16 | +Unified TypeScript SDK for building chat bots across Slack, Teams, Google Chat, Discord, GitHub, and Linear. Write bot logic once, deploy everywhere. |
| 17 | + |
| 18 | +## Critical: Read the bundled docs |
| 19 | + |
| 20 | +The `chat` package ships with full documentation in `node_modules/chat/docs/` and TypeScript source types. **Always read these before writing code:** |
| 21 | + |
| 22 | +``` |
| 23 | +node_modules/chat/docs/ # Full documentation (MDX files) |
| 24 | +node_modules/chat/dist/ # Built types (.d.ts files) |
| 25 | +``` |
| 26 | + |
| 27 | +Key docs to read based on task: |
| 28 | +- `docs/getting-started.mdx` — setup guides |
| 29 | +- `docs/usage.mdx` — event handlers, threads, messages, channels |
| 30 | +- `docs/streaming.mdx` — AI streaming with AI SDK |
| 31 | +- `docs/cards.mdx` — JSX interactive cards |
| 32 | +- `docs/actions.mdx` — button/dropdown handlers |
| 33 | +- `docs/modals.mdx` — form dialogs (Slack only) |
| 34 | +- `docs/adapters.mdx` — platform-specific adapter setup |
| 35 | +- `docs/state.mdx` — state adapter config (Redis, ioredis, PostgreSQL, memory) |
| 36 | + |
| 37 | +Also read the TypeScript types from `node_modules/chat/dist/` to understand the full API surface. |
| 38 | + |
| 39 | +## Quick start |
| 40 | + |
| 41 | +```typescript |
| 42 | +import { Chat } from "chat"; |
| 43 | +import { createSlackAdapter } from "@chat-adapter/slack"; |
| 44 | +import { createRedisState } from "@chat-adapter/state-redis"; |
| 45 | + |
| 46 | +const bot = new Chat({ |
| 47 | + userName: "mybot", |
| 48 | + adapters: { |
| 49 | + slack: createSlackAdapter({ |
| 50 | + botToken: process.env.SLACK_BOT_TOKEN!, |
| 51 | + signingSecret: process.env.SLACK_SIGNING_SECRET!, |
| 52 | + }), |
| 53 | + }, |
| 54 | + state: createRedisState({ url: process.env.REDIS_URL! }), |
| 55 | +}); |
| 56 | + |
| 57 | +bot.onNewMention(async (thread) => { |
| 58 | + await thread.subscribe(); |
| 59 | + await thread.post("Hello! I'm listening to this thread."); |
| 60 | +}); |
| 61 | + |
| 62 | +bot.onSubscribedMessage(async (thread, message) => { |
| 63 | + await thread.post(`You said: ${message.text}`); |
| 64 | +}); |
| 65 | +``` |
| 66 | + |
| 67 | +## Core concepts |
| 68 | + |
| 69 | +- **Chat** — main entry point, coordinates adapters and routes events |
| 70 | +- **Adapters** — platform-specific (Slack, Teams, GChat, Discord, GitHub, Linear) |
| 71 | +- **State** — pluggable persistence (Redis or PostgreSQL for prod, memory for dev) |
| 72 | +- **Thread** — conversation thread with `post()`, `schedule()`, `subscribe()`, `startTyping()` |
| 73 | +- **Message** — normalized format with `text`, `formatted` (mdast AST), `raw` |
| 74 | +- **Channel** — container for threads, supports listing and posting |
| 75 | + |
| 76 | +## Event handlers |
| 77 | + |
| 78 | +| Handler | Trigger | |
| 79 | +|---------|---------| |
| 80 | +| `onNewMention` | Bot @-mentioned in unsubscribed thread | |
| 81 | +| `onSubscribedMessage` | Any message in subscribed thread | |
| 82 | +| `onNewMessage(regex)` | Messages matching pattern in unsubscribed threads | |
| 83 | +| `onSlashCommand("/cmd")` | Slash command invocations | |
| 84 | +| `onReaction(emojis)` | Emoji reactions added/removed | |
| 85 | +| `onAction(actionId)` | Button clicks and dropdown selections | |
| 86 | +| `onAssistantThreadStarted` | Slack Assistants API thread opened | |
| 87 | +| `onAppHomeOpened` | Slack App Home tab opened | |
| 88 | + |
| 89 | +## Streaming |
| 90 | + |
| 91 | +Pass any `AsyncIterable<string>` to `thread.post()`. Works with AI SDK's `textStream`: |
| 92 | + |
| 93 | +```typescript |
| 94 | +import { ToolLoopAgent } from "ai"; |
| 95 | +const agent = new ToolLoopAgent({ model: "anthropic/claude-4.5-sonnet" }); |
| 96 | + |
| 97 | +bot.onNewMention(async (thread, message) => { |
| 98 | + const result = await agent.stream({ prompt: message.text }); |
| 99 | + await thread.post(result.textStream); |
| 100 | +}); |
| 101 | +``` |
| 102 | + |
| 103 | +## Cards (JSX) |
| 104 | + |
| 105 | +Set `jsxImportSource: "chat"` in tsconfig. Components: `Card`, `CardText`, `Button`, `Actions`, `Fields`, `Field`, `Select`, `SelectOption`, `Image`, `Divider`, `LinkButton`, `Section`, `RadioSelect`. |
| 106 | + |
| 107 | +```tsx |
| 108 | +await thread.post( |
| 109 | + <Card title="Order #1234"> |
| 110 | + <CardText>Your order has been received!</CardText> |
| 111 | + <Actions> |
| 112 | + <Button id="approve" style="primary">Approve</Button> |
| 113 | + <Button id="reject" style="danger">Reject</Button> |
| 114 | + </Actions> |
| 115 | + </Card> |
| 116 | +); |
| 117 | +``` |
| 118 | + |
| 119 | +## Packages |
| 120 | + |
| 121 | +| Package | Purpose | |
| 122 | +|---------|---------| |
| 123 | +| `chat` | Core SDK | |
| 124 | +| `@chat-adapter/slack` | Slack | |
| 125 | +| `@chat-adapter/teams` | Microsoft Teams | |
| 126 | +| `@chat-adapter/gchat` | Google Chat | |
| 127 | +| `@chat-adapter/discord` | Discord | |
| 128 | +| `@chat-adapter/github` | GitHub Issues | |
| 129 | +| `@chat-adapter/linear` | Linear Issues | |
| 130 | +| `@chat-adapter/state-redis` | Redis state (production) | |
| 131 | +| `@chat-adapter/state-ioredis` | ioredis state (alternative) | |
| 132 | +| `@chat-adapter/state-pg` | PostgreSQL state (production) | |
| 133 | +| `@chat-adapter/state-memory` | In-memory state (development) | |
| 134 | + |
| 135 | +## Changesets (Release Flow) |
| 136 | + |
| 137 | +This monorepo uses [Changesets](https://github.com/changesets/changesets) for versioning and changelogs. Every PR that changes a package's behavior must include a changeset. |
| 138 | + |
| 139 | +```bash |
| 140 | +pnpm changeset |
| 141 | +# → select affected package(s) (e.g. @chat-adapter/slack, chat) |
| 142 | +# → choose bump type: patch (fixes), minor (features), major (breaking) |
| 143 | +# → write a short summary for the CHANGELOG |
| 144 | +``` |
| 145 | + |
| 146 | +This creates a file in `.changeset/` — commit it with the PR. When merged to `main`, the Changesets GitHub Action opens a "Version Packages" PR to bump versions and update CHANGELOGs. Merging that PR publishes to npm. |
| 147 | + |
| 148 | +## Building a custom adapter |
| 149 | + |
| 150 | +To create a community or vendor adapter, implement the `Adapter` interface from `chat` and read: |
| 151 | + |
| 152 | +- `docs/contributing/building.mdx` — full step-by-step guide (uses a Matrix adapter as example) |
| 153 | +- `docs/contributing/testing.mdx` — testing your adapter |
| 154 | +- `docs/contributing/publishing.mdx` — npm naming conventions and publishing |
| 155 | + |
| 156 | +The adapter must implement `handleWebhook`, `parseMessage`, `postMessage`, `editMessage`, `deleteMessage`, thread ID encoding/decoding, and a `FormatConverter` (extend `BaseFormatConverter` from `chat`). Use `@chat-adapter/shared` for error classes and message utilities. |
| 157 | + |
| 158 | +## Webhook setup |
| 159 | + |
| 160 | +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). |
0 commit comments