chat 4.14.0 → 4.16.0

package/docs/handling-events.mdx

@@ -0,0 +1,375 @@
+---
+title: Handling Events
+description: Register handlers for mentions, messages, reactions, and platform-specific events.
+type: guide
+prerequisites:
+  - /docs/getting-started
+related:
+  - /docs/slash-commands
+  - /docs/actions
+  - /docs/modals
+---
+
+Chat SDK uses an event-driven architecture. You register handlers for different event types, and the SDK routes incoming webhooks to the appropriate handler.
+
+## How routing works
+
+When a message arrives, the SDK evaluates handlers in this order:
+
+1. **Subscribed threads** — if the thread is subscribed, `onSubscribedMessage` fires and no other message handler runs.
+2. **Mentions** — if the bot is @-mentioned in an unsubscribed thread, `onNewMention` fires.
+3. **Pattern matches** — if the message text matches any `onNewMessage` regex patterns, those handlers fire.
+
+Reactions, slash commands, actions, and modals have their own dedicated routing and are not affected by subscription state.
+
+## Handling @-mentions
+
+`onNewMention` fires when your bot is @-mentioned in a thread it hasn't subscribed to. This is the primary entry point for new conversations.
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onNewMention(async (thread, message) => {
+  await thread.subscribe();
+  await thread.post("Hello! I'm now listening to this thread.");
+});
+```
+
+The handler receives a [`Thread`](/docs/api/thread) and a [`Message`](/docs/api/message). Once you call `thread.subscribe()`, future messages in that thread route to `onSubscribedMessage` instead.
+
+### When to use
+
+- **AI assistants** — subscribe on first mention, then respond to all follow-up messages in the thread.
+- **Ticket bots** — create a ticket when mentioned, then track the conversation.
+- **One-shot commands** — respond to a mention without subscribing for bots that don't need ongoing context.
+
+### Example: AI assistant with context
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onNewMention(async (thread, message) => {
+  await thread.subscribe();
+  await thread.startTyping();
+
+  const response = await generateAIResponse(message.text);
+  await thread.post(response);
+});
+```
+
+### Example: Triage bot
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onNewMention(async (thread, message) => {
+  const ticket = await createTicket({
+    title: message.text.slice(0, 100),
+    reporter: message.author.fullName,
+  });
+
+  await thread.post(`Ticket created: ${ticket.url}`);
+});
+```
+
+## Handling subscribed messages
+
+`onSubscribedMessage` fires for every new message in a thread your bot has subscribed to. Once subscribed, all messages (including @-mentions) route here instead of `onNewMention`.
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onSubscribedMessage(async (thread, message) => {
+  if (message.isMention) {
+    await thread.post("You mentioned me!");
+    return;
+  }
+
+  await thread.post(`Got your message: ${message.text}`);
+});
+```
+
+<Callout type="info">
+Messages sent by the bot itself do not trigger this handler. You don't need to filter out your own messages.
+</Callout>
+
+### When to use
+
+- **Conversational AI** — maintain a back-and-forth conversation with message history.
+- **Thread monitoring** — watch a thread for updates and react to specific keywords or patterns.
+- **Collaborative workflows** — track all messages in a thread to update external systems.
+
+### Example: Conversational AI with history
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onSubscribedMessage(async (thread, message) => {
+  await thread.startTyping();
+
+  // Build conversation history from thread messages
+  const history = [];
+  for await (const msg of thread.allMessages) {
+    history.push({
+      role: msg.author.isMe ? "assistant" : "user",
+      content: msg.text,
+    });
+  }
+
+  const response = await generateAIResponse(history);
+  await thread.post(response);
+});
+```
+
+### Example: Unsubscribe on keyword
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onSubscribedMessage(async (thread, message) => {
+  if (message.text.toLowerCase().includes("stop")) {
+    await thread.unsubscribe();
+    await thread.post("Got it, I'll stop watching this thread.");
+    return;
+  }
+
+  // Handle other messages...
+});
+```
+
+### Example: Thread state for multi-step flows
+
+```typescript title="lib/bot.ts" lineNumbers
+interface ThreadState {
+  step: "awaiting_name" | "awaiting_email" | "done";
+}
+
+const bot = new Chat<typeof adapters, ThreadState>({ /* ...config */ });
+
+bot.onNewMention(async (thread) => {
+  await thread.subscribe();
+  await thread.setState({ step: "awaiting_name" });
+  await thread.post("Let's get you set up. What's your name?");
+});
+
+bot.onSubscribedMessage(async (thread, message) => {
+  const state = await thread.state;
+
+  switch (state?.step) {
+    case "awaiting_name":
+      await thread.setState({ step: "awaiting_email" });
+      await thread.post(`Thanks, ${message.text}! What's your email?`);
+      break;
+    case "awaiting_email":
+      await thread.setState({ step: "done" });
+      await thread.post("All set! Your account has been created.");
+      await thread.unsubscribe();
+      break;
+  }
+});
+```
+
+## Handling pattern matches
+
+`onNewMessage` fires for messages matching a regex pattern in threads the bot is **not** subscribed to. Use it for keyword-triggered responses without requiring an @-mention.
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onNewMessage(/^help$/i, async (thread, message) => {
+  await thread.post("Here's how I can help...");
+});
+```
+
+The first argument is a `RegExp` that's tested against the message text. Only messages in unsubscribed threads are evaluated.
+
+### When to use
+
+- **Keyword triggers** — respond to specific words or phrases without requiring a mention.
+- **Auto-responders** — detect common questions and provide instant answers.
+- **Escalation detection** — watch for urgent language and alert the right people.
+
+### Example: FAQ auto-responder
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onNewMessage(/\b(deploy|deployment|ship)\b/i, async (thread, message) => {
+  await thread.post(
+    "Deployments run automatically on push to `main`. " +
+    "Check status at https://dashboard.example.com/deploys"
+  );
+});
+```
+
+### Example: Incident detection
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onNewMessage(/\b(outage|down|incident|p[01])\b/i, async (thread, message) => {
+  await thread.subscribe();
+  await thread.post(
+    "I've flagged this as a potential incident and I'm monitoring this thread."
+  );
+
+  await notifyOnCallTeam({
+    channel: thread.channel.id,
+    reporter: message.author.fullName,
+    text: message.text,
+  });
+});
+```
+
+## Handling reactions
+
+`onReaction` fires when users add or remove emoji reactions to messages. You can handle all reactions or filter by specific emoji.
+
+```typescript title="lib/bot.ts" lineNumbers
+import { emoji } from "chat";
+
+// Handle specific emoji
+bot.onReaction(["thumbs_up", "heart"], async (event) => {
+  if (!event.added) return;
+
+  await event.adapter.addReaction(
+    event.threadId,
+    event.messageId,
+    emoji.raised_hands
+  );
+});
+
+// Handle all reactions
+bot.onReaction(async (event) => {
+  console.log(`${event.user.userName} ${event.added ? "added" : "removed"} ${event.emoji}`);
+});
+```
+
+### ReactionEvent
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `emoji` | `EmojiValue` | Normalized emoji name for cross-platform comparison |
+| `rawEmoji` | `string` | Platform-specific emoji string |
+| `added` | `boolean` | `true` if added, `false` if removed |
+| `user` | `Author` | The user who reacted |
+| `message` | `Message` (optional) | The message that was reacted to |
+| `thread` | `Thread` | Thread for posting replies |
+| `messageId` | `string` | ID of the message that was reacted to |
+| `threadId` | `string` | Thread ID |
+| `adapter` | `Adapter` | The platform adapter |
+| `raw` | `unknown` | Platform-specific event payload |
+
+### When to use
+
+- **Approval workflows** — use thumbs up/down as lightweight approve/reject signals.
+- **Bookmarking** — save messages to an external system when a specific emoji is added.
+- **Polls and voting** — count reactions as votes.
+
+### Example: Approval workflow
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onReaction(["thumbs_up", "thumbs_down"], async (event) => {
+  if (!event.added) return;
+
+  const approved = event.emoji === "thumbs_up";
+  const status = approved ? "approved" : "rejected";
+
+  await event.thread.post(
+    `Request ${status} by ${event.user.fullName}`
+  );
+
+  await updateRequestStatus(event.messageId, status, event.user.userId);
+});
+```
+
+### Example: Save to external system
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onReaction(["bookmark"], async (event) => {
+  if (!event.added || !event.message) return;
+
+  await saveToDatabase({
+    text: event.message.text,
+    savedBy: event.user.userId,
+    source: event.threadId,
+  });
+
+  await event.thread.post(
+    `Bookmarked by ${event.user.fullName}`
+  );
+});
+```
+
+## Handling interactions
+
+For button clicks, slash commands, and modal forms, see the dedicated guides:
+
+- **[Slash Commands](/docs/slash-commands)** — handle `/command` invocations from the message composer.
+- **[Actions](/docs/actions)** — handle button clicks and interactive card events.
+- **[Modals](/docs/modals)** — collect structured input through modal dialogs with validation.
+
+## Handling Slack-specific events
+
+These handlers are specific to the Slack platform and require the Slack adapter.
+
+### Handling assistant threads
+
+`onAssistantThreadStarted` fires when a user opens a new assistant thread in Slack. Use it with the [Slack Assistants API](/adapters/slack#slack-assistants-api) to set suggested prompts and status indicators.
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onAssistantThreadStarted(async (event) => {
+  const slack = bot.getAdapter("slack") as SlackAdapter;
+  await slack.setSuggestedPrompts(event.channelId, event.threadTs, [
+    { title: "Get started", message: "What can you help me with?" },
+    { title: "Summarize", message: "Summarize the current channel" },
+  ]);
+});
+```
+
+The `event` object includes:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `channelId` | `string` | The assistant thread's channel |
+| `threadTs` | `string` | Thread timestamp |
+| `threadId` | `string` | Thread ID |
+| `userId` | `string` | User who started the thread |
+| `context` | `object` | Assistant context (channelId, teamId, enterpriseId, threadEntryPoint) |
+| `adapter` | `Adapter` | The Slack adapter |
+
+### Handling assistant context changes
+
+`onAssistantContextChanged` fires when the assistant context changes, for example when a user navigates to a different channel while the assistant thread is open.
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onAssistantContextChanged(async (event) => {
+  const slack = bot.getAdapter("slack") as SlackAdapter;
+  await slack.setStatus(event.channelId, event.threadTs, "Updating context...");
+
+  // Update prompts based on new context
+  const channelName = event.context.channelId ?? "general";
+  await slack.setSuggestedPrompts(event.channelId, event.threadTs, [
+    { title: "Summarize", message: `Summarize #${channelName}` },
+  ]);
+});
+```
+
+### Handling App Home opens
+
+`onAppHomeOpened` fires when a user opens your bot's Home tab in Slack. Use it to publish a dynamic view.
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onAppHomeOpened(async (event) => {
+  const slack = bot.getAdapter("slack") as SlackAdapter;
+  await slack.publishHomeView(event.userId, {
+    type: "home",
+    blocks: [
+      {
+        type: "section",
+        text: { type: "mrkdwn", text: `Welcome, <@${event.userId}>!` },
+      },
+      {
+        type: "actions",
+        elements: [
+          {
+            type: "button",
+            text: { type: "plain_text", text: "Open Dashboard" },
+            url: "https://dashboard.example.com",
+          },
+        ],
+      },
+    ],
+  });
+});
+```
+
+The `event` object includes:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `userId` | `string` | User who opened the Home tab |
+| `channelId` | `string` | Channel context |
+| `adapter` | `Adapter` | The Slack adapter |

package/docs/index.mdx

@@ -1,10 +1,10 @@
 ---
 title: Introduction
-description: A unified SDK for building chat bots across Slack, Microsoft Teams, Google Chat, Discord, and more.
+description: A unified SDK for building chat bots across Slack, Microsoft Teams, Google Chat, Discord, Telegram, and more.
 type: overview
 ---
 
-Chat SDK is a TypeScript library for building chat bots that work across multiple platforms with a single codebase. Write your bot logic once and deploy it to Slack, Microsoft Teams, Google Chat, Discord, GitHub, and Linear.
+Chat SDK is a TypeScript library for building chat bots that work across multiple platforms with a single codebase. Write your bot logic once and deploy it to Slack, Microsoft Teams, Google Chat, Discord, Telegram, GitHub, and Linear.
 
 ## Why Chat SDK?
 
@@ -55,6 +55,7 @@ Each adapter factory auto-detects credentials from environment variables (`SLACK
 | Microsoft Teams | `@chat-adapter/teams` | Yes | Read-only | Yes | No | Post+Edit | Yes |
 | Google Chat | `@chat-adapter/gchat` | Yes | Yes | Yes | No | Post+Edit | Yes |
 | Discord | `@chat-adapter/discord` | Yes | Yes | Yes | No | Post+Edit | Yes |
+| Telegram | `@chat-adapter/telegram` | Yes | Yes | Partial | No | Post+Edit | Yes |
 | GitHub | `@chat-adapter/github` | Yes | Yes | No | No | No | No |
 | Linear | `@chat-adapter/linear` | Yes | Yes | No | No | No | No |
 
@@ -79,6 +80,7 @@ The SDK is distributed as a set of packages you install based on your needs:
 | `@chat-adapter/teams` | Microsoft Teams adapter |
 | `@chat-adapter/gchat` | Google Chat adapter |
 | `@chat-adapter/discord` | Discord adapter |
+| `@chat-adapter/telegram` | Telegram adapter |
 | `@chat-adapter/github` | GitHub Issues adapter |
 | `@chat-adapter/linear` | Linear Issues adapter |
 | `@chat-adapter/state-redis` | Redis state adapter (production) |

package/docs/meta.json

@@ -3,7 +3,10 @@
   "pages": [
     "index",
     "getting-started",
+    "---Usage---",
     "usage",
+    "threads-messages-channels",
+    "handling-events",
     "posting-messages",
     "---Features---",
     "...",
@@ -15,6 +18,8 @@
     "---Guides---",
     "...guides",
     "---API Reference---",
-    "...api"
+    "...api",
+    "---Contributing---",
+    "...contributing"
   ]
 }

package/docs/posting-messages.mdx

@@ -16,7 +16,7 @@ related:
 
 The simplest option. Pass a string and it goes through as-is to the platform.
 
-```typescript title="lib/bot.ts"
+```typescript title="lib/bot.ts" lineNumbers
 await thread.post("Hello world");
 ```
 
@@ -26,7 +26,7 @@ This sends the string directly without any formatting conversion.
 
 Pass a `{ markdown }` object to have the SDK convert standard markdown to each platform's native format — mrkdwn for Slack, HTML for Teams, and so on.
 
-```typescript title="lib/bot.ts"
+```typescript title="lib/bot.ts" lineNumbers
 await thread.post({
   markdown: "**Bold**, _italic_, and `code`",
 });
@@ -38,7 +38,7 @@ Under the hood, the SDK parses the markdown into an mdast AST, then each adapter
 
 For programmatic control over message formatting, use the mdast AST builder functions exported from `chat`. This is the recommended approach for most use cases — it gives you fine-grained control without the overhead of card rendering.
 
-```typescript title="lib/bot.ts"
+```typescript title="lib/bot.ts" lineNumbers
 import { root, paragraph, text, strong, link } from "chat";
 
 await thread.post({
@@ -71,7 +71,7 @@ await thread.post({
 
 You can also parse a markdown string into an AST, manipulate it, then send it:
 
-```typescript title="lib/bot.ts"
+```typescript title="lib/bot.ts" lineNumbers
 import { parseMarkdown, stringifyMarkdown } from "chat";
 
 const ast = parseMarkdown("**Hello** world");
@@ -87,7 +87,7 @@ When you need interactive elements like buttons, dropdowns, or structured layout
 
 Use the function-call API for type-safe card construction:
 
-```typescript title="lib/bot.ts"
+```typescript title="lib/bot.ts" lineNumbers
 import { Card, Text, Actions, Button } from "chat";
 
 await thread.post(
@@ -141,7 +141,7 @@ See the [Cards](/docs/cards) page for the full list of card components.
 
 Pass an `AsyncIterable<string>` (like the AI SDK's `textStream`) to stream a message in real time. The SDK uses platform-native streaming where available and falls back to post-then-edit on other platforms.
 
-```typescript title="lib/bot.ts"
+```typescript title="lib/bot.ts" lineNumbers
 import { streamText } from "ai";
 
 const result = streamText({ model, prompt: message.text });
@@ -154,7 +154,7 @@ See the [Streaming](/docs/streaming) page for details on platform behavior and c
 
 Any structured message format (`markdown`, `ast`, or `card`) supports `files` for uploading attachments alongside the message:
 
-```typescript title="lib/bot.ts"
+```typescript title="lib/bot.ts" lineNumbers
 await thread.post({
   markdown: "Here's the report:",
   files: [{ data: buffer, filename: "report.pdf" }],

package/docs/slash-commands.mdx

@@ -7,10 +7,13 @@ prerequisites:
 related:
   - /docs/modals
   - /docs/adapters/slack
+  - /docs/adapters/discord
 ---
 
 Slash commands let users invoke your bot with `/command` syntax. Register handlers with `onSlashCommand` to respond.
 
+Slash commands are supported on [Slack](/docs/adapters/slack) and [Discord](/docs/adapters/discord).
+
 ## Handle a specific command
 
 ```typescript title="lib/bot.ts" lineNumbers
@@ -108,3 +111,23 @@ bot.onModalSubmit("feedback_form", async (event) => {
   }
 });
 ```
+
+## Discord
+
+Discord slash commands are received via [HTTP Interactions](/docs/adapters/discord#architecture-http-interactions-vs-gateway) — no Gateway connection is needed. The adapter automatically sends a deferred response to Discord, then resolves it when your handler calls `event.channel.post()`.
+
+### Subcommands
+
+Discord supports subcommand groups and subcommands. The adapter flattens these into the `event.command` path:
+
+| Discord command | `event.command` | `event.text` |
+|-----------------|-----------------|--------------|
+| `/status` | `/status` | `""` |
+| `/project create --name="Acme"` | `/project create` | `Acme` |
+| `/project issue list --status="open"` | `/project issue list` | `open` |
+
+For full option details (names, types), use `event.raw` to access the original Discord interaction payload.
+
+### Registering commands with Discord
+
+You need to register slash commands with the [Discord API](https://discord.com/developers/docs/interactions/application-commands) before they appear in the client. The Chat SDK handles incoming commands but does not register them for you.

package/docs/state/meta.json

@@ -1,9 +1,4 @@
 {
   "title": "State",
-  "pages": [
-    "index",
-    "redis",
-    "ioredis",
-    "memory"
-  ]
+  "pages": ["index", "redis", "ioredis", "memory"]
 }

package/docs/streaming.mdx

@@ -58,6 +58,38 @@ const bot = new Chat({
 });
 ```
 
+### Disabling the placeholder message
+
+By default, post+edit adapters send an initial `"..."` placeholder message before the first chunk arrives. You can disable this to wait for real content before posting:
+
+```typescript title="lib/bot.ts" lineNumbers
+const bot = new Chat({
+  // ...
+  fallbackStreamingPlaceholderText: null,
+});
+```
+
+You can also customize the placeholder text:
+
+```typescript title="lib/bot.ts"
+const bot = new Chat({
+  // ...
+  fallbackStreamingPlaceholderText: "Thinking...",
+});
+```
+
+## Markdown healing
+
+During streaming, chunks often arrive mid-word or mid-syntax — for example, `**bold` before the closing `**` arrives. The SDK automatically heals incomplete markdown in intermediate renders using [remend](https://www.npmjs.com/package/remend), so messages always display with correct formatting while streaming.
+
+The final message uses the raw accumulated text without healing, so the original markdown is preserved.
+
+## Table buffering
+
+When streaming content that contains GFM tables (e.g. from an LLM), the SDK automatically buffers potential table headers until a separator line (`|---|---|`) confirms them. This prevents tables from briefly flashing as raw pipe-delimited text before the table structure is complete.
+
+This happens transparently — no configuration needed.
+
 ## Stop blocks (Slack only)
 
 When streaming in Slack, you can attach Block Kit elements to the final message using `stopBlocks`. This is useful for adding action buttons after a streamed response completes: