Slack - Mibyan Docs

Commands, package names, and image names on this page come from the open-source project that Mibyan Desktop is built on, and can differ from the Mibyan Desktop installer. For the supported Mibyan install and update path, see Install and update.

Connect Mibyan to Slack as a bot using Socket Mode. Socket Mode uses WebSockets instead of public HTTP endpoints, so your Mibyan instance doesn’t need to be publicly accessible — it works behind firewalls, on your laptop, or on a private server.

Classic Slack Apps DeprecatedClassic Slack apps (using RTM API) were fully deprecated in March 2025. Mibyan uses the modern Bolt SDK with Socket Mode. If you have an old classic app, you must create a new one following the steps below.

Overview

Component	Value
Library	`slack-bolt` / `slack_sdk` for Python (Socket Mode)
Connection	WebSocket — no public URL required
Auth tokens needed	Bot Token (`xoxb-`) + App-Level Token (`xapp-`)
User identification	Slack Member IDs (e.g., `U01ABC2DEF3`)

Step 1: Create a Slack App

The fastest path is to paste a manifest Mibyan generates for you. It declares every built-in slash command (/btw, /stop, /model, …), every required OAuth scope, every event subscription, and enables Socket Mode — all at once.

Option A: From a Mibyan-generated manifest (recommended)

Generate the manifest. New Slack apps must use Agent view:
mibyan slack manifest --agent-view --write
This writes ~/.mibyan/slack-manifest.json and prints paste-in instructions. Existing apps that still use Slack’s legacy Assistant view can omit --agent-view until they are ready to migrate. To populate Slack’s long app description from an existing UTF-8 text or Markdown file, add --long-description-file:
mibyan slack manifest --agent-view \ --long-description-file AGENTS.md --write
The file contents are preserved exactly within Slack’s 175–4,000-character range. Use --long-description "..." for inline text instead; the inline and file options are mutually exclusive and cannot be combined with --slashes-only.
Go to https://api.slack.com/apps → Create New App → From an app manifest
Pick your workspace, paste the JSON contents, review, click Next → Create
Skip ahead to Step 6: Install App to Workspace. The manifest handled scopes, events, and slash commands for you.

Option B: From scratch (manual)

Go to https://api.slack.com/apps
Click Create New App
Choose From scratch
Enter an app name (e.g., “Mibyan”) and select your workspace
Click Create App

You’ll land on the app’s Basic Information page. Continue with Steps 2–6 below.

Step 2: Configure Bot Token Scopes

Navigate to Features → OAuth & Permissions in the sidebar. Scroll to Scopes → Bot Token Scopes and add the following:

Scope	Purpose
`chat:write`	Send messages as the bot
`app_mentions:read`	Detect when @mentioned in channels
`channels:history`	Read messages in public channels the bot is in
`channels:read`	List and get info about public channels
`groups:history`	Read messages in private channels the bot is invited to
`im:history`	Read direct message history
`im:read`	View basic DM info
`im:write`	Open and manage DMs
`mpim:history`	Read group direct message (multi-person DM) history
`mpim:read`	View basic group DM info
`users:read`	Look up user information
`files:read`	Read and download attached files, including voice notes/audio
`files:write`	Upload files (images, audio, documents)

Missing scopes = missing featuresWithout channels:history and groups:history, the bot will not receive messages in channels — it will only work in DMs. Without files:read, Mibyan can chat but cannot reliably read user-uploaded attachments. These are the most commonly missed scopes.

Optional scopes:

Scope	Purpose
`groups:read`	List and get info about private channels
`assistant:write`	Render the working-state status line (“is thinking…”) next to the bot name while it processes a message. Without this scope the status call (`agents.sessions.setStatus` on slack-sdk 3.44+, `assistant.threads.setStatus` on older SDKs) fails silently and Slack shows its own rotating generic placeholders instead (“Finding answers…”, “Reviewing findings…”, …) — Mibyan never controls the text. Required for `typing_status_text` to have any visible effect.

Step 3: Enable Socket Mode

Socket Mode lets the bot connect via WebSocket instead of requiring a public URL.

In the sidebar, go to Settings → Socket Mode
Toggle Enable Socket Mode to ON
You’ll be prompted to create an App-Level Token:
- Name it something like mibyan-socket (the name doesn’t matter)
- Add the connections:write scope
- Click Generate
Copy the token — it starts with xapp-. This is your SLACK_APP_TOKEN

You can always find or regenerate app-level tokens under Settings → Basic Information → App-Level Tokens.

This step is critical — it controls what messages the bot can see.

In the sidebar, go to Features → Event Subscriptions
Toggle Enable Events to ON
Expand Subscribe to bot events and add:

Event	Required?	Purpose
`message.im`	Yes	Bot receives direct messages
`message.mpim`	Yes	Bot receives messages in group DMs (multi-person DMs) it’s added to
`message.channels`	Yes	Bot receives messages in public channels it’s added to
`message.groups`	Recommended	Bot receives messages in private channels it’s invited to
`app_mention`	Yes	Prevents Bolt SDK errors when bot is @mentioned

Click Save Changes at the bottom of the page

Missing event subscriptions is the #1 setup issueIf the bot works in DMs but not in channels, you almost certainly forgot to add message.channels (for public channels) and/or message.groups (for private channels). Without these events, Slack simply never delivers channel messages to the bot.

Step 5: Enable the Messages Tab

This step enables direct messages to the bot. Without it, users see “Sending messages to this app has been turned off” when trying to DM the bot.

In the sidebar, go to Features → App Home
Scroll to Show Tabs
Toggle Messages Tab to ON
Check “Allow users to send Slash commands and messages from the messages tab”

Without this step, DMs are completely blockedEven with all the correct scopes and event subscriptions, Slack will not allow users to send direct messages to the bot unless the Messages Tab is enabled. This is a Slack platform requirement, not a Mibyan configuration issue.

Step 6: Install App to Workspace

In the sidebar, go to Settings → Install App
Click Install to Workspace
Review the permissions and click Allow
After authorization, you’ll see a Bot User OAuth Token starting with xoxb-
Copy this token — this is your SLACK_BOT_TOKEN

If you change scopes or event subscriptions later, you must reinstall the app for the changes to take effect. The Install App page will show a banner prompting you to do so.

Step 7: Find User IDs for the Allowlist

Mibyan uses Slack Member IDs (not usernames or display names) for the allowlist. To find a Member ID:

In Slack, click on the user’s name or avatar
Click View full profile
Click the ⋮ (more) button
Select Copy member ID

Member IDs look like U01ABC2DEF3. You need your own Member ID at minimum.

Step 8: Configure Mibyan

Add the following to your ~/.mibyan/.env file:

# Required
SLACK_BOT_TOKEN=xoxb-your-bot-token-here
SLACK_APP_TOKEN=xapp-your-app-token-here
SLACK_ALLOWED_USERS=U01ABC2DEF3              # Comma-separated Member IDs

# Optional
SLACK_HOME_CHANNEL=C01234567890              # Default channel for cron/scheduled messages
SLACK_HOME_CHANNEL_NAME=general              # Human-readable name for the home channel (optional)

Or run the interactive setup:

mibyan gateway setup    # Select Slack when prompted

Then start the gateway:

mibyan gateway              # Foreground
mibyan gateway install      # Install as a user service
sudo mibyan gateway install --system   # Linux only: boot-time system service

Codex reasoning-effort safetyFor Codex-backed Slack peer-agent channels, prefer agent.reasoning_effort: high or lower. xhigh can spend the entire turn in hidden reasoning and never produce visible assistant text; Mibyan now suppresses those incomplete-turn warnings from the thread and keeps the diagnostics in gateway logs.

Step 9: Invite the Bot to Channels

After starting the gateway, you need to invite the bot to any channel where you want it to respond:

/invite @Mibyan

The bot will not automatically join channels. You must invite it to each channel individually.

Slash Commands

Every Mibyan command (/btw, /stop, /new, /model, /help, …) is a native Slack slash command — exactly the way they work on Telegram and Discord. Type / in Slack and the autocomplete picker lists every Mibyan command with its description. Under the hood: Mibyan ships with a generated Slack app manifest (see Step 1, Option A) that declares every command in COMMAND_REGISTRY as a slash command. In Socket Mode, Slack routes the command event through the WebSocket regardless of the manifest’s url field.

Agent messaging experience

New Slack apps use Slack’s Agent messaging experience. Existing Mibyan Assistant apps can migrate by regenerating the manifest with --agent-view:

mibyan slack manifest --agent-view --write

Update the manifest in Features → App Manifest, then reinstall the app if Slack asks. Agent view cannot be reverted to Assistant view, and users may need to hard-refresh Slack after the switch. The generated Agent manifest subscribes to message.im, app_home_opened, and app_context_changed, so Mibyan can identify a Messages-tab DM and receive the user’s active Slack context with a turn. Mibyan only supplies that context as a label; it does not read the viewed channel’s history.

Refreshing slash commands after updates

When Mibyan adds new commands (e.g. after mibyan update), regenerate the manifest and update your Slack app:

mibyan slack manifest --write

Then in Slack:

Open https://api.slack.com/apps → your Mibyan app
Features → App Manifest → Edit
Paste the new contents of ~/.mibyan/slack-manifest.json
Save. Slack will prompt to reinstall the app if scopes or slash commands changed.

Legacy `/mibyan <subcommand>` still works

For backward compatibility with older manifests, you can still type /mibyan bg run the tests — Mibyan routes it the same way as /bg run the tests. Free-form questions also work: /mibyan what's the weather? is treated as a regular message.

Using commands inside threads (the `!cmd` prefix)

Slack itself blocks native slash commands inside thread replies — try /queue in a thread and Slack responds with “/queue is not supported in threads. Sorry!” There is no app-side setting that re-enables them; Slack never delivers them to Mibyan. As a workaround, Mibyan recognises a leading ! as an alternate command prefix that works in threads (and anywhere else). Type !queue, !stop, !model gpt-5.4, etc. as a regular thread reply — Mibyan treats it identically to the slash form and replies in the same thread. Only the first token is checked against the known command list, so casual messages like !nice work pass through to the agent unchanged. The bang form also works behind a mention (@Mibyan !stop) and with leading whitespace — both dispatch as commands in threads. Approval prompts (dangerous command / execute_code approval) normally render as interactive buttons. When buttons can’t be delivered and Mibyan falls back to a text prompt, the prompt instructs you to reply with !approve / !deny — the form that works inside threads.

Slash replies are ephemeral

Replies to a native slash command (e.g. /status, /help) are delivered ephemerally — “Only visible to you” — so command output never spams the channel. The “Running /cmd…” placeholder is replaced with the real reply; long replies are chunked into follow-up ephemeral messages. Slack caps the reply flow at 5 posts, so extremely long output is closed with an explicit truncation notice rather than silently dropped. If the primary ephemeral path fails, Mibyan retries via a second ephemeral API path — a slash reply is never posted publicly to the channel as a fallback. (Commands typed as regular messages — !cmd in threads, @Mibyan /cmd — reply as normal visible messages instead.)

Clarify prompts (one-tap buttons)

When the agent needs to ask you a multiple-choice question (the clarify tool), Slack renders it as Block Kit buttons — one tap per option, plus an “✏️ Other…” button that switches to free-text mode (your next typed message becomes the answer). After a tap, the message updates in place to show who answered and what was chosen; further clicks on the same prompt are ignored. Button clicks honor the same user authorization as messages. When the prompt times out (agent.clarify_timeout), the session is reset, or you reply with free text instead of tapping a button, the card is rewritten in place without its buttons (”⏳ This prompt expired…” or “↩️ Clarification cancelled…”); a click on a card orphaned by a gateway restart still tells you to re-ask instead of silently eating the click. Open-ended clarify questions render as a plain question and accept your next typed reply. No configuration needed — this works regardless of the rich_blocks setting.

Advanced: emit only the slash-commands array

If you maintain your Slack manifest by hand and just want the slash command list:

mibyan slack manifest --slashes-only > ~/.mibyan/cache/scratch/slashes.json

Paste that array into the features.slash_commands key of your existing manifest.

How the Bot Responds

Understanding how Mibyan behaves in different contexts:

Context	Behavior
DMs	Bot responds to every message — no @mention needed
Channels	Bot only responds when @mentioned (e.g., `@Mibyan what time is it?`). In channels, Mibyan replies in a thread attached to that message.
Threads	If you @mention Mibyan inside an existing thread, it replies in that same thread. Once the bot has an active session in a thread, subsequent replies in that thread do not require @mention — the bot follows the conversation naturally.

In channels, always @mention the bot to start a conversation. Once the bot is active in a thread, you can reply in that thread without mentioning it. Outside of threads, messages without @mention are ignored to prevent noise in busy channels.

Configuration Options

Beyond the required environment variables from Step 8, you can customize Slack bot behavior through ~/.mibyan/config.yaml.

Thread & Reply Behavior

platforms:
  slack:
    # Controls how multi-part responses are threaded
    # "off"   — never thread replies to the original message
    # "first" — first chunk threads to user's message (default)
    # "all"   — all chunks thread to user's message
    reply_to_mode: "first"

    extra:
      # Whether to reply in a thread (default: true).
      # When false, channel messages get direct channel replies instead
      # of threads. Messages inside existing threads still reply in-thread.
      reply_in_thread: true

      # Also post thread replies to the main channel
      # (Slack's "Also send to channel" feature).
      # Only the first chunk of the first reply is broadcast.
      reply_broadcast: false

      # Control Slack's automatic link-preview cards without changing or
      # removing clickable links from message text. Omit either key to keep
      # Slack's default behavior for that preview type.
      unfurl_links: false
      unfurl_media: false

      # Render agent messages as Slack Block Kit blocks (default: false).
      # When true, the final agent message is sent with structured blocks —
      # section headers, dividers, true nested lists (via rich_text), and
      # native Block Kit tables — instead of flat mrkdwn text. A plain-text
      # fallback is always sent alongside for notifications/accessibility.
      # Tables exceeding Slack's limits (100 rows / 20 cols / 10k chars)
      # gracefully fall back to aligned monospace.
      rich_blocks: false

      # Append Slack-native feedback controls to final Block Kit replies.
      # Requires rich_blocks: true. Default: false.
      feedback_buttons: false

      # Render live tool calls as Slack-native plan/task cards. Works with
      # Slack's built-in tool_progress: off default; a tool_progress: off you
      # write yourself disables cards too. Cards need a thread: an un-threaded
      # chat shows no tool progress (text progress if you wrote new/all).
      # Recoverable native API failures keep one
      # editable text fallback current for the rest of the turn.
      native_task_cards: false

      # Suggested prompts pinned at the top of Agent view's Messages tab.
      # Either a list of {title, message} rows, or a titled object:
      # {title: "Start here", prompts: [{title: "Plan", message: "..."}]}
      suggested_prompts: []

      # Title Agent/Assistant DM threads from the first user message.
      # Default: true. Set false to leave Slack's default thread titles.
      assistant_thread_titles: true

      # Accept messages posted by other Slack bots (default: "none").
      # "none" ignores bots, "mentions" accepts a bot message only when
      # that message itself @mentions Mibyan, and "all" accepts every
      # other bot. Mibyan always ignores its own bot user to prevent
      # self-echoes.
      allow_bots: "none"

      # Continuable-cron delivery surface (default: "thread").
      # "in_channel" delivers a continuable cron job FLAT into the channel
      # (no dedicated thread); pair with reply_in_thread: false (and
      # require_mention: false) so a plain reply continues the job.
      # See the cron guide → "Flat, in-channel continuation".
      cron_continuable_surface: thread

Key	Default	Description
`platforms.slack.reply_to_mode`	`"first"`	Threading mode for multi-part messages: `"off"`, `"first"`, or `"all"`
`platforms.slack.extra.reply_in_thread`	`true`	When `false`, channel messages get direct replies instead of threads. Messages inside existing threads still reply in-thread.
`platforms.slack.extra.reply_broadcast`	`false`	When `true`, thread replies are also posted to the main channel. Only the first chunk is broadcast.
`platforms.slack.extra.unfurl_links`	Slack default	Set to `false` to suppress automatic previews for linked web pages while preserving clickable links. When either unfurl key is set, media captions are posted as a separate message before the file (Slack’s upload API cannot carry unfurl controls), and native draft streaming falls back to edit-based delivery.
`platforms.slack.extra.unfurl_media`	Slack default	Set to `false` to suppress automatic media previews while preserving clickable links. Same caption-ordering and streaming notes as `unfurl_links`.
`platforms.slack.extra.rich_blocks`	`false`	When `true`, agent messages are rendered as Block Kit blocks (headers, dividers, true nested lists, and native tables). Markdown `[label](https://github.com/NousResearch/hermes-agent/tree/main/website/docs/user-guide/messaging/url)` links and Slack `<url\|label>` autolinks both become clickable links inside lists, quotes and table cells; mentions (`<@U…>`, `<#C…>`, `<!here>`) are left as-is. A plain-text fallback is always sent. Tables over Slack’s limits fall back to aligned monospace. No app reinstall required — it’s a send-side change only.
`platforms.slack.extra.feedback_buttons`	`false`	When `true` with `rich_blocks`, appends Slack-native feedback controls to final replies.
`platforms.slack.extra.native_task_cards`	`false`	When `true`, renders live tool calls as Slack-native plan/task cards. Cards work with Slack’s built-in default `tool_progress: off`; an explicitly configured `display.tool_progress: off` (global or `display.platforms.slack`; `/verbose` writes the same key) disables cards too. Cards need a thread: when the card lane is active and the chat has no thread to anchor on (a top-level DM with `reply_in_thread: false`), Mibyan shows no tool progress instead of text bubbles, unless you explicitly set `tool_progress: new`/`all`, which falls back to editable text progress there. Recoverable native API failures fall back to one continuously edited text update.
`platforms.slack.extra.suggested_prompts`	`[]`	Up to four `{title, message}` prompts for Agent/Assistant DM entry points; accepts either a list or `{title, prompts}`.
`platforms.slack.extra.assistant_thread_titles`	`true`	When `true`, names Agent/Assistant DM threads from the first user message.
`platforms.slack.extra.allow_bots`	`"none"`	Controls messages from other Slack bots: `"none"` ignores them, `"mentions"` accepts a bot message only when that message itself @mentions Mibyan, and `"all"` accepts all of them. Use `"mentions"` for the safest bot-to-bot collaboration mode. See Accepting messages from other bots.
`platforms.slack.extra.api_human_users`	`[]`	Slack user IDs whose Web-API (user-token) posts count as human. Such posts carry the posting `app_id` and no `client_msg_id`, so by default they are dropped as app traffic; allowlist your own front-end’s users here instead of `allow_bots: all`. See Treating your own app’s user-token posts as human.
`platforms.slack.extra.cron_continuable_surface`	`"thread"`	Delivery surface for continuable cron jobs. `"thread"` opens a dedicated thread per delivery (default); `"in_channel"` delivers flat into the channel timeline. Pair `in_channel` with `reply_in_thread: false` (and `require_mention: false`) so a plain channel reply continues the job.

The equivalent environment variable is SLACK_ALLOW_BOTS=none|mentions|all. When both are set, the explicit environment variable takes precedence (the same env-over-YAML rule as every other setting). Avoid all when peer bots can answer each other without an explicit mention, because their own reply policies can still create loops.

Working-State Status Line

While the agent processes a message, Slack shows a status line next to the bot name in the thread. By default Mibyan sets it to is thinking...; customize it with typing_status_text — e.g. a kitten assistant named Ada:

platforms:
  slack:
    # Custom working-state status line (default: "is thinking...").
    typing_status_text: "is pouncing… 🐾"

Key	Default	Description
`platforms.slack.typing_status_text`	`"is thinking..."`	Text of the working-state status line shown while the agent processes a message. Requires the `assistant:write` scope — without it the status call fails silently and Slack renders its own generic placeholder, whatever this is set to. Set `typing_indicator: false` to disable the status line entirely.

Where the status rendersThe custom status appears in the footer beneath the reply composer (“BotName is thinking…”), not inline in the message list. The inline “Generating response…” / “Finding answers…” lines Slack shows in the message area while an AI app works are Slack’s own rotating indicators — the status API (agents.sessions.setStatus / assistant.threads.setStatus) does not control those, and both can appear at the same time.

The same key customizes Google Chat’s visible working-state marker message (platforms.google_chat.typing_status_text, default "Mibyan is thinking…") — note that on Google Chat it is a real posted message that gets patched into the reply, not an ephemeral status.

Live Status (per-tool)

By default the status line updates live as the agent works: instead of a static is thinking..., it shows what the agent is doing right now — is running pytest tests/…, is reading docs/api.md…, is searching the web for slack api limits…. Between tool calls it reverts to the static text. This rides the existing status-refresh cadence, so it makes no additional Slack API calls, and it works even with tool_progress: off (Slack’s default) — unlike progress bubbles, the status line is ephemeral and leaves nothing behind in the channel. Control it with display.live_status (global or per-platform):

display:
  platforms:
    slack:
      # full = verb + argument ("is running pytest…")   [default]
      # verb = verb only ("is running…") — hides commands/paths,
      #        useful in shared or customer-facing channels
      # off  = static text (typing_status_text or "is thinking...")
      live_status: full

Key	Default	Description
`display.live_status`	`"full"`	Live per-tool status line. `full` shows verb + argument preview; `verb` shows the verb only (keeps file paths and commands out of shared channels); `off` restores the static text. Requires the `assistant:write` scope, same as the static status line.

Native Streaming (live-typing replies)

Slack’s Agents & AI Apps feature ships a native streaming surface (chat.startStream / chat.appendStream / chat.stopStream) that renders the reply as a live-typing message — much smoother than the edit-based progressive updates used otherwise. When streaming.enabled is on (transport auto or draft), Mibyan uses native streaming automatically wherever it’s available:

The stream starts on the first frame and appends only deltas (the API is append-only). The streamed message is the final message — Mibyan seals it via chat.stopStream instead of posting a duplicate final reply.
If your Slack app doesn’t have the AI features enabled (or lacks the assistant:write scope), the first failure is cached and Mibyan falls back to edit-based streaming with a single log warning naming the fix.
Opt-in Block Kit (rich_blocks: true) is applied to the sealed message, same as the edit-based finalize path.

No extra configuration is needed beyond enabling streaming:

streaming:
  enabled: true       # transport auto/draft lights up Slack native streaming

Native Task Cards (live tool progress)

With platforms.slack.extra.native_task_cards: true, live tool calls render as Slack-native plan/task cards (the same UI Slack’s own AI features use) instead of text progress bubbles: one card per turn, one row per tool call, with per-task running/complete/error states updating in place.

platforms:
  slack:
    extra:
      native_task_cards: true

Cards are the Slack rendering of tool progress. They work with Slack’s built-in default tool_progress: off. Writing tool_progress: off yourself (globally, under display.platforms.slack, or by cycling /verbose to off) turns cards off as well; new or all keeps them. A null value inherits and is not an “off”. Null also allows the existing environment bridge to supply the mode when no YAML layer sets a non-null value. Changes apply when the next turn resolves its display settings.
Cards need a thread. With the card lane active, a chat that has no thread to anchor on (a top-level DM under reply_in_thread: false) shows no tool progress rather than text bubbles under Slack’s default tool_progress: off; if you wrote new or all, that chat gets the editable text progress you asked for. Replies inside an existing thread still get cards.
Concurrent calls to the same tool are correlated by real tool-call ID, so parallel web_search calls each get their own row with the right status.
Mibyan checks thread eligibility before attempting publication, so a disconnect or timeout cannot turn an unthreaded destination into text fallback.
On a supported threaded destination, if the native stream fails for a recoverable reason (API error, rate limit), Mibyan falls back to a single continuously edited text message so progress stays live for the turn. A relay egress refusal of the destination is not recoverable and suppresses progress for the turn.
If Slack closes a stream during a long turn, Mibyan opens a fresh card in the same thread with the current task list and keeps updating there. The previous card remains visible.
The card stream is stopped exactly once when the turn finalizes, including on interrupt/disconnect, so no dangling live indicator is left behind.

Session Isolation

# Global setting — applies to Slack and all other platforms
group_sessions_per_user: true

When true (the default), each user in a shared channel gets their own isolated conversation session. Two people talking to Mibyan in #general will have separate histories and contexts. Set to false if you want a collaborative mode where the entire channel shares one conversation session. Be aware this means users share context growth and token costs, and one user’s /reset clears the session for everyone.

Mention & Trigger Behavior

slack:
  # Require @mention in channels (this is the default behavior;
  # the Slack adapter enforces @mention gating in channels regardless,
  # but you can set this explicitly for consistency with other platforms)
  require_mention: true

  # Prevent thread auto-engagement: only reply to channel messages that
  # contain an explicit @mention. With this OFF (default), Slack can
  # "auto-engage" — remembering past mentions in a thread and following
  # up on bot-message replies, and resuming active sessions without a
  # fresh mention. With strict_mention ON, every new channel message
  # must @mention the bot before Mibyan will respond.
  strict_mention: false

  # Ignore messages addressed to another user: when a channel or thread
  # message *opens* by @mentioning someone other than the bot (e.g.
  # "@rasha can you take this?"), stay silent unless the bot is also
  # mentioned. Only a *leading* mention counts as "addressed to" — a
  # message that references someone mid-sentence ("loop in @rasha")
  # still reaches the bot. Overrides free_response_channels and thread
  # auto-engagement. Opt-in; default off. Env: SLACK_IGNORE_OTHER_USER_MENTIONS.
  ignore_other_user_mentions: false

  # Require an explicit @mention for THREAD replies, while leaving
  # top-level channel messages governed by require_mention /
  # free_response_channels. Narrower than strict_mention: use it when a
  # free-response bot should not join every follow-up in busy threads.
  # Opt-in; default off. Env: SLACK_THREAD_REQUIRE_MENTION.
  thread_require_mention: false

  # Per-channel force-mention override — the opposite direction of
  # free_response_channels. Channels listed here ALWAYS require an
  # explicit @mention, even when require_mention is false globally.
  # Ongoing conversations still auto-follow (mentioned threads, active
  # sessions, bot-authored threads). Comma-separated IDs or a list.
  # Env: SLACK_REQUIRE_MENTION_CHANNELS.
  require_mention_channels: ""

  # Custom mention patterns that trigger the bot
  # (in addition to the default @mention detection)
  mention_patterns:
    - "hey mibyan"
    - "mibyan,"

  # Text prepended to every outgoing message
  reply_prefix: ""

When to use strict_mentionSet this to true in busy workspaces where Slack’s default “the bot remembers this thread” behavior surprises users — for example, a long tech-support thread where the bot helped at the start and you’d rather it stay silent unless explicitly pinged again. DMs and active interactive sessions are unaffected.

When to use ignore_other_user_mentionsSet this to true when the bot follows busy threads (via thread auto-engagement or free_response_channels) and butts in on messages humans address to each other. It is a narrower tool than strict_mention: plain follow-ups in an engaged thread still get answers; only messages that open by @mentioning another person are skipped. 1:1 DMs are unaffected; group DMs (MPIMs) and channels both apply it, matching the shared-surface policy below. Broadcast tokens (@here, @channel) and channel references address the room, not a person, so they are never skipped.

Silence markers on messages not addressed to the botWhen the bot answers a human message with only a silence token, Mibyan normally posts a short notice instead so a question never goes unanswered. On Slack the token is allowed to stand when the message opened by @mentioning someone else, or was an unmentioned top-level message in a free_response_channels channel that starts its own thread (the default reply_in_thread: true). A 1:1 DM, a mention of the bot, a command, a reaction trigger, or a plain follow-up in a conversation the bot is part of (a thread, or a reply_in_thread: false channel) still gets the notice.

Slack supports both patterns: @mention required to start a conversation by default, but you can opt specific channels out via SLACK_FREE_RESPONSE_CHANNELS (comma-separated channel IDs) or slack.free_response_channels in config.yaml. Once the bot has an active session in a thread, subsequent thread replies do not require a mention. In 1:1 DMs the bot always responds without needing a mention. These gating keys can be set in the top-level slack: block or under platforms.slack.extra; within user YAML, when the same key is set in both, platforms.slack.extra wins and the gateway logs a warning. Administrator-managed pins remain authoritative, and explicit environment settings retain their existing precedence.

Group DMs (MPIMs) are shared surfaces, not 1:1 DMsA 1:1 direct message is a private conversation with one person, so it is mention-exempt. A group DM (MPIM / multi-person DM) is a shared surface — multiple people can see and trigger the bot — so it obeys the same operator controls as a channel: require_mention, strict_mention, free_response_channels, and allowed_channels all apply, and the bot only adds :eyes:/:white_check_mark: reactions when it is actually @mentioned. To let the bot respond freely in a specific group DM, add its channel ID (starts with G) to free_response_channels.

Which mention option do I want?

The gating options compose — each answers a different question:

Option	Question it answers	Default	Scope
`require_mention`	Do top-level channel messages need an @mention?	`true`	All channels
`free_response_channels`	Which channels are exempt from `require_mention`?	none	Listed channels
`require_mention_channels`	Which channels ALWAYS need an @mention, even when `require_mention` is `false` or the channel is free-response? Wins over both.	none	Listed channels
`thread_require_mention`	Do thread replies need an @mention, even when top-level messages don’t? Mentioned threads are not remembered.	`false`	Threads only
`strict_mention`	Does every channel message (top-level and thread) need a fresh @mention? Disables all auto-follow: mentioned-thread memory, bot-reply follow-ups, active-session resume.	`false`	All channels + threads
`ignore_other_user_mentions`	Should a message that opens by @mentioning someone else (`@rasha can you take this?`) be skipped? Overrides free-response and thread auto-follow; mid-sentence references still reach the bot.	`false`	Channels + group DMs

Rules of thumb: strict_mention is the broadest hammer; thread_require_mention quiets busy threads without touching top-level gating; require_mention_channels re-tightens individual channels on an otherwise free-response bot; ignore_other_user_mentions only skips messages explicitly addressed to another person. 1:1 DMs always respond and are unaffected by all of these.

Accepting messages from other bots (`allow_bots`)

By default Mibyan ignores every message authored by another Slack bot or app (including Workflow Builder posts). For multi-agent workspaces — several Mibyan instances or peer bots collaborating in one channel — opt in with allow_bots:

platforms:
  slack:
    extra:
      # "none" (default) — ignore all bot/app-authored messages
      # "mentions"       — accept a bot message only when THAT message
      #                    @mentions this bot
      # "all"            — accept every bot message (except the bot's own)
      allow_bots: mentions

Env equivalent: SLACK_ALLOW_BOTS=none|mentions|all (the config key wins when both are set). Unknown values are treated as none. How mentions mode gates:

A peer-bot message is accepted only when the message itself contains a current @mention of this bot — in its text or its Block Kit blocks. Thread history does not count: a bot having been mentioned earlier in the thread, replies to the bot’s own messages, and active thread sessions do not admit later unmentioned peer-bot messages. This is deliberate — it is what breaks agent-to-agent ack/status loops.
Human messages are unaffected; normal mention gating applies to them.
Mibyan always ignores its own messages, in every mode, to prevent self-echo loops.

mentions is the recommended mode for bot-to-bot collaboration: each agent must explicitly summon the other per turn. Avoid all unless every peer bot’s own reply policy is loop-safe — two bots that answer everything will answer each other forever. Detection covers labeled bot messages (bot_id, subtype: bot_message), app-originated events, and unlabeled bot users (probed via users.info), so peer Mibyan agents are filtered consistently across workspaces. For strict multi-bot deployments, pair with require_mention: true and strict_mention: true — see the smoke-check profile below.

Treating your own app’s user-token posts as human (`api_human_users`)

A message posted through the Web API with a user token (xoxp-) is authored by a real person, but it arrives with the posting app_id and no client_msg_id — the same signature Mibyan uses to recognise app posts — so it is dropped as bot traffic. This blocks a common pattern: a custom front-end (an internal dashboard, a mobile shell, a kiosk) that sends messages to Mibyan as the logged-in user. allow_bots: all would let those posts through, but it opens the door to every bot in the channel and weakens the loop protections. Instead, allowlist just the people who use your front-end:

platforms:
  slack:
    extra:
      api_human_users: ["U0AAAAAAA", "U0BBBBBBB"]

The equivalent environment variable is SLACK_API_HUMAN_USERS (comma-separated). Scope and safety:

The allowlist is users only. There is deliberately no app-ID variant: a modern bot token (xoxb-) posts with the same user + app_id shape, so trusting an app would also admit its own bot posts and defeat the loop guard.
Events carrying bot_id or subtype: bot_message, or no user at all, are always treated as bot posts regardless of the allowlist.
The rest of the pipeline is unchanged: mention gating, allowed_channels, and SLACK_ALLOWED_USERS still apply to the (now human) sender.

Reaction Triggers (`reaction_triggers`)

By default, emoji reactions are acknowledged and dropped — a 👍 on a bot message does nothing. Set slack.reaction_triggers to route reactions into the agent loop (requires the reactions:read scope plus the reaction_added/reaction_removed bot event subscriptions in your Slack app manifest — regenerate with mibyan slack manifest):

slack:
  # Opt-in. false/absent (default) = reactions are acked and dropped.
  # true = any reaction ON THE BOT'S OWN MESSAGES routes to the agent.
  reaction_triggers: true
  # Or an explicit emoji allowlist — only these names route, and they may
  # target ANY message (emoji-handoff workflows, e.g. :task: to capture):
  # reaction_triggers: [white_check_mark, thumbsup, task]
  # Optional handoff target: respond in this channel (top-level) or thread
  # (C123:<thread_ts>) instead of the reacted-to message's thread.
  # reaction_trigger_target: C0123456789

Environment equivalents: SLACK_REACTION_TRIGGERS (true/all or a comma-separated list) and SLACK_REACTION_TRIGGER_TARGET. Behavior:

The reaction arrives as a normal agent turn with text reaction:added:👍 / reaction:removed:👍 (common Slack names are translated to unicode; unknown names pass through as-is, e.g. reaction:added:custom-emoji), threaded under the reacted-to message so the agent sees what was reacted to and the turn lands in the same session as a reply would.
The reactor becomes the message’s user, so user authorization and allowed_channels gating apply exactly as for typed messages — a random user’s reaction cannot trigger the agent anywhere their message couldn’t.
With reaction_triggers: true, only reactions on the bot’s own messages route (approve/acknowledge flows). With an explicit emoji allowlist, the listed emojis route from any message.
The bot’s own lifecycle reactions (:eyes: etc.) never feed back.
Independent of this opt-in, every human reaction fires the reaction:added/reaction:removed gateway hooks for observers that don’t need agent turns.

Peer-Agent Smoke Check

For multi-bot Slack deployments that rely on strict per-turn mentions, keep the following profile:

slack:
  require_mention: true
  strict_mention: true
  allow_bots: mentions
  allowed_channels: ""

After gateway config changes, deploys, or restarts, run this synthetic smoke target:

scripts/run_tests.sh tests/gateway/test_slack_peer_agent_smoke.py -q

This target uses in-process synthetic Slack events only. It does not send live Slack messages and does not require real bot tokens by default. Failure buckets:

config: test_peer_agent_smoke_preflight_contract caught a profile mismatch (require_mention, strict_mention, allow_bots, or allowed_channels).
platform_connectivity: the adapter/client was not initialized, so routing smoke is not a trustworthy signal yet.
bot_identity: the adapter never resolved its bot user ID, so current-message mention checks cannot work.
routing_logic: the Slack adapter regressed on one of the peer-agent invariants (human mention routing, peer-bot ignore, explicit peer mention admit, or passive ack/status/error suppression).

If this target passes but a live workspace still misroutes messages, investigate Slack token/workspace connectivity and runtime deployment state outside the routing logic itself.

Channel allowlist (`allowed_channels`)

Restrict the bot to a fixed set of Slack channels — useful when the bot is invited to many channels but should only respond in a few. When set, messages from channels NOT in this list are silently ignored, even if the bot is @mentioned. 1:1 DMs are exempt from this filter, so authorized users can always reach the bot in a direct message. Group DMs (MPIMs) are not exempt — like channels, an MPIM must be on the allowlist (its ID starts with G) or its messages are dropped.

slack:
  allowed_channels:
    - "C0123456789"   # #ops
    - "C0987654321"   # #incident-response

Or via env var (comma-separated):

SLACK_ALLOWED_CHANNELS="C0123456789,C0987654321"

Behavior:

Empty / unset → no restriction (fully backward compatible).
Non-empty → channel ID must be on the list, or the message is dropped before any other gating (mention requirement, free_response_channels, etc.) runs.
Slack channel IDs start with C (public), G (private), or D (DM). Look them up via the Slack UI’s “Open channel details” → “About” panel, or via the API.

See also: admin/user slash command split.

Unauthorized User Handling

slack:
  # What happens when an unauthorized user (not in SLACK_ALLOWED_USERS) DMs the bot
  # "pair"   — prompt them for a pairing code (default)
  # "ignore" — silently drop the message
  unauthorized_dm_behavior: "pair"

You can also set this globally for all platforms:

unauthorized_dm_behavior: "pair"

The platform-specific setting under slack: takes precedence over the global setting.

Voice Transcription

# Global setting — enable/disable automatic transcription of incoming voice messages
stt_enabled: true

When true (the default), incoming audio messages are automatically transcribed using the configured STT provider before being processed by the agent.

Full Example

# Global gateway settings
group_sessions_per_user: true
unauthorized_dm_behavior: "pair"
stt_enabled: true

# Slack-specific settings
slack:
  require_mention: true
  unauthorized_dm_behavior: "pair"

# Platform config
platforms:
  slack:
    reply_to_mode: "first"
    extra:
      reply_in_thread: true
      reply_broadcast: false

Home Channel

Set SLACK_HOME_CHANNEL to a channel ID where Mibyan will deliver scheduled messages, cron job results, and other proactive notifications. To find a channel ID:

Right-click the channel name in Slack
Click View channel details
Scroll to the bottom — the Channel ID is shown there

SLACK_HOME_CHANNEL=C01234567890

Make sure the bot has been invited to the channel (/invite @Mibyan).

Cron delivery targeting

Cron jobs (see the cron guide) can target Slack three ways:

`deliver:` value	Where it lands
`slack`	The home channel (`SLACK_HOME_CHANNEL`)
`slack:C0123456789`	A specific channel by ID
`slack:U0123456789`	That user’s DM — the bare user ID is resolved to a DM conversation automatically (requires the `im:write` scope)

Delivery works even when the cron process isn’t co-located with the gateway — Mibyan falls back to a standalone Web API sender using SLACK_BOT_TOKEN. MEDIA: attachments in the cron output are uploaded as native Slack file shares to the same target.

Sending messages and media (`send_message`)

The agent’s send_message tool accepts the same target shapes: a channel ID (C…/G…), a DM conversation (D…), or a bare user ID (U…/W…), which is resolved to the user’s DM on every send path — text, media, and interactive prompts alike. MEDIA:<path> attachments (images, PDFs, documents) upload as native file shares; when a short message accompanies a single attachment it rides as the file’s caption instead of a separate message. Missing files are reported per-file as warnings rather than failing the whole send.

Multi-Workspace Support

Mibyan can connect to multiple Slack workspaces simultaneously using a single gateway instance. Each workspace is authenticated independently with its own bot user ID.

Configuration

Provide multiple bot tokens as a comma-separated list in SLACK_BOT_TOKEN:

# Multiple bot tokens — one per workspace
SLACK_BOT_TOKEN=xoxb-workspace1-token,xoxb-workspace2-token,xoxb-workspace3-token

# A single app-level token is still used for Socket Mode
SLACK_APP_TOKEN=xapp-your-app-token

Or in ~/.mibyan/config.yaml:

platforms:
  slack:
    token: "xoxb-workspace1-token,xoxb-workspace2-token"

OAuth Token File

In addition to tokens in the environment or config, Mibyan also loads tokens from an OAuth token file at:

~/.mibyan/slack_tokens.json

This file is a JSON object mapping team IDs to token entries:

{
  "T01ABC2DEF3": {
    "token": "xoxb-workspace-token-here",
    "team_name": "My Workspace"
  }
}

Tokens from this file are merged with any tokens specified via SLACK_BOT_TOKEN. Duplicate tokens are automatically deduplicated.

How it works

The first token in the list is the primary token, used for the Socket Mode connection (AsyncApp).
Each token is authenticated via auth.test on startup. The gateway maps each team_id to its own WebClient and bot_user_id.
When a message arrives, Mibyan uses the correct workspace-specific client to respond.
The primary bot_user_id (from the first token) is used for backward compatibility with features that expect a single bot identity.

Voice Messages

Mibyan supports voice on Slack:

Incoming: Voice/audio messages are automatically transcribed using the configured STT provider: local faster-whisper, Groq Whisper (GROQ_API_KEY), or OpenAI Whisper (VOICE_TOOLS_OPENAI_KEY)
Outgoing: TTS responses are sent as audio file attachments

Per-Channel Prompts

Assign ephemeral system prompts to specific Slack channels. The prompt is injected at runtime on every turn — never persisted to transcript history — so changes take effect immediately.

slack:
  channel_prompts:
    "C01RESEARCH": |
      You are a research assistant. Focus on academic sources,
      citations, and concise synthesis.
    "C02ENGINEERING": |
      Code review mode. Be precise about edge cases and
      performance implications.

Keys are Slack channel IDs (find them via channel details → “About” → scroll to bottom). All messages in the matching channel get the prompt injected as an ephemeral system instruction.

Per-Channel Skill Bindings

Auto-load a skill whenever a new session starts in a specific channel or DM. Unlike per-channel prompts (which are injected on every turn), skill bindings inject the skill content as a user message at session start — it becomes part of the conversation history and does not need to be reloaded on subsequent turns. This is ideal for DMs or channels with a dedicated purpose (flashcards, a domain-specific Q&A bot, a support triage channel, etc.) where you don’t want the model’s own skill selector to decide whether to load on every short reply.

slack:
  channel_skill_bindings:
    # DM channel — always runs in "german-flashcards" mode
    - id: "D0ATH9TQ0G6"
      skills:
        - german-flashcards
    # Research channel — preload multiple skills in order
    - id: "C01RESEARCH"
      skills:
        - arxiv
        - writing-plans
    # Short form: single skill as a string
    - id: "C02SUPPORT"
      skill: hubspot-on-demand

Notes:

The binding matches by channel ID. For threaded messages in a bound channel, the thread inherits the parent channel’s binding.
The skill is loaded only at session start (new session). If you change the binding, run /new for it to take effect.
Combine with channel_prompts for per-channel tone/constraints on top of the skill’s instructions.

Troubleshooting

Problem	Solution
Bot doesn’t respond to DMs	Verify `message.im` is in your event subscriptions and the app is reinstalled
Bot works in DMs but not in channels	Most common issue. Add `message.channels` and `message.groups` to event subscriptions, reinstall the app, and invite the bot to the channel with `/invite @Mibyan`
Bot doesn’t respond to @mentions in channels	1) Check `message.channels` event is subscribed. 2) Bot must be invited to the channel. 3) Ensure `channels:history` scope is added. 4) Reinstall the app after scope/event changes
Bot ignores messages in private channels	Add both the `message.groups` event subscription and `groups:history` scope, then reinstall the app and `/invite` the bot
Bot doesn’t respond in group DMs (multi-person DMs)	Add the `message.mpim` event subscription and the `mpim:history` scope (plus `mpim:read`), then reinstall the app. Without `message.mpim`, Slack never delivers group-DM messages to the bot — even though 1:1 DMs work.
”Sending messages to this app has been turned off” in DMs	Enable the Messages Tab in App Home settings (see Step 5)
“not_authed” or “invalid_auth” errors	Regenerate your Bot Token and App Token, update `.env`
Bot responds but can’t post in a channel	Invite the bot to the channel with `/invite @Mibyan`
Bot can chat but can’t read uploaded images/files	Add `files:read`, then reinstall the app. Mibyan now surfaces attachment access diagnostics in-chat when Slack returns scope/auth/permission failures.
`missing_scope` error	Add the required scope in OAuth & Permissions, then reinstall the app
Socket disconnects frequently	Check your network; Bolt auto-reconnects but unstable connections cause lag
Changed scopes/events but nothing changed	You must reinstall the app to your workspace after any scope or event subscription change

Quick Checklist

If the bot isn’t working in channels, verify all of the following:

✅ message.channels event is subscribed (for public channels)
✅ message.groups event is subscribed (for private channels)
✅ app_mention event is subscribed
✅ channels:history scope is added (for public channels)
✅ groups:history scope is added (for private channels)
✅ App was reinstalled after adding scopes/events
✅ Bot was invited to the channel (/invite @Mibyan)
✅ You are @mentioning the bot in your message

Security

Always set SLACK_ALLOWED_USERS with the Member IDs of authorized users. Without this setting, the gateway will deny all messages by default as a safety measure. Never share your bot tokens — treat them like passwords.

Tokens should be stored in ~/.mibyan/.env (file permissions 600)
Rotate tokens periodically via the Slack app settings
Audit who has access to your Mibyan config directory
Socket Mode means no public endpoint is exposed — one less attack surface

​Overview

​Step 1: Create a Slack App

​Option A: From a Mibyan-generated manifest (recommended)

​Option B: From scratch (manual)

​Step 2: Configure Bot Token Scopes

​Step 3: Enable Socket Mode

​Step 4: Subscribe to Events

​Step 5: Enable the Messages Tab

​Step 6: Install App to Workspace

​Step 7: Find User IDs for the Allowlist

​Step 8: Configure Mibyan

​Step 9: Invite the Bot to Channels

​Slash Commands

​Agent messaging experience

​Refreshing slash commands after updates

​Legacy /mibyan <subcommand> still works

​Using commands inside threads (the !cmd prefix)

​Slash replies are ephemeral

​Clarify prompts (one-tap buttons)

​Advanced: emit only the slash-commands array

​How the Bot Responds

​Configuration Options

​Thread & Reply Behavior

​Working-State Status Line

​Live Status (per-tool)

​Native Streaming (live-typing replies)

​Native Task Cards (live tool progress)

​Session Isolation

​Mention & Trigger Behavior

​Which mention option do I want?

​Accepting messages from other bots (allow_bots)

​Treating your own app’s user-token posts as human (api_human_users)

​Reaction Triggers (reaction_triggers)

​Peer-Agent Smoke Check

​Channel allowlist (allowed_channels)

​Unauthorized User Handling

​Voice Transcription

​Full Example

​Home Channel

​Cron delivery targeting

​Sending messages and media (send_message)

​Multi-Workspace Support

​Configuration

​OAuth Token File

​How it works

​Voice Messages

​Per-Channel Prompts

​Per-Channel Skill Bindings

​Troubleshooting

​Quick Checklist

​Security

Overview

Step 1: Create a Slack App

Option A: From a Mibyan-generated manifest (recommended)

Option B: From scratch (manual)

Step 2: Configure Bot Token Scopes

Step 3: Enable Socket Mode

Step 4: Subscribe to Events

Step 5: Enable the Messages Tab

Step 6: Install App to Workspace

Step 7: Find User IDs for the Allowlist

Step 8: Configure Mibyan

Step 9: Invite the Bot to Channels

Slash Commands

Agent messaging experience

Refreshing slash commands after updates

Legacy `/mibyan <subcommand>` still works

Using commands inside threads (the `!cmd` prefix)

Slash replies are ephemeral

Clarify prompts (one-tap buttons)

Advanced: emit only the slash-commands array

How the Bot Responds

Configuration Options

Thread & Reply Behavior

Working-State Status Line

Live Status (per-tool)

Native Streaming (live-typing replies)

Native Task Cards (live tool progress)

Session Isolation

Mention & Trigger Behavior

Which mention option do I want?

Accepting messages from other bots (`allow_bots`)

Treating your own app’s user-token posts as human (`api_human_users`)

Reaction Triggers (`reaction_triggers`)

Peer-Agent Smoke Check

Channel allowlist (`allowed_channels`)

Unauthorized User Handling

Voice Transcription

Full Example

Home Channel

Cron delivery targeting

Sending messages and media (`send_message`)

Multi-Workspace Support

Configuration

OAuth Token File

How it works

Voice Messages

Per-Channel Prompts

Per-Channel Skill Bindings

Troubleshooting

Quick Checklist

Security