Chat

The Chat class coordinates adapters, state, and event handlers. Create one instance and register handlers for different event types.

import { Chat } from "chat";

Constructor

const bot = new Chat(config);

These options are deprecated but still read, so existing bots keep working:

Event handlers

onNewMention

Fires when the bot is @-mentioned in a thread it has not subscribed to. Most bots start new conversations from this handler.

bot.onNewMention(async (thread, message) => {
  await thread.subscribe();
  await thread.post("Hello!");
});

onDirectMessage

Fires for every direct message when registered. Direct message handlers run before onSubscribedMessage, onNewMention, and pattern handlers. If no direct message handler is registered, unsubscribed DMs fall through to onNewMention for backward compatibility.

bot.onDirectMessage(async (thread, message, channel) => {
  await thread.post(`Got your DM in ${channel.id}: ${message.text}`);
});

onSubscribedMessage

Fires for every new message in a subscribed non-DM thread. Once subscribed, messages (including @-mentions) route here instead of onNewMention. DM threads route to onDirectMessage first when a direct message handler is registered.

bot.onSubscribedMessage(async (thread, message) => {
  if (message.isMention) {
    // User @-mentioned us in a thread we're already watching
  }
  await thread.post(`Got: ${message.text}`);
});

onNewMessage

Fires for messages in unsubscribed threads that aren't DMs and don't mention the bot. Pass a regex to filter by message text, or pass only a handler to receive every such message, including attachment-only messages with empty text. All onNewMessage handlers run one after another in registration order.

bot.onNewMessage(/^!help/i, async (thread, message) => {
  await thread.post("Available commands: !help, !status");
});

bot.onNewMessage(async (thread, message) => {
  await thread.post(`Received: ${message.text || "an attachment"}`);
});

The handler-only form doesn't receive DMs or mentions, even when no onDirectMessage or onNewMention handler is registered. Passing arguments in the wrong order, a pattern that isn't a RegExp, or no handler throws a ChatError when the handler is registered.

onReaction

Fires when a user adds or removes an emoji reaction.

import { emoji } from "chat";

// Filter to specific emoji
bot.onReaction([emoji.thumbs_up, emoji.heart], async (event) => {
  if (event.added) {
    await event.thread.post(`Thanks for the ${event.emoji}!`);
  }
});

// Handle all reactions
bot.onReaction(async (event) => { /* ... */ });

onAction

Fires when a user clicks a button or selects an option in a card.

// Single action
bot.onAction("approve", async (event) => {
  if (event.thread) {
    await event.thread.post("Approved!");
  }
});

// Multiple actions
bot.onAction(["approve", "reject"], async (event) => { /* ... */ });

// All actions
bot.onAction(async (event) => { /* ... */ });

onModalSubmit

Fires when a user submits a modal form.

bot.onModalSubmit("feedback", async (event) => {
  const comment = event.values.comment;
  if (event.relatedThread) {
    await event.relatedThread.post(`Feedback: ${comment}`);
  }
});

Returns ModalResponse | undefined to control the modal after submission:

onOptionsLoad

Fires when an ExternalSelect requests options dynamically. Slack only. The handler is keyed on the select's id and must return options within Slack's 3-second budget. The adapter caps the loader at about 2.5 seconds and returns an empty result on timeout.

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, such as "Recent" and "All". Slack allows at most 100 groups and 100 options per group.

onSlashCommand

Fires when a user invokes a /command in the message composer. Supported on Slack and Discord.

// Specific command
bot.onSlashCommand("/status", async (event) => {
  await event.channel.post("All systems operational!");
});

// Multiple commands
bot.onSlashCommand(["/help", "/info"], async (event) => {
  await event.channel.post(`You invoked ${event.command}`);
});

// Catch-all
bot.onSlashCommand(async (event) => {
  console.log(`${event.command} ${event.text}`);
});

onModalClose

Fires when a user closes a modal. Requires notifyOnClose: true on the modal.

bot.onModalClose("feedback", async (event) => { /* ... */ });

onAssistantThreadStarted

Fires when a user opens a new assistant thread through the Slack Assistants API. Use it to set suggested prompts, show a status indicator, or send an initial greeting.

bot.onAssistantThreadStarted(async (event) => {
  const slack = bot.getAdapter("slack") as SlackAdapter;
  await slack.setSuggestedPrompts(event.channelId, event.threadTs, [
    { title: "Get started", message: "What can you help me with?" },
  ]);
});

onAssistantContextChanged

Fires when a user navigates to a different channel while the Slack Assistants API panel is open. Use it to update suggested prompts or context for the new channel.

bot.onAssistantContextChanged(async (event) => {
  const slack = bot.getAdapter("slack") as SlackAdapter;
  await slack.setAssistantStatus(event.channelId, event.threadTs, "Updating context...");
});

The event shape is identical to onAssistantThreadStarted.

onAgentSessionStopped

Fires after a user clicks Slack's native agent-session stop button. Chat SDK aborts the active turn and moves the session out of processing before this handler runs.

bot.onAgentSessionStopped(async (event) => {
  await releaseExternalResources(event.threadId);
});

The event contains threadId, channelId, threadTs, streamingMessageTs, userId, and adapter. streamingMessageTs lists the streaming messages Slack stopped and can be empty when no stream was active.

onAgentSessionTitleChanged

Fires when a user renames a Slack agent session.

bot.onAgentSessionTitleChanged(async (event) => {
  await syncTitle(event.threadId, event.title);
});

The event contains title, previousTitle, threadId, channelId, threadTs, userId, and adapter. previousTitle is omitted when the session did not have a title before the change.

onAppHomeOpened

Fires when a user opens the bot's Home tab in Slack. Use it to publish a dynamic Home tab view.

bot.onAppHomeOpened(async (event) => {
  const slack = bot.getAdapter("slack") as SlackAdapter;
  await slack.publishHomeView(event.userId, {
    type: "home",
    blocks: [{ type: "section", text: { type: "mrkdwn", text: "Welcome!" } }],
  });
});

onInstalled

Fires when the bot is installed, including when an app upgrade adds the bot to the manifest. Routine upgrades do not emit this event. Only the Teams adapter emits it, for personal, group chat, and team installs.

bot.onInstalled(async (event) => {
  if (!event.channelId) return;
  await bot.channel(event.channelId).post("Thanks for installing!");
});

onUninstalled

Fires when the bot is removed, including when an app upgrade removes it from the manifest. Same event shape as onInstalled, with action set to "remove" or "remove-upgrade". Clean up durable records for both actions, and do not post to the conversation after removal.

bot.onUninstalled(async (event) => {
  if (event.adapter.name === "teams") {
    await removeTeamsInstallation(event);
  } else if (event.adapter.name === "slack") {
    await removeSlackInstallation(event.conversationId);
  }
});

removeTeamsInstallation and removeSlackInstallation are application-owned. For Teams team installs, associate records with event.raw.channelData.team.id as well as conversationId, which can differ between installation and removal. See the Teams persistence example.

The Slack adapter emits onUninstalled, with action set to "remove", when a workspace or org uninstalls the app. conversationId is the Slack installation key: the team_id, or the enterprise_id for org-wide installs. tenantId is the Enterprise Grid enterprise_id when the event carries one. See Slack uninstalls.

Utility methods

abortTurn

Abort the active handler turn for a thread. Chat SDK signals work in this process immediately and publishes the cancellation through the configured state adapter for another serverless instance to observe.

await bot.abortTurn(thread.id);

Platform adapters normally invoke this for native cancellation events. Model and tool calls must receive thread.signal to stop their own upstream work.

webhooks

Typed webhook handlers keyed by adapter name. Call them from your HTTP route handler.

bot.webhooks.slack(request, { waitUntil });
bot.webhooks.teams(request, { waitUntil });

getAdapter

Get a typed adapter instance by name.

const slack = bot.getAdapter("slack");

Direct client access

Each adapter exposes its platform's typed native API client through a getter named after the SDK: .webClient on Slack, .linearClient on Linear, and .octokit on GitHub.

// Slack - full WebClient from @slack/web-api
const slack = bot.getAdapter("slack").webClient;
await slack.pins.add({ channel: "C123ABC", timestamp: "1234567890.123456" });

// Linear - full LinearClient from @linear/sdk
const linear = bot.getAdapter("linear").linearClient;
const issue = await linear.issue("ENG-123");
const project = await issue.project;

// GitHub - full Octokit from @octokit/rest
const github = bot.getAdapter("github").octokit;
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 or multi-workspace adapters (Slack, Linear, GitHub), it returns the client bound to the credentials for the current webhook request context.

openDM

Open a direct message thread with a user.

const dm = await bot.openDM("U123456");
await dm.post("Hello via DM!");

// Or with an Author object
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.

bot.getUser picks the adapter from the format of the user ID, so it only works for platforms whose IDs it can recognize: Slack (U... or W...), Microsoft Teams (29:...), Google Chat (users/...), Linear (UUID), and Discord, Telegram, and GitHub (numeric). For other adapters that implement getUser, such as X, Twilio, and Twitch, call the adapter directly with bot.getAdapter("x").getUser(userId).

const user = await bot.getUser("U123456");
console.log(user?.email);    // "alice@company.com"
console.log(user?.fullName); // "Alice Smith"

// Or with an Author object from a message handler. The adapter is still
// inferred from author.userId.
const user = await bot.getUser(message.author);

Fields that aren't available return undefined.

Numeric user IDs from Discord, Telegram, and GitHub are ambiguous when more than one of those adapters is registered. In that case bot.getUser throws a ChatError with code AMBIGUOUS_USER_ID, even when you pass an Author, because the adapter is inferred from the ID alone. Call the adapter directly instead, for example thread.adapter.getUser?.(message.author.userId) inside a handler or bot.getAdapter("telegram").getUser(userId) elsewhere.

bot.getUser throws a ChatError in three cases. Handle them if your bot runs on multiple platforms.

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. Use it to post to threads outside a webhook, such as from a cron job or an external trigger.

const thread = bot.thread("slack:C123ABC:1234567890.123456");
await thread.post("Hello from a cron job!");

channel

Get a Channel by its channel ID.

const channel = bot.channel("slack:C123ABC");

for await (const msg of channel.messages) {
  console.log(msg.text);
}

initialize / shutdown

Manage the lifecycle manually. Initialization happens automatically on the first webhook. Call initialize() yourself when the bot does work outside a webhook.

await bot.initialize();
// ... do work ...
await bot.shutdown();

During shutdown, the SDK calls the optional disconnect() method on each adapter before disconnecting the state adapter. Adapters use it to clean up platform connections, close WebSockets, or tear down subscriptions. If one adapter's disconnect() fails, the remaining adapters and the state adapter still disconnect.

reviver

Get a JSON.parse reviver that deserializes Thread and Message objects from workflow payloads.

const data = JSON.parse(payload, bot.reviver());
await data.thread.post("Hello from workflow!");

Threads and channels restored by bot.reviver() stay bound to that bot's adapters and state, and restored threads use that bot's streaming defaults, even if another Chat instance is registered later. When using multiple bots, parse each payload with the receiving bot's reviver. This does not isolate state keys if the bots share the same state store.

The binding is not serialized. If a restored object crosses a Workflow step boundary, automatic deserialization uses the registered singleton again. For multiple bots, pass the serialized data and explicitly restore it with the receiving bot's reviver inside the step.

There is also a workflow-safe serialization entrypoint that works without importing the Chat runtime. Use it in Vercel Workflow files so serializer registration does not load Node-only runtime dependencies:

import { Message, reviver, ThreadImpl } from "chat/serialization";

const data = JSON.parse(payload, reviver) as {
  thread: ThreadImpl;
  message: Message;
};

Message, ThreadImpl, and ChannelImpl retain their automatic Workflow serialization when imported from either chat or chat/serialization. The dedicated entrypoint guarantees their serializer module graph does not load the Node-only Chat conversation context.

The standalone reviver resolves adapters lazily, looking them up from the Chat singleton on first access. Call chat.registerSingleton() before using thread methods like post() (typically inside a "use step" function). Once a restored thread or channel resolves its runtime, it retains that Chat instance for its adapter, state, and streaming defaults, even if the singleton changes. Registering the correct bot before first use remains the caller's responsibility; use bot.reviver() when the owner must be explicit.

history

Namespaced access to the History API: cross-platform user history, per-thread reads and cache, and per-channel reads.

// User scope: cross-platform, keyed by identity resolver result
await bot.history.user.append(thread, message);
const entries = await bot.history.user.list({ userKey, limit: 20 });
await bot.history.user.delete({ userKey });

// Thread scope: adapter.fetchMessages with cache fallback
const { messages } = await bot.history.thread.list(thread.id, { limit: 20 });

// Channel scope: platform APIs
const { messages: channelMessages } = await bot.history.channel.listMessages(
  channel.id,
  { limit: 10 }
);
const { threads } = await bot.history.channel.listThreads(channel.id, {
  limit: 20,
});

See History API reference for full details and the History guide for setup and patterns.