Slack

Prerequisites

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

Creating a Slack app

Gamut supports two setup paths: quick setup using an app manifest, or manual setup configuring each setting by hand.

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 Gamut 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., "gamut"), 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

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 Gamut

1. Open your agent in Gamut.
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. Gamut 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.

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

Channel ID (optional)

If left empty, the bot responds to any DM or channel it is invited to. 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 keeps responding to follow-ups in that thread without needing another mention: mention the bot to start, then continue the discussion in the thread.

Reply in thread

When enabled, the bot replies in a thread rather than posting to the channel directly, keeping the main channel clean. For top-level channel messages, the bot creates a new thread anchored to the original message. For messages already in a thread, it replies there.

New session per thread

Available when "Reply in thread" is enabled. When on, each Slack thread gets its own agent session, so the agent starts fresh in every thread with no memory of the others. When off, all messages in a channel (across all threads) share a single session, and the agent carries context between conversations.

How messages flow

Slack user sends message (DM or channel)
        |
        v
Slack Socket Mode (WebSocket)
        |
        v
Message routing (mention filter, thread logic)
        |
        v
Gamut 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 mention syntax (<@U123>) is resolved to real user names first.
• File uploads are downloaded (requires the files:read scope) and attached to the message. If a 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, so Gamut adds a thinking_face reaction to the user's last message while the agent works and removes it once the response is sent.
• Thread context: When the bot joins an existing thread mid-conversation, it fetches earlier messages so the agent has full context.
• Markdown formatting in agent responses is converted to Slack mrkdwn (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 appear in the Gamut sidebar; a dropdown switches between them when more than one exists. Send /clear in the chat at any time to reset the session.

Managing the integration

Once connected, manage the integration from the Gamut 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 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 (requires Reply in Thread).
• Rename / Delete: Rename or permanently remove the integration.