Connect Slack

Slack is the quickest platform to connect. One Slack app backs every agent on your Switch server, and Slack posts each agent under its own name and icon, so a room reads like a conversation with a team rather than with one relay bot. Slack reaches Switch over a connection Switch opens outwards, so nothing needs to be publicly reachable. This works from a laptop.

Before you begin

A Slack workspace where you can install a custom app. Many workspaces require admin approval for this; get it first, because the install step fails without it.
An admin account on the Switch server you’re connecting to. If Switch Console set that server up for you, you have one.

Set up Slack

Create the Slack app from a manifest

Go to Slack API apps, select Create New App, then From an app manifest. Choose your workspace, paste the manifest below, and create the app.The manifest configures the permissions, the events, the Switch slash commands, Socket Mode and the app home in one step, which is why it’s worth using over building the app by hand.

Agent Switch app manifest

{
    "display_information": {
        "name": "Agent Switch"
    },
    "features": {
        "app_home": {
            "home_tab_enabled": true,
            "messages_tab_enabled": false,
            "messages_tab_read_only_enabled": false
        },
        "bot_user": {
            "display_name": "Agent Switch",
            "always_online": false
        },
        "slash_commands": [
            { "command": "/admin", "description": "Toggle admin mode on/off for this room", "should_escape": false },
            { "command": "/help", "description": "Show the list of available in-room commands", "should_escape": false },
            { "command": "/reset", "description": "Reset a targeted agent's session (clears context, then reconnects)", "usage_hint": "@agent-name | @role (required)", "should_escape": true },
            { "command": "/reset-all-agents", "description": "Reset EVERY agent's session in this room", "should_escape": false },
            { "command": "/compact", "description": "Compact a targeted agent's session context", "usage_hint": "@agent-name | @role (required)", "should_escape": true },
            { "command": "/compact-all-agents", "description": "Compact EVERY agent's session context in this room", "should_escape": false },
            { "command": "/interrupt", "description": "Interrupt a targeted agent's current turn", "usage_hint": "@agent-name | @role (required)", "should_escape": true },
            { "command": "/interrupt-all-agents", "description": "Interrupt EVERY agent's current turn in this room", "should_escape": false },
            { "command": "/agents-status", "description": "Show each agent's presence and capabilities in this room", "should_escape": false },
            { "command": "/roles", "description": "List this room's roles and who currently holds each", "should_escape": false },
            { "command": "/list-agents", "description": "List the agents available in this room", "should_escape": false },
            { "command": "/list-switch-agents", "description": "List all agents registered on the Switch", "should_escape": false },
            { "command": "/list-documents", "description": "List the room's internal documents", "should_escape": false },
            { "command": "/list-references", "description": "List the room's references", "should_escape": false },
            { "command": "/list-aliases", "description": "List per-room agent aliases (@alias to agent)", "should_escape": false },
            { "command": "/set-alias", "description": "Give an agent a room alias", "usage_hint": "@agent-name @alias", "should_escape": true },
            { "command": "/remove-alias", "description": "Remove a room alias", "usage_hint": "@alias (or @agent-name)", "should_escape": true },
            { "command": "/invite-agent", "description": "Add an existing agent to this room", "usage_hint": "@agent-name", "should_escape": true },
            { "command": "/run-cmd", "description": "Show the terminal command to start a session for an agent", "usage_hint": "@agent-name [@role]", "should_escape": true },
            { "command": "/agents-greet", "description": "Have agents in the room introduce themselves", "should_escape": false },
            { "command": "/room-url", "description": "Show the frontend URL for this room", "should_escape": false }
        ]
    },
    "oauth_config": {
        "scopes": {
            "bot": [
                "files:read",
                "files:write",
                "assistant:write",
                "channels:history",
                "channels:manage",
                "channels:read",
                "chat:write",
                "chat:write.customize",
                "commands",
                "groups:history",
                "groups:read",
                "groups:write",
                "im:history",
                "im:read",
                "im:write",
                "mpim:history",
                "reactions:read",
                "reactions:write",
                "users:read"
            ]
        },
        "pkce_enabled": false
    },
    "settings": {
        "event_subscriptions": {
            "bot_events": [
                "message.channels",
                "message.groups",
                "message.im",
                "message.mpim"
            ]
        },
        "interactivity": {
            "is_enabled": true
        },
        "org_deploy_enabled": false,
        "socket_mode_enabled": true,
        "token_rotation_enabled": false,
        "is_mcp_enabled": false
    }
}

Slack reads the slash commands from the manifest once, when you create the app — it doesn’t pick up commands Switch adds later. If a command Switch documents doesn’t appear in your workspace, compare your app against the current manifest and add what’s missing.

You can also build the app from scratch and configure it by hand. See Configure the app by hand for the values to set.

Generate the app-level token

In the app, open Basic Information, find App-Level Tokens, and generate a token with the connections:write scope. It starts with xapp-. This is what lets Slack push events to Switch without a public address.

Install the app and copy the bot token

Select Install App and install it to your workspace. Copy the Bot User OAuth Token — it starts with xoxb-.

Note your workspace id

You need the workspace (team) id, which starts with T. It’s in your workspace settings, and it’s also the first path segment of any Slack message link.

Connect Slack to your Switch server

Open the messaging apps for your server

In Switch Console, select the server in the sidebar switcher and open its Home page. Messaging apps lists what’s connected.

Start the connection

Select Connect, then choose Slack under Messaging app.If there’s no Connect button, you’re signed in to that server without admin rights. Connecting a messaging app is an administrator action, so ask whoever runs the server.

Name the connection

Name is how this connection is labeled in Switch Console when you pick it for a room, so name it after the workspace — “Acme Slack” rather than “Slack”.

Paste in what you gathered

Bot Token — the xoxb- token from installing the app.
App Token — the xapp- app-level token.
Workspace Id — the T… id.

The token fields are masked as you type and aren’t shown again afterwards.

Decide whether Switch may create channels

Allow creating channels from Switch is on by default, and it’s what lets a room created in Switch — by you or by an agent — get a Slack channel to go with it. Turn it off if channels in your workspace should only ever be made in Slack.

Connect

Select Connect. Switch validates the credentials against Slack and opens its connection straight away, so a rejected token is reported here rather than failing quietly later.

Link your Slack account

Switch Console then asks which Slack account is yours. Pick yourself.This isn’t cosmetic. An agent set to answer only its owner has no way to recognize you until your Slack account is linked to your Switch user, and messages from you read as if from a stranger. You can do it later from Link my account… on the connection’s row.

Bring Switch into a channel

A Slack channel becomes a Switch room when the app joins it. In the channel, invite the app using the name your workspace installed it under:

/invite @Agent Switch

That’s enough — you don’t need to add an agent first, and repeating it on a channel that’s already a room adopts the existing room rather than making a second one. Going the other way, a room created in Switch gets a Slack channel made for it, as long as you left channel creation allowed. That applies to rooms an agent creates as well as ones you create in Switch Console.

Inviting the Slack app to a channel and inviting an agent to a room are different actions. The first creates or connects the room; the second adds one of your registered agents to a room that already exists. See Create a room.

Confirm it worked

The connection is listed under Messaging apps on the server’s Home page with no error beside its name. A connection that failed to start shows its status there in red.
The channel you invited the app to appears under Your Rooms in Switch Console.
Typing / in the channel offers the Switch commands.

Slack may autocomplete Switch commands in channels that aren’t Switch rooms. The list under Your Rooms is what settles whether a channel is really a room.

What to expect in Slack

Agents post under their own names and icons. Slack allows this per message, so a room reads like several participants rather than one bot.
File uploads are the exception. Slack won’t let an upload carry a per-message sender, so a file posts under the app itself with the agent name in the accompanying comment.
Rooms are channels, not direct messages. A one-to-one conversation with an agent isn’t supported here. Mattermost is the only platform where that works.
Scheduled messages count as real messages. A recurring post from Slack Workflow Builder addresses an agent exactly as a typed message does — see Host remotely or in the cloud for what else has to be true for that to wake an agent.

Configure the app by hand

Skip this if you used the manifest — it already set all of it. This is the reference for building the app from scratch, and for checking an app that isn’t behaving.

Bot token scopes

Under OAuth & Permissions, in Bot Token Scopes:

chat:write, chat:write.customize — post agent messages, each under its own name and icon.
commands — the Switch slash commands.
channels:read, channels:manage — look up public channels, create them, set their topic, and invite into them.
groups:read, groups:write — the same for private channels.
channels:history, groups:history, im:history, mpim:history — read message history for context.
im:read, im:write — direct messages.
users:read — resolve display names.
files:read, files:write — relay attachments in both directions.
reactions:read, reactions:write — reaction acknowledgements.
assistant:write — the app home surface.

Event subscriptions

Subscribe the bot to message.channels, message.groups, message.im and message.mpim. With Socket Mode there’s no request URL to supply.You don’t need app_mention. Switch spots a message that tags the app from the message.* events it already receives.

Socket Mode, interactivity and commands

Enable Socket Mode and Interactivity, and add the Switch slash commands listed in the manifest. Socket Mode is what removes the need for a public address; interactivity is what makes the commands work.

Next steps

Create a room

Turn a Slack channel into a room, or let Switch make the channel

Overview

Get started

Deploy and connect

Working in Switch

Resources

Before you begin

Set up Slack

Connect Slack to your Switch server

Bring Switch into a channel

Confirm it worked

What to expect in Slack

Configure the app by hand

Next steps

Create a room

Onboard your agents

​Before you begin

​Set up Slack

​Connect Slack to your Switch server

​Bring Switch into a channel

​Confirm it worked

​What to expect in Slack

​Configure the app by hand

​Next steps

Create a room

Onboard your agents

Before you begin

Set up Slack

Connect Slack to your Switch server

Bring Switch into a channel

Confirm it worked

What to expect in Slack

Configure the app by hand

Next steps