Gamut

Slack

Set up a Slack bot connected to your Superagent agent.

The Slack integration connects a Slack bot to your agent using Socket Mode (WebSocket-based, no public URL required). The bot can respond to direct messages, participate in channels, reply in threads, and handle interactive prompts with Block Kit buttons.

Prerequisites

  • A Slack workspace where you have permission to create apps.
  • An agent already created in Superagent.

Creating a Slack App

Superagent provides two setup paths: quick setup using an app manifest, or manual setup where you configure each setting yourself.

Quick Setup (Recommended)

  1. Go to api.slack.com/apps.
  2. Click Create New App and select From an app manifest.
  3. Select your workspace.
  4. In the Superagent setup dialog, copy the generated manifest (the dialog provides a copy button). Paste it into Slack's manifest editor, replacing the default content.
  5. Click through to create the app.
  6. In Basic Information, scroll to App-Level Tokens. Click Generate Tokens and Scopes.
  7. Name the token (e.g., "superagent"), click Add Scope, select connections:write, then click Generate.
  8. Copy the generated xapp-... token. This is your App-Level Token.
  9. Go to OAuth & Permissions. Click Install to Workspace (or reinstall if updating). Authorize the app.
  10. Copy the Bot User OAuth Token (xoxb-...). This is your Bot Token.

Manual Setup

If you prefer to configure the app yourself:

  1. Go to api.slack.com/apps. Click Create New App and select From scratch. Choose your workspace.
  2. Settings > Socket Mode -- Toggle Socket Mode ON.
  3. Basic Information > App-Level Tokens -- Generate a token with the connections:write scope. Copy the xapp-... token.
  4. OAuth & Permissions > Bot Token Scopes -- Add all required scopes:
    • chat:write
    • im:history, im:read, im:write
    • channels:history, channels:read
    • groups:history, groups:read
    • mpim:history, mpim:read
    • users:read
    • files:read, files:write
    • reactions:write
  5. Event Subscriptions -- Toggle ON. Under Subscribe to bot events, add:
    • message.im
    • message.channels
    • message.groups
    • message.mpim
  6. Interactivity & Shortcuts -- Toggle ON.
  7. App Home > Show Tabs -- Check "Messages Tab" and "Allow users to send Slash commands and messages from the messages tab".
  8. OAuth & Permissions -- Click Install to Workspace. Copy the xoxb-... Bot Token.

Connecting to Superagent

  1. Open your agent in Superagent.
  2. Open the chat integrations setup and select Slack.
  3. Paste the App-Level Token (xapp-...) and Bot Token (xoxb-...).
  4. Optionally click Verify token to confirm both tokens are valid. Superagent validates the bot token via auth.test and the app token via apps.connections.open.
  5. Configure channel behavior settings (see below).
  6. Click Connect.

Superagent opens a WebSocket connection to Slack via Socket Mode. Once connected, the bot appears online in your workspace.

Channel ID (Optional)

The Channel ID field is optional. If left empty, the bot will respond to any DM or channel it is invited to. You can specify a channel ID to restrict the bot to a single channel.

Channel Behavior Settings

These settings control how the bot behaves in channels (they do not affect DMs, where the bot always responds to every message):

Only Trigger on @mention

When enabled, the bot only responds to channel messages that @mention it. Messages without a mention are ignored.

Once the bot responds in a thread, it will continue to respond to follow-up messages in that same thread even without being mentioned again. This provides a natural conversation flow: mention the bot to start, then continue the discussion in the thread.

DMs are never filtered regardless of this setting.

Reply in Thread

When enabled, the bot replies in a thread rather than posting to the channel directly. This keeps the main channel clean while allowing detailed conversations in threads.

For top-level channel messages, the bot creates a new thread anchored to the original message. For messages already in a thread, the bot replies in that thread.

New Session per Thread

Available when "Reply in thread" is enabled. When turned on, each Slack thread gets its own independent agent session. This means the agent starts fresh in each thread with no memory of other threads.

When turned off, all messages in a channel (across all threads) share a single agent session, so the agent has context from previous conversations.

How Messages Flow

Slack user sends message (DM or channel)
        |
        v
Slack Socket Mode (WebSocket)
        |
        v
Message routing (mention filter, thread logic)
        |
        v
Superagent routes to agent session
        |
        v
Agent processes message (tools, skills, etc.)
        |
        v
Response streams back to Slack
(message updates in place as text arrives)
  • Text messages are forwarded to the agent. Slack-specific mention syntax (<@U123>) is resolved to real user names before being sent to the agent.
  • File uploads are downloaded (requires the files:read scope) and attached to the message. If the download fails, the bot posts a warning and continues with the text portion.
  • Interactive buttons (Block Kit) are used for questions, approval prompts, and other interactive events.
  • Typing indicator -- Slack does not support typing indicators for bots. As a workaround, Superagent adds a thinking_face reaction to the user's last message while the agent is working, and removes it once the response is sent.
  • Thread context -- When the bot joins an existing thread mid-conversation, it fetches earlier messages in the thread so the agent has full context.
  • Markdown formatting in agent responses is converted to Slack mrkdwn format (bold, italic, code blocks, lists, links).

Sessions

Each unique conversation gets its own session:

  • Each user who DMs the bot gets a dedicated session.
  • Each channel the bot is active in gets a session (or each thread, if "New session per thread" is enabled).
  • In group contexts, messages are prefixed with the sender's name so the agent knows who is speaking.

Sessions are visible in the Superagent sidebar. If multiple sessions exist, a dropdown lets you switch between them to view the conversation history.

Send /clear in the chat at any time to reset the session.

Managing the Integration

Once connected, you can manage the integration from the Superagent sidebar:

  • Pause / Resume -- Temporarily stop the bot without deleting the integration.
  • Show Tool Calls -- Toggle visibility of tool invocation messages in the chat.
  • Session Timeout -- Set an inactivity timeout for automatic session rotation.
  • Model and Effort -- Override the AI model or effort level.
  • Only on @mention -- Toggle the mention-only filter.
  • Reply in Thread -- Toggle threaded replies.
  • New Session per Thread -- Toggle per-thread session isolation (only available when Reply in Thread is on).
  • Rename / Delete -- Rename or permanently remove the integration.