Chat SDK Documentation

To build with Chat SDK, you need to master four core patterns:

1. Creating a Chat Instance: Initialize the Chat class by providing adapters, state management, and configuration options.
2. Managing Threads, Messages, and Channels: Understand how to work with these abstractions to ensure consistent behavior across different chat platforms.
3. Handling Events: Register specific handlers to respond to user actions such as mentions, messages, reactions, and other platform-specific events.
4. Posting Messages: Use thread.post() to render and send various message types back to users.

The telegram-chat example serves as a smoke-test harness for the @chat-adapter/telegram package, demonstrating several end-to-end SDK capabilities through an interactive menu:

• Text & Markdown: Demonstrates MarkdownV2 rendering and streaming edits.
• Cards & Actions: Demonstrates interactive cards with inline-keyboard actions, callback-data handling, and link buttons.
• Media & Reactions: Demonstrates file uploads (e.g., PNG and PDF) and on-demand reactions.

Note that this specific example runs in polling mode (no webhooks or public URL required) and is stateless (no persistence or thread subscription).

The chat/ai subpath contains the following core utilities:

• createChatTools: Generates standalone tool factories that allow an agent to perform actions (post messages, send DMs, react, edit, delete, manage subscriptions) across all registered adapters. It supports built-in approval gates and presets.
• toAiMessages: Converts Chat SDK Message[] into the { role, content }[] shape expected by AI SDK calls. It handles role mapping, attachments, links, sorting, and optional per-message transforms.
• Types: Exported types for agent message shapes, tool option contracts, presets, approval configurations, and the binding type that connects tools to a Chat instance.

When requesting a token, you must specify a subject which determines how the token acts:

• app: The application itself uses the connector's installation. Best for bot accounts or tenant-wide admin actions. These skip the user-consent flow.
• user: Acts on behalf of a specific signed-in user. The user must authorize the connector once before tokens can be minted.
• jwt-bearer: Used for exchanging an external identity for a provider token (federated identity).

Note: In the SDK, subject is required. The Vercel CLI requests a user token by default; use --subject app for an app token.

The adapter implements the full Chat SDK StateAdapter interface using Durable Object SQLite. It persists:

• Subscriptions: For thread.subscribe() and thread.unsubscribe().
• Locks: For per-thread or per-channel concurrency.
• Queues: Pending message queues for queue, debounce, and burst strategies.
• KV Cache: Generic key-value cache entries (with optional TTL).
• Lists: Append-only lists with max-length trimming and TTL refresh.

This enables features like message deduplication, persistent thread history, and cross-platform transcripts.

In the Dial adapter, a Chat SDK thread is represented as a unique pair of phone numbers (your Dial-owned number and the peer's number). The thread ID follows this format:

dial:{yourDialNumber}:{peerNumber}

Because every distinct pair is a distinct thread, Chat SDK's per-thread state (such as subscriptions, locks, and conversation memory) is automatically scoped to each individual conversation, preventing data leakage between concurrent users.

Adapters in the Chat SDK are categorized into two types: platform (connecting to messaging services) and state (storing SDK state).

Each adapter in the catalog provides an env spec that defines how to configure it:

• required: Variables needed regardless of the authentication mode.
• credentialModes: Groups of mutually exclusive authentication methods (e.g., choosing between a Bot Token or OAuth credentials).
• optional: Tuning variables that can be omitted.
• config: Constructor options that cannot be set via environment variables.

Capabilities

• Mentions and DMs
• Rich text (bold, italic, code, links) via Markdown
• Adaptive Cards (buttons, selects, radio selects, fields, sections)
• Modals (form cards with submit/close actions)
• File uploads (single file per message)
• Thread support via parent IDs
• Webhook signature verification (HMAC-SHA1)

Limitations

• Reactions: addReaction and removeReaction throw NotImplementedError because reactions are not supported by Webex bot tokens.
• Typing indicators: Not available in the Webex Messaging API.
• File uploads: Only one file upload per message is supported.
• Combinations: Cards and file uploads cannot be combined in the same message.

When interacting with threads via the Messenger adapter, the thread ID follows the pattern messenger:{recipientId}.

Example: messenger:27161130920158013

When building with the Photon iMessage adapter, be aware of the following constraints:

• Group Chat Addressing: Group chats are session-bound. You cannot send a 'cold' message to a group ID that hasn't been received via the gateway/stream in the current session. DMs, however, can be sent 'cold'.
• No History/Thread Info: fetchMessages, fetchThread, fetchChannelMessages, and other fetch methods are not supported.
• No Reaction Removal: removeReaction is not supported.
• Remote-only Features: Reactions, typing indicators, editing, and modals require Cloud or Self-host mode. Local mode only supports sending and receiving.
• Plain Text Only: iMessage does not support markdown or structured cards. Outbound markdown is stripped to plain text, and inbound text is parsed into the Chat SDK AST.
• Platform Constraints: Local mode requires macOS.