chat 4.28.1 → 4.30.0

package/docs/{api → ai}/to-ai-messages.mdx

@@ -2,18 +2,31 @@
 title: toAiMessages
 description: Convert Chat SDK messages to AI SDK conversation format.
 type: reference
+related:
+  - /docs/ai
+  - /docs/ai/ai-sdk-tools
+  - /docs/ai/types
+  - /docs/streaming
 ---
 
-Convert an array of `Message` objects into the `{ role, content }[]` format expected by AI SDKs. The output is structurally compatible with AI SDK's `ModelMessage[]`.
+Convert an array of [`Message`](/docs/api/message) objects into the `{ role, content }[]` format expected by the AI SDK. The output is structurally compatible with AI SDK's `ModelMessage[]`.
 
 ```typescript
-import { toAiMessages } from "chat";
+import { toAiMessages } from "chat/ai";
 ```
 
+<Callout>
+  `toAiMessages` is also re-exported from the main `chat` entrypoint
+  for backwards compatibility (with a `@deprecated` JSDoc hint), but
+  new code should import it from [`chat/ai`](/docs/ai) alongside
+  [`createChatTools`](/docs/ai/ai-sdk-tools) and the rest of the AI
+  utilities.
+</Callout>
+
 ## Usage
 
 ```typescript title="lib/bot.ts" lineNumbers
-import { toAiMessages } from "chat";
+import { toAiMessages } from "chat/ai";
 
 bot.onSubscribedMessage(async (thread, message) => {
   const result = await thread.adapter.fetchMessages(thread.id, { limit: 20 });

package/docs/ai/types.mdx

@@ -0,0 +1,243 @@
+---
+title: Types
+description: TypeScript types exported from the chat/ai subpath.
+type: reference
+related:
+  - /docs/ai
+  - /docs/ai/ai-sdk-tools
+  - /docs/ai/to-ai-messages
+---
+
+Every type exported from `chat/ai`. Pulling these from the subpath keeps the optional `ai` and `zod` peer deps out of bundles that don't import them.
+
+```ts
+import type {
+  AiMessage,
+  AiUserMessage,
+  AiAssistantMessage,
+  AiMessagePart,
+  AiTextPart,
+  AiImagePart,
+  AiFilePart,
+  ToAiMessagesOptions,
+  ChatBinding,
+  ChatTools,
+  ChatToolName,
+  ChatToolPreset,
+  ChatWriteToolName,
+  ApprovalConfig,
+  ToolOptions,
+  ToolOverrides,
+} from "chat/ai";
+```
+
+## Conversation messages
+
+Used by [`toAiMessages`](/docs/ai/to-ai-messages) and any agent prompt you build by hand. The shapes are structurally compatible with AI SDK's `ModelMessage` so the result is directly assignable to `prompt` / `messages`.
+
+### AiMessage
+
+```typescript
+type AiMessage = AiUserMessage | AiAssistantMessage;
+```
+
+A single normalized turn in a conversation — the array form is what AI SDK calls expect.
+
+### AiUserMessage
+
+```typescript
+interface AiUserMessage {
+  role: "user";
+  content: string | AiMessagePart[];
+}
+```
+
+User content can be plain text, or a multipart array when attachments are present.
+
+### AiAssistantMessage
+
+```typescript
+interface AiAssistantMessage {
+  role: "assistant";
+  content: string;
+}
+```
+
+Assistant turns are always plain strings — `toAiMessages` produces this for any message authored by the bot itself (`author.isMe === true`).
+
+### AiMessagePart
+
+```typescript
+type AiMessagePart = AiTextPart | AiImagePart | AiFilePart;
+```
+
+The discriminated union used inside multipart user messages.
+
+### AiTextPart
+
+```typescript
+interface AiTextPart {
+  type: "text";
+  text: string;
+}
+```
+
+### AiImagePart
+
+```typescript
+interface AiImagePart {
+  type: "image";
+  image: DataContent | URL;
+  mediaType?: string;
+}
+```
+
+`DataContent` matches AI SDK's type — `string | Uint8Array | ArrayBuffer | Buffer`.
+
+### AiFilePart
+
+```typescript
+interface AiFilePart {
+  type: "file";
+  data: DataContent | URL;
+  filename?: string;
+  mediaType: string;
+}
+```
+
+`toAiMessages` emits text-like attachments (JSON, XML, YAML, source files, etc.) as file parts.
+
+### ToAiMessagesOptions
+
+```typescript
+interface ToAiMessagesOptions {
+  includeNames?: boolean;
+  transformMessage?: (
+    aiMessage: AiMessage,
+    source: Message
+  ) => AiMessage | null | Promise<AiMessage | null>;
+  onUnsupportedAttachment?: (
+    attachment: Attachment,
+    message: Message
+  ) => void;
+}
+```
+
+See [`toAiMessages`](/docs/ai/to-ai-messages) for behavior and examples.
+
+## Tools
+
+Returned by [`createChatTools`](/docs/ai/ai-sdk-tools) and used to configure it.
+
+### ChatBinding
+
+```typescript
+type ChatBinding = Chat<any, any>;
+```
+
+Whatever [`Chat`](/docs/api/chat) instance the tools should dispatch operations against. The generics are intentionally loose so any strongly-typed `Chat<TAdapters, TState>` is assignable.
+
+### ChatTools
+
+```typescript
+type ChatTools = ReturnType<typeof createChatTools>;
+```
+
+Convenience alias for the object returned by `createChatTools` — handy when you want to type a wrapper or pass the toolset around.
+
+### ChatToolPreset
+
+```typescript
+type ChatToolPreset = "reader" | "messenger" | "moderator";
+```
+
+Predefined toolset scopes. See [Presets](/docs/ai/ai-sdk-tools#presets) for the exact tool list per preset.
+
+### ChatToolName
+
+```typescript
+type ChatToolName =
+  | "fetchMessages"
+  | "fetchChannelMessages"
+  | "fetchThread"
+  | "listThreads"
+  | "getThreadParticipants"
+  | "getChannelInfo"
+  | "getUser"
+  | "startTyping"
+  | "postMessage"
+  | "postChannelMessage"
+  | "sendDirectMessage"
+  | "editMessage"
+  | "deleteMessage"
+  | "addReaction"
+  | "removeReaction"
+  | "subscribeThread"
+  | "unsubscribeThread";
+```
+
+The names of every generated tool. Useful when typing per-tool overrides.
+
+### ChatWriteToolName
+
+```typescript
+type ChatWriteToolName =
+  | "postMessage"
+  | "postChannelMessage"
+  | "sendDirectMessage"
+  | "editMessage"
+  | "deleteMessage"
+  | "addReaction"
+  | "removeReaction"
+  | "subscribeThread"
+  | "unsubscribeThread";
+```
+
+The names of every mutating tool. Useful when wiring per-tool approval overrides.
+
+### ApprovalConfig
+
+```typescript
+type ApprovalConfig =
+  | boolean
+  | Partial<Record<ChatWriteToolName, boolean>>;
+```
+
+Controls the `requireApproval` option:
+
+- `true` (default) — every write tool needs approval.
+- `false` — no write tool needs approval.
+- object — per-tool override; unspecified write tools fall back to `true`.
+
+### ToolOptions
+
+```typescript
+interface ToolOptions {
+  needsApproval?: boolean;
+}
+```
+
+Common options accepted by every standalone write-tool factory (e.g. `postMessage(chat, { needsApproval: false })`).
+
+### ToolOverrides
+
+```typescript
+type ToolOverrides = Partial<
+  Pick<
+    Tool,
+    | "description"
+    | "inputExamples"
+    | "metadata"
+    | "needsApproval"
+    | "onInputAvailable"
+    | "onInputDelta"
+    | "onInputStart"
+    | "providerOptions"
+    | "strict"
+    | "title"
+    | "toModelOutput"
+  >
+>;
+```
+
+Per-tool overrides accepted by `createChatTools({ overrides })`. Core fields like `execute`, `inputSchema`, `outputSchema`, `type`, `id`, and `args` are intentionally excluded so tool semantics stay stable across upgrades.

package/docs/api/chat.mdx

@@ -74,9 +74,36 @@ bot.onNewMention(async (thread, message) => {
   }}
 />
 
+### onDirectMessage
+
+Fires for every direct message when registered. Direct message handlers run before `onSubscribedMessage`, `onNewMention`, and pattern handlers. If no direct message handler is registered, unsubscribed DMs fall through to `onNewMention` for backward compatibility.
+
+```typescript
+bot.onDirectMessage(async (thread, message, channel) => {
+  await thread.post(`Got your DM in ${channel.id}: ${message.text}`);
+});
+```
+
+<TypeTable
+  type={{
+    thread: {
+      description: 'The DM thread where the message occurred.',
+      type: 'Thread',
+    },
+    message: {
+      description: 'The direct message.',
+      type: 'Message',
+    },
+    channel: {
+      description: 'The DM channel.',
+      type: 'Channel',
+    },
+  }}
+/>
+
 ### onSubscribedMessage
 
-Fires for every new message in a subscribed thread. Once subscribed, all messages (including @-mentions) route here instead of `onNewMention`.
+Fires for every new message in a subscribed non-DM thread. Once subscribed, messages (including @-mentions) route here instead of `onNewMention`. DM threads route to `onDirectMessage` first when a direct message handler is registered.
 
 ```typescript
 bot.onSubscribedMessage(async (thread, message) => {
@@ -474,16 +501,20 @@ const slack = bot.getAdapter("slack");
 
 #### Direct client access
 
-Use `.client` to access the platform's typed native API client directly — available on Linear and GitHub:
+Access the platform's typed native API client directly via an SDK-named getter — `.webClient` on Slack, `.linearClient` on Linear, `.octokit` on GitHub:
 
 ```typescript
+// Slack - full WebClient from @slack/web-api
+const slack = bot.getAdapter("slack").webClient;
+await slack.pins.add({ channel: "C123ABC", timestamp: "1234567890.123456" });
+
 // Linear - full LinearClient from @linear/sdk
-const linear = bot.getAdapter("linear").client;
+const linear = bot.getAdapter("linear").linearClient;
 const issue = await linear.issue("ENG-123");
 const project = await issue.project;
 
 // GitHub - full Octokit from @octokit/rest
-const github = bot.getAdapter("github").client;
+const github = bot.getAdapter("github").octokit;
 const { data: pulls } = await github.rest.pulls.list({
   owner: "vercel",
   repo: "chat",
@@ -491,16 +522,25 @@ const { data: pulls } = await github.rest.pulls.list({
 });
 ```
 
-The client uses the credentials from your adapter config. For multi-tenant adapters (Linear, GitHub), it returns the client for the current webhook request context.
+The client uses the credentials from your adapter config. For multi-tenant / multi-workspace adapters (Slack, Linear, GitHub), it returns the client bound to the credentials for the current webhook request context.
+
+<Callout type="info">
+  The previous `.client` getter still works on all three adapters as a deprecated alias for `.webClient` / `.linearClient` / `.octokit`.
+</Callout>
 
 <Callout type="warn">
-  For multi-tenant adapters (GitHub App without a fixed installation ID, Linear with per-org OAuth), `client` requires webhook handler context to resolve credentials. Calling it outside a handler throws. Single-tenant adapters (PAT, API key) work anywhere.
+  Multi-tenant adapters (GitHub App without a fixed installation ID, Linear with per-org OAuth, Slack in multi-workspace mode) require a webhook handler context to resolve credentials when the native client getter is accessed. Calling it outside a handler throws.
+
+  For Slack, you can also bind a token explicitly outside a webhook with `adapter.withBotToken(token, () => adapter.webClient.…)` — useful for cron jobs or workflows. The same pattern is required when `botToken` is configured as an async resolver function, since `.webClient` resolves the token synchronously.
+
+  Single-tenant adapters (PAT, API key, static `botToken` string, or a synchronous `botToken` resolver) work anywhere.
 </Callout>
 
-| Adapter | `client` type |
-|---------|---------------|
-| Linear | `LinearClient` from `@linear/sdk` |
-| GitHub | `Octokit` from `@octokit/rest` |
+| Adapter | Getter | Type |
+|---------|--------|------|
+| Slack | `.webClient` | `WebClient` from `@slack/web-api` |
+| Linear | `.linearClient` | `LinearClient` from `@linear/sdk` |
+| GitHub | `.octokit` | `Octokit` from `@octokit/rest` |
 
 ### openDM
 

package/docs/api/index.mdx

@@ -20,12 +20,6 @@ import { Chat, root, paragraph, text, Card, Button, emoji } from "chat";
 | [`Message`](/docs/api/message) | Normalized message with text, AST, author, and metadata |
 | [`ScheduledMessage`](/docs/api/thread#scheduledmessage) | Returned by `thread.schedule()` / `channel.schedule()` with `cancel()` |
 
-## Utilities
-
-| Export | Description |
-|--------|-------------|
-| [`toAiMessages`](/docs/api/to-ai-messages) | Convert `Message[]` to AI SDK `{ role, content }[]` format |
-
 ## Message formats
 
 | Export | Description |
@@ -36,3 +30,7 @@ import { Chat, root, paragraph, text, Card, Button, emoji } from "chat";
 | [`Cards`](/docs/api/cards) | Rich card components — `Card`, `Text`, `Button`, `Actions`, etc. |
 | [`Markdown`](/docs/api/markdown) | AST builder functions — `root`, `paragraph`, `text`, `strong`, etc. |
 | [`Modals`](/docs/api/modals) | Modal form components — `Modal`, `TextInput`, `Select`, etc. |
+
+## AI utilities
+
+`toAiMessages`, `createChatTools`, and the supporting types live in the [`chat/ai`](/docs/ai) subpath — see the [AI section](/docs/ai) for the full reference.

package/docs/api/message.mdx

@@ -194,7 +194,7 @@ Links found in incoming messages are extracted and exposed as `LinkPreview` obje
 />
 
 <Callout type="info">
-When using [`toAiMessages()`](/docs/api/to-ai-messages), link metadata is automatically appended to the message content. Embedded message links are labeled as `[Embedded message: ...]` so the AI model understands the context.
+When using [`toAiMessages()`](/docs/ai/to-ai-messages), link metadata is automatically appended to the message content. Embedded message links are labeled as `[Embedded message: ...]` so the AI model understands the context.
 </Callout>
 
 ### Platform support

package/docs/api/meta.json

@@ -6,7 +6,6 @@
     "thread",
     "channel",
     "message",
-    "to-ai-messages",
     "postable-message",
     "transcripts",
     "cards",

package/docs/api/postable-message.mdx

@@ -38,7 +38,7 @@ await thread.post({ raw: "Hello world" });
       type: 'string',
     },
     attachments: {
-      description: 'File/image attachments.',
+      description: 'Typed media attachments for adapters that support outgoing attachments.',
       type: 'Attachment[]',
     },
     files: {
@@ -63,7 +63,7 @@ await thread.post({ markdown: "**Bold** and _italic_" });
       type: 'string',
     },
     attachments: {
-      description: 'File/image attachments.',
+      description: 'Typed media attachments for adapters that support outgoing attachments.',
       type: 'Attachment[]',
     },
     files: {
@@ -92,7 +92,7 @@ await thread.post({
       type: 'Root',
     },
     attachments: {
-      description: 'File/image attachments.',
+      description: 'Typed media attachments for adapters that support outgoing attachments.',
       type: 'Attachment[]',
     },
     files: {

package/docs/api/thread.mdx

@@ -146,7 +146,7 @@ if (participants.length > 1) {
 
 ## subscribe / unsubscribe
 
-Manage thread subscriptions. Subscribed threads route all messages to `onSubscribedMessage` handlers.
+Manage thread subscriptions. Subscribed non-DM threads route all messages to `onSubscribedMessage` handlers. DM threads route to `onDirectMessage` first when a direct message handler is registered.
 
 ```typescript
 await thread.subscribe();

package/docs/concurrency.mdx

@@ -1,6 +1,6 @@
 ---
 title: Overlapping Messages
-description: Control how overlapping messages on the same thread are handled — queue, debounce, drop, or process concurrently.
+description: Control how overlapping messages on the same thread are handled - burst, queue, debounce, drop, or process concurrently.
 type: guide
 prerequisites:
   - /docs/handling-events
@@ -57,11 +57,49 @@ A done     → drain: [B, C, D] → handler(D, { skipped: [B, C] })
 D done     → queue empty → release lock
 ```
 
+### Burst
+
+Waits for `debounceMs` before the first handler on an idle thread, then drains the collected burst like `queue`. The latest message is dispatched, and earlier messages in the burst are available as `context.skipped`.
+
+Use this for assistant-style bots where users often send one logical turn as several short messages inside a small window and you want one response with full context. Compared to `debounce`, `burst` keeps the earlier messages in `context.skipped` instead of dropping them, and it flushes queued messages that arrive while the handler is running.
+
+Choose `debounce` when the latest message replaces earlier ones, like rapid corrections. Choose `burst` when earlier messages still matter, like "hey", "quick question", and then the actual question. The tradeoff is that even a lone message waits for `debounceMs` before the handler runs.
+
+```typescript title="lib/bot.ts" lineNumbers
+const bot = new Chat({
+  concurrency: { strategy: "burst", debounceMs: 1000 },
+  // ...
+});
+
+bot.onNewMention(async (thread, message, context) => {
+  const turn = [...(context?.skipped ?? []), message]
+    .map((m) => m.text)
+    .join("\n\n");
+
+  const response = await generateAIResponse(turn);
+  await thread.post(response);
+});
+```
+
+**Flow:**
+
+```
+A arrives  → acquire lock → enqueue A → sleep(debounceMs)
+B arrives  → lock busy → enqueue B
+C arrives  → lock busy → enqueue C
+             ... debounceMs elapses ...
+           → drain: [A, B, C] → handler(C, { skipped: [A, B] })
+D arrives while C is running → lock busy → enqueue D
+E arrives while C is running → lock busy → enqueue E
+C done     → drain: [D, E] → handler(E, { skipped: [D] })
+E done     → queue empty → release lock
+```
+
 ### Debounce
 
-Every message starts or resets a debounce timer. Only the **final message in a burst** is processed.
+The first message waits for `debounceMs`. Messages that arrive during that window replace the pending message, so only the **final message in the burst window** is processed.
 
-This is particularly useful for platforms like **WhatsApp** and **Telegram** where users tend to send a flurry of short messages in quick succession instead of composing a single message — "hey", "quick question", "how do I reset my password?" arriving as three separate webhooks within a few seconds. Without debounce, the bot would respond to "hey" before the actual question even arrives. With debounce, the SDK waits for a pause in the conversation and processes only the final message.
+This is particularly useful for platforms like **WhatsApp** and **Telegram** where users tend to send a flurry of short messages in quick succession instead of composing a single message - "hey", "quick question", "how do I reset my password?" arriving as three separate webhooks within a few seconds. Without debounce, the bot would respond to "hey" before the actual question even arrives. With debounce, the SDK waits briefly and processes only the final message in the window.
 
 ```typescript title="lib/bot.ts" lineNumbers
 const bot = new Chat({
@@ -118,10 +156,10 @@ const bot = new Chat({
 | Option | Strategies | Default | Description |
 |--------|-----------|---------|-------------|
 | `strategy` | all | `"drop"` | The concurrency strategy to use |
-| `maxQueueSize` | queue, debounce | `10` | Maximum queued messages per thread |
-| `onQueueFull` | queue, debounce | `"drop-oldest"` | Whether to evict the oldest or reject the newest message when the queue is full |
-| `queueEntryTtlMs` | queue, debounce | `90000` | TTL for queued entries in milliseconds. Expired entries are discarded on dequeue |
-| `debounceMs` | debounce | `1500` | Debounce window in milliseconds |
+| `maxQueueSize` | queue, burst | `10` | Maximum queued messages per thread |
+| `onQueueFull` | queue, burst | `"drop-oldest"` | Whether to evict the oldest or reject the newest message when the queue is full |
+| `queueEntryTtlMs` | queue, debounce, burst | `90000` | TTL for queued entries in milliseconds. Expired entries are discarded on dequeue |
+| `debounceMs` | debounce, burst | `1500` | Debounce window in milliseconds |
 | `maxConcurrent` | concurrent | `Infinity` | Max concurrent handlers per thread |
 
 <Callout type="warn">
@@ -130,7 +168,7 @@ const bot = new Chat({
 
 ## MessageContext
 
-All handler types (`onNewMention`, `onSubscribedMessage`, `onNewMessage`) accept an optional `MessageContext` as their last parameter. It is only populated when using the `queue` strategy and messages were skipped.
+All handler types (`onNewMention`, `onSubscribedMessage`, `onNewMessage`) accept an optional `MessageContext` as their last parameter. It is populated when using the `queue` strategy for queued messages, and when using `burst` for a collapsed turn. A lone `burst` message receives `skipped: []` and `totalSinceLastHandler: 1`.
 
 ```typescript
 interface MessageContext {
@@ -186,7 +224,7 @@ const bot = new Chat({
 
 ## State adapter requirements
 
-The `queue` and `debounce` strategies require three additional methods on your state adapter:
+The `queue`, `debounce`, and `burst` strategies require three additional methods on your state adapter:
 
 | Method | Description |
 |--------|-------------|
@@ -202,12 +240,12 @@ All strategies emit structured log events at `info` level:
 
 | Event | Strategy | Data |
 |-------|----------|------|
-| `message-queued` | queue | threadId, messageId, queueDepth |
-| `message-dequeued` | queue, debounce | threadId, messageId, skippedCount |
-| `message-dropped` | drop, queue | threadId, messageId, reason |
-| `message-expired` | queue, debounce | threadId, messageId |
+| `message-queued` | queue, burst | threadId, messageId, queueDepth |
+| `message-dequeued` | queue, debounce, burst | threadId, messageId, skippedCount for queue/burst |
+| `message-dropped` | drop, queue, burst | threadId, messageId, reason |
+| `message-expired` | queue, debounce, burst | threadId, messageId |
 | `message-superseded` | debounce | threadId, droppedId |
-| `message-debouncing` | debounce | threadId, messageId, debounceMs |
+| `message-debouncing` | debounce, burst | threadId, messageId, debounceMs |
 | `message-debounce-reset` | debounce | threadId, messageId |
 
 ## Choosing a strategy
@@ -216,7 +254,8 @@ All strategies emit structured log events at `info` level:
 |----------|----------|-----|
 | Simple bots, one-shot commands | `drop` | No complexity, no queue overhead |
 | AI chatbots, customer support | `queue` | Never lose messages; handler sees full conversation context |
-| WhatsApp/Telegram bots, rapid corrections | `debounce` | Users send many short messages in quick succession; wait for a pause before responding |
+| AI chatbots with multi-message user turns | `burst` | Wait for the idle burst window, then respond once with every message in that window |
+| WhatsApp/Telegram bots, rapid corrections | `debounce` | Users send many short messages in quick succession; wait briefly and keep only the latest |
 | Stateless lookups, translations | `concurrent` | Maximum throughput, no ordering needed |
 
 ## Backward compatibility

package/docs/contributing/building.mdx

@@ -370,7 +370,7 @@ parseMessage(raw: unknown): Message<unknown> {
 
 ### Sending messages
 
-Use `extractCard()` and `extractFiles()` from `@chat-adapter/shared` to check for rich content. Use your format converter's `renderPostable()` to convert the message to platform format.
+Use `extractCard()` and `extractFiles()` from `@chat-adapter/shared` to check for rich content. Use `extractPostableAttachments()` if your adapter maps normalized `Attachment` objects to platform-native media uploads. Use your format converter's `renderPostable()` to convert the message to platform format.
 
 ```typescript title="src/adapter.ts" lineNumbers
 async postMessage(

package/docs/contributing/testing.mdx

@@ -14,6 +14,10 @@ Chat SDK adapters are the trust boundary between your application and a platform
 
 All adapters in this repo use [vitest](https://vitest.dev) with `@vitest/coverage-v8`. Community adapters should follow the same convention.
 
+<Callout type="info">
+This page covers the hand-rolled patterns used inside this repo's `packages/`. If you're testing a bot or a custom adapter as a **consumer** of Chat SDK, use [`@chat-adapter/tests`](/docs/testing) — it ships factories and Vitest matchers that cover most of these patterns in a few lines.
+</Callout>
+
 ## Unit tests
 
 ### Factory function

package/docs/direct-messages.mdx

@@ -12,9 +12,18 @@ Open direct message conversations with users using `bot.openDM()`. For globally
 
 DMs behave slightly differently from channel messages:
 
-- **Implicit mentions** — DM messages automatically set `isMention=true`, so your `onNewMention` handler fires without the user needing to @-mention the bot. This feels natural for 1:1 conversations.
+- **Direct message handlers** — if you register `onDirectMessage`, every incoming DM routes there before `onSubscribedMessage`, `onNewMention`, and pattern handlers. This keeps DM-centric flows like WhatsApp conversations, Telegram DMs, and web chat on one consistent handler.
+- **Mention fallback** — if no `onDirectMessage` handlers are registered, DMs continue through normal routing. Unsubscribed DMs are treated as mentions, so existing `onNewMention` bots keep working without requiring the user to @-mention the bot.
 - **Per-conversation threading** — Each top-level DM starts a new conversation. Thread replies within a DM continue the same conversation, giving you the same per-thread isolation as channels.
 
+## Handle incoming DMs
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onDirectMessage(async (thread, message) => {
+  await thread.post(`You said: ${message.text}`);
+});
+```
+
 ## Open a DM
 
 ### From an Author object

package/docs/files.mdx

@@ -25,6 +25,26 @@ await thread.post({
 });
 ```
 
+### Typed attachments
+
+Use `attachments` when you already have normalized `Attachment` objects and the adapter supports typed outgoing media. Telegram supports one outgoing attachment per message and uses the native media method for the attachment type:
+
+```typescript title="lib/bot.ts" lineNumbers
+await thread.post({
+  markdown: "Here's the image:",
+  attachments: [
+    {
+      data: imageBuffer,
+      name: "diagram.png",
+      mimeType: "image/png",
+      type: "image",
+    },
+  ],
+});
+```
+
+Outgoing `attachments` are available on `{ raw }`, `{ markdown }`, and `{ ast }` messages. Card messages use `files` for uploads. Use `files` for generic uploads. On Telegram, `files` always upload as documents, while `attachments` preserve image, audio, video, or file media type. Use `data` or `fetchData` for private/authenticated files; URL-only attachments must be public URLs Telegram can fetch directly.
+
 ### Multiple files
 
 ```typescript title="lib/bot.ts" lineNumbers

package/docs/getting-started.mdx

@@ -25,4 +25,8 @@ Connect your bot to chat platforms and persist state across restarts.
 
 Browse all official and community adapters on the [Adapters](/adapters) page.
 
-Step-by-step guides and starter templates are available on the [Resources](/resources) page.
+## Resources
+
+- [The Complete Guide to Chat SDK](https://vercel.com/kb/guide/the-complete-guide-to-chat-sdk) — End-to-end walkthrough that takes you from zero to a deployed multi-platform bot, covering adapters, state, handlers, cards, and streaming.
+
+See all guides and templates on the [resources](/resources) page.