Configure the gateway

The gateway connects Maia to Discord, Slack, Telegram, WhatsApp, Mattermost, Matrix, and other messaging platforms. Gateway admission and Maia governance are separate gates.

Understand the two identity gates

A newly admitted user who is not the bootstrap administrator remains Pending Governance. The user cannot send normal messages to Maia until an administrator creates a governance record with at least one role.

Choose a platform guide

Slack and Discord have dedicated setup guides in the documentation menu. Each guide covers app creation, credentials, platform permissions, allowlists, first-run testing, and both supported configuration paths.

• Connect Slack with Socket Mode, an xoxb- bot token, and an xapp- app token.
• Connect Discord with a bot application, gateway intents, and stable user or role IDs.

Configure with the dashboard or CLI

Configure a channel

1. Open Maia's local dashboard and select Gateway.
2. Select the platform and enter its bot credentials through the secret-aware fields.
3. Add the first administrator identity and save. On a fresh installation, Maia can bootstrap only this first identity as an administrator.
4. Start or restart the gateway.
5. Send a private test message from the administrator account.

Configure Slack step by step

Slack is the recommended corporate starting point when your company already uses a Slack workspace. Socket Mode lets Maia connect outward over WebSocket, so you do not need to expose a public webhook endpoint.

1. After installing Maia, generate its Slack app manifest:

   maia slack manifest --write

   The manifest includes Maia's required bot scopes, Socket Mode settings, event subscriptions, and slash commands.
2. Open Slack API Apps, select Create New App, choose From an app manifest, select your workspace, and paste the generated manifest.
3. Open OAuth & Permissions and verify these 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 if Maia must discover private channels.
4. Open Socket Mode, enable it, and create an app-level token with the connections:write scope. Copy the token beginning with xapp-; Maia stores it as SLACK_APP_TOKEN.
5. Open Event Subscriptions and subscribe the bot to message.im, message.channels, message.groups, and app_mention. Missing message.channels or message.groups is the usual reason a bot works in direct messages but not in channels.
6. Open App Home, enable the Messages Tab, and allow users to send messages from that tab. Without this setting, Slack can block direct messages even when the tokens and scopes are correct.
7. Install the app to the workspace. Copy the Bot User OAuth Token beginning with xoxb-; Maia stores it as SLACK_BOT_TOKEN. Reinstall the app whenever you change scopes, events, or slash commands.
8. In Slack, open each permitted person's profile, select the more-actions menu, and copy their member ID. Use IDs such as U01ABC2DEF3, not display names.
9. Run the guided Maia setup and select Slack:

   maia setup gateway

   Enter the xoxb- bot token, the xapp- app token, and the allowed member IDs when prompted.
10. Start Maia in the foreground for the first test:

    maia gateway run

    In each Slack channel where Maia must respond, run /invite @Maia. Send Maia a direct message, then test an @mention in an invited channel.

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

Configure Discord step by step

Discord uses a bot application. A working setup requires the correct gateway intents, an invite with the correct scopes and permissions, and stable user or role IDs for admission.

1. Open the Discord Developer Portal, select New Application, name the application, and create it.
2. Open Bot. Create or reset the bot token and copy it immediately. Store it only in Maia's secret-aware Gateway form or <MAIA_HOME>/.env; never commit it to source control.
3. Still under Bot, enable Message Content Intent so Maia can read messages. Enable Server Members Intent so Maia can resolve members and use role-based admission. Save the changes.
4. Open Installation and configure a Guild Install, or use the OAuth2 URL generator. Select the bot and applications.commands scopes.
5. Grant at least View Channels, Send Messages, Read Message History, Attach Files, and Send Messages in Threads. Add Embed Links and Add Reactions for Maia's full response experience.
6. Open the generated install link, choose your server, and authorize the bot. You must have permission to manage that server. The bot can remain offline until the Maia gateway starts.
7. In Discord, open User Settings > Advanced and enable Developer Mode. Right-click your username and select Copy User ID. Copy role and channel IDs the same way if you plan to use role admission or a home channel.
8. Run the guided Maia setup and select Discord:

   maia setup gateway

   Enter the bot token and at least one allowed user ID. Use an allowed role ID only when every intended member of that role will receive Maia governance.
9. Start Maia in the foreground for the first test:

   maia gateway run

   Send the bot a direct message. In a server channel, @mention Maia unless you deliberately configured that channel for free response.

# <MAIA_HOME>/.env
DISCORD_BOT_TOKEN=...
DISCORD_ALLOWED_USERS=284102345871466496,198765432109876543
# Or admit members by Discord role:
DISCORD_ALLOWED_ROLES=123456789012345678
DISCORD_HOME_CHANNEL=234567890123456789

# Optional behavior controls
DISCORD_REQUIRE_MENTION=true
DISCORD_FREE_RESPONSE_CHANNELS=234567890123456789
DISCORD_IGNORED_CHANNELS=345678901234567890
DISCORD_AUTO_THREAD=true

Add another user

1. Add or pair the user's platform identity in Gateway.
2. Follow the Pending Governance link shown for that identity.
3. In Governance → People, assign at least one role and any required teams.
4. Ask the user to send /whoami to verify the mapping.
5. Test one allowed action and one action that should be denied.

Operate the gateway service

maia gateway status
maia gateway restart
maia logs --follow

Exact service-management commands can vary by platform. Use maia status and maia doctor when the gateway does not start.

Avoid shared bot credentials

If Maia and upstream Hermes run on the same machine, use distinct bot credentials. Configuring the same Discord, Telegram, or other bot in both gateways can produce competing or duplicate replies.