chat 4.26.0 → 4.28.1

package/dist/{jsx-runtime-DxATbnrP.d.ts → jsx-runtime-DxGwoLu2.d.ts}

@@ -52,6 +52,8 @@ type TextStyle = "plain" | "bold" | "muted";
 interface ButtonElement {
     /** Whether this button triggers a regular action or opens a modal dialog. Default: "action" */
     actionType?: "action" | "modal";
+    /** URL to POST action data to when this button is clicked */
+    callbackUrl?: string;
     /** If true, the button is displayed in an inactive state and doesn't respond to user actions */
     disabled?: boolean;
     /** Unique action ID for callback routing */
@@ -241,6 +243,8 @@ declare function Actions(children: (ButtonElement | LinkButtonElement | SelectEl
 interface ButtonOptions {
     /** Whether this button triggers a regular action or opens a modal dialog. Default: "action" */
     actionType?: "action" | "modal";
+    /** URL to POST action data to when this button is clicked */
+    callbackUrl?: string;
     /** If true, the button is displayed in an inactive state and doesn't respond to user actions */
     disabled?: boolean;
     /** Unique action ID for callback routing */
@@ -371,9 +375,11 @@ declare function cardChildToFallbackText(child: CardChild): string | null;
  * Modal elements for form dialogs.
  */
 
-type ModalChild = TextInputElement | SelectElement | RadioSelectElement | TextElement | FieldsElement;
+type ModalChild = TextInputElement | SelectElement | ExternalSelectElement | RadioSelectElement | TextElement | FieldsElement;
 interface ModalElement {
     callbackId: string;
+    /** URL to POST form values to when this modal is submitted */
+    callbackUrl?: string;
     children: ModalChild[];
     closeLabel?: string;
     notifyOnClose?: boolean;
@@ -402,6 +408,15 @@ interface SelectElement {
     placeholder?: string;
     type: "select";
 }
+interface ExternalSelectElement {
+    id: string;
+    initialOption?: SelectOptionElement;
+    label: string;
+    minQueryLength?: number;
+    optional?: boolean;
+    placeholder?: string;
+    type: "external_select";
+}
 interface SelectOptionElement {
     description?: string;
     label: string;
@@ -418,6 +433,8 @@ interface RadioSelectElement {
 declare function isModalElement(value: unknown): value is ModalElement;
 interface ModalOptions {
     callbackId: string;
+    /** URL to POST form values to when this modal is submitted */
+    callbackUrl?: string;
     children?: ModalChild[];
     closeLabel?: string;
     notifyOnClose?: boolean;
@@ -446,6 +463,15 @@ interface SelectOptions {
     placeholder?: string;
 }
 declare function Select(options: SelectOptions): SelectElement;
+interface ExternalSelectOptions {
+    id: string;
+    initialOption?: SelectOptionElement;
+    label: string;
+    minQueryLength?: number;
+    optional?: boolean;
+    placeholder?: string;
+}
+declare function ExternalSelect(options: ExternalSelectOptions): ExternalSelectElement;
 declare function SelectOption(options: {
     label: string;
     value: string;
@@ -509,6 +535,7 @@ interface TextProps {
 /** Props for Button component in JSX */
 interface ButtonProps {
     actionType?: "action" | "modal";
+    callbackUrl?: string;
     children?: string | number | (string | number | undefined)[];
     disabled?: boolean;
     id: string;
@@ -548,6 +575,7 @@ type DividerProps = Record<string, never>;
 /** Props for Modal component in JSX */
 interface ModalProps {
     callbackId: string;
+    callbackUrl?: string;
     children?: unknown;
     closeLabel?: string;
     notifyOnClose?: boolean;
@@ -574,6 +602,18 @@ interface SelectProps {
     optional?: boolean;
     placeholder?: string;
 }
+/** Props for ExternalSelect component in JSX */
+interface ExternalSelectProps {
+    id: string;
+    initialOption?: {
+        label: string;
+        value: string;
+    };
+    label: string;
+    minQueryLength?: number;
+    optional?: boolean;
+    placeholder?: string;
+}
 /** Props for SelectOption component in JSX */
 interface SelectOptionProps {
     description?: string;
@@ -586,9 +626,9 @@ interface TableProps {
     rows: string[][];
 }
 /** Union of all valid JSX props */
-type CardJSXProps = CardProps | TextProps | ButtonProps | LinkButtonProps | CardLinkProps | ImageProps | FieldProps | ContainerProps | DividerProps | ModalProps | TextInputProps | SelectProps | SelectOptionProps | TableProps;
+type CardJSXProps = CardProps | TextProps | ButtonProps | LinkButtonProps | CardLinkProps | ImageProps | FieldProps | ContainerProps | DividerProps | ModalProps | TextInputProps | SelectProps | ExternalSelectProps | SelectOptionProps | TableProps;
 /** Component function type with proper overloads */
-type CardComponentFunction = typeof Card | typeof Text | typeof Button | typeof LinkButton | typeof CardLink | typeof Image | typeof Field | typeof Divider | typeof Section | typeof Actions | typeof Fields | typeof Modal | typeof TextInput | typeof Select | typeof RadioSelect | typeof SelectOption | typeof Table;
+type CardComponentFunction = typeof Card | typeof Text | typeof Button | typeof LinkButton | typeof CardLink | typeof Image | typeof Field | typeof Divider | typeof Section | typeof Actions | typeof Fields | typeof Modal | typeof TextInput | typeof Select | typeof ExternalSelect | typeof RadioSelect | typeof SelectOption | typeof Table;
 /**
  * Represents a JSX element from the chat JSX runtime.
  * This is the type returned when using JSX syntax with chat components.
@@ -600,7 +640,7 @@ interface CardJSXElement<P extends CardJSXProps = CardJSXProps> {
     type: CardComponentFunction;
 }
 /** Union of all element types that can be produced by chat components */
-type ChatElement = CardJSXElement | CardElement | TextElement | ButtonElement | LinkButtonElement | LinkElement | ImageElement | DividerElement | ActionsElement | SectionElement | FieldsElement | FieldElement | ModalElement | TextInputElement | SelectElement | SelectOptionElement | RadioSelectElement | TableElement;
+type ChatElement = CardJSXElement | CardElement | TextElement | ButtonElement | LinkButtonElement | LinkElement | ImageElement | DividerElement | ActionsElement | SectionElement | FieldsElement | FieldElement | ModalElement | TextInputElement | SelectElement | ExternalSelectElement | SelectOptionElement | RadioSelectElement | TableElement;
 interface CardComponent {
     (options?: CardOptions): CardElement;
     (props: CardProps): ChatElement;
@@ -668,6 +708,10 @@ interface SelectComponent {
     (options: SelectOptions): SelectElement;
     (props: SelectProps): ChatElement;
 }
+interface ExternalSelectComponent {
+    (options: ExternalSelectOptions): ExternalSelectElement;
+    (props: ExternalSelectProps): ChatElement;
+}
 interface SelectOptionComponent {
     (options: {
         label: string;
@@ -735,4 +779,4 @@ declare namespace JSX {
     }
 }
 
-export { type DividerProps as $, type ActionsComponent as A, type ButtonComponent as B, type ChatElement as C, type DividerComponent as D, type ImageElement as E, type FieldComponent as F, type LinkButtonElement as G, type LinkButtonOptions as H, type ImageComponent as I, type LinkElement as J, type SectionElement as K, type LinkButtonComponent as L, type ModalElement as M, type TableAlignment as N, type TableElement as O, type TableOptions as P, type TextElement as Q, type RadioSelectComponent as R, type SectionComponent as S, type TextComponent as T, type TextStyle as U, type ButtonProps as V, type CardJSXElement as W, type CardJSXProps as X, type CardLinkProps as Y, type CardProps as Z, type ContainerProps as _, type CardElement as a, type FieldProps as a0, type ImageProps as a1, type LinkButtonProps as a2, type ModalProps as a3, type SelectOptionProps as a4, type SelectProps as a5, type TextInputProps as a6, type TextProps as a7, type ModalChild as a8, type ModalOptions as a9, type RadioSelectElement as aa, type RadioSelectOptions as ab, type SelectElement as ac, type SelectOptionElement as ad, type SelectOptions as ae, type TextInputElement as af, type TextInputOptions as ag, type TableProps as ah, type TableComponent as ai, isCardLinkProps as aj, jsx as ak, jsxs as al, jsxDEV as am, Fragment as an, JSX as ao, type CardChild as b, type CardComponent as c, cardChildToFallbackText as d, type CardLinkComponent as e, type FieldsComponent as f, fromReactElement as g, isJSX as h, isCardElement as i, Table as j, toModalElement as k, fromReactModalElement as l, isModalElement as m, type ModalComponent as n, type SelectComponent as o, type SelectOptionComponent as p, type TextInputComponent as q, type ActionsElement as r, type ButtonElement as s, toCardElement as t, type ButtonOptions as u, type ButtonStyle as v, type CardOptions as w, type DividerElement as x, type FieldElement as y, type FieldsElement as z };
+export { type CardProps as $, type ActionsComponent as A, type ButtonComponent as B, type ChatElement as C, type DividerComponent as D, type ExternalSelectComponent as E, type FieldComponent as F, type FieldsElement as G, type ImageElement as H, type ImageComponent as I, type LinkButtonElement as J, type LinkButtonOptions as K, type LinkButtonComponent as L, type ModalElement as M, type LinkElement as N, type SectionElement as O, type TableAlignment as P, type TableElement as Q, type RadioSelectComponent as R, type SelectOptionElement as S, type TextComponent as T, type TableOptions as U, type TextElement as V, type TextStyle as W, type ButtonProps as X, type CardJSXElement as Y, type CardJSXProps as Z, type CardLinkProps as _, type CardElement as a, type ContainerProps as a0, type DividerProps as a1, type ExternalSelectProps as a2, type FieldProps as a3, type ImageProps as a4, type LinkButtonProps as a5, type ModalProps as a6, type SelectOptionProps as a7, type SelectProps as a8, type TextInputProps as a9, type TextProps as aa, type ExternalSelectElement as ab, type ExternalSelectOptions as ac, type ModalChild as ad, type ModalOptions as ae, type RadioSelectElement as af, type RadioSelectOptions as ag, type SelectElement as ah, type SelectOptions as ai, type TextInputElement as aj, type TextInputOptions as ak, type TableProps as al, type TableComponent as am, isCardLinkProps as an, jsx as ao, jsxs as ap, jsxDEV as aq, Fragment as ar, JSX as as, type CardChild as b, type CardComponent as c, cardChildToFallbackText as d, type CardLinkComponent as e, type FieldsComponent as f, fromReactElement as g, isJSX as h, isCardElement as i, type SectionComponent as j, Table as k, toModalElement as l, fromReactModalElement as m, isModalElement as n, type ModalComponent as o, type SelectComponent as p, type SelectOptionComponent as q, type TextInputComponent as r, type ActionsElement as s, toCardElement as t, type ButtonElement as u, type ButtonOptions as v, type ButtonStyle as w, type CardOptions as x, type DividerElement as y, type FieldElement as z };

package/dist/jsx-runtime.d.ts

@@ -1 +1 @@
-export { A as ActionsComponent, B as ButtonComponent, V as ButtonProps, c as CardComponent, W as CardJSXElement, X as CardJSXProps, e as CardLinkComponent, Y as CardLinkProps, Z as CardProps, C as ChatElement, _ as ContainerProps, D as DividerComponent, $ as DividerProps, F as FieldComponent, a0 as FieldProps, f as FieldsComponent, an as Fragment, I as ImageComponent, a1 as ImageProps, ao as JSX, L as LinkButtonComponent, a2 as LinkButtonProps, n as ModalComponent, a3 as ModalProps, R as RadioSelectComponent, S as SectionComponent, o as SelectComponent, p as SelectOptionComponent, a4 as SelectOptionProps, a5 as SelectProps, ai as TableComponent, ah as TableProps, T as TextComponent, q as TextInputComponent, a6 as TextInputProps, a7 as TextProps, aj as isCardLinkProps, h as isJSX, ak as jsx, am as jsxDEV, al as jsxs, t as toCardElement, k as toModalElement } from './jsx-runtime-DxATbnrP.js';
+export { A as ActionsComponent, B as ButtonComponent, X as ButtonProps, c as CardComponent, Y as CardJSXElement, Z as CardJSXProps, e as CardLinkComponent, _ as CardLinkProps, $ as CardProps, C as ChatElement, a0 as ContainerProps, D as DividerComponent, a1 as DividerProps, E as ExternalSelectComponent, a2 as ExternalSelectProps, F as FieldComponent, a3 as FieldProps, f as FieldsComponent, ar as Fragment, I as ImageComponent, a4 as ImageProps, as as JSX, L as LinkButtonComponent, a5 as LinkButtonProps, o as ModalComponent, a6 as ModalProps, R as RadioSelectComponent, j as SectionComponent, p as SelectComponent, q as SelectOptionComponent, a7 as SelectOptionProps, a8 as SelectProps, am as TableComponent, al as TableProps, T as TextComponent, r as TextInputComponent, a9 as TextInputProps, aa as TextProps, an as isCardLinkProps, h as isJSX, ao as jsx, aq as jsxDEV, ap as jsxs, t as toCardElement, l as toModalElement } from './jsx-runtime-DxGwoLu2.js';

package/dist/jsx-runtime.js

@@ -7,7 +7,7 @@ import {
   jsxs,
   toCardElement,
   toModalElement
-} from "./chunk-OPV5U4WG.js";
+} from "./chunk-V25FKIIL.js";
 export {
   Fragment,
   isCardLinkProps,

package/docs/actions.mdx

@@ -94,5 +94,56 @@ bot.onAction("feedback", async (event) => {
 ```
 
 <Callout type="info">
-Modals are currently supported on Slack. Other platforms will receive a no-op or fallback behavior.
+  Modals are currently supported on Slack and Teams. Other platforms will receive a no-op
+  or fallback behavior.
 </Callout>
+
+## Callback URLs
+
+Buttons accept a `callbackUrl` prop. When clicked, the action data is POSTed to that URL in addition to firing any `onAction` handler. This pairs naturally with webhook-based workflow engines to build approval flows without any `onAction` handler at all:
+
+```tsx title="lib/bot.tsx" lineNumbers
+bot.onNewMention(async (thread) => {
+  const approveUrl = "https://example.com/webhook/approve";
+  const denyUrl = "https://example.com/webhook/deny";
+
+  await thread.post(
+    <Card title="Deploy v2.4.1?">
+      <Actions>
+        <Button callbackUrl={approveUrl} id="approve" style="primary">
+          Approve
+        </Button>
+        <Button callbackUrl={denyUrl} id="deny" style="danger">
+          Deny
+        </Button>
+      </Actions>
+    </Card>
+  );
+});
+```
+
+### Callback payload
+
+The POST body sent to the `callbackUrl`:
+
+```json
+{
+  "type": "action",
+  "actionId": "approve",
+  "user": { "id": "U123", "name": "alice" },
+  "threadId": "slack:C123:1234567890.123",
+  "messageId": "1234567890.456"
+}
+```
+
+If the button also has a `value` prop, it is included in the payload as `"value"`.
+
+<Callout type="info">
+  Platform limits apply to encoded button data. Discord's `custom_id` has a 100
+  character limit - if the action ID plus callback token exceed this, posting
+  the card throws a `ValidationError`. Telegram's `callback_data` has a 64 byte
+  limit - buttons that exceed this will throw a `ValidationError`. Keep action
+  IDs short when using `callbackUrl` on these platforms.
+</Callout>
+
+For modals, see [callbackUrl on modals](/docs/modals#callback-urls).

package/docs/adapters.mdx

@@ -8,60 +8,66 @@ prerequisites:
 
 Adapters handle webhook verification, message parsing, and API calls for each platform. Install only the adapters you need. Browse all available adapters — including community-built ones — on the [Adapters](/adapters) page.
 
+Need a browser chat UI? See the [Web adapter](/adapters/web) — it speaks the AI SDK `useChat` protocol so the same bot serves Slack, Teams, **and** a `<Conversation>` from `ai-elements` out of the box.
+
 Ready to build your own? Follow the [building](/docs/contributing/building) guide.
 
 ## Feature matrix
 
 ### Messaging
 
-| Feature | [Slack](/adapters/slack) | [Teams](/adapters/teams) | [Google Chat](/adapters/google-chat) | [Discord](/adapters/discord) | [Telegram](/adapters/telegram) | [GitHub](/adapters/github) | [Linear](/adapters/linear) | [WhatsApp](/adapters/whatsapp) |
-|---------|-------|-------|-------------|---------|---------|--------|--------|-----------|
-| Post message | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Edit message | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Delete message | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
-| File uploads | ✅ | ✅ | ❌ | ✅ | ⚠️ Single file | ❌ | ❌ | ✅ Images, audio, docs |
-| Streaming | ✅ Native | ⚠️ Post+Edit | ⚠️ Post+Edit | ⚠️ Post+Edit | ⚠️ Post+Edit | ❌ | ❌ | ❌ |
-| Scheduled messages | ✅ Native | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Feature | [Slack](/adapters/slack) | [Teams](/adapters/teams) | [Google Chat](/adapters/google-chat) | [Discord](/adapters/discord) | [Telegram](/adapters/telegram) | [GitHub](/adapters/github) | [Linear](/adapters/linear) | [WhatsApp](/adapters/whatsapp) | [Messenger](/adapters/messenger) |
+|---------|-------|-------|-------------|---------|---------|--------|--------|-----------|-----------|
+| Post message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> |
+| Edit message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Partial | <Cross /> | <Cross /> |
+| Delete message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Partial | <Cross /> | <Cross /> |
+| File uploads | <Check /> | <Check /> | <Cross /> | <Check /> | <Warn /> Single file | <Cross /> | <Cross /> | <Check /> Images, audio, docs | <Cross /> |
+| Streaming | <Check /> Native | <Warn /> Native (DMs) / Buffered | <Warn /> Post+Edit | <Warn /> Post+Edit | <Warn /> Post+Edit | <Warn /> Buffered | <Warn /> Agent sessions / Post+Edit | <Warn /> Buffered | <Warn /> Buffered |
+| Scheduled messages | <Check /> Native | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
 
 ### Rich content
 
-| Feature | Slack | Teams | Google Chat | Discord | Telegram | GitHub | Linear | WhatsApp |
-|---------|-------|-------|-------------|---------|----------|--------|--------|-----------|
-| Card format | Block Kit | Adaptive Cards | Google Chat Cards | Embeds | Markdown + inline keyboard buttons | GFM Markdown | Markdown | WhatsApp templates |
-| Buttons | ✅ | ✅ | ✅ | ✅ | ⚠️ Inline keyboard callbacks | ❌ | ❌ | ✅ Interactive replies |
-| Link buttons | ✅ | ✅ | ✅ | ✅ | ⚠️ Inline keyboard URLs | ❌ | ❌ | ❌ |
-| Select menus | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| Tables | ✅ Block Kit | ✅ GFM | ⚠️ ASCII | ✅ GFM | ⚠️ ASCII | ✅ GFM | ✅ GFM | ❌ |
-| Fields | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⚠️ Template variables |
-| Images in cards | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ | ✅ |
-| Modals | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Feature | Slack | Teams | Google Chat | Discord | Telegram | GitHub | Linear | WhatsApp | Messenger |
+|---------|-------|-------|-------------|---------|----------|--------|--------|-----------|-----------|
+| Card format | Block Kit | Adaptive Cards | Google Chat Cards | Embeds | Markdown + inline keyboard buttons | GFM Markdown | Markdown | WhatsApp templates | Generic/Button Templates |
+| Buttons | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Inline keyboard callbacks | <Cross /> | <Cross /> | <Check /> Interactive replies | <Warn /> Max 3, postback |
+| Link buttons | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Inline keyboard URLs | <Cross /> | <Cross /> | <Cross /> | <Check /> |
+| Select menus | <Check /> | <Cross /> | <Check /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
+| Tables | <Check /> Block Kit | <Check /> GFM | <Warn /> ASCII | <Check /> GFM | <Warn /> ASCII | <Check /> GFM | <Check /> GFM | <Cross /> | <Warn /> ASCII |
+| Fields | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Template variables | <Warn /> ASCII |
+| Images in cards | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Check /> | <Cross /> | <Check /> | <Check /> |
+| Modals | <Check /> | <Check /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
 
 ### Conversations
 
-| Feature | Slack | Teams | Google Chat | Discord | Telegram | GitHub | Linear | WhatsApp |
-|---------|-------|-------|-------------|---------|----------|--------|--------|-----------|
-| Slash commands | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
-| Mentions | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
-| Add reactions | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
-| Remove reactions | ✅ | ❌ | ✅ | ✅ | ✅ | ⚠️ | ⚠️ | ❌ |
-| Typing indicator | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ |
-| DMs | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ |
-| Ephemeral messages | ✅ Native | ❌ | ✅ Native | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Feature | Slack | Teams | Google Chat | Discord | Telegram | GitHub | Linear | WhatsApp | Messenger |
+|---------|-------|-------|-------------|---------|----------|--------|--------|-----------|-----------|
+| Slash commands | <Check /> | <Cross /> | <Cross /> | <Check /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
+| Mentions | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Check /> |
+| Add reactions | <Check /> | <Cross /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> |
+| Remove reactions | <Check /> | <Cross /> | <Check /> | <Check /> | <Check /> | <Warn /> | <Warn /> | <Check /> | <Cross /> |
+| Typing indicator | <Check /> | <Check /> | <Cross /> | <Check /> | <Check /> | <Cross /> | <Warn /> Agent sessions | <Cross /> | <Check /> |
+| DMs | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Cross /> | <Check /> | <Check /> |
+| Ephemeral messages | <Check /> Native | <Cross /> | <Check /> Native | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
+| User lookup ([`getUser`](/docs/api/chat#getuser)) | <Check /> | <Warn /> Cached | <Warn /> Cached | <Check /> | <Warn /> Seen users | <Check /> | <Check /> | <Cross /> | <Cross /> |
+| Parent subject ([`message.subject`](/docs/subject)) | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Check /> | <Check /> | <Cross /> | <Cross /> |
+| Native client ([`.client`](/docs/api/chat#getadapter)) | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Check /> | <Check /> | <Cross /> | <Cross /> |
+| Custom API endpoint (`apiUrl`) | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> |
 
 ### Message history
 
-| Feature | Slack | Teams | Google Chat | Discord | Telegram | GitHub | Linear | WhatsApp |
-|---------|-------|-------|-------------|---------|----------|--------|--------|-----------|
-| Fetch messages | ✅ | ✅ | ✅ | ✅ | ⚠️ Cached | ✅ | ✅ | ⚠️ Cached sent messages only |
-| Fetch single message | ✅ | ❌ | ❌ | ❌ | ⚠️ Cached | ❌ | ❌ | ⚠️ Cached sent messages only |
-| Fetch thread info | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
-| Fetch channel messages | ✅ | ✅ | ✅ | ✅ | ⚠️ Cached | ✅ | ❌ | ⚠️ Cached sent messages only |
-| List threads | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ |
-| Fetch channel info | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
-| Post channel message | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ |
+| Feature | Slack | Teams | Google Chat | Discord | Telegram | GitHub | Linear | WhatsApp | Messenger |
+|---------|-------|-------|-------------|---------|----------|--------|--------|-----------|-----------|
+| Fetch messages | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Cached | <Check /> | <Check /> | <Warn /> Cached sent messages only | <Warn /> Cached sent messages only |
+| Fetch single message | <Check /> | <Cross /> | <Cross /> | <Cross /> | <Warn /> Cached | <Cross /> | <Cross /> | <Cross /> | <Warn /> Cached |
+| Fetch thread info | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> |
+| Fetch channel messages | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Cached | <Check /> | <Cross /> | <Cross /> | <Warn /> Cached |
+| List threads | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Check /> | <Cross /> | <Cross /> | <Cross /> |
+| Fetch channel info | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Cross /> | <Check /> |
+| Post channel message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Cross /> | <Check /> | <Check /> |
 
 <Callout type="info">
-⚠️ indicates partial support — the feature works with limitations. See individual adapter pages for details.
+<Warn /> indicates partial support — the feature works with limitations. See individual adapter pages for details.
 </Callout>
 
 ## How adapters work

package/docs/api/cards.mdx

@@ -100,6 +100,10 @@ Button({ id: "delete", label: "Delete", style: "danger", value: "item-123" })
       type: '"action" | "modal"',
       default: '"action"',
     },
+    callbackUrl: {
+      description: 'URL to POST action data to when this button is clicked.',
+      type: 'string',
+    },
   }}
 />
 

package/docs/api/chat.mdx

@@ -168,7 +168,9 @@ Fires when a user clicks a button or selects an option in a card.
 ```typescript
 // Single action
 bot.onAction("approve", async (event) => {
-  await event.thread.post("Approved!");
+  if (event.thread) {
+    await event.thread.post("Approved!");
+  }
 });
 
 // Multiple actions
@@ -193,8 +195,8 @@ bot.onAction(async (event) => { /* ... */ });
       type: 'Author',
     },
     'event.thread': {
-      description: 'The thread containing the card.',
-      type: 'Thread',
+      description: 'The thread containing the card, or null for view-based actions.',
+      type: 'Thread | null',
     },
     'event.triggerId': {
       description: 'Trigger ID for opening modals (platform-specific, may expire quickly).',
@@ -255,14 +257,53 @@ bot.onModalSubmit("feedback", async (event) => {
 
 Returns `ModalResponse | undefined` to control the modal after submission:
 
-- `{ action: "close" }` — close the modal
+- `{ 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
 - `{ action: "update", modal: ModalElement }` — replace the modal content
 - `{ action: "push", modal: ModalElement }` — push a new modal view onto the stack
 
+### onOptionsLoad
+
+Fires when an `ExternalSelect` requests options dynamically. The handler is keyed on the select's `id` and must return options synchronously enough for Slack's 3-second budget (the adapter caps the loader at ~2.5s and substitutes an empty result on timeout). Slack-only.
+
+```typescript
+bot.onOptionsLoad("assignee", async (event) => {
+  const people = await peopleService.search(event.query);
+  return people.map((p) => ({ label: p.fullName, value: p.id }));
+});
+```
+
+Return an array of `OptionsLoadGroup` (`{ label, options }[]`) instead of a flat array to render grouped headers (e.g. "Recent" / "All"). Slack limits: max 100 groups, max 100 options per group.
+
+<TypeTable
+  type={{
+    'event.actionId': {
+      description: 'The id of the select requesting options (matches the id passed to bot.onOptionsLoad).',
+      type: 'string',
+    },
+    'event.query': {
+      description: 'The text the user has typed so far.',
+      type: 'string',
+    },
+    'event.user': {
+      description: 'The user requesting options.',
+      type: 'Author',
+    },
+    'event.adapter': {
+      description: 'The adapter that received this event.',
+      type: 'Adapter',
+    },
+    'event.raw': {
+      description: 'Raw platform-specific payload.',
+      type: 'unknown',
+    },
+  }}
+/>
+
 ### onSlashCommand
 
-Fires when a user invokes a `/command` in the message composer. Currently supported on Slack.
+Fires when a user invokes a `/command` in the message composer. Currently supported on Slack and Discord.
 
 ```typescript
 // Specific command
@@ -425,12 +466,42 @@ bot.webhooks.teams(request, { waitUntil });
 
 ### getAdapter
 
-Get an adapter instance by name.
+Get a typed adapter instance by name.
 
 ```typescript
 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:
+
+```typescript
+// Linear - full LinearClient from @linear/sdk
+const linear = bot.getAdapter("linear").client;
+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 { data: pulls } = await github.rest.pulls.list({
+  owner: "vercel",
+  repo: "chat",
+  state: "open",
+});
+```
+
+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.
+
+<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.
+</Callout>
+
+| Adapter | `client` type |
+|---------|---------------|
+| Linear | `LinearClient` from `@linear/sdk` |
+| GitHub | `Octokit` from `@octokit/rest` |
+
 ### openDM
 
 Open a direct message thread with a user.
@@ -443,6 +514,101 @@ await dm.post("Hello via DM!");
 const dm = await bot.openDM(message.author);
 ```
 
+### getUser
+
+Look up user information by user ID. Returns a `UserInfo` object with name, email, avatar, and bot status, or `null` if the user was not found. Supported on Slack, Microsoft Teams, Discord, Google Chat, GitHub, Linear, and Telegram. Other adapters will throw `NOT_SUPPORTED`.
+
+```typescript
+const user = await bot.getUser("U123456");
+console.log(user?.email);    // "alice@company.com"
+console.log(user?.fullName); // "Alice Smith"
+```
+
+```typescript
+// Or with an Author object from a message handler
+const user = await bot.getUser(message.author);
+```
+
+<TypeTable
+  type={{
+    userId: {
+      description: 'Platform-specific user ID.',
+      type: 'string',
+    },
+    userName: {
+      description: 'Username/handle.',
+      type: 'string',
+    },
+    fullName: {
+      description: 'Display name / full name.',
+      type: 'string',
+    },
+    isBot: {
+      description: 'Whether the user is a bot.',
+      type: 'boolean',
+    },
+    email: {
+      description: 'Email address (requires scopes on some platforms).',
+      type: 'string | undefined',
+    },
+    avatarUrl: {
+      description: 'Profile image URL.',
+      type: 'string | undefined',
+    },
+  }}
+/>
+
+<Callout type="info">
+  **Per-platform constraints:**
+  - **Slack** — requires both `users:read` and `users:read.email` scopes (the email scope must be granted at OAuth install time).
+  - **Discord** — bot tokens never see email (the `email` OAuth scope only applies in user-context auth).
+  - **Telegram** — bots can only look up users who have previously messaged them.
+  - **Microsoft Teams** — only works for users who previously interacted with the bot (cached from webhook activity). `avatarUrl` is not returned (Graph API requires a separate photo call).
+  - **Google Chat** — same caching constraint as Teams: only users seen in prior webhooks.
+  - **GitHub** — `email` is `null` unless the user made it public, or you authenticated with the `user:email` scope.
+  - **Linear** — full profile (incl. email + avatar) for any active workspace member.
+
+  Fields that aren't available return `undefined`. Numeric user IDs (Discord/Telegram/GitHub) can be ambiguous when multiple of those adapters are registered — `bot.getUser` throws a `ChatError` with code `AMBIGUOUS_USER_ID` in that case. Pass an `Author` from a message handler (which already carries the adapter), or call the adapter directly (`adapter.getUser(userId)`).
+</Callout>
+
+`bot.getUser` throws a `ChatError` in three cases. Handle them if your bot runs on multiple platforms:
+
+| Code | When |
+|------|------|
+| `NOT_SUPPORTED` | The resolved adapter doesn't implement `getUser` (e.g. WhatsApp) |
+| `AMBIGUOUS_USER_ID` | A numeric user ID could belong to more than one registered adapter (Discord/Telegram/GitHub) |
+| `UNKNOWN_USER_ID_FORMAT` | The `userId` string doesn't match any registered platform's ID format |
+
+```typescript
+import { ChatError } from "chat";
+
+try {
+  const user = await bot.getUser(userId);
+  if (!user) {
+    // User not found on this platform
+  }
+} catch (error) {
+  if (error instanceof ChatError) {
+    if (error.code === "NOT_SUPPORTED") {
+      // This adapter doesn't support user lookups
+    } else if (error.code === "AMBIGUOUS_USER_ID") {
+      // Pass message.author or call adapter.getUser(userId) directly
+    } else if (error.code === "UNKNOWN_USER_ID_FORMAT") {
+      // userId doesn't match any known platform format
+    }
+  }
+}
+```
+
+### thread
+
+Get a Thread handle by its thread ID. Useful for posting to threads outside of webhook contexts (e.g. cron jobs, external triggers).
+
+```typescript
+const thread = bot.thread("slack:C123ABC:1234567890.123456");
+await thread.post("Hello from a cron job!");
+```
+
 ### channel
 
 Get a Channel by its channel ID.

package/docs/api/index.mdx

@@ -31,6 +31,8 @@ import { Chat, root, paragraph, text, Card, Button, emoji } from "chat";
 | Export | Description |
 |--------|-------------|
 | [`PostableMessage`](/docs/api/postable-message) | Union type accepted by `thread.post()` |
+| [`Plan`](/docs/api/postable-message#plan) | Step-by-step task list that mutates after posting |
+| [`StreamingPlan`](/docs/api/postable-message#streamingplan) | Wraps an async iterable with platform-specific streaming options |
 | [`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. |