chat 4.24.0 → 4.26.0

package/dist/index.d.ts

@@ -95,7 +95,9 @@ declare class ChannelImpl<TState = Record<string, unknown>> implements Channel<T
      */
     threads(): AsyncIterable<ThreadSummary>;
     fetchMetadata(): Promise<ChannelInfo>;
-    post(message: string | PostableMessage | ChatElement): Promise<SentMessage>;
+    post<T extends PostableObject>(message: T): Promise<T>;
+    post(message: string | AdapterPostableMessage | AsyncIterable<string> | ChatElement): Promise<SentMessage>;
+    private handlePostableObject;
     private postSingleMessage;
     postEphemeral(user: string | Author, message: AdapterPostableMessage | ChatElement, options: PostEphemeralOptions): Promise<EphemeralMessage | null>;
     schedule(message: AdapterPostableMessage | ChatElement, options: {
@@ -141,6 +143,43 @@ declare class ConsoleLogger implements Logger {
     error(message: string, ...args: unknown[]): void;
 }
 
+/**
+ * Context provided to a PostableObject after it has been posted.
+ */
+interface PostableObjectContext {
+    adapter: Adapter;
+    logger?: Logger;
+    messageId: string;
+    threadId: string;
+}
+/**
+ * Base interface for objects that can be posted to threads/channels.
+ * Examples: Plan, Poll, etc.
+ *
+ * @template TData - The data type returned by getPostData()
+ */
+interface PostableObject<TData = unknown> {
+    /** Symbol identifying this as a postable object */
+    readonly $$typeof: symbol;
+    /**
+     * Get a fallback text representation for adapters that don't support this object type.
+     * This should return a human-readable string representation.
+     */
+    getFallbackText(): string;
+    /** Get the data to send to the adapter */
+    getPostData(): TData;
+    /** Check if the adapter supports this object type */
+    isSupported(adapter: Adapter): boolean;
+    /** The kind of object - used by adapters to dispatch */
+    readonly kind: string;
+    /** Called after successful posting to bind the object to the thread */
+    onPosted(context: PostableObjectContext): void;
+}
+/**
+ * Type guard to check if a value is a PostableObject.
+ */
+declare function isPostableObject(value: unknown): value is PostableObject;
+
 /**
  * Serialized thread data for passing to external systems (e.g., workflow engines).
  */
@@ -252,7 +291,9 @@ declare class ThreadImpl<TState = Record<string, unknown>> implements Thread<TSt
     isSubscribed(): Promise<boolean>;
     subscribe(): Promise<void>;
     unsubscribe(): Promise<void>;
-    post(message: string | PostableMessage | ChatElement): Promise<SentMessage>;
+    post<T extends PostableObject>(message: T): Promise<T>;
+    post(message: string | AdapterPostableMessage | AsyncIterable<string> | ChatElement): Promise<SentMessage>;
+    private handlePostableObject;
     postEphemeral(user: string | Author, message: AdapterPostableMessage | ChatElement, options: PostEphemeralOptions): Promise<EphemeralMessage | null>;
     schedule(message: AdapterPostableMessage | ChatElement, options: {
         postAt: Date;
@@ -337,6 +378,85 @@ declare class NotImplementedError extends ChatError {
     constructor(message: string, feature?: string, cause?: unknown);
 }
 
+type PlanTaskStatus = "pending" | "in_progress" | "complete" | "error";
+interface PlanTask {
+    id: string;
+    status: PlanTaskStatus;
+    title: string;
+}
+interface PlanModel {
+    tasks: PlanModelTask[];
+    title: string;
+}
+interface PlanModelTask {
+    details?: PlanContent;
+    id: string;
+    output?: PlanContent;
+    status: PlanTaskStatus;
+    title: string;
+}
+type PlanContent = string | string[] | {
+    markdown: string;
+} | {
+    ast: Root;
+};
+interface StartPlanOptions {
+    /** Initial plan title and first task title */
+    initialMessage: PlanContent;
+}
+interface AddTaskOptions {
+    /** Task details/substeps. */
+    children?: PlanContent;
+    title: PlanContent;
+}
+type UpdateTaskInput = PlanContent | {
+    /** Task output/results. */
+    output?: PlanContent;
+    /** Optional status override. */
+    status?: PlanTaskStatus;
+};
+interface CompletePlanOptions {
+    /** Final plan title shown when completed */
+    completeMessage: PlanContent;
+}
+/**
+ * A Plan represents a task list that can be posted to a thread.
+ *
+ * Create a plan with `new Plan({ initialMessage: "..." })` and post it with `thread.post(plan)`.
+ * After posting, use methods like `addTask()`, `updateTask()`, and `complete()` to update it.
+ *
+ * @example
+ * ```typescript
+ * const plan = new Plan({ initialMessage: "Starting task..." });
+ * await thread.post(plan);
+ * await plan.addTask({ title: "Fetch data" });
+ * await plan.updateTask("Got 42 results");
+ * await plan.complete({ completeMessage: "Done!" });
+ * ```
+ */
+declare class Plan implements PostableObject<PlanModel> {
+    readonly $$typeof: symbol;
+    readonly kind = "plan";
+    private _model;
+    private _bound;
+    constructor(options: StartPlanOptions);
+    isSupported(adapter: Adapter): boolean;
+    getPostData(): PlanModel;
+    getFallbackText(): string;
+    onPosted(context: PostableObjectContext): void;
+    get id(): string;
+    get threadId(): string;
+    get title(): string;
+    get tasks(): readonly PlanTask[];
+    get currentTask(): PlanTask | null;
+    addTask(options: AddTaskOptions): Promise<PlanTask | null>;
+    updateTask(update?: UpdateTaskInput): Promise<PlanTask | null>;
+    reset(options: StartPlanOptions): Promise<PlanTask | null>;
+    complete(options: CompletePlanOptions): Promise<void>;
+    private canMutate;
+    private enqueueEdit;
+}
+
 /**
  * Represents the visibility scope of a channel.
  *
@@ -488,6 +608,16 @@ interface Adapter<TThreadId = unknown, TRawMessage = unknown> {
     disconnect?(): Promise<void>;
     /** Edit an existing message */
     editMessage(threadId: string, messageId: string, message: AdapterPostableMessage): Promise<RawMessage<TRawMessage>>;
+    /**
+     * Edit a previously posted object (Plan, Poll, etc.).
+     * If not implemented, object updates will throw PlanNotSupportedError.
+     *
+     * @param threadId - The thread containing the message
+     * @param messageId - The message ID to edit
+     * @param kind - The object kind (e.g., "plan")
+     * @param data - The object data (type depends on kind)
+     */
+    editObject?(threadId: string, messageId: string, kind: string, data: unknown): Promise<RawMessage<TRawMessage>>;
     /** Encode platform-specific data into a thread ID string */
     encodeThreadId(platformData: TThreadId): string;
     /**
@@ -633,6 +763,15 @@ interface Adapter<TThreadId = unknown, TRawMessage = unknown> {
     postEphemeral?(threadId: string, userId: string, message: AdapterPostableMessage): Promise<EphemeralMessage<TRawMessage>>;
     /** Post a message to a thread */
     postMessage(threadId: string, message: AdapterPostableMessage): Promise<RawMessage<TRawMessage>>;
+    /**
+     * Post a special object (Plan, Poll, etc.) as a single message.
+     * If not implemented, posting such objects will throw PlanNotSupportedError.
+     *
+     * @param threadId - The thread to post to
+     * @param kind - The object kind (e.g., "plan")
+     * @param data - The object data (type depends on kind)
+     */
+    postObject?(threadId: string, kind: string, data: unknown): Promise<RawMessage<TRawMessage>>;
     /** Remove a reaction from a message */
     removeReaction(threadId: string, messageId: string, emoji: EmojiValue | string): Promise<void>;
     /** Render formatted content to platform-specific string */
@@ -920,6 +1059,7 @@ interface Postable<TState = Record<string, unknown>, TRawMessage = unknown> {
     /**
      * Post a message.
      */
+    post<T extends PostableObject>(message: T): Promise<T>;
     post(message: string | PostableMessage | ChatElement): Promise<SentMessage<TRawMessage>>;
     /**
      * Post an ephemeral message visible only to a specific user.
@@ -1097,8 +1237,15 @@ interface Thread<TState = Record<string, unknown>, TRawMessage = unknown> extend
      * // Stream from AI SDK
      * const result = await agent.stream({ prompt: message.text });
      * await thread.post(result.textStream);
+     *
+     * // Plan with live updates
+     * const plan = new Plan({ initialMessage: "Working..." });
+     * await thread.post(plan);
+     * await plan.addTask({ title: "Step 1" });
+     * await plan.complete({ completeMessage: "Done!" });
      * ```
      */
+    post<T extends PostableObject>(message: T): Promise<T>;
     post(message: string | PostableMessage | ChatElement): Promise<SentMessage<TRawMessage>>;
     /**
      * Post an ephemeral message visible only to a specific user.
@@ -1171,6 +1318,7 @@ interface Thread<TState = Record<string, unknown>, TRawMessage = unknown> extend
      */
     unsubscribe(): Promise<void>;
 }
+
 interface ThreadInfo {
     channelId: string;
     channelName?: string;
@@ -1358,7 +1506,7 @@ type AdapterPostableMessage = string | PostableRaw | PostableMarkdown | Postable
  * - `AsyncIterable<string>` - Streaming text (e.g., from AI SDK's textStream)
  * - `AsyncIterable<string | StreamEvent>` - AI SDK fullStream (auto-detected, extracts text with step separators)
  */
-type PostableMessage = AdapterPostableMessage | AsyncIterable<string | StreamChunk | StreamEvent>;
+type PostableMessage = AdapterPostableMessage | AsyncIterable<string | StreamChunk | StreamEvent> | PostableObject;
 /**
  * Duck-typed stream event compatible with AI SDK's `fullStream`.
  * - `text-delta` events are extracted as text output.
@@ -2733,6 +2881,28 @@ declare class Chat<TAdapters extends Record<string, Adapter> = Record<string, Ad
  */
 declare function fromFullStream(stream: AsyncIterable<unknown>): AsyncIterable<string | StreamChunk>;
 
+/**
+ * Standalone JSON reviver for Chat SDK objects.
+ *
+ * Restores serialized Thread, Channel, and Message instances during
+ * JSON.parse() without requiring a Chat instance. This is useful in
+ * environments like Vercel Workflow functions where importing the full
+ * Chat instance (with its adapter dependencies) is not possible.
+ *
+ * Thread instances created this way use lazy adapter resolution —
+ * the adapter is looked up from the Chat singleton when first accessed,
+ * so `chat.registerSingleton()` must be called before using thread
+ * methods like `post()` (typically inside a "use step" function).
+ */
+declare function reviver(_key: string, value: unknown): unknown;
+
+interface StreamingMarkdownRendererOptions {
+    /**
+     * Wrap confirmed table blocks in code fences for append-only consumers that
+     * cannot render markdown tables while a stream is in flight.
+     */
+    wrapTablesForAppend?: boolean;
+}
 /**
  * A streaming markdown renderer that buffers potential table headers
  * until confirmed by a separator line, preventing tables from flashing
@@ -2750,6 +2920,8 @@ declare class StreamingMarkdownRenderer {
     private fenceToggles;
     /** Incomplete trailing line buffer for incremental fence tracking. */
     private incompleteLine;
+    private readonly options;
+    constructor(options?: StreamingMarkdownRendererOptions);
     /** Append a chunk from the LLM stream. */
     push(chunk: string): void;
     /** O(1) check if accumulated text is inside an unclosed code fence. */
@@ -2766,9 +2938,10 @@ declare class StreamingMarkdownRenderer {
      * Get text safe for append-only streaming (e.g. Slack native streaming).
      *
      * - Holds back unconfirmed table headers until separator arrives.
-     * - Wraps confirmed tables in code fences so pipes render as literal
-     *   text (not broken mrkdwn). The code fence is left OPEN while
-     *   the table is still streaming, keeping output monotonic for deltas.
+     * - Optionally wraps confirmed tables in code fences so pipes render as
+     *   literal text on append-only surfaces that lack native table support.
+     *   The code fence is left OPEN while the table is still streaming,
+     *   keeping output monotonic for deltas.
      * - Holds back unclosed inline markers (**, *, ~~, `, [).
      * - The final editMessage replaces everything with properly formatted text.
      */
@@ -2777,6 +2950,7 @@ declare class StreamingMarkdownRenderer {
     getText(): string;
     /** Signal stream end. Flushes held-back lines. Returns final render. */
     finish(): string;
+    private formatAppendOnlyText;
 }
 
 /**
@@ -3222,4 +3396,4 @@ declare const Select: SelectComponent;
 declare const SelectOption: SelectOptionComponent;
 declare const TextInput: TextInputComponent;
 
-export { type ActionEvent, type ActionHandler, Actions, ActionsComponent, type Adapter, type AdapterPostableMessage, type AiAssistantMessage, type AiFilePart, type AiImagePart, type AiMessage, type AiMessagePart, type AiTextPart, type AiUserMessage, type AppHomeOpenedEvent, type AppHomeOpenedHandler, type AssistantContextChangedEvent, type AssistantContextChangedHandler, type AssistantThreadStartedEvent, type AssistantThreadStartedHandler, type Attachment, type Author, BaseFormatConverter, Button, ButtonComponent, Card, CardChild, CardComponent, CardElement, CardLink, CardLinkComponent, CardText, type Channel, ChannelImpl, type ChannelInfo, type ChannelVisibility, Chat, type ChatConfig, ChatElement, ChatError, type ChatInstance, type ConcurrencyConfig, type ConcurrencyStrategy, ConsoleLogger, type CustomEmojiMap, DEFAULT_EMOJI_MAP, type DirectMessageHandler, Divider, DividerComponent, type Emoji, type EmojiFormats, type EmojiMapConfig, EmojiResolver, type EmojiValue, type EphemeralMessage, type FetchDirection, type FetchOptions, type FetchResult, Field, FieldComponent, Fields, FieldsComponent, type FileUpload, type FormatConverter, type FormattedContent, Image, ImageComponent, LinkButton, LinkButtonComponent, type LinkPreview, type ListThreadsOptions, type ListThreadsResult, type Lock, LockError, type LockScope, type LockScopeContext, type LogLevel, type Logger, type MarkdownConverter, type MarkdownTextChunk, type MemberJoinedChannelEvent, type MemberJoinedChannelHandler, type MentionHandler, Message, type MessageContext, type MessageData, type MessageHandler, MessageHistoryCache, type MessageHistoryConfig, type MessageMetadata, Modal, type ModalCloseEvent, type ModalCloseHandler, type ModalCloseResponse, ModalComponent, ModalElement, type ModalErrorsResponse, type ModalPushResponse, type ModalResponse, type ModalSubmitEvent, type ModalSubmitHandler, type ModalUpdateResponse, NotImplementedError, type PlanUpdateChunk, type PostEphemeralOptions, type Postable, type PostableAst, type PostableCard, type PostableMarkdown, type PostableMessage, type PostableRaw, type QueueEntry, RadioSelect, RadioSelectComponent, RateLimitError, type RawMessage, type ReactionEvent, type ReactionHandler, type ScheduledMessage, Section, SectionComponent, Select, SelectComponent, SelectOption, SelectOptionComponent, type SentMessage, type SerializedChannel, type SerializedMessage, type SerializedThread, type SlashCommandEvent, type SlashCommandHandler, type StateAdapter, type StreamChunk, type StreamEvent, type StreamOptions, StreamingMarkdownRenderer, type SubscribedMessageHandler, THREAD_STATE_TTL_MS, Table, type TaskUpdateChunk, TextComponent, TextInput, TextInputComponent, type Thread, ThreadImpl, type ThreadInfo, type ThreadSummary, type WebhookOptions, type WellKnownEmoji, blockquote, cardChildToFallbackText, codeBlock, convertEmojiPlaceholders, createEmoji, defaultEmojiResolver, deriveChannelId, emoji, emphasis, fromFullStream, fromReactElement, fromReactModalElement, getEmoji, getNodeChildren, getNodeValue, inlineCode, isBlockquoteNode, isCardElement, isCodeNode, isDeleteNode, isEmphasisNode, isInlineCodeNode, isJSX, isLinkNode, isListItemNode, isListNode, isModalElement, isParagraphNode, isStrongNode, isTableCellNode, isTableNode, isTableRowNode, isTextNode, link, markdownToPlainText, paragraph, parseMarkdown, root, strikethrough, stringifyMarkdown, strong, tableElementToAscii, tableToAscii, text, toAiMessages, toCardElement, toModalElement, toPlainText, walkAst };
+export { type ActionEvent, type ActionHandler, Actions, ActionsComponent, type Adapter, type AdapterPostableMessage, type AddTaskOptions, type AiAssistantMessage, type AiFilePart, type AiImagePart, type AiMessage, type AiMessagePart, type AiTextPart, type AiUserMessage, type AppHomeOpenedEvent, type AppHomeOpenedHandler, type AssistantContextChangedEvent, type AssistantContextChangedHandler, type AssistantThreadStartedEvent, type AssistantThreadStartedHandler, type Attachment, type Author, BaseFormatConverter, Button, ButtonComponent, Card, CardChild, CardComponent, CardElement, CardLink, CardLinkComponent, CardText, type Channel, ChannelImpl, type ChannelInfo, type ChannelVisibility, Chat, type ChatConfig, ChatElement, ChatError, type ChatInstance, type CompletePlanOptions, type ConcurrencyConfig, type ConcurrencyStrategy, ConsoleLogger, type CustomEmojiMap, DEFAULT_EMOJI_MAP, type DirectMessageHandler, Divider, DividerComponent, type Emoji, type EmojiFormats, type EmojiMapConfig, EmojiResolver, type EmojiValue, type EphemeralMessage, type FetchDirection, type FetchOptions, type FetchResult, Field, FieldComponent, Fields, FieldsComponent, type FileUpload, type FormatConverter, type FormattedContent, Image, ImageComponent, LinkButton, LinkButtonComponent, type LinkPreview, type ListThreadsOptions, type ListThreadsResult, type Lock, LockError, type LockScope, type LockScopeContext, type LogLevel, type Logger, type MarkdownConverter, type MarkdownTextChunk, type MemberJoinedChannelEvent, type MemberJoinedChannelHandler, type MentionHandler, Message, type MessageContext, type MessageData, type MessageHandler, MessageHistoryCache, type MessageHistoryConfig, type MessageMetadata, Modal, type ModalCloseEvent, type ModalCloseHandler, type ModalCloseResponse, ModalComponent, ModalElement, type ModalErrorsResponse, type ModalPushResponse, type ModalResponse, type ModalSubmitEvent, type ModalSubmitHandler, type ModalUpdateResponse, NotImplementedError, Plan, type PlanContent, type PlanModel, type PlanModelTask, type PlanTask, type PlanTaskStatus, type PlanUpdateChunk, type PostEphemeralOptions, type Postable, type PostableAst, type PostableCard, type PostableMarkdown, type PostableMessage, type PostableObject, type PostableObjectContext, type PostableRaw, type QueueEntry, RadioSelect, RadioSelectComponent, RateLimitError, type RawMessage, type ReactionEvent, type ReactionHandler, type ScheduledMessage, Section, SectionComponent, Select, SelectComponent, SelectOption, SelectOptionComponent, type SentMessage, type SerializedChannel, type SerializedMessage, type SerializedThread, type SlashCommandEvent, type SlashCommandHandler, type StartPlanOptions, type StateAdapter, type StreamChunk, type StreamEvent, type StreamOptions, StreamingMarkdownRenderer, type SubscribedMessageHandler, THREAD_STATE_TTL_MS, Table, type TaskUpdateChunk, TextComponent, TextInput, TextInputComponent, type Thread, ThreadImpl, type ThreadInfo, type ThreadSummary, type UpdateTaskInput, type WebhookOptions, type WellKnownEmoji, blockquote, cardChildToFallbackText, codeBlock, convertEmojiPlaceholders, createEmoji, defaultEmojiResolver, deriveChannelId, emoji, emphasis, fromFullStream, fromReactElement, fromReactModalElement, getEmoji, getNodeChildren, getNodeValue, inlineCode, isBlockquoteNode, isCardElement, isCodeNode, isDeleteNode, isEmphasisNode, isInlineCodeNode, isJSX, isLinkNode, isListItemNode, isListNode, isModalElement, isParagraphNode, isPostableObject, isStrongNode, isTableCellNode, isTableNode, isTableRowNode, isTextNode, link, markdownToPlainText, paragraph, parseMarkdown, reviver, root, strikethrough, stringifyMarkdown, strong, tableElementToAscii, tableToAscii, text, toAiMessages, toCardElement, toModalElement, toPlainText, walkAst };

package/dist/index.js

@@ -380,6 +380,27 @@ var Message = class _Message {
   }
 };
 
+// src/postable-object.ts
+var POSTABLE_OBJECT = /* @__PURE__ */ Symbol.for("chat.postable");
+function isPostableObject(value) {
+  return typeof value === "object" && value !== null && value.$$typeof === POSTABLE_OBJECT;
+}
+async function postPostableObject(obj, adapter, threadId, postFn, logger) {
+  const context = (raw) => ({
+    adapter,
+    logger,
+    messageId: raw.id,
+    threadId: raw.threadId ?? threadId
+  });
+  if (obj.isSupported(adapter) && adapter.postObject) {
+    const raw = await adapter.postObject(threadId, obj.kind, obj.getPostData());
+    obj.onPosted(context(raw));
+  } else {
+    const raw = await postFn(threadId, obj.getFallbackText());
+    obj.onPosted(context(raw));
+  }
+}
+
 // src/errors.ts
 var ChatError = class extends Error {
   code;
@@ -605,6 +626,10 @@ var ChannelImpl = class _ChannelImpl {
     };
   }
   async post(message) {
+    if (isPostableObject(message)) {
+      await this.handlePostableObject(message);
+      return message;
+    }
     if (isAsyncIterable(message)) {
       let accumulated = "";
       for await (const chunk of fromFullStream(message)) {
@@ -624,6 +649,14 @@ var ChannelImpl = class _ChannelImpl {
     }
     return this.postSingleMessage(postable);
   }
+  async handlePostableObject(obj) {
+    await postPostableObject(
+      obj,
+      this.adapter,
+      this.id,
+      (threadId, message) => this.adapter.postChannelMessage ? this.adapter.postChannelMessage(threadId, message) : this.adapter.postMessage(threadId, message)
+    );
+  }
   async postSingleMessage(postable) {
     const rawMessage = this.adapter.postChannelMessage ? await this.adapter.postChannelMessage(this.id, postable) : await this.adapter.postMessage(this.id, postable);
     const sent = this.createSentMessage(
@@ -696,7 +729,7 @@ var ChannelImpl = class _ChannelImpl {
     return {
       _type: "chat:Channel",
       id: this.id,
-      adapterName: this.adapter.name,
+      adapterName: this._adapterName ?? this.adapter.name,
       channelVisibility: this.channelVisibility,
       isDM: this.isDM
     };
@@ -877,6 +910,12 @@ var StreamingMarkdownRenderer = class {
   fenceToggles = 0;
   /** Incomplete trailing line buffer for incremental fence tracking. */
   incompleteLine = "";
+  options;
+  constructor(options = {}) {
+    this.options = {
+      wrapTablesForAppend: options.wrapTablesForAppend ?? true
+    };
+  }
   /** Append a chunk from the LLM stream. */
   push(chunk) {
     this.accumulated += chunk;
@@ -928,30 +967,31 @@ var StreamingMarkdownRenderer = class {
    * Get text safe for append-only streaming (e.g. Slack native streaming).
    *
    * - Holds back unconfirmed table headers until separator arrives.
-   * - Wraps confirmed tables in code fences so pipes render as literal
-   *   text (not broken mrkdwn). The code fence is left OPEN while
-   *   the table is still streaming, keeping output monotonic for deltas.
+   * - Optionally wraps confirmed tables in code fences so pipes render as
+   *   literal text on append-only surfaces that lack native table support.
+   *   The code fence is left OPEN while the table is still streaming,
+   *   keeping output monotonic for deltas.
    * - Holds back unclosed inline markers (**, *, ~~, `, [).
    * - The final editMessage replaces everything with properly formatted text.
    */
   getCommittableText() {
     if (this.finished) {
-      return wrapTablesForAppend(this.accumulated, true);
+      return this.formatAppendOnlyText(this.accumulated, true);
     }
     let text2 = this.accumulated;
     if (text2.length > 0 && !text2.endsWith("\n")) {
       const lastNewline = text2.lastIndexOf("\n");
       const withoutIncompleteLine = lastNewline >= 0 ? text2.slice(0, lastNewline + 1) : "";
       if (isInsideCodeFence(withoutIncompleteLine)) {
-        return wrapTablesForAppend(text2);
+        return this.formatAppendOnlyText(text2);
       }
       text2 = withoutIncompleteLine;
     }
     if (isInsideCodeFence(text2)) {
-      return wrapTablesForAppend(text2);
+      return this.formatAppendOnlyText(text2);
     }
     const committed = getCommittablePrefix(text2);
-    const wrapped = wrapTablesForAppend(committed);
+    const wrapped = this.formatAppendOnlyText(committed);
     if (isInsideCodeFence(wrapped)) {
       return wrapped;
     }
@@ -967,6 +1007,12 @@ var StreamingMarkdownRenderer = class {
     this.dirty = true;
     return this.render();
   }
+  formatAppendOnlyText(text2, closeFences = false) {
+    if (!this.options.wrapTablesForAppend) {
+      return text2;
+    }
+    return wrapTablesForAppend(text2, closeFences);
+  }
 };
 var INLINE_MARKER_CHARS = /* @__PURE__ */ new Set(["*", "~", "`", "["]);
 function isClean(text2) {
@@ -1308,6 +1354,10 @@ var ThreadImpl = class _ThreadImpl {
     await this._stateAdapter.unsubscribe(this.id);
   }
   async post(message) {
+    if (isPostableObject(message)) {
+      await this.handlePostableObject(message);
+      return message;
+    }
     if (isAsyncIterable2(message)) {
       return this.handleStream(message);
     }
@@ -1330,6 +1380,15 @@ var ThreadImpl = class _ThreadImpl {
     }
     return result;
   }
+  async handlePostableObject(obj) {
+    await postPostableObject(
+      obj,
+      this.adapter,
+      this.id,
+      (threadId, message) => this.adapter.postMessage(threadId, message),
+      this._logger
+    );
+  }
   async postEphemeral(user, message, options) {
     const { fallbackToDM } = options;
     const userId = typeof user === "string" ? user : user.userId;
@@ -1482,7 +1541,7 @@ var ThreadImpl = class _ThreadImpl {
         return;
       }
       const content = renderer.render();
-      if (content !== lastEditContent) {
+      if (content.trim() && content !== lastEditContent) {
         try {
           await this.adapter.editMessage(threadIdForEdits, msg.id, {
             markdown: content
@@ -1504,12 +1563,14 @@ var ThreadImpl = class _ThreadImpl {
         renderer.push(chunk);
         if (!msg) {
           const content = renderer.render();
-          msg = await this.adapter.postMessage(this.id, {
-            markdown: content
-          });
-          threadIdForEdits = msg.threadId || this.id;
-          lastEditContent = content;
-          scheduleNextEdit();
+          if (content.trim()) {
+            msg = await this.adapter.postMessage(this.id, {
+              markdown: content
+            });
+            threadIdForEdits = msg.threadId || this.id;
+            lastEditContent = content;
+            scheduleNextEdit();
+          }
         }
       }
     } finally {
@@ -1526,12 +1587,12 @@ var ThreadImpl = class _ThreadImpl {
     const finalContent = renderer.finish();
     if (!msg) {
       msg = await this.adapter.postMessage(this.id, {
-        markdown: accumulated
+        markdown: accumulated.trim() ? accumulated : " "
       });
       threadIdForEdits = msg.threadId || this.id;
       lastEditContent = accumulated;
     }
-    if (finalContent !== lastEditContent) {
+    if (finalContent.trim() && finalContent !== lastEditContent) {
       await this.adapter.editMessage(threadIdForEdits, msg.id, {
         markdown: accumulated
       });
@@ -1583,7 +1644,7 @@ var ThreadImpl = class _ThreadImpl {
       channelVisibility: this.channelVisibility,
       currentMessage: this._currentMessage?.toJSON(),
       isDM: this.isDM,
-      adapterName: this.adapter.name
+      adapterName: this._adapterName ?? this.adapter.name
     };
   }
   /**
@@ -1773,6 +1834,23 @@ function extractMessageContent2(message) {
   throw new Error("Invalid PostableMessage format");
 }
 
+// src/reviver.ts
+function reviver(_key, value) {
+  if (value && typeof value === "object" && "_type" in value) {
+    const typed = value;
+    if (typed._type === "chat:Thread") {
+      return ThreadImpl.fromJSON(value);
+    }
+    if (typed._type === "chat:Channel") {
+      return ChannelImpl.fromJSON(value);
+    }
+    if (typed._type === "chat:Message") {
+      return Message.fromJSON(value);
+    }
+  }
+  return value;
+}
+
 // src/chat.ts
 var DEFAULT_LOCK_TTL_MS = 3e4;
 function sleep(ms) {
@@ -2189,21 +2267,7 @@ var Chat = class {
    */
   reviver() {
     this.registerSingleton();
-    return function reviver(_key, value) {
-      if (value && typeof value === "object" && "_type" in value) {
-        const typed = value;
-        if (typed._type === "chat:Thread") {
-          return ThreadImpl.fromJSON(value);
-        }
-        if (typed._type === "chat:Channel") {
-          return ChannelImpl.fromJSON(value);
-        }
-        if (typed._type === "chat:Message") {
-          return Message.fromJSON(value);
-        }
-      }
-      return value;
-    };
+    return reviver;
   }
   // ChatInstance interface implementations
   /**
@@ -3311,6 +3375,220 @@ var Chat = class {
   }
 };
 
+// src/plan.ts
+function contentToPlainText(content) {
+  if (!content) {
+    return "";
+  }
+  if (Array.isArray(content)) {
+    return content.join(" ").trim();
+  }
+  if (typeof content === "string") {
+    return content;
+  }
+  if ("markdown" in content) {
+    return toPlainText(parseMarkdown(content.markdown));
+  }
+  if ("ast" in content) {
+    return toPlainText(content.ast);
+  }
+  return "";
+}
+var Plan = class {
+  $$typeof = POSTABLE_OBJECT;
+  kind = "plan";
+  _model;
+  _bound = null;
+  constructor(options) {
+    const title = contentToPlainText(options.initialMessage) || "Plan";
+    const firstTask = {
+      id: crypto.randomUUID(),
+      title,
+      status: "in_progress"
+    };
+    this._model = { title, tasks: [firstTask] };
+  }
+  isSupported(adapter) {
+    return !!adapter.postObject && !!adapter.editObject;
+  }
+  getPostData() {
+    return this._model;
+  }
+  getFallbackText() {
+    const lines = [];
+    lines.push(`\u{1F4CB} ${this._model.title || "Plan"}`);
+    for (const task of this._model.tasks) {
+      const statusIcons = {
+        complete: "\u2705",
+        in_progress: "\u{1F504}",
+        error: "\u274C"
+      };
+      const statusIcon = statusIcons[task.status] ?? "\u2B1C";
+      lines.push(`${statusIcon} ${task.title}`);
+    }
+    return lines.join("\n");
+  }
+  onPosted(context) {
+    this._bound = {
+      adapter: context.adapter,
+      fallback: !this.isSupported(context.adapter),
+      logger: context.logger,
+      messageId: context.messageId,
+      threadId: context.threadId,
+      updateChain: Promise.resolve()
+    };
+  }
+  get id() {
+    return this._bound?.messageId ?? "";
+  }
+  get threadId() {
+    return this._bound?.threadId ?? "";
+  }
+  get title() {
+    return this._model.title;
+  }
+  get tasks() {
+    return this._model.tasks.map((t) => ({
+      id: t.id,
+      title: t.title,
+      status: t.status
+    }));
+  }
+  get currentTask() {
+    let current;
+    for (let i = this._model.tasks.length - 1; i >= 0; i--) {
+      if (this._model.tasks[i].status === "in_progress") {
+        current = this._model.tasks[i];
+        break;
+      }
+    }
+    current ??= this._model.tasks.at(-1);
+    if (!current) {
+      return null;
+    }
+    return { id: current.id, title: current.title, status: current.status };
+  }
+  async addTask(options) {
+    if (!this.canMutate()) {
+      return null;
+    }
+    const title = contentToPlainText(options.title) || "Task";
+    for (const task of this._model.tasks) {
+      if (task.status === "in_progress") {
+        task.status = "complete";
+      }
+    }
+    const nextTask = {
+      id: crypto.randomUUID(),
+      title,
+      status: "in_progress",
+      details: options.children
+    };
+    this._model.tasks.push(nextTask);
+    this._model.title = title;
+    await this.enqueueEdit();
+    return { id: nextTask.id, title: nextTask.title, status: nextTask.status };
+  }
+  async updateTask(update) {
+    if (!this.canMutate()) {
+      return null;
+    }
+    let current;
+    for (let i = this._model.tasks.length - 1; i >= 0; i--) {
+      if (this._model.tasks[i].status === "in_progress") {
+        current = this._model.tasks[i];
+        break;
+      }
+    }
+    current ??= this._model.tasks.at(-1);
+    if (!current) {
+      return null;
+    }
+    if (update !== void 0) {
+      if (typeof update === "object" && update !== null && "output" in update) {
+        if (update.output !== void 0) {
+          current.output = update.output;
+        }
+        if (update.status) {
+          current.status = update.status;
+        }
+      } else {
+        current.output = update;
+      }
+    }
+    await this.enqueueEdit();
+    return { id: current.id, title: current.title, status: current.status };
+  }
+  async reset(options) {
+    if (!this.canMutate()) {
+      return null;
+    }
+    const title = contentToPlainText(options.initialMessage) || "Plan";
+    const firstTask = {
+      id: crypto.randomUUID(),
+      title,
+      status: "in_progress"
+    };
+    this._model = { title, tasks: [firstTask] };
+    await this.enqueueEdit();
+    return {
+      id: firstTask.id,
+      title: firstTask.title,
+      status: firstTask.status
+    };
+  }
+  async complete(options) {
+    if (!this.canMutate()) {
+      return;
+    }
+    for (const task of this._model.tasks) {
+      if (task.status === "in_progress") {
+        task.status = "complete";
+      }
+    }
+    this._model.title = contentToPlainText(options.completeMessage) || this._model.title;
+    await this.enqueueEdit();
+  }
+  canMutate() {
+    return !!this._bound;
+  }
+  enqueueEdit() {
+    if (!this._bound) {
+      return Promise.resolve();
+    }
+    const bound = this._bound;
+    const doEdit = async () => {
+      if (bound.fallback) {
+        await bound.adapter.editMessage(
+          bound.threadId,
+          bound.messageId,
+          this.getFallbackText()
+        );
+      } else {
+        const editObject = bound.adapter.editObject;
+        if (!editObject) {
+          return;
+        }
+        await editObject.call(
+          bound.adapter,
+          bound.threadId,
+          bound.messageId,
+          this.kind,
+          this._model
+        );
+      }
+    };
+    const chained = bound.updateChain.then(doEdit, doEdit);
+    bound.updateChain = chained.then(
+      () => void 0,
+      (err) => {
+        bound.logger?.warn("Failed to edit plan", err);
+      }
+    );
+    return chained;
+  }
+};
+
 // src/emoji.ts
 var emojiRegistry = /* @__PURE__ */ new Map();
 function getEmoji(name) {
@@ -3749,6 +4027,7 @@ export {
   MessageHistoryCache,
   Modal2 as Modal,
   NotImplementedError,
+  Plan,
   RadioSelect2 as RadioSelect,
   RateLimitError,
   Section2 as Section,
@@ -3787,6 +4066,7 @@ export {
   isListNode,
   isModalElement2 as isModalElement,
   isParagraphNode,
+  isPostableObject,
   isStrongNode,
   isTableCellNode,
   isTableNode,
@@ -3796,6 +4076,7 @@ export {
   markdownToPlainText,
   paragraph,
   parseMarkdown,
+  reviver,
   root,
   strikethrough,
   stringifyMarkdown,

package/docs/adapters.mdx

@@ -34,7 +34,7 @@ Ready to build your own? Follow the [building](/docs/contributing/building) guid
 | Tables | ✅ Block Kit | ✅ GFM | ⚠️ ASCII | ✅ GFM | ⚠️ ASCII | ✅ GFM | ✅ GFM | ❌ |
 | Fields | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⚠️ Template variables |
 | Images in cards | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ | ✅ |
-| Modals | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Modals | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
 
 ### Conversations
 
@@ -64,7 +64,7 @@ Ready to build your own? Follow the [building](/docs/contributing/building) guid
 ⚠️ indicates partial support — the feature works with limitations. See individual adapter pages for details.
 </Callout>
 
-## How [adapters](/adapters) work
+## How adapters work
 
 Each adapter implements a standard interface that the `Chat` class uses to route events and send messages. When a webhook arrives:
 
@@ -73,7 +73,7 @@ Each adapter implements a standard interface that the `Chat` class uses to route
 3. Routes to your handlers via the `Chat` class
 4. Converts outgoing messages from markdown/AST/cards to the platform's native format
 
-## Using multiple [adapters](/adapters)
+## Using multiple adapters
 
 Register multiple [adapters](/adapters) and your event handlers work across all of them:
 

package/docs/api/cards.mdx

@@ -95,6 +95,11 @@ Button({ id: "delete", label: "Delete", style: "danger", value: "item-123" })
       description: 'Optional payload sent with the action callback.',
       type: 'string',
     },
+    actionType: {
+      description: 'Hints to adapters like Teams that this button will open a modal via event.openModal().',
+      type: '"action" | "modal"',
+      default: '"action"',
+    },
   }}
 />
 

package/docs/api/chat.mdx

@@ -475,3 +475,13 @@ Get a `JSON.parse` reviver that deserializes `Thread` and `Message` objects from
 const data = JSON.parse(payload, bot.reviver());
 await data.thread.post("Hello from workflow!");
 ```
+
+There is also a standalone `reviver` export that works without a `Chat` instance. This is useful in Vercel Workflow functions where importing the full Chat instance (with its adapter dependencies) is not possible:
+
+```typescript
+import { reviver } from "chat";
+
+const data = JSON.parse(payload, reviver) as { thread: Thread; message: Message };
+```
+
+The standalone reviver uses lazy adapter resolution - the adapter is looked up from the Chat singleton when first accessed. Call `chat.registerSingleton()` before using thread methods like `post()` (typically inside a `"use step"` function).

package/docs/api/modals.mdx

@@ -4,7 +4,7 @@ description: Modal form components for collecting user input.
 type: reference
 ---
 
-Modals display form dialogs that collect structured user input. Currently supported on Slack.
+Modals display form dialogs that collect structured user input. Currently supported on Slack and Teams.
 
 ```typescript
 import { Modal, TextInput, Select, RadioSelect, SelectOption } from "chat";

package/docs/cards.mdx

@@ -109,6 +109,12 @@ The `id` maps to your `onAction` handler. Optional `value` passes extra data:
 <Button id="report" value="bug">Report Bug</Button>
 ```
 
+Set `actionType="modal"` to indicate the button opens a [modal](/docs/modals). The button still triggers your `onAction` handler, where you call `event.openModal()` — this prop tells adapters like Teams to wire up the button for dialog opening:
+
+```tsx title="lib/bot.tsx"
+<Button id="open-feedback" actionType="modal">Give Feedback</Button>
+```
+
 ### CardLink
 
 Inline hyperlink rendered as text. Unlike `LinkButton` (which must be inside `Actions`), `CardLink` can be placed directly in a card alongside other content.

package/docs/getting-started.mdx

@@ -14,7 +14,7 @@ Learn the core patterns for handling incoming events and posting messages back t
   <Card title="Posting Messages" description="Different ways to render and send messages with thread.post()." href="/docs/posting-messages" />
 </Cards>
 
-## [Adapters](/adapters)
+## Adapters
 
 Connect your bot to chat platforms and persist state across restarts.
 

package/docs/guides/durable-chat-sessions-nextjs.mdx

@@ -98,14 +98,14 @@ export type ChatTurnPayload = {
 
 ## Create the durable session workflow
 
-The workflow receives the serialized thread and first message, restores them with `bot.reviver()`, and then keeps waiting for more turns through the hook.
+The workflow receives the serialized thread and first message, restores them with `reviver`, and then keeps waiting for more turns through the hook.
 
 The important detail is that the workflow only orchestrates. Chat SDK side effects such as `post()`, `unsubscribe()`, and `setState()` stay inside step helpers:
 
 ```typescript title="workflows/durable-chat-session.ts" lineNumbers
-import { Message, type Thread } from "chat";
+import { Message, reviver, type Thread } from "chat";
 import { createHook, getWorkflowMetadata } from "workflow";
-import { bot, type ThreadState } from "@/lib/bot";
+import type { ThreadState } from "@/lib/bot";
 import type { ChatTurnPayload } from "@/workflows/chat-turn-hook";
 
 async function postAssistantMessage(
@@ -114,6 +114,7 @@ async function postAssistantMessage(
 ) {
   "use step";
 
+  const { bot } = await import("@/lib/bot");
   await bot.initialize();
   await thread.post(text);
 }
@@ -121,6 +122,7 @@ async function postAssistantMessage(
 async function closeSession(thread: Thread<ThreadState>) {
   "use step";
 
+  const { bot } = await import("@/lib/bot");
   await bot.initialize();
   await thread.post("Session closed.");
   await thread.unsubscribe();
@@ -154,7 +156,7 @@ export async function durableChatSession(payload: string) {
   "use workflow";
 
   const { workflowRunId } = getWorkflowMetadata();
-  const { thread, message } = JSON.parse(payload, bot.reviver()) as {
+  const { thread, message } = JSON.parse(payload, reviver) as {
     thread: Thread<ThreadState>;
     message: Message;
   };
@@ -186,11 +188,15 @@ export async function durableChatSession(payload: string) {
   The `using` keyword requires TypeScript 5.2+ with `"lib": ["esnext.disposable"]` in your `tsconfig.json`. If you are on an older version, call `hook.dispose()` manually when the session ends.
 </Callout>
 
+<Callout type="warn">
+  Do not import `bot` at the top level of a workflow file. Adapter packages depend on Node.js modules that are not available in the workflow sandbox. Use the standalone `reviver` for deserialization and import `bot` dynamically inside `"use step"` functions where Node.js modules are available.
+</Callout>
+
 This is the core integration:
 
 - `thread.toJSON()` and `message.toJSON()` cross the workflow boundary safely
-- `bot.reviver()` restores real Chat SDK objects inside the workflow
-- `bot.registerSingleton()` lets Workflow deserialize `Thread` objects again inside step functions
+- `reviver` restores real Chat SDK objects inside the workflow without pulling in adapter dependencies
+- `registerSingleton()` is called in `lib/bot.ts` and the singleton is available inside step functions when `bot` is dynamically imported
 - `createHook<ChatTurnPayload>({ token: workflowRunId })` makes the workflow run itself the session identifier
 - `runTurn()`, `postAssistantMessage()`, and `closeSession()` are steps, so adapter and state side effects stay outside the workflow sandbox
 
@@ -328,4 +334,4 @@ From here you can add:
 - [Handling Events](/docs/handling-events) — Mentions, subscribed messages, and routing behavior
 - [Streaming](/docs/streaming) — Stream AI SDK responses directly to chat platforms
 - [Thread API](/docs/api/thread) — `thread.toJSON()`, `thread.setState()`, and other thread primitives
-- [Chat API](/docs/api/chat) — `bot.reviver()`, initialization, and webhook access
+- [Chat API](/docs/api/chat) — `reviver`, initialization, and webhook access

package/docs/guides/slack-nextjs.mdx

@@ -87,6 +87,8 @@ After creating the app:
 1. Go to **OAuth & Permissions**, click **Install to Workspace**, and copy the **Bot User OAuth Token** (`xoxb-...`) — you'll need this as `SLACK_BOT_TOKEN`
 2. Go to **Basic Information** → **App Credentials** and copy the **Signing Secret** — you'll need this as `SLACK_SIGNING_SECRET`
 
+If you're distributing the app across multiple workspaces via OAuth instead of installing it to one workspace, configure `clientId` and `clientSecret` on the Slack adapter and pass the same redirect URI used during the authorize step into `handleOAuthCallback(request, { redirectUri })` in your callback route.
+
 ## Configure environment variables
 
 Create a `.env.local` file in your project root:

package/docs/modals.mdx

@@ -6,7 +6,7 @@ prerequisites:
   - /docs/actions
 ---
 
-Modals open form dialogs in response to button clicks or [slash commands](/docs/slash-commands). They support text inputs, dropdowns, radio buttons, and server-side validation. Currently supported on Slack.
+Modals open form dialogs in response to button clicks or [slash commands](/docs/slash-commands). They support text inputs, dropdowns, radio buttons, and server-side validation. Currently supported on Slack and Teams.
 
 ## Open a modal
 

package/docs/state.mdx

@@ -8,7 +8,7 @@ prerequisites:
 
 State adapters handle persistent storage for thread subscriptions, distributed locks (to prevent duplicate processing), and caching. You must provide a state adapter when creating a `Chat` instance. Browse all available state adapters on the [Adapters](/adapters) page.
 
-## What state [adapters](/adapters) manage
+## What state adapters manage
 
 ### Thread subscriptions
 

package/docs/usage.mdx

@@ -39,7 +39,7 @@ bot.onNewMention(async (thread) => {
 
 Each adapter factory auto-detects credentials from environment variables (`SLACK_BOT_TOKEN`, `SLACK_SIGNING_SECRET`, `REDIS_URL`, etc.), so you can get started with zero config. Pass explicit values to override.
 
-## Multiple [adapters](/adapters)
+## Multiple adapters
 
 Register multiple [adapters](/adapters) to deploy your bot across platforms simultaneously:
 
@@ -76,7 +76,7 @@ Your event handlers work identically across all registered adapters — the SDK
 | `fallbackStreamingPlaceholderText` | `string \| null` | `"..."` | Placeholder text while streaming starts. Set to `null` to skip |
 | `onLockConflict` | `'drop' \| 'force' \| (threadId, message) => 'drop' \| 'force'` | `"drop"` | Behavior when a thread lock is already held. `'force'` releases the existing lock and re-acquires it, enabling interrupt/steerability for long-running handlers |
 
-## Accessing [adapters](/adapters)
+## Accessing adapters
 
 Use `getAdapter` to access platform-specific APIs when you need functionality beyond the unified interface:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chat",
-  "version": "4.24.0",
+  "version": "4.26.0",
   "description": "Unified chat abstraction for Slack, Teams, Google Chat, and Discord",
   "type": "module",
   "main": "./dist/index.js",

package/docs/adapters/whatsapp.mdx

@@ -1,222 +0,0 @@
----
-title: WhatsApp
-description: Configure the WhatsApp adapter for the WhatsApp Business Cloud API.
-type: integration
-prerequisites:
-  - /docs/getting-started
----
-
-## Installation
-
-```sh title="Terminal"
-pnpm add @chat-adapter/whatsapp
-```
-
-## Usage
-
-The adapter auto-detects `WHATSAPP_ACCESS_TOKEN`, `WHATSAPP_APP_SECRET`, `WHATSAPP_PHONE_NUMBER_ID`, and `WHATSAPP_VERIFY_TOKEN` from environment variables:
-
-```typescript title="lib/bot.ts" lineNumbers
-import { Chat } from "chat";
-import { createWhatsAppAdapter } from "@chat-adapter/whatsapp";
-
-const bot = new Chat({
-  userName: "mybot",
-  adapters: {
-    whatsapp: createWhatsAppAdapter(),
-  },
-});
-
-bot.onNewMention(async (thread, message) => {
-  await thread.post(`You said: ${message.text}`);
-});
-```
-
-Since all WhatsApp conversations are 1:1 DMs, every incoming message is treated as a mention.
-
-## Webhook route
-
-WhatsApp uses two webhook mechanisms:
-
-1. **Verification handshake** (GET) — Meta sends a `hub.verify_token` challenge that must match your `WHATSAPP_VERIFY_TOKEN`.
-2. **Event delivery** (POST) — incoming messages, reactions, and interactive responses, verified via `X-Hub-Signature-256`.
-
-Both are handled by the same `handleWebhook` method:
-
-```typescript title="app/api/webhooks/whatsapp/route.ts" lineNumbers
-import { bot } from "@/lib/bot";
-
-export async function GET(request: Request): Promise<Response> {
-  return bot.webhooks.whatsapp(request);
-}
-
-export async function POST(request: Request): Promise<Response> {
-  return bot.webhooks.whatsapp(request);
-}
-```
-
-## Meta app setup
-
-### 1. Create a Meta app
-
-1. Go to [developers.facebook.com/apps](https://developers.facebook.com/apps)
-2. Click **Create App** and select **Business** type
-3. Give it a name and click **Create App**
-
-### 2. Add WhatsApp product
-
-1. In the app dashboard, find **WhatsApp** and click **Set Up**
-2. This creates a test phone number and sandbox environment
-
-### 3. Get credentials
-
-From the app dashboard:
-
-| Credential | Where to find it |
-|---|---|
-| **Access Token** | WhatsApp > API Setup > Temporary access token (or create a System User token for production) |
-| **Phone Number ID** | WhatsApp > API Setup > Phone number ID |
-| **App Secret** | Settings > Basic > App Secret |
-| **Verify Token** | You define this — any secret string you choose |
-
-### 4. Configure webhooks
-
-1. Go to **WhatsApp** > **Configuration** in your app dashboard
-2. Click **Edit** next to Webhook URL
-3. Set **Callback URL** to `https://your-domain.com/api/webhooks/whatsapp`
-4. Set **Verify token** to the same value as your `WHATSAPP_VERIFY_TOKEN`
-5. Click **Verify and Save**
-6. Subscribe to the **messages** webhook field
-
-### 5. Production access
-
-For production use:
-
-1. Add a real phone number under **WhatsApp** > **API Setup**
-2. Create a **System User** in Meta Business Suite for a permanent access token
-3. Complete Meta's **App Review** process for the `whatsapp_business_messaging` permission
-
-## Interactive messages
-
-Card elements are automatically converted to WhatsApp interactive messages:
-
-- **3 or fewer buttons** — rendered as WhatsApp reply buttons (title max 20 characters)
-- **More than 3 buttons** — falls back to formatted text
-
-```typescript title="lib/bot.ts" lineNumbers
-import { Card, Actions, Button, Body, BodyText } from "chat";
-
-bot.onNewMention(async (thread) => {
-  await thread.post(
-    <Card>
-      <Body>
-        <BodyText>How can I help?</BodyText>
-      </Body>
-      <Actions>
-        <Button id="help" value="help">Get Help</Button>
-        <Button id="status" value="status">Check Status</Button>
-      </Actions>
-    </Card>
-  );
-});
-```
-
-## Media attachments
-
-Incoming media messages (images, documents, audio, video, voice, stickers) are exposed as attachments with a lazy `fetchData()` function. Media is downloaded in two steps via the Graph API — first fetching the media URL, then downloading the binary data.
-
-```typescript title="lib/bot.ts" lineNumbers
-bot.onNewMention(async (thread, message) => {
-  for (const attachment of message.attachments) {
-    if (attachment.fetchData) {
-      const data = await attachment.fetchData();
-      // Process the media buffer...
-    }
-  }
-});
-```
-
-## 24-hour messaging window
-
-WhatsApp enforces a [24-hour customer service window](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-messages#customer-service-windows). You can only send free-form messages to a user within 24 hours of their last message. After that, you must use approved **message templates**.
-
-## Configuration
-
-All options are auto-detected from environment variables when not provided.
-
-| Option | Required | Description |
-|--------|----------|-------------|
-| `accessToken` | No* | Meta access token. Auto-detected from `WHATSAPP_ACCESS_TOKEN` |
-| `appSecret` | No* | App secret for webhook signature verification. Auto-detected from `WHATSAPP_APP_SECRET` |
-| `phoneNumberId` | No* | Bot's phone number ID. Auto-detected from `WHATSAPP_PHONE_NUMBER_ID` |
-| `verifyToken` | No* | Secret for webhook verification handshake. Auto-detected from `WHATSAPP_VERIFY_TOKEN` |
-| `apiVersion` | No | Graph API version (defaults to `v21.0`) |
-| `userName` | No | Bot username. Auto-detected from `WHATSAPP_BOT_USERNAME` or defaults to `whatsapp-bot` |
-| `logger` | No | Logger instance (defaults to `ConsoleLogger("info")`) |
-
-*All four credentials are required — either via config or environment variables.
-
-## Environment variables
-
-```bash title=".env.local"
-WHATSAPP_ACCESS_TOKEN=EAAx...         # Meta access token
-WHATSAPP_APP_SECRET=abc123...         # App secret for signature verification
-WHATSAPP_PHONE_NUMBER_ID=1234567890   # Phone number ID from Meta dashboard
-WHATSAPP_VERIFY_TOKEN=my-secret       # Your chosen webhook verify token
-```
-
-## Features
-
-| Feature | Supported |
-|---------|-----------|
-| Mentions | N/A (all messages are DMs) |
-| Reactions (add/remove) | Yes |
-| Cards | Interactive messages (max 3 buttons) / text fallback |
-| Modals | No |
-| Streaming | No |
-| DMs | Yes (all conversations) |
-| Ephemeral messages | No |
-| File uploads | Receive only |
-| Typing indicator | Yes |
-| Message history | No |
-| Edit message | No (throws) |
-| Delete message | No (throws) |
-
-## Thread ID format
-
-```
-whatsapp:{phoneNumberId}:{userWaId}
-```
-
-Example: `whatsapp:1234567890:15551234567`
-
-## Notes
-
-- All WhatsApp conversations are 1:1 DMs between the business phone number and the user, so every message sets `isMention: true`.
-- `editMessage()` and `deleteMessage()` throw errors — WhatsApp does not support these operations.
-- `fetchMessages()` returns empty results — WhatsApp does not provide a message history API.
-- Messages exceeding 4096 characters are automatically split at paragraph or line boundaries.
-- Webhook signatures are verified using HMAC-SHA256 with `timingSafeEqual` for timing-attack resistance.
-
-## Troubleshooting
-
-### Webhook verification failing
-
-- Verify `WHATSAPP_VERIFY_TOKEN` matches what you set in the Meta dashboard
-- Ensure both GET and POST routes are configured for the webhook URL
-
-### "Invalid signature" error
-
-- Check that `WHATSAPP_APP_SECRET` is correct (find it under Settings > Basic in your Meta app)
-- Ensure the raw request body is not parsed before verification
-
-### Bot not responding
-
-- Confirm the **messages** webhook field is subscribed in Meta dashboard
-- Check that you're within the 24-hour messaging window (or using template messages)
-- Verify the phone number ID matches your configured `WHATSAPP_PHONE_NUMBER_ID`
-
-### Media downloads failing
-
-- Ensure your access token has the required permissions
-- Check that the media hasn't expired (WhatsApp media URLs are temporary)