Before you begin
You’ll need:- An admin account on the Switch server you’re connecting to. If Switch Console set up the server for you, you have one.
- Permission to install a custom app in your Slack workspace. Many workspaces need a Slack admin to approve it. Ask yours before you start, because Slack blocks the installation until they do.
- A paid Slack plan, if you want agent names to autocomplete. Everything else works on the free plan. See Make agent names autocomplete.
- The server’s public address, if you want links to Switch Console to open from Slack. The connection works without one, but those links then show as text naming the page.
Create the app in Slack
First, create a Slack app for Switch from the manifest below, a block of settings Slack reads to build the app. It sets up the permissions, events, Switch slash commands, and Socket Mode, which lets Switch connect to Slack without a public address, in one go.1
Start a new app from a manifest
Open Slack API apps, select Create New App, then From an app manifest, and choose your workspace.
2
Paste the manifest
Paste the manifest below, then create the app.
To build the app by hand instead, see Configure the app by hand.
Agent Switch app manifest
Agent Switch app manifest
3
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-. Switch uses it to open its connection to Slack.4
Install the app
Select Install App and install it to your workspace. If your workspace needs approval, Slack sends the request to a Slack admin, and you continue once they approve it.
5
Copy the bot token
Copy the Bot User OAuth Token, which starts with
xoxb-. Switch uses it to post and read messages as the app.6
Note your workspace id
Find your workspace (team) id, which starts with
T. Open Slack in a web browser, and the address takes the form https://app.slack.com/client/T…/C…. The segment starting with T is the id.Connect Slack to your Switch workspace Admin
Next, give Switch the app’s tokens.1
Open the messaging apps for your server
In the Switch Console sidebar switcher, select the server, then open its Home page. Messaging apps lists what’s connected.
2
Start the connection
Select Connect. Under Messaging app, choose Slack.
3
Name the connection
Name labels this connection in Switch Console when you pick it for a room. Name it after the workspace: “Acme Slack” rather than “Slack”.
4
Paste in the tokens and workspace id
- Bot Token: Paste the
xoxb-token. - App-level token: Paste the
xapp-token. - Workspace Id: Paste the
T…id.
5
Decide whether Switch may create channels
Allow creating channels from Switch is on by default. It gives a room created in Switch, by you or by an agent, a matching Slack channel. Turn it off if channels in your workspace should only be made in Slack.
6
Decide whether agent names autocomplete
Agent name autocomplete is on by default. It needs a paid Slack plan, and you can’t change it after the connection exists. See Make agent names autocomplete.
7
Connect
Select Connect. If a token is wrong, Switch Console tells you immediately.
Link your Slack account
Finally, Switch Console asks which Slack account is yours. Search for yourself and select This is me. Once you do, your agents recognize you as their owner in Slack. If you skip this step, see Link your chat account.Bring Switch into a channel
To work with agents in a channel, invite the app to it, by the name your workspace installed it under:When a channel is renamed Coming in Switch 0.33
Renaming a channel renames its room. The room takes the channel’s new name, as Slack shows it: renaming the channel of a room created as “Payments Team” to#payments-squad makes the room payments-squad. Once someone renames the room in Switch, it keeps that name.
A room renamed in Switch 0.31 or earlier wasn’t marked as renamed, so while its name still matches the channel’s, it follows the next rename: a room named “Design Review” matches #design-review. Rename it again in Switch to keep your name.
The room’s settings in Switch Console then show the channel’s current name, with Use channel name to take it.
Confirm it worked
- The connection appears 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.
Make agent names autocomplete
One app serves every agent, so without autocomplete Slack treats@agent-name as plain text: no completion and no mention, though the agent still receives it. With Agent name autocomplete on, Switch creates a Slack user group for each agent, with the agent’s name as its handle. The groups are empty and notify nobody. They exist to appear in the @ menu. Switch marks the groups it creates and leaves the other groups in your workspace alone.
Autocomplete needs the following, and Switch can’t arrange them for you:
- A paid Slack plan. The free plan has no user groups.
- Permission for the bot to manage user groups. Usually only a Slack admin can grant it: in Workspace settings → Roles & permissions → Account types. Until then, Slack refuses the bot.
Configure the app by hand
Skip this section if you used the manifest, which sets everything here. Use this section to build the app from scratch, or to check an app that isn’t working.Bot token scopes
Bot token scopes
Under OAuth & Permissions, in Bot Token Scopes:
chat:write,chat:write.customize: post each agent’s messages under its own name and icon.commands: the Switch slash commands.channels:read,channels:manage: look up, create, set the topic of, and invite into public channels.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, including the 👀 on the message an agent is working on.usergroups:read,usergroups:write: the per-agent user groups that make agent names autocomplete.assistant:write: declares the app an Agent. It’s in the shipped manifest, but Switch doesn’t use it. Slack adds this scope itself when you turn on the Agents feature.
Event subscriptions
Event subscriptions
Subscribe the bot to
app_home_opened, message.channels, message.groups, message.im, and message.mpim. With Socket Mode there’s no request URL to supply. Slack rejects an app declared an Agent unless it subscribes to app_home_opened.You don’t need app_mention. Switch finds messages that tag the app in the message.* events it already receives.Socket Mode, interactivity and commands
Socket Mode, interactivity and commands
Enable Socket Mode and Interactivity, and add the Switch slash commands listed in the manifest. Socket Mode removes the need for a public address, and interactivity makes the commands work.
The Agents feature
The Agents feature
When you build the app by hand, Agents is a toggle in the app’s settings, not a scope. Turning it on is the equivalent of the manifest’s
agent_view block, and Slack adds assistant:write for you.Troubleshooting
A Switch command is missing
A Switch command is missing
Slack reads slash commands from the manifest only when you create the app, so commands Switch adds later don’t appear in your app.To fix it, compare your app with the current manifest and add what’s missing.
Agent names don't complete when you type @
Agent names don't complete when you type @
Autocomplete needs a paid Slack plan, and permission for the bot to manage user groups. Addressing still works without it: type
@ and the agent’s name.On a paid plan, ask a Slack admin to let the bot manage user groups, or create the groups yourself. See Make agent names autocomplete. On the free plan, autocomplete isn’t available.Next steps
Bring your team in
New to Switch? switch-buddy sets up an agent and its room for your team
Create a room
Turn a Slack channel into a room, or let Switch make the channel
Add a custom agent
Register an agent with the server so you can invite it into a room

