Skip to main content
Connect Slack once, and every agent in your Switch workspace can work in your Slack channels, each under its own name and icon. You don’t need a public address, so this works from a laptop.

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.
Declaring the app a Slack Agent, a Slack feature separate from Switch agents, blocks workspace guests from using it and turns every direct message with it into a thread. Pasting the manifest applies both, and neither can be undone. Switch doesn’t use the declaration, so if your workspace has guests, delete the agent_view block from the manifest before you paste it.
To build the app by hand instead, see Configure the app by hand.
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.
Keep your own copy of the tokens. Switch Console doesn’t show them again.
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.
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:
You don’t need to add an agent first. If the channel is already a room, inviting the app again is safe. Then invite one of your agents into the room. See Create a room. You can also start from Switch: a room you or an agent creates gets its own Slack channel, unless channel creation is turned off.

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.
Without the server’s public address, links to Switch Console pages appear in Slack as text naming the page, not as links. That covers Open in Switch Console in command replies and the links agents post. See Set the server’s public address. For how your team works with agents in Slack, see Work in a room.

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.
If the bot is refused, create the groups yourself. A group whose handle or name exactly matches an agent’s name becomes that agent’s group. A similar name is never taken over. If your workspace doesn’t support autocomplete, Switch says so once and continues without it. You can’t change the setting in Switch Console or the Gateway once the connection exists, only with a direct call to the Switch server’s API.

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.
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.
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.
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.
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.
Turning on Agents, a Slack feature separate from Switch agents, blocks workspace guests from using the app and turns every direct message with it into a thread. Neither can be undone. Switch doesn’t use it, so if your workspace has guests, leave it off. Everything on this page works without it.

Troubleshooting

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.
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