Ben Sabic
80def3ab17
Closes #653 Chat SDK's normalized author only distinguished the current bot from other bots (`isBot`/`isMe`), so Slack system notifications authored by the reserved `USLACK` user — which carry no `bot_id` and no system subtype — were dispatched to handlers as if human-authored. Consumers had to hard-code `message.author.userId === "USLACK"`, leaking Slack-specific identifiers into adapter-independent code. This adds an optional `isSystem?: boolean` to the normalized `Author` type, documented so that an absent value means `false`. Keeping it optional avoids breaking existing custom adapters and serialized messages, as proposed in the issue. The Slack adapter now sets it in both parse paths (`parseSlackMessage` and the sync `parseMessage` path) via a `SLACK_SYSTEM_USER_ID` constant, so applications can write: ```ts bot.onNewMention(async (thread, message) => { if (message.author.isSystem) { return; } await generateAssistantResponse(thread, message); }); ``` Other adapters can adopt the same field when their platforms expose equivalent system-generated messages. Also included: - Regression tests covering the issue's exact case (`USLACK` DM, no `bot_id`, no subtype) across all three layers: async parse, sync `parseMessage`, and end-to-end `handleWebhook` dispatch — plus the negative case for human authors. - A `USLACK` webhook fixture in `sample-messages.md`. - `isSystem` documented in the Author type table on the Message API docs page. - Changesets for `chat` and `@chat-adapter/slack`. --------- Co-authored-by: mdnanocom <arnaud@massive-dynamic.ai> Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com> Co-authored-by: dancer <josh@afterima.ge>
Chat SDK
npm package:
chat
Universal TypeScript SDK for building multi-platform chat bots and AI agents on Slack, Teams, Google Chat, Discord, WhatsApp, and more. Provides the Chat class, event handlers, JSX cards, emoji helpers, and type-safe message formatting.
Documentation: chat-sdk.dev/docs · Guides: vercel.com/kb/chat-sdk
Installation
npm install chat
CLI
Scaffold a minimal Next.js bot app with create-chat-sdk:
npx create-chat-sdk@latest my-bot
The CLI generates your Chat configuration, webhook route, .env.example file, dependencies, and optional Web adapter route from the adapter catalog. See the CLI docs for options and non-interactive usage.
Usage
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! }),
dedupeTtlMs: 600_000, // 10 minutes (default: 5 min)
});
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}`);
});
Tip: PostgreSQL and ioredis adapters are also available for production. See State Adapters for all options.
Configuration
| Option | Type | Default | Description |
|---|---|---|---|
userName |
string |
required | Default bot username across all adapters |
adapters |
Record<string, Adapter> |
required | Map of adapter name to adapter instance |
state |
StateAdapter |
required | State adapter for subscriptions, locking, and dedup |
logger |
Logger | LogLevel |
"info" |
Logger instance or log level ("silent" to disable) |
streamingUpdateIntervalMs |
number |
500 |
Update interval for fallback streaming (post + edit) in ms |
dedupeTtlMs |
number |
300000 |
TTL for message deduplication entries in ms. Increase if webhook cold starts cause platform retries (e.g., Slack's http_timeout retry) that arrive after the default window |
AI Coding Agents
If you use an AI coding agent such as OpenAI Codex, Claude Code, or Cursor, install the Chat SDK skill so it knows the SDK APIs, adapter patterns, and project conventions before writing code.
npx skills add vercel/chat
The skill references bundled documentation in node_modules/chat/docs, plus adapter guides and starter templates in the published package.
You can also install the Vercel Plugin for a broader agent toolkit — it includes the Chat SDK skill alongside specialist agents, agent slash commands, and more:
npx plugins add vercel/vercel-plugin
The plugin is optional; the skill alone is enough to build with Chat SDK.
For agent-readable documentation, see chat-sdk.dev/llms.txt (page index) or chat-sdk.dev/llms-full.txt (full text).
Documentation
Full documentation is available at chat-sdk.dev/docs.
- Usage — event handlers, threads, messages, channels
- Chat API — full
Chatclass reference - Cards — JSX-based interactive cards
- Streaming — AI SDK integration
- Emoji — cross-platform emoji helpers
License
MIT