Slack

This guide takes you from zero to a Slack bot you can @-mention in a channel, then adds an interactive button card. You write handlers in TypeScript, Copilot Runtime hosts the agent, and rich messages are JSX that the adapter renders to Block Kit (Slack's message-UI format). No public URL needed.

Prerequisites#

• Node.js 20+
• A Slack workspace where you can install apps
• An OpenAI API key (or Anthropic/Google — any model supported by Model Selection)

Getting started#

mkdir my-slack-bot && cd my-slack-bot
npm init -y && npm pkg set type=module

npm install @copilotkit/bot @copilotkit/bot-ui @copilotkit/bot-slack @copilotkit/runtime
npm install -D tsx typescript @types/node

pnpm add @copilotkit/bot @copilotkit/bot-ui @copilotkit/bot-slack @copilotkit/runtime
pnpm add -D tsx typescript @types/node

yarn add @copilotkit/bot @copilotkit/bot-ui @copilotkit/bot-slack @copilotkit/runtime
yarn add -D tsx typescript @types/node

{
  "compilerOptions": {
    "target": "es2022",
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true,
    "types": ["node"],
    "jsx": "react-jsx",
    "jsxImportSource": "@copilotkit/bot-ui"
  },
  "include": ["bot.tsx"]
}

import { createServer } from "node:http";
import { createBot } from "@copilotkit/bot";
import { slack, SanitizingHttpAgent } from "@copilotkit/bot-slack"; 
import { BuiltInAgent, CopilotRuntime } from "@copilotkit/runtime/v2";
import { createCopilotNodeListener } from "@copilotkit/runtime/v2/node";

const agentId = "assistant";
const runtimePort = Number(process.env.RUNTIME_PORT ?? 8200);
const runtimeUrl = `http://localhost:${runtimePort}/api/copilotkit`;

// Copilot Runtime: hosts the assistant agent.
const runtime = new CopilotRuntime({
  agents: {
    [agentId]: new BuiltInAgent({
      model: process.env.OPENAI_MODEL ?? "openai:gpt-5-mini",
      prompt: "You are a helpful Slack assistant. Keep replies short.",
    }),
  },
});
createServer(
  createCopilotNodeListener({
    runtime,
    basePath: "/api/copilotkit",
    cors: true,
  }),
).listen(runtimePort, () => {
  console.log(`Copilot Runtime listening at ${runtimeUrl}`);
});

// The bot: the Slack adapter + one handler.
const bot = createBot({
  adapters: [
    slack({
      botToken: process.env.SLACK_BOT_TOKEN!, // xoxb-…
      appToken: process.env.SLACK_APP_TOKEN!, // xapp-…
    }),
  ],
  // One agent connection per Slack conversation.
  agent: (threadId) => {
    const agent = new SanitizingHttpAgent({
      url: `${runtimeUrl}/agent/${encodeURIComponent(agentId)}/run`,
    });
    agent.threadId = threadId;
    return agent;
  },
});

bot.onMention(async ({ thread }) => {
  await thread.runAgent(); 
});

await bot.start();
console.log("⚡ Bot connected over Socket Mode");

export SLACK_BOT_TOKEN=xoxb-…
export SLACK_APP_TOKEN=xapp-…
export OPENAI_API_KEY=sk-…

npx tsx bot.tsx

/invite @YourBot
@YourBot what can you do?

import { Message, Header, Section, Actions, Button } from "@copilotkit/bot-ui"; 

bot.onMention(async ({ thread, message }) => {
  if (message.text.toLowerCase().includes("deploy")) {
    await thread.post(
      <Message accent="#27AE60">
        <Header>Deploy v1.4.2</Header>
        <Section>Ship **v1.4.2** to production?</Section>
        <Actions>
          <Button
            style="primary"
            onClick={async ({ thread }) => {
              await thread.post("🚀 Shipping!");
            }}
          >
            Ship it
          </Button>
          <Button
            onClick={async ({ thread }) => {
              await thread.post("Standing down.");
            }}
          >
            Cancel
          </Button>
        </Actions>
      </Message>,
    );
    return;
  }
  await thread.runAgent();
});

bot.onCommand("agent", async ({ thread, text }) => {
  await thread.runAgent({ prompt: text }); 
});

Split the bot and the agent#

The bot and its agent talk over AG-UI through Copilot Runtime, so they don't have to share a process. The production shape is two services joined by a URL: move the CopilotRuntime block into its own process (or use a deployed Copilot Runtime) and point the bot at it via env, exactly how the full on-call triage example is wired:

const runtimeUrl = process.env.COPILOT_RUNTIME_URL!;

agent: (threadId) => {
  const agent = new SanitizingHttpAgent({
    url: `${runtimeUrl}/agent/assistant/run`, 
  });
  agent.threadId = threadId;
  return agent;
},

SanitizingHttpAgent is an HttpAgent that tolerates the event streams real agent backends emit — use it over the stock HttpAgent when connecting a Slack bot to Copilot Runtime.

Platform capability matrix#

The three CopilotKit bot adapters — Slack, Discord, and Telegram — share the same @copilotkit/bot API surface but differ in what the underlying platform natively supports. The table below shows exactly what shipped in the current release.

Reactions — setup notes#

Slack: subscribe to reaction_added and reaction_removed events in the Slack app manifest (or in the Event Subscriptions UI). The reactions:read scope lets the bot read reactions; reactions:write lets it add or remove them. Without the event subscriptions, Slack won't deliver reaction events even if the scopes are present.

Discord: the adapter automatically requests GuildMessageReactions and DirectMessageReactions intents (both non-privileged — no Developer Portal toggle required), and enables Partials.Message + Partials.Reaction. The partials are necessary because reaction events for messages that were sent before the bot started (or evicted from in-memory cache) arrive as partial objects; without them, those reactions are silently dropped.

Telegram: message_reaction is already included in TELEGRAM_ALLOWED_UPDATES — no manual configuration needed for long-polling. For webhook mode, pass the exported constant to setWebhook:

import { TELEGRAM_ALLOWED_UPDATES } from "@copilotkit/bot-telegram";
await bot.api.setWebhook(url, { allowed_updates: [...TELEGRAM_ALLOWED_UPDATES] });

In ordinary group chats, the bot must be an administrator to receive message_reaction events. Private chats and channels work without extra permissions.

Emoji normalization#

All three adapters normalize platform-specific emoji representations into a common emoji string. Standard named emoji (:thumbsup:, :white_check_mark:, etc.) are surfaced as their short-name. Unknown or custom emoji that cannot be mapped pass through as rawEmoji on the reaction event, so your handler can inspect them without losing information.

Modals — Discord timing rule#

Discord requires the modal to be opened before any other response to a button click or slash command. Discord's acknowledgement window is ≈3 seconds — call openModal(view) first, then do any long-running work in a follow-up message. Opening a modal after sending another response will fail silently.

Known limitations (v1)#

• Single workspace / guild / bot — one token per adapter instance; no OAuth multi-tenant install flow
• In-memory action store by default — inline button handlers expire on restart unless you provide a durable ActionStore
• Replies only — the bot answers turns it's part of (mentions, its threads, DMs); it doesn't post proactively

Next steps#

• API reference: the Bots reference — createBot, the Thread API, tools & commands, the component vocabulary, and the Slack adapter
• Full example: on-call triage bot over Linear + Notion MCP — tools, human-in-the-loop, slash commands, file uploads