Slack

The slack tool lets agents search and read Slack, list recent conversations, download and upload files, and post, edit, delete, and react to messages through one Slack app that your organization creates for MindRoom. Agents can also answer mentions of that app in Slack channels, and people can have their own Slack mentions and direct messages forwarded into a Matrix room. OAuth connection mechanics shared with other providers are on OAuth Integration Framework.

An agent works in one of two modes, chosen by whether its slack entry lists channels:

Functions

Functions take a conversation ID such as C0123ABCD, <conversation>:<ts> such as C0123ABCD:1714000000.000100, or a message link, never a channel name. slack_upload takes a path in the agent's workspace and follows the agent's file_access setting. Background scripts cannot call slack.

Set Up The Slack App

An administrator creates one Slack app for the MindRoom installation. One MindRoom serves one Slack workspace: accounts from other workspaces cannot connect, their events are ignored, and Enterprise Grid org-wide installs are not supported. Slack must reach MindRoom for the OAuth redirect and for events, so set MINDROOM_PUBLIC_URL to a public HTTPS address.

1. In Slack, open Your Apps, choose Create New App, then From a manifest, pick the workspace, and paste this manifest with mindroom.example.com replaced by your public MindRoom host:

display_information:
  name: MindRoom
features:
  app_home:
    home_tab_enabled: false
    messages_tab_enabled: false
  bot_user:
    display_name: MindRoom
    always_online: true
oauth_config:
  redirect_urls:
    - https://mindroom.example.com/api/oauth/slack/callback
  scopes:
    bot:
      - app_mentions:read
      - channels:history
      - channels:read
      - groups:history
      - groups:read
      - chat:write
      - reactions:write
      - files:read
      - files:write
      - users:read
      - users:read.email
    user:
      - search:read
      - channels:history
      - channels:read
      - groups:history
      - groups:read
      - im:history
      - im:read
      - mpim:history
      - mpim:read
      - users:read
      - users:read.email
      - chat:write
      - im:write
      - reactions:write
      - files:read
      - files:write
settings:
  event_subscriptions:
    request_url: https://mindroom.example.com/api/slack/events
    bot_events:
      - app_mention
      - message.channels
      - message.groups
    user_events:
      - message.channels
      - message.groups
      - message.im
      - message.mpim
  org_deploy_enabled: false
  socket_mode_enabled: false
  token_rotation_enabled: false

The bot's users:read.email scope is what maps a Slack author to a MindRoom account; without it nobody can wake a project agent. Keep token_rotation_enabled and socket_mode_enabled off, because MindRoom stores Slack user tokens that do not expire and receives events over HTTP.

1. Install the app to the workspace and copy the Bot User OAuth Token.
2. On Basic Information, copy the Client ID, Client Secret, and Signing Secret. Under App-Level Tokens, generate a token with the authorizations:read scope; watches need it, and everything else works without it.
3. Store the credentials in the two credential services below, through the dashboard credentials page or a credential seed.
4. Set the slack section of config.yaml so Slack people map to MindRoom accounts.
5. If MindRoom sits behind an SSO proxy, let POST /api/slack/events through without SSO. Slack signs every request and MindRoom rejects unsigned ones.
6. In the app's Event Subscriptions, retry the request URL's verification. MindRoom answers Slack's verification only once step 4 is done, so the first check fails.

[
  {
    "service": "slack_oauth_client",
    "credentials": {
      "client_id": {"env": "SLACK_CLIENT_ID"},
      "client_secret": {"env": "SLACK_CLIENT_SECRET"}
    }
  },
  {
    "service": "slack_app",
    "credentials": {
      "bot_token": {"env": "SLACK_BOT_TOKEN"},
      "signing_secret": {"env": "SLACK_SIGNING_SECRET"},
      "app_token": {"env": "SLACK_APP_TOKEN"}
    }
  }
]

A seed with an empty field is skipped, so leave app_token out of the seed when you have no app-level token. The Slack app's credentials stay in the primary runtime and are never given to workers.

Slack Configuration

slack:
  email_domain: example.com
  matrix_user_id_template: "@{localpart}:example.org"

Only project agents that answer mentions need this section; personal agents and watches do not.

The slack entry of an agent takes these options:

An agent that another agent creates keeps its creator's channels but not its room, because it has no rooms and never answers mentions.

Personal Agents

agents:
  mind:
    private:
      per: user
    tools:
      - slack

The first time a person asks for something in Slack, the agent replies with a link to connect Slack. After the person approves in Slack, the agent searches, reads, and posts with that person's own account, so it finds only what they can see and posts as them. A person can also connect or disconnect on the Connections portal; when Slack revokes a token, the agent replies with a new link.

Downloads are saved in the agent's workspace. On an agent that is not private, every requester of the agent shares that workspace and can read what another person downloaded, so use a private agent for personal Slack.

Project Agents

agents:
  launch:
    rooms: [launch]
    tools:
      - slack:
          channels: [C0123ABCD, C0456EFGH]
          room: launch

Invite the MindRoom app to each listed channel, for example with /invite @MindRoom. The agent reads and posts only in listed channels that the app has joined, never in direct messages, even when one is listed. Without room, the agent works in those channels only when someone asks it in Matrix.

With room, the agent answers Slack:

1. A person mentions the app in a listed channel, and a 👀 reaction appears on their message.
2. A thread opens in room, showing the Slack message with its author's name and a link, marked as from Slack.
3. The agent answers as that person's MindRoom account, so the agent's access rules and the person's own connected accounts apply.
4. The agent's final reply is posted in the Slack thread by the app, cut with "…" at Slack's length limit. The agent does not need slack_post to answer.
5. Replies in that Slack thread need no mention for 7 days after the last message; they continue the same Matrix thread, as whoever wrote them. After that, mention the app again.

Who can wake the agent:

• The author's Slack email must be confirmed and in slack.email_domain, and its localpart maps to a Matrix account through slack.matrix_user_id_template.
• Guests, bots and other apps, deactivated accounts, and people from other workspaces never wake an agent.
• The mapped account must also pass the agent's access check in room.
• Anyone else sees a message in Slack that only they can see, MindRoom can't answer you here., at most once a day per thread, and nothing reaches Matrix.

Only replies to Slack messages are posted to Slack; what people write in the Matrix thread stays in Matrix. A reply can be missing in Slack when Slack is unavailable, although it exists in Matrix. A channel has one answering agent, so two agents cannot both set room with the same channel, and a personal_agents template cannot set room.

Watches

A watch forwards a person's own Slack mentions and direct messages into the Matrix room where they start it. It works with a personal agent, needs the app-level token, and needs the person's connected Slack account.

In the room, ask the agent, for example "Tell me when someone messages or mentions me in Slack", and it calls slack_watch:

• action="start" creates the watch, or replaces the one the person has with this agent in this room.
• action="stop" ends it, and action="status" shows its filters and, when it is not delivering, why.
• mentions (default true) delivers messages that mention the person, including in group direct messages.
• direct_messages (default true) delivers every message others send in the person's direct messages and group direct messages.
• channels (optional) limits channel messages to those channel IDs; direct messages are not limited by it. Replies in a thread where the person was mentioned also arrive, within those channels.

Each delivery opens a thread in the room, such as "Slack direct message for you from Dana", with the Slack text, its author, its channel unless it is a direct message, and a link. Messages in the same direct message conversation join one thread, and replies in a Slack channel thread join that thread, until 7 days pass without a message. The agent can then summarize it or draft a reply; its turn runs as the watch's owner. A watch lasts until it is stopped.

A watch delivers only while all of these hold, so someone else never reads a private message:

• Only the owner and MindRoom's own accounts are in the room, and nobody is invited; a bridge or other bot counts as a person.
• The room hides earlier messages from people who join later. A personal room MindRoom created already does.
• The owner's Slack connection works and is still the Slack account the watch started with.

slack_watch(action="status") reports a paused watch with one of these texts:

Security: Slack text comes from other people, so during a turn that a watch started, slack_post, slack_edit, slack_delete, slack_react, and slack_upload refuse with Ask me in a new message to post to Slack, and slack_watch start and stop refuse with Ask me in a new message to change your Slack watch. A new message from the owner in the same thread can post. Work that turn schedules or delegates still runs as the owner, so add the approval rules below to keep Slack writes behind a person's approval.

MCP

slack works through the MCP gateway: select the agent and the slack tool on the Connections portal, and calls use the signed-in person's own Slack account, as in Matrix. slack_watch does not work there. A project agent's channels are readable over MCP by everyone allowed to use that agent, and writable unless write is false, because its calls use the app's token. Which agents the gateway offers is described in Agent eligibility.

Approval

Add tool_approval rules to make Slack writes wait for a person:

tool_approval:
  rules:
    - match: slack_post
      action: require_approval
    - match: slack_edit
      action: require_approval
    - match: slack_delete
      action: require_approval
    - match: slack_react
      action: require_approval
    - match: slack_upload
      action: require_approval

The 👀 reaction and the reply MindRoom posts to a Slack mention are not tool calls, so these rules do not gate them.

Limits

• Slack sends at most 30,000 events per hour per workspace, and events beyond that are not delivered, so in a very busy workspace some watch deliveries and mentions can be missed until the next hour.
• If MindRoom is unreachable for more than a few minutes, Slack stops resending, and those messages never reach agents.
• Messages sent directly to the app in Slack are not answered.
• While anyone's watch takes direct messages, every direct message that a connected person sends or receives costs one Slack request to check who can see it, which counts against Slack's rate limits.
• slack_recent makes one Slack request per conversation, so for a person in many conversations Slack's rate limit, or more than 1,000 conversations, ends a call early. The call then answers with the conversations it read, complete: false, and a next_cursor; the agent waits retry_after seconds, calls again with that cursor to read the next conversations, and merges the batches.

Troubleshooting

Config errors name the setting: