Chat SDK
Unified TypeScript SDK for building chat bots across Slack, Teams, Google Chat, Discord, GitHub, and Linear. Write bot logic once, deploy everywhere.
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, PostgreSQL, memory)
Also read the TypeScript types from
node_modules/chat/dist/
to understand the full API surface.
Quick start
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 or PostgreSQL for prod, memory for dev)
Thread
— conversation thread with
post()
,
schedule()
,
subscribe()
,
startTyping()
Message
— normalized format with
text
,
formatted
(mdast AST),
raw
Channel
— container for threads, supports listing and posting
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
Streaming
Pass any
AsyncIterable
< 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-pg PostgreSQL state (production) @chat-adapter/state-memory In-memory state (development) Changesets (Release Flow) This monorepo uses Changesets for versioning and changelogs. Every PR that changes a package's behavior must include a changeset. pnpm changeset
→ select affected package(s) (e.g. @chat-adapter/slack, chat)
→ choose bump type: patch (fixes), minor (features), major (breaking)
→ write a short summary for the CHANGELOG
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. Building a custom adapter To create a community or vendor adapter, implement the Adapter interface from chat and read: docs/contributing/building.mdx — full step-by-step guide (uses a Matrix adapter as example) docs/contributing/testing.mdx — testing your adapter docs/contributing/publishing.mdx — npm naming conventions and publishing 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. Webhook setup 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).