Slack Integration Guide

Bring your Sutra agents directly into Slack — where your team already communicates. Agents respond to @mentions in channels, handle DMs, and process approval requests with interactive buttons. Your team gets AI-powered assistance without leaving their primary workspace.

Setup

1. Create a Slack App

  1. Go to api.slack.com/apps and click Create New App.
  2. Choose From scratch, name your app (e.g., "Sutra Bot"), and select your workspace.
  3. Under Features > OAuth & Permissions, scroll down to Scopes. Add the following Bot Token Scopes:
  4. app_mentions:read
  5. chat:write
  6. channels:history
  7. groups:history
    8. What these scopes do: app_mentions:read lets the bot see when it's @mentioned. chat:write lets it post responses. channels:history and groups:history let it read message context in public and private channels. If your agents need to read direct messages, also add im:history. For file uploads, add files:write.
  8. Scroll up and click Install to Workspace.
  9. Copy the Bot User OAuth Token (starts with xoxb-...).

2. Enable Events (Socket Mode or Webhooks)

To receive messages in real-time, Sutra needs to listen to Slack events.

Using Socket Mode (Recommended for internal networks): 1. In your Slack App settings, go to Socket Mode and enable it. 2. Generate an App-Level Token (starts with xapp-...). 3. Go to Event Subscriptions, enable events, and subscribe to the app_mention and message.channels bot events.

Using Webhooks (If Sutra is publicly accessible): 1. Go to Event Subscriptions and enable it. 2. Enter your Sutra webhook URL (e.g., https://sutra.mycompany.com/api/webhooks/slack). 3. Subscribe to the app_mention bot event.

Which should you choose? Use Socket Mode if your Sutra instance runs behind a firewall or on a local network — it doesn't require a public URL. Use Webhooks if your Sutra server is publicly accessible and you want lower latency. Both methods deliver the same functionality; the difference is purely about network topology.

3. Configure Sutra

In the Sutra UI, go to Settings > Configuration (Integrations group), or update your .env file:

SLACK_BOT_TOKEN=xoxb-...
# If using Socket Mode:
SLACK_APP_TOKEN=xapp-...
# If using Webhooks, you'll need the Signing Secret:
SLACK_SIGNING_SECRET=your_signing_secret

Using Agents in Slack

Connecting Channels to Agents

Unlike Telegram, where you /connect a bot to an agent, Slack channels are typically mapped to specific agents in the Sutra UI.

  1. Go to Agents and edit the agent you want to place in Slack.
  2. In the configuration, enter the Slack Channel ID (e.g., C1234567890) where this agent should reside.
  3. Invite the Sutra Bot to that channel in Slack (/invite @Sutra Bot).
Finding your Channel ID: Right-click a channel name in Slack, select "View channel details," and scroll to the bottom — the Channel ID is displayed there (e.g., C1234567890). Alternatively, open the channel in a browser — the ID is the last segment of the URL.

You can map multiple channels to different agents, creating specialized support zones within your Slack workspace. For example, map #engineering-help to your DevOps agent, #marketing-ideas to your Content Strategist agent, and #data-questions to your Data Analyst agent.

Interacting

  • Mentions: Simply @mention the bot in the channel. The agent mapped to that channel will receive the message, process it, and reply in a thread to keep the channel clean.
  • Example: @SutraBot can you summarize the deployment status?
  • Direct Messages: You can also DM the Sutra Bot directly. DMs are typically routed to a default "Assistant" agent, providing a private workspace for individual employees.

Agent responses in channels are always posted as threaded replies to keep the main channel clean. For longer conversations, the agent maintains full context within the thread — so follow-up questions work naturally without re-explaining the context.

Approvals via Slack

If configured, Sutra can route Human-in-the-Loop approval requests directly to a specific Slack channel (e.g., #ops-approvals). The message will include interactive Block Kit buttons (Approve / Reject), allowing managers to authorize agent actions without leaving Slack.

Approval messages include full context: the agent's name, the action it wants to take, the risk level, and the exact payload. Managers can review and decide without needing additional context. Approved actions execute immediately; rejected actions send feedback to the agent, which can adjust and resubmit.

Tip: Create a dedicated #sutra-approvals channel and route all approval requests there. This gives your team a single place to monitor and manage agent requests, and makes it easy to set up Slack notifications so approvals never sit waiting.