Skip to main content

Constructor

Parameters

ChatConfig<TAdapters>
required

Returns

Chat

Properties

required
Unified History API. Sub-APIs:
  • history.user — cross-platform per-user transcript store (throws if not configured)
  • history.thread — per-thread message listing
  • history.channel — channel-level messages and thread listings
Cross-platform per-user transcript store. Deprecated alias for ChatInstance.history.user — throws on access when user history was not configured (history.user or legacy transcripts + identity).
Deprecated: Use ChatInstance.history.user instead.
Webhooks<TAdapters>
required
Type-safe webhook handlers keyed by adapter name.

Methods

abortTurn()

Abort active work for a conversation, including work running in another process that shares the configured state adapter.

Parameters

string
required

Returns

Promise<void>

channel()

Get a Channel by its channel ID. The adapter is automatically inferred from the channel ID prefix.

Parameters

string
required
Channel ID (e.g., “slack:C123ABC”, “gchat:spaces/ABC123”)

Returns

Channel A Channel that can be used to list threads, post messages, iterate messages, etc.

getAdapter()

Get an adapter by name with type safety.

Parameters

K
required

Returns

TAdapters[K]

getLogger()

Get the configured logger, optionally with a child prefix

Parameters

string

Returns

Logger

getSingleton()

Get the registered singleton Chat instance. Throws if no singleton has been registered.

Returns

Chat

getState()

Returns

StateAdapter

getUser()

Look up user information by user ID. The adapter is automatically inferred from the user ID format. Returns user details including email (where available — requires appropriate scopes on some platforms, e.g. users:read.email on Slack).

Parameters

string | Author
required
Type: AuthorPlatform-specific user ID string, or an Author object

Returns

UserInfo User info, or null if user not found

getUserName()

Returns

string

handleIncomingMessage()

Handle an incoming message from an adapter. This is called by adapters when they receive a webhook. The Chat class handles common concerns centrally:
  • Deduplication: Same message may arrive multiple times (e.g., Slack sends both message and app_mention events, GChat sends direct webhook + Pub/Sub)
  • Bot filtering: Messages from the bot itself are skipped
  • Concurrency: Controlled by concurrency config (drop, queue, debounce, burst, concurrent)

Parameters

required
string
required
required

Returns

Promise<void>

hasSingleton()

Check if a singleton has been registered.

Returns

boolean

initialize()

Initialize the chat instance and all adapters. This is called automatically when handling webhooks, but can be called manually for non-webhook use cases (e.g., Gateway listeners).

Returns

Promise<void>

onAction()

Register a handler for action events (button clicks in cards).

Parameters

The handler (if action ID filter is provided)
Register a handler for action events (button clicks in cards).

Parameters

string | string[]
required
The handler (if action ID filter is provided)

onAgentSessionStopped()

Parameters

onAgentSessionTitleChanged()

Parameters

onAppContextChanged()

Parameters

onAppHomeOpened()

Parameters

onAssistantContextChanged()

Parameters

onAssistantThreadStarted()

Parameters

onDirectMessage()

Register a handler for direct messages. Called for every message received in a DM thread when at least one direct message handler is registered. Direct message handlers run before onSubscribedMessage, onNewMention, and pattern handlers. If no onDirectMessage handlers are registered, DMs continue through normal routing. Unsubscribed DMs fall through to onNewMention for backward compatibility.

Parameters

DirectMessageHandler<TState>
required
Type: DirectMessageHandlerHandler called for DM messages

onInstalled()

Handle bot installation, including upgrades that add the bot (currently Teams only).

Parameters

onMemberJoinedChannel()

Parameters

onMessageDeleted()

Register a handler for message delete events. Delete events usually do not include the deleted message body. Handlers get the normalized platform IDs needed to update external storage.

Parameters

onMessageUpdated()

Register a handler for message edit/update events. These lifecycle events are dispatched directly by adapters and do not route through onNewMessage, onNewMention, or onSubscribedMessage.

Parameters

MessageUpdatedHandler<TState>
required

onModalClose()

Register a handler for modal close/cancel events. Only fires when the modal was created with notifyOnClose: true.

Parameters

The handler (if callback ID filter is provided)
Register a handler for modal close/cancel events. Only fires when the modal was created with notifyOnClose: true.

Parameters

string | string[]
required
The handler (if callback ID filter is provided)

onModalSubmit()

Register a handler for modal form submissions.

Parameters

The handler (if callback ID filter is provided)
Register a handler for modal form submissions.

Parameters

string | string[]
required
The handler (if callback ID filter is provided)

onNewMention()

Register a handler for new @-mentions of the bot. Important: This handler is ONLY called for mentions in unsubscribed threads. Once a thread is subscribed (via thread.subscribe()), subsequent messages including @-mentions go to onSubscribedMessage handlers instead. To detect mentions in subscribed threads, check message.isMention:

Parameters

MentionHandler<TState>
required

onNewMessage()

Register a handler for messages matching a regex pattern.

Parameters

RegExp
required
Regular expression to match against message text
MessageHandler<TState>
required
Type: MessageHandlerHandler called when pattern matches

onOptionsLoad()

Register a handler for loading dynamic options for external selects. Specific action IDs run before catch-all handlers.

Parameters

Register a handler for loading dynamic options for external selects. Specific action IDs run before catch-all handlers.

Parameters

string | string[]
required

onReaction()

Register a handler for reaction events.

Parameters

The handler (if emoji filter is provided)
Register a handler for reaction events.

Parameters

EmojiFilter[]
required
The handler (if emoji filter is provided)

onSlashCommand()

Register a handler for slash command events. Slash commands are triggered when a user types /command in the message composer. Use event.channel.post() or event.channel.postEphemeral() to respond.

Parameters

SlashCommandHandler<TState>
required
Type: SlashCommandHandlerThe handler (if command filter is provided)
Register a handler for slash command events. Slash commands are triggered when a user types /command in the message composer. Use event.channel.post() or event.channel.postEphemeral() to respond.

Parameters

string | string[]
required
SlashCommandHandler<TState>
required
Type: SlashCommandHandlerThe handler (if command filter is provided)

onSubscribedMessage()

Register a handler for messages in subscribed threads. Called for all messages in threads that have been subscribed via thread.subscribe(). This includes:
  • Follow-up messages from users
  • Messages that @-mention the bot (check message.isMention)
Does NOT fire for:
  • The message that triggered the subscription (e.g., the initial @mention)
  • Messages sent by the bot itself

Parameters

SubscribedMessageHandler<TState>
required

onUninstalled()

Handle bot removal, including upgrades that remove the bot (currently Teams only).

Parameters

openDM()

Open a direct message conversation with a user. Accepts either a user ID string or an Author object (from message.author or event.user). The adapter is automatically inferred from the userId format:
  • Slack: U... (e.g., “U00FAKEUSER1”)
  • Teams: 29:... (e.g., “29:198PbJuw…”)
  • Google Chat: users/... (e.g., “users/100000000000000000001”)
  • Discord: numeric snowflake (e.g., “1033044521375764530”)

Parameters

string | Author
required
Type: AuthorPlatform-specific user ID string, or an Author object

Returns

Thread A Thread that can be used to post messages

processAction()

Process an incoming action event (button click) from an adapter. Handles waitUntil registration and error catching internally.

Parameters

Omit<ActionEvent<unknown>, "thread" | "openModal"> & { adapter: Adapter }
required
WebhookOptions | undefined
required

Returns

Promise<void>

processAgentSessionStopped()

Parameters

processAgentSessionTitleChanged()

Parameters

processAppContextChanged()

Parameters

processAppHomeOpened()

Parameters

processAssistantContextChanged()

Parameters

processAssistantThreadStarted()

Parameters

processInstalled()

Optional so custom ChatInstance implementations predating it keep compiling.

Parameters

processMemberJoinedChannel()

Parameters

processMessage()

Process an incoming message from an adapter. Handles waitUntil registration and error catching internally. Adapters should call this instead of handleIncomingMessage directly.

Parameters

required
string
required
Message<unknown> | () => Promise<Message<unknown>>
required

Returns

Promise<void>

processMessageDeleted()

Process an incoming message delete from an adapter. Handles waitUntil registration and error catching internally.

Parameters

Omit<MessageDeletedEvent<unknown>, "platform" | "adapter"> & { adapter: Adapter…
required

Returns

Promise<void>

processMessageUpdated()

Process an incoming message update from an adapter. Handles waitUntil registration and error catching internally.

Parameters

{ adapter: Adapter; message: Message<unknown> | () => Promise<Message<unknown>>…
required

Returns

Promise<void>

processModalClose()

Process a modal close event from an adapter.

Parameters

Omit<ModalCloseEvent, "relatedThread" | "relatedMessage" | "relatedChannel">
required
Type: ModalCloseEventThe modal close event (without relatedThread/relatedMessage/relatedChannel)
string
Context ID for retrieving stored thread/message/channel context
Webhook options

processModalSubmit()

Process a modal submit event from an adapter.

Parameters

Omit<ModalSubmitEvent, "relatedThread" | "relatedMessage" | "relatedChannel">
required
Type: ModalSubmitEventThe modal submit event (without relatedThread/relatedMessage/relatedChannel)
string
Context ID for retrieving stored thread/message/channel context
Webhook options

Returns

ModalResponse

processOptionsLoad()

Process an interactive options load event from an adapter. Returns normalized select options for the adapter to render.

Parameters

Returns

OptionsLoadResult

processReaction()

Process an incoming reaction event from an adapter. Handles waitUntil registration and error catching internally.

Parameters

Omit<ReactionEvent<unknown>, "thread" | "adapter"> & { adapter: Adapter<unknown…
required

Returns

Promise<void>

processSlashCommand()

Process an incoming slash command from an adapter. Handles waitUntil registration and error catching internally.

Parameters

Omit<SlashCommandEvent<Record<string, unknown>>, "channel" | "openModal"> & { a…
required
WebhookOptions | undefined
required

Returns

Promise<void>

processUninstalled()

Optional so custom ChatInstance implementations predating it keep compiling.

Parameters

registerSingleton()

Register this Chat instance as the global singleton. Required for Thread deserialization via @workflow/serde.

Returns

this

reviver()

Get a JSON.parse reviver function that automatically deserializes chat:Thread and chat:Message objects. Use this when parsing JSON that contains serialized Thread or Message objects (e.g., from workflow engine payloads).

Returns

(key: string, value: unknown) => unknown A reviver function for JSON.parse

shutdown()

Gracefully shut down the chat instance.

Returns

Promise<void>

thread()

Get a Thread handle by its thread ID. The adapter is automatically inferred from the thread ID prefix.

Parameters

string
required
Full thread ID (e.g., “slack:C123ABC:1234567890.123456”)

Returns

Thread A Thread that can be used to post messages, subscribe, etc.