Gateway › Slack

Slack

Overview

The workspace is the group, a channel is the topic. It connects over Socket Mode, so no public URL is needed.

Create the app from a manifest

display_information:
  name: agent-hub
features:
  bot_user: { display_name: agent-hub, always_online: true }
  slash_commands: [/agent, /ask, /scope, /project, /user]
oauth_config:
  scopes:
    bot: [app_mentions:read, channels:history, channels:read, groups:history,
          groups:read, im:history, im:write, mpim:history, chat:write,
          reactions:write, users:read, files:read, commands]
settings:
  event_subscriptions:
    bot_events: [message.channels, message.groups, message.im, message.mpim,
                 team_join, user_change, member_joined_channel]
  interactivity: { is_enabled: true }
  socket_mode_enabled: true

Field	Meaning
`socket_mode_enabled`	Events arrive over the bot’s own websocket.
`interactivity`	Button clicks (scope picker, approvals) reach the bot.
`im:write`	Opens a DM with a person (login link, private reply).
`reactions:write`	The 👀 mark once a message has been handed to an agent.
`team_join` / `user_change`	Registers new members, drops deactivated ones.
`member_joined_channel`	The bot is added to a channel → shows the scope picker.

Set up credentials

Install App to get the Bot User OAuth Token (xoxb-).
Basic Information → App-Level Tokens → scope connections:write to get the App-Level Token (xapp-).

On the web app Integrations page → Gateways → Create on the slack row: Bot token (xoxb-…), App token (xapp-…), Owner user id, then Enable. Skip the App token and Socket Mode can’t connect. Credentials are stored by agent-hub, not in .env.

For a default lane for messages with no resolvable target, open Settings on the Slack row of the Integrations page (Gateways card) and set Fallback target to slack:<team_id>:<channel_id>.

Usage

Commands start with ! (e.g. !agent status) — Slack drops unregistered / commands; see Chat commands.

You want to	Type
Run a command in a plain message	`!agent status` — Slack swallows messages starting with /, so use !
Send to a specific agent	`!dev fix the bug` or `@dev …`
Reply to an agent	Write inside that agent message’s thread
Hand off to another agent	`!b <text>` inside agent A’s thread
Log in to the web app	`!start login` in a DM with the bot

Invite the bot into each channel with /invite @agent-hub. Slash commands only run at the channel root; inside a thread use the !… form.