Slack Gateway

BMO can expose a Slack Socket Mode gateway for direct messages via:

bmo service start gateway

Supported scope

• Slack is the only built-in gateway adapter in this repo.
• Direct messages are the only supported interaction mode.
• Group channels, thread routing, and mention-based activation are not supported by this gateway.

Health model

If services.gateway.listen is set, BMO exposes:

• GET /health for liveness only

/health does not validate Slack credentials or adapter connectivity. Treat a healthy response as process liveness only.

For local readiness without contacting Slack, run:

bmo service status gateway
bmo service status gateway --format json

The shared status family validates the TOML config, supported direct-message routing scope, local gateway session store, worker capacity, and configured liveness endpoint metadata. Output is token-redacted. Detached readers do not probe /health automatically, and they report recent gateway.* events as unavailable because those events are process-local to the live gateway runtime; they do not fabricate an empty ring.

The same detached JSON snapshot is exposed through:

• bmo service status gateway --format json
• GET /v1/gateway/status
• /gateway_status
• get_gateway_status
• bmo_get_gateway_status

Add --live-slack only when you intentionally want the CLI command to call Slack with the configured credentials.

Configuration

Use the canonical bmo.toml service surface:

[services.gateway]
enabled = true
listen = "127.0.0.1:8081"
dm_scope = "per_channel_peer"

[services.gateway.slack]
app_token = "xapp-..."
bot_token = "xoxb-..."

Gateway always runs with auto approval. Use dm_scope = "main", "per_peer", or "per_channel_peer" depending on how you want Slack direct messages mapped into BMO sessions.

Slack app setup

Configure the Slack app around the BMO gateway contract: Slack-only, DM-first, Socket Mode.

1. Create the Slack app

• Create a new internal Slack app for the target workspace.
• Add a bot user to the app.

2. Enable Socket Mode

• Turn on Socket Mode for the app.
• Create an app-level token (xapp-...).
• Grant the app-level token the connections:write scope.

BMO uses the app token to open the Socket Mode connection.

3. Configure bot scopes

Add these bot token scopes:

• chat:write
• im:history

BMO uses the bot token for auth.test, DM event handling, and message replies.

4. Subscribe to the DM event

Under Event Subscriptions, enable events and add:

• message.im

The gateway listens for Slack direct-message events.

5. Install the app to the workspace

• Install or reinstall the app after scopes and events are configured.
• Copy the bot token (xoxb-...) after installation.

6. Provide both tokens to BMO

You need both:

• app_token: xapp-...
• bot_token: xoxb-...

7. Start the gateway

Check local posture first:

bmo service status gateway

This command does not send a Slack DM and does not contact Slack unless you add --live-slack.

bmo service start gateway

Optional liveness endpoint:

bmo service start gateway --listen :8081

8. Verify behavior

• Send the bot a direct message in Slack.
• Confirm BMO receives it and replies.
• Confirm Slack channels remain ignored.

Limits

• The /health endpoint exposes liveness, not readiness; use bmo service status gateway for local readiness posture.
• Detached inspect surfaces preserve the configured health endpoint address but keep health.state=unchecked until a caller performs its own liveness probe against /health.
• Detached inspect surfaces (GET /v1/gateway/status, /gateway_status, get_gateway_status, bmo_get_gateway_status) do not expose recent gateway events because those events are process-local to the live gateway runtime.
• No support for Slack channels or mention-triggered activation.
• Slack MCP tools are configured separately and are not this inbound gateway.
• Teams, Mattermost, Telegram, Discord, and Google Chat adapters are not implemented.