chat 4.26.0 → 4.28.1

package/docs/contributing/building.mdx

@@ -414,6 +414,62 @@ async deleteMessage(threadId: string, messageId: string): Promise<void> {
 }
 ```
 
+### Buttons and callback URLs
+
+When the host app passes a `Card` with `<Button callbackUrl={...}>`, the SDK rewrites each such button **before** your adapter sees the postable: the `callbackUrl` is stored in the state adapter under a short token, and the button's `value` field is replaced with `__cb:<16-hex-chars>` (21 characters total). Your adapter does not need to know this happens — just round-trip `button.value` through your platform's button payload.
+
+What this means in practice:
+
+1. **Send side**: when rendering a `ButtonElement` to your platform's button payload, encode both `button.id` (the action ID) and `button.value` (which may be `undefined`, a user-supplied value, or a callback token). Pick a delimiter that cannot appear in either, and validate the encoded string fits the platform's limit.
+2. **Receive side**: when the user clicks a button, decode the platform payload back into `actionId` and `value`, and pass them to `chat.processAction({ actionId, value, ... })`. The SDK will detect the `__cb:` prefix, look up the stored callback URL, POST to it, and pass the original value (if any) to user `onAction` handlers.
+
+Discord's adapter is a good reference — it joins the action ID and value with `\n` and validates against Discord's 100-character `custom_id` limit:
+
+```typescript title="src/cards.ts (discord)" lineNumbers
+const DISCORD_CUSTOM_ID_DELIMITER = "\n";
+const DISCORD_CUSTOM_ID_MAX_LENGTH = 100;
+
+export function encodeDiscordCustomId(
+  actionId: string,
+  value?: string
+): string {
+  if (value == null || value === "") {
+    validateLength(actionId);
+    return actionId;
+  }
+  const encoded = `${actionId}${DISCORD_CUSTOM_ID_DELIMITER}${value}`;
+  validateLength(encoded);
+  return encoded;
+}
+
+export function decodeDiscordCustomId(customId: string): {
+  actionId: string;
+  value: string | undefined;
+} {
+  const idx = customId.indexOf(DISCORD_CUSTOM_ID_DELIMITER);
+  if (idx === -1) {
+    return { actionId: customId, value: undefined };
+  }
+  // Use the FIRST delimiter only — values may legitimately contain "\n".
+  return {
+    actionId: customId.slice(0, idx),
+    value: customId.slice(idx + 1),
+  };
+}
+```
+
+<Callout type="info">
+  Platform button-data limits are the main constraint to plan for. Discord's
+  `custom_id` is 100 chars; Telegram's `callback_data` is 64 bytes. The SDK's
+  callback token is fixed at 21 chars (`__cb:` + 16 hex), so the worst-case
+  payload your encoding must fit is `actionId + delimiter + 21`. If the
+  encoded string exceeds the platform limit, throw a `ValidationError` from
+  `@chat-adapter/shared` so the host app fails fast at post time rather than
+  silently truncating.
+</Callout>
+
+Modals with `callbackUrl` are handled entirely inside the SDK via stored modal context — your adapter does not need any special handling. Just call `chat.processModalSubmit(event, contextId, { waitUntil })` from your webhook handler and the SDK will POST to the modal's `callbackUrl` (using `waitUntil` if you provide it, so the response is not blocked).
+
 ### Reactions
 
 Handle both `EmojiValue` objects and plain strings. `EmojiValue` has a `name` property and `toString()` method — there is no `unicode` field.
@@ -535,7 +591,7 @@ export class MatrixFormatConverter extends BaseFormatConverter {
 }
 ```
 
-For platforms with non-standard formatting (e.g., Slack's `mrkdwn`), implement custom parsing in `toAst()` and rendering in `fromAst()`. See the [Discord adapter](https://github.com/vercel/chat/blob/main/packages/adapter-discord/src/markdown.ts) for an example of handling platform-specific mention syntax.
+For platforms with non-standard formatting, implement custom parsing in `toAst()` and rendering in `fromAst()`. See the [Discord adapter](https://github.com/vercel/chat/blob/main/packages/adapter-discord/src/markdown.ts) for an example of handling platform-specific mention syntax.
 
 ## Optional methods
 
@@ -639,3 +695,19 @@ import {
   cardToFallbackText, // Convert card to plain text
 } from "@chat-adapter/shared";
 ```
+
+### Token encryption
+
+If your adapter persists OAuth tokens to a `StateAdapter`, encrypt them at rest with the shared AES-256-GCM helpers instead of rolling your own:
+
+```typescript
+import {
+  encryptToken,         // Encrypt a string into an EncryptedTokenData envelope
+  decryptToken,         // Decrypt an envelope back to the original string
+  decodeKey,            // Decode a hex-64 or base64-44 32-byte key (throws on wrong length)
+  isEncryptedTokenData, // Type guard for tolerating legacy plaintext records
+  type EncryptedTokenData,
+} from "@chat-adapter/shared";
+```
+
+Accept the key as an optional `encryptionKey` config field (auto-detected from a `*_ENCRYPTION_KEY` env var), encrypt on `setInstallation()`, decrypt on `getInstallation()`, and use `isEncryptedTokenData` to keep accepting plaintext records so operators can roll the key in without flushing existing installs. See `@chat-adapter/slack` and `@chat-adapter/linear` for reference implementations.

package/docs/contributing/publishing.mdx

@@ -159,3 +159,36 @@ You should see your exported symbols (`createMatrixAdapter`, `MatrixAdapter`, et
 - Watch the [Chat SDK changelog](https://github.com/vercel/chat/releases) for new features and breaking changes
 - Run your test suite against new Chat SDK releases before they ship to catch compatibility issues early
 - When the `Adapter` interface adds new optional methods, consider implementing them to keep your adapter feature-complete
+
+## Listing on chat-sdk.dev
+
+Community adapters can be listed on the [Adapters](https://chat-sdk.dev/adapters) page by opening a PR that adds an entry to `apps/docs/adapters.json` in the [Chat SDK repo](https://github.com/vercel/chat). Your adapter's README is fetched from GitHub at build time and rendered on its dedicated page.
+
+### Pin your README to a commit or tag
+
+<Callout type="warn">
+  The `readme` field **must** reference a specific commit SHA or tag — not a branch name like `main`.
+</Callout>
+
+The docs site re-renders on every deploy, so an unpinned `readme` would serve whatever currently sits at your default branch — including edits made after the listing PR was reviewed. Pinning freezes the rendered content at the state we approved; new content goes live through a follow-up PR that bumps the ref.
+
+```json title="apps/docs/adapters.json"
+{
+  "name": "My Adapter",
+  "slug": "my-adapter",
+  "type": "platform",
+  "community": true,
+  "packageName": "chat-adapter-my-thing",
+  "readme": "https://github.com/your-org/chat-adapter-my-thing/tree/v1.2.0"
+}
+```
+
+Accepted `readme` formats:
+
+| Format | Example |
+|--------|---------|
+| Repo root at a tag | `https://github.com/owner/repo/tree/v1.0.0` |
+| Repo root at a commit | `https://github.com/owner/repo/tree/abc1234...` |
+| Subpath in a monorepo | `https://github.com/owner/repo/tree/<ref>/packages/adapter` |
+
+Unpinned refs (e.g., `tree/main`, or omitting `/tree/<ref>` entirely) will emit a build warning and are rejected during PR review.

package/docs/conversation-history.mdx

@@ -0,0 +1,137 @@
+---
+title: Conversation History
+description: Persist messages per user across every platform — for LLM context, audit, or compliance.
+type: guide
+prerequisites:
+  - /docs/state
+related:
+  - /docs/handling-events
+  - /docs/api/transcripts
+---
+
+Bots that hold context across a user's conversations need somewhere to store it. The platform's own message history won't do — a user might talk to your bot in Slack today and Discord tomorrow, and you want the same memory to follow them.
+
+`bot.transcripts` keeps a per-user transcript in your state adapter, keyed by a stable identifier you choose (an email, an internal user ID, anything that's the same person no matter where they are).
+
+## Setup
+
+You opt in by setting two fields on `ChatConfig`:
+
+```typescript title="lib/bot.ts" lineNumbers
+import { Chat } from "chat";
+import { createSlackAdapter } from "@chat-adapter/slack";
+import { createDiscordAdapter } from "@chat-adapter/discord";
+import { createRedisState } from "@chat-adapter/state-redis";
+
+const bot = new Chat({
+  userName: "mybot",
+  adapters: {
+    slack: createSlackAdapter(),
+    discord: createDiscordAdapter(),
+  },
+  state: createRedisState({ url: process.env.REDIS_URL! }),
+
+  // Resolve the cross-platform identifier for an inbound message.
+  // Return null for messages you don't want to remember.
+  identity: ({ author }) => author.email ?? null,
+
+  // Storage tuning. retention is the list TTL, refreshed on every append.
+  transcripts: {
+    retention: "30d",
+    maxPerUser: 200,
+  },
+});
+```
+
+`transcripts` and `identity` are paired — set one without the other and the constructor throws. This keeps the API loud rather than silently no-op'ing on every call.
+
+## Building LLM context
+
+The most common pattern: append the user's message, build a prompt from recent transcript entries, post the reply, append the reply too.
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onSubscribedMessage(async (thread, msg) => {
+  await bot.transcripts.append(thread, msg);
+
+  const recent = await bot.transcripts.list({
+    userKey: msg.userKey!,
+    limit: 20,
+  });
+
+  const reply = await generateReply(recent, msg);
+  await thread.post(reply);
+
+  await bot.transcripts.append(
+    thread,
+    { role: "assistant", text: reply },
+    { userKey: msg.userKey! }
+  );
+});
+```
+
+A few things worth knowing:
+
+- **`msg.userKey`** is set automatically from your `identity` resolver before your handler runs. If the resolver returned `null`, it stays `undefined` and the `append` call no-ops.
+- **Bot replies are explicit.** The SDK doesn't auto-capture `thread.post()` output — you decide what gets remembered. That's important for retries, intermediate streaming chunks, and anything you don't want feeding back into the model later.
+- **Order is chronological.** `list` returns oldest-first, ready to feed into a model. Set `limit` to keep prompts bounded.
+
+## Identity resolution
+
+`identity` runs once per inbound message during dispatch. The `author`, `message`, and `adapter` name are all available:
+
+```typescript
+identity: async ({ adapter, author, message }) => {
+  // Look up by email when the platform exposes it
+  if (author.email) {
+    return author.email;
+  }
+  // Or map a platform user to an internal ID
+  return await lookupUser(adapter, author.userId);
+}
+```
+
+Return `null` when you can't resolve a key. The SDK won't fall back to a platform-specific ID — that would silently fragment a user's transcript across platforms, which is exactly what this feature is here to prevent.
+
+If your resolver throws, the SDK logs a warning and dispatches the message without a `userKey`. Handlers still run; only the persistence is skipped.
+
+## Filtering entries
+
+`list` accepts a few filters. They compose, and they're applied after `getList` — useful for narrowing prompts without restructuring storage.
+
+```typescript
+// Recent N across all platforms
+await bot.transcripts.list({ userKey: "mike@acme.com", limit: 50 });
+
+// Single platform
+await bot.transcripts.list({ userKey: "mike@acme.com", platforms: ["slack"] });
+
+// Single thread
+await bot.transcripts.list({
+  userKey: "mike@acme.com",
+  threadId: "slack:C123:1234.5678",
+});
+
+// Only the user's own messages
+await bot.transcripts.list({ userKey: "mike@acme.com", roles: ["user"] });
+```
+
+## Deleting a user's transcript
+
+For data-subject requests or simple "forget me" flows:
+
+```typescript
+await bot.transcripts.delete({ userKey: "mike@acme.com" });
+// → { deleted: 47 }
+```
+
+This wipes every entry stored under the key. Single-entry and time-range deletes aren't part of the API — `appendToList` doesn't support them safely under concurrent writes.
+
+## Where it's stored
+
+`bot.transcripts` is backed by `StateAdapter.appendToList` / `getList` / `delete`. Every built-in state adapter (`memory`, `redis`, `ioredis`, `pg`) supports these primitives, so this works on whichever one you've already configured.
+
+Entries are written under the key `transcripts:user:{userKey}` as a capped list. `appendToList` is atomic, so concurrent inbound messages on the same user don't race.
+
+## Reference
+
+See [Transcripts](/docs/api/transcripts) for full type signatures, configuration options, and the entry shape.

package/docs/direct-messages.mdx

@@ -1,12 +1,12 @@
 ---
-title: Direct messages
+title: Direct Messages
 description: Initiate DM conversations with users programmatically.
 type: guide
 prerequisites:
   - /docs/usage
 ---
 
-Open direct message conversations with users using `bot.openDM()`. The adapter is automatically inferred from the user ID format.
+Open direct message conversations with users using `bot.openDM()`. For globally recognizable user IDs, the adapter is automatically inferred from the ID format.
 
 ## DM behavior
 
@@ -40,10 +40,19 @@ const dmThread = await bot.openDM("U1234567890"); // Slack
 
 | Format | Platform |
 |--------|----------|
-| `U...` | Slack |
+| `U...` / `W...` | Slack |
 | `29:...` | Teams |
 | `users/...` | Google Chat |
-| Snowflake (numeric) | Discord |
+| Numeric ID | Discord or Telegram |
+
+<Callout type="info">
+  Numeric IDs can be ambiguous when multiple numeric-ID adapters are registered. For platforms whose user IDs are not globally distinguishable, call the adapter directly and wrap the returned thread ID with `bot.thread()`.
+</Callout>
+
+```typescript title="lib/bot.ts"
+const threadId = await bot.getAdapter("whatsapp").openDM("15551234567");
+const dmThread = bot.thread(threadId);
+```
 
 ## Check if a thread is a DM
 

package/docs/ephemeral-messages.mdx

@@ -1,5 +1,5 @@
 ---
-title: Ephemeral messages
+title: Ephemeral Messages
 description: Send messages visible only to a specific user.
 type: guide
 prerequisites:

package/docs/error-handling.mdx

@@ -1,5 +1,5 @@
 ---
-title: Error handling
+title: Error Handling
 description: Handle rate limits, unsupported features, and other errors from adapters.
 type: guide
 prerequisites:
@@ -16,7 +16,19 @@ import { ChatError, RateLimitError, NotImplementedError, LockError } from "chat"
 
 ### ChatError
 
-Base error class for all SDK errors. Every error below extends `ChatError`.
+Base error class for all SDK errors. Every error below extends `ChatError`. The `code` property carries a machine-readable identifier you can branch on:
+
+| Code | Thrown by | Meaning |
+|------|-----------|---------|
+| `NOT_SUPPORTED` | `bot.openDM`, `bot.getUser` | The resolved adapter doesn't implement this method |
+| `INVALID_THREAD_ID` | `bot.thread`, internal routing | Thread ID does not match the `adapter:channel:thread` shape |
+| `INVALID_CHANNEL_ID` | `bot.channel` | Channel ID does not match the `adapter:channel` shape |
+| `ADAPTER_NOT_FOUND` | `bot.thread`, `bot.channel` | Thread/channel ID references an adapter that wasn't registered on this `Chat` instance |
+| `AMBIGUOUS_USER_ID` | `bot.getUser`, `bot.openDM` | Numeric user ID could match more than one registered adapter (Discord/Telegram/GitHub) |
+| `UNKNOWN_USER_ID_FORMAT` | `bot.getUser`, `bot.openDM` | The `userId` doesn't match any platform's known ID format |
+| `RATE_LIMITED` | Any platform call | Platform returned 429; see `RateLimitError` below |
+| `NOT_IMPLEMENTED` | Any platform call | The adapter doesn't implement this feature; see `NotImplementedError` below |
+| `LOCK_FAILED` | Inbound message routing | Distributed lock was busy; see `LockError` below |
 
 <TypeTable
   type={{
@@ -25,7 +37,7 @@ Base error class for all SDK errors. Every error below extends `ChatError`.
       type: 'string',
     },
     code: {
-      description: 'Machine-readable error code.',
+      description: 'Machine-readable error code (see table above).',
       type: 'string',
     },
     cause: {

package/docs/files.mdx

@@ -1,5 +1,5 @@
 ---
-title: File uploads
+title: File Uploads
 description: Send and receive files across chat platforms.
 type: guide
 prerequisites:
@@ -75,3 +75,4 @@ bot.onSubscribedMessage(async (thread, message) => {
 | `width` | `number` (optional) | Image width |
 | `height` | `number` (optional) | Image height |
 | `fetchData` | `() => Promise<Buffer>` (optional) | Download the file data |
+| `fetchMetadata` | `Record<string, string>` (optional) | Platform-specific IDs for reconstructing `fetchData` after serialization |

package/docs/getting-started.mdx

@@ -25,14 +25,4 @@ Connect your bot to chat platforms and persist state across restarts.
 
 Browse all official and community adapters on the [Adapters](/adapters) page.
 
-## Guides
-
-Step-by-step tutorials to get up and running on your platform of choice.
-
-<Cards>
-  <Card title="Slack bot with Next.js and Redis" description="Build a Slack bot from scratch using Chat SDK, Next.js, and Redis." href="/docs/guides/slack-nextjs" />
-  <Card title="Durable chat sessions with Next.js, Workflow, and Redis" description="Build a bot whose thread sessions survive restarts by combining Chat SDK with Workflow." href="/docs/guides/durable-chat-sessions-nextjs" />
-  <Card title="Schedule Slack posts with Next.js, Workflow, and Neon" description="Build durable scheduled posts backed by Neon and Workflow timers." href="/docs/guides/scheduled-posts-neon" />
-  <Card title="Code review GitHub bot with Hono and Redis" description="Build a GitHub bot that reviews pull requests using AI SDK, Vercel Sandbox, and Chat SDK." href="/docs/guides/code-review-hono" />
-  <Card title="Discord support bot with Nuxt and Redis" description="Build a Discord support bot using Chat SDK, Nuxt, and AI SDK." href="/docs/guides/discord-nuxt" />
-</Cards>
+Step-by-step guides and starter templates are available on the [Resources](/resources) page.

package/docs/index.mdx

@@ -4,7 +4,7 @@ description: A unified SDK for building chat bots across Slack, Microsoft Teams,
 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, Telegram, GitHub, Linear, and WhatsApp.
+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, Linear, WhatsApp, and Messenger.
 
 ## Why Chat SDK?
 
@@ -52,13 +52,14 @@ Each adapter factory auto-detects credentials from environment variables (`SLACK
 | Platform | Package | Mentions | Reactions | Cards | Modals | Streaming | DMs |
 |----------|---------|----------|-----------|-------|--------|-----------|-----|
 | Slack | `@chat-adapter/slack` | Yes | Yes | Yes | Yes | Native | Yes |
-| Microsoft Teams | `@chat-adapter/teams` | Yes | Read-only | Yes | No | Post+Edit | Yes |
+| Microsoft Teams | `@chat-adapter/teams` | Yes | Read-only | Yes | Yes | Native (DMs) / Buffered | 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 |
-| WhatsApp | `@chat-adapter/whatsapp` | N/A | Yes | Partial | No | No | Yes |
+| GitHub | `@chat-adapter/github` | Yes | Yes | No | No | Buffered | No |
+| Linear | `@chat-adapter/linear` | Yes | Yes | No | No | Agent sessions / Post+Edit | No |
+| WhatsApp | `@chat-adapter/whatsapp` | N/A | Yes | Partial | No | Buffered | Yes |
+| Messenger | `@chat-adapter/messenger` | Yes | Receive-only | Partial | No | Buffered | Yes |
 
 ## AI coding agent support
 
@@ -85,6 +86,7 @@ The SDK is distributed as a set of packages you install based on your needs:
 | `@chat-adapter/github` | GitHub Issues adapter |
 | `@chat-adapter/linear` | Linear Issues adapter |
 | `@chat-adapter/whatsapp` | WhatsApp Business adapter |
+| `@chat-adapter/messenger` | Facebook Messenger adapter |
 | `@chat-adapter/state-redis` | Redis state adapter (production) |
 | `@chat-adapter/state-ioredis` | ioredis state adapter (alternative) |
 | `@chat-adapter/state-pg` | PostgreSQL state adapter (production) |

package/docs/meta.json

@@ -8,15 +8,24 @@
     "threads-messages-channels",
     "handling-events",
     "posting-messages",
+    "error-handling",
     "---Adapters---",
     "adapters",
     "state",
-    "---Features---",
+    "---Messaging---",
+    "streaming",
+    "direct-messages",
+    "ephemeral-messages",
+    "files",
+    "conversation-history",
+    "subject",
     "concurrency",
-    "...",
-    "error-handling",
-    "---Guides---",
-    "...guides",
+    "---Interactivity---",
+    "cards",
+    "modals",
+    "actions",
+    "slash-commands",
+    "emoji",
     "---API Reference---",
     "...api",
     "---Contributing---",

package/docs/modals.mdx

@@ -59,6 +59,7 @@ The top-level container for the form.
 | `submitLabel` | `string` (optional) | Submit button text (defaults to "Submit") |
 | `closeLabel` | `string` (optional) | Cancel button text (defaults to "Cancel") |
 | `notifyOnClose` | `boolean` (optional) | Fire `onModalClose` when user cancels |
+| `callbackUrl` | `string` (optional) | URL to POST form values to on submit |
 | `privateMetadata` | `string` (optional) | Custom context passed through to handlers |
 
 ### TextInput
@@ -87,6 +88,77 @@ A dropdown for selecting a single option.
 | `initialOption` | `string` (optional) | Pre-selected value |
 | `optional` | `boolean` (optional) | Allow empty submission |
 
+### ExternalSelect
+
+A dropdown that loads its options dynamically from a handler as the user types. Useful for large or remote-backed option sets (people, tickets, records) where a static `<Select>` would be impractical. Slack-only.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `id` | `string` | Field identifier (key in `event.values`) |
+| `label` | `string` | Field label |
+| `placeholder` | `string` (optional) | Placeholder text |
+| `minQueryLength` | `number` (optional) | Minimum characters before the loader fires (Slack default: 3) |
+| `initialOption` | `{ label, value }` (optional) | Pre-selected option when the modal opens (must match an option returned by the loader). For static `<Select>`, `initialOption` is just the value string — for `<ExternalSelect>` it's the full `{ label, value }` object since the loader hasn't run yet. |
+| `optional` | `boolean` (optional) | Allow empty submission |
+
+Register the loader with `onOptionsLoad`:
+
+```tsx title="lib/bot.tsx" lineNumbers
+import { ExternalSelect, Modal } from "chat";
+
+bot.onAction("assign", async (event) => {
+  await event.openModal(
+    <Modal callbackId="assign_form" title="Assign to…">
+      <ExternalSelect
+        id="assignee"
+        label="Assignee"
+        placeholder="Search people"
+        minQueryLength={1}
+      />
+    </Modal>
+  );
+});
+
+bot.onOptionsLoad("assignee", async (event) => {
+  const people = await peopleService.search(event.query);
+  return people.map((p) => ({ label: p.fullName, value: p.id }));
+});
+
+bot.onModalSubmit("assign_form", async (event) => {
+  const assigneeId = event.values.assignee;
+  // …
+});
+```
+
+The selected value arrives in `event.values` on submit just like a static `<Select>`.
+
+#### Grouped options
+
+Return an array of groups instead of a flat options array to render headers between sections (e.g. "Recent" / "All"):
+
+```tsx
+bot.onOptionsLoad("assignee", async (event) => {
+  const [recent, all] = await Promise.all([
+    peopleService.recent(event.user.userId),
+    peopleService.search(event.query),
+  ]);
+  return [
+    { label: "Recent", options: recent.map((p) => ({ label: p.fullName, value: p.id })) },
+    { label: "All", options: all.map((p) => ({ label: p.fullName, value: p.id })) },
+  ];
+});
+```
+
+Slack limits: max 100 groups, max 100 options per group, group label max 75 characters.
+
+<Callout type="warn">
+Slack requires a response within 3 seconds for options requests. The adapter caps the loader at ~2.5s and returns an empty result on timeout — keep your loader fast (cache, prefetch, or narrow the query server-side).
+</Callout>
+
+<Callout type="info">
+**Slack setup:** `ExternalSelect` uses Slack's `block_suggestion` payload, which is dispatched to the **Options Load URL**. In your [Slack app settings](https://api.slack.com/apps) go to **Interactivity & Shortcuts** → **Select Menus** and set the **Options Load URL** to the same endpoint as your Interactivity Request URL (e.g. `https://your-domain.com/api/webhooks/slack`). Without this, typing into an external select will silently return no results.
+</Callout>
+
 ### RadioSelect
 
 A radio button group for mutually exclusive options.
@@ -142,7 +214,8 @@ bot.onModalSubmit("feedback_form", async (event) => {
 
 | Response | Description |
 |----------|-------------|
-| `undefined` or `{ action: "close" }` | Close the modal |
+| `undefined` or `{ action: "close" }` | Close the current view (goes back one level in the stack) |
+| `{ action: "clear" }` | Close all views and dismiss the modal entirely |
 | `{ action: "errors", errors: { fieldId: "message" } }` | Show validation errors on specific fields |
 | `{ action: "update", modal: ModalElement }` | Replace the modal content |
 | `{ action: "push", modal: ModalElement }` | Push a new modal view onto the stack |
@@ -176,6 +249,29 @@ bot.onModalClose("feedback_form", async (event) => {
 });
 ```
 
+## Callback URLs
+
+Like buttons, modals accept a `callbackUrl`. When the modal is submitted, the form values are POSTed to the URL:
+
+```tsx title="lib/bot.tsx" lineNumbers
+await event.openModal(
+  <Modal callbackUrl={webhook.url} callbackId="intake" title="Request Access" submitLabel="Submit">
+    <TextInput id="reason" label="Reason" multiline />
+  </Modal>
+);
+```
+
+The POST body for modal submissions:
+
+```json
+{
+  "type": "modal_submit",
+  "callbackId": "intake",
+  "values": { "reason": "Need access to production logs" },
+  "user": { "id": "U123", "name": "alice" }
+}
+```
+
 ## Pass context with privateMetadata
 
 Use `privateMetadata` to carry context from the button click through to the submit handler:

package/docs/posting-messages.mdx

@@ -24,7 +24,7 @@ This sends the string directly without any formatting conversion.
 
 ## Markdown
 
-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.
+Pass a `{ markdown }` object to have the SDK render standard markdown on each platform — passed through to Slack's native `markdown_text` field, converted to HTML for Teams, and so on.
 
 ```typescript title="lib/bot.ts" lineNumbers
 await thread.post({
@@ -32,7 +32,7 @@ await thread.post({
 });
 ```
 
-Under the hood, the SDK parses the markdown into an mdast AST, then each adapter converts it to the platform's format.
+Under the hood, the SDK parses the markdown into an mdast AST, then each adapter handles it natively or converts it to the platform's format.
 
 ## AST builders
 
@@ -139,7 +139,7 @@ See the [Cards](/docs/cards) page for the full list of card components.
 
 ## Streaming
 
-Pass an AI SDK stream to `thread.post()` 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.
+Pass an AI SDK stream to `thread.post()` to stream a message in real time. The SDK uses platform-native streaming where available and falls back to post-then-edit or buffered delivery depending on the platform.
 
 ```typescript title="lib/bot.ts" lineNumbers
 import { ToolLoopAgent } from "ai";
@@ -153,6 +153,8 @@ Both `fullStream` and `textStream` are supported. Use `fullStream` with multi-st
 
 For multi-turn conversations, use [`toAiMessages()`](/docs/api/to-ai-messages) to convert thread history into the `{ role, content }[]` format expected by AI SDKs.
 
+To pass platform-specific streaming options (e.g. Slack task grouping or stop blocks), wrap the stream in a [`StreamingPlan`](/docs/streaming#streaming-with-options) and post that.
+
 See the [Streaming](/docs/streaming) page for details on platform behavior and configuration.
 
 ## Attachments and files
@@ -178,5 +180,7 @@ See the [Files](/docs/files) page for more on attachments.
 | Card (function) | You need buttons, fields, or structured layouts | Approval flows, dashboards |
 | Card (JSX) | Same as above, with JSX syntax preference | Same use cases as function cards |
 | `AsyncIterable` | Streaming AI responses | Chat with LLMs |
+| [`Plan`](/docs/streaming#plan-api) | Step-by-step tasks that mutate after posting | Multi-step agents, deploy progress |
+| [`StreamingPlan`](/docs/streaming#streaming-with-options) | Streaming with platform-specific options | Slack streaming with grouped tasks or stop blocks |
 
 For most cases, **AST builders** give the best balance of control and simplicity. Reach for **cards** when you need interactive elements like buttons or dropdowns.