Connect Slack

Connect Maia to a Slack workspace with Socket Mode. Maia opens an outbound WebSocket connection, so this setup does not require a public webhook endpoint.

Before you start

• You need permission to create and install a Slack app in the target workspace.
• Decide which Slack member ID will be Maia's first administrator.
• Keep the bot and app tokens in Maia's secret-aware dashboard fields or <MAIA_HOME>/.env. Never commit them.

Create the Slack app

1. Generate Maia's app manifest:

   maia slack manifest --write

2. Open Slack API Apps, select Create New App, choose From an app manifest, select your workspace, and paste the generated manifest.
3. Under OAuth & Permissions, verify the bot scopes chat:write, app_mentions:read, channels:history, channels:read, groups:history, im:history, im:read, im:write, users:read, files:read, and files:write. Add groups:read when Maia must discover private channels.
4. Enable Socket Mode. Create an app-level token with connections:write and copy the token beginning with xapp-.
5. Under Event Subscriptions, subscribe to message.im, message.channels, message.groups, and app_mention.
6. Under App Home, enable the Messages Tab and allow users to send messages from it.
7. Install the app to the workspace and copy the Bot User OAuth Token beginning with xoxb-. Reinstall the app after changing scopes, events, or slash commands.
8. Open each permitted person's Slack profile and copy the member ID, such as U01ABC2DEF3. Authorization must use stable IDs, not display names.

Configure Slack in the dashboard

1. Run maia or maia dashboard and open Gateway in the dashboard menu.
2. Select Slack. Enter the xoxb- bot token and xapp- app-level token in the secret-aware fields.
3. Add the allowed Slack member IDs. Optionally set a home channel with a stable channel ID.
4. Select Save Slack, then use Start or Restart on the Gateway page.
5. Invite Maia to every permitted channel with /invite @Maia. Test a direct message and an @mention.

Configure Slack from the CLI

1. Run maia setup gateway and select Slack.
2. Enter the xoxb- bot token, xapp- app token, and allowed member IDs when prompted.
3. Start Maia in the foreground for the first test:

   maia gateway run

# <MAIA_HOME>/.env
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...
SLACK_ALLOWED_USERS=U01ABC2DEF3,U09TEAMLEAD
SLACK_HOME_CHANNEL=C01234567890

Use Slack for governed edit review

A Slack edit review works when gateway admission, Governance permissions, and conversation scope all match:

1. Add both the employee and the reviewer to SLACK_ALLOWED_USERS, then register their stable Slack member IDs in Governance → People. Admission lets them talk to Maia; Governance determines what each person can do.
2. Give the employee Write after approval on the target file or folder and select at least one named governed manager or administrator. The selected manager receives the path access needed to inspect and execute the reviewed edit; administrators already have global file access.
3. In a channel where Maia is present, have the employee @mention Maia with the edit request. Maia's review response uses the selected Slack member's native <@USER_ID> markup, and the employee may also tag that reviewer. Keep the employee, reviewer, and Maia in that same Slack thread.
4. After the thread session exists, the reviewer can reply in the thread without mentioning Maia again. Maia receives that reply as a new turn owned by the reviewer's authenticated Slack member ID.
5. Let the reviewer answer naturally. No word such as “approve” or “OK” has special authority: the reviewer may accept, reject, ask a question, or request a different edit. Every file-tool call is authorized again for the person who sent the current message.

Keep shared thread sessions enabled in <MAIA_HOME>/config.yaml (this is the default):

gateway:
  thread_sessions_per_user: false

For the matching file policy and the full authorization behavior, see Handle write confirmation.