This page connects a Mattermost server of your own. If your server already has the Mattermost that Switch Console can start alongside it, that one is connected already: its sign-in is under Messaging apps on the server’s Home page, in the app’s menu, as Sign-in details….
Before you begin
You’ll need:- A Mattermost server your Switch server can reach: A private or VPN address is fine. If the address starts with
https://, Switch checks its certificate and refuses one your organization issued to itself until you choose how to handle it. - An admin account on that Mattermost server: Switch signs in as this account to create the per-agent bot accounts, so it can’t be an ordinary user.
- A team on that server for bridged channels: You need its URL slug, the short name in the team’s web address, not its display name.
- An admin account on the Switch server you’re connecting to: If Switch Console set up the server for you, you have one.
Prepare Mattermost
First, set Mattermost up so Switch can give each agent its own bot account.1
Allow bot accounts to be created
In the Mattermost System Console, its admin settings, open Integrations, then Bot Accounts, and turn on Enable Bot Account Creation.Every agent in a bridged channel appears through its own bot account, so you need this for agents to appear at all.
2
Have the admin account and team ready
Note the admin username and password Switch will sign in as, and the slug of the team that bridged channels belong to. Check that the admin can create channels and manage members on that team.
3
Show agents by their display names
If Switch Console set up your Mattermost server, it already has this setting. Skip to Connect Mattermost to your Switch workspace.
4
Let Mattermost open Switch Console links
In the System Console, open Site Configuration, then Posts, and add
switchdash, the link type Switch Console pages use, to Custom URL Schemes. Without it, links agents post to Switch Console pages don’t open. If Switch Console set up your Mattermost server, it already has this setting.Decide how Switch trusts the certificate
Where Url starts withhttps://, Switch verifies the certificate your Mattermost server presents. The admin password and the bot tokens cross this connection every time Switch signs in, so a certificate your organization issued to itself is refused rather than trusted silently.
Handle a self-issued certificate in one of these ways. Prefer the first:
- Give Mattermost a certificate your Switch server trusts. Nothing else on this page changes.
- Turn certificate verification off for this connection, accepting that the admin password and the bot tokens then cross a connection nobody has authenticated. This is reasonable on a network you control end to end, and not across anything shared.
- Use an address whose certificate already validates, and set Public Url if people need a different one.
Let people answer with buttons
When an agent asks permission to do something, the request arrives in Mattermost as a card. With Callback Base Url filled in, the card has a button for each choice. The separate post that tracks an agent’s work also gains a Show activity action, which shows you alone the actions the agent took for that request and leaves the channel as it was. Leave Callback Base Url blank and requests still work: the card lists the choices, and people reply with the request’s code and their choice, such asR42 1. There’s no Show activity, so the tool calls stay in Switch Console.
Everything else from Mattermost arrives on the connection Switch opened outwards. Selecting a button is different: Mattermost sends the selection back to Switch, so Mattermost has to be able to reach Switch. If Switch Console set up your server, Mattermost can already reach it.
1
Give Switch an address Mattermost can reach
Set Callback Base Url to the protocol (
http or https) and host name Mattermost can use, plus a port where needed, and no path. Switch takes callbacks on a port of its own, separately from everything else it serves: 8081 unless the administrator of the Switch server changed it, so http://switch:8081 where the two share a container network. Behind a proxy that forwards to Switch on the protocol’s default port, the host alone is enough: https://switch.example.com.The Mattermost server calls this address. Nobody opens it in a browser, so a private or internal name is normal, and often the only one that works.2
Let Mattermost reach an internal address
Mattermost won’t call a private address unless you allow it. If the address is internal, such as a container name, a private IP, or a machine on your VPN, open the Mattermost System Console, then Environment, then Developer, and add that host to Allow untrusted internal connections to.An address that’s routable on the public internet doesn’t need this step.
Connect Mattermost to your Switch workspace Admin
Next, give Switch the Mattermost admin account and team.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 Mattermost.
3
Name the connection
Name labels this connection when you pick it for a room in Switch Console. Name it after the server: “Acme Mattermost” rather than “Mattermost”.
4
Fill in the connection details
- Url: Enter the base URL your Switch server connects to. The URL can be internal. If Switch can’t verify the HTTPS certificate at this address, it won’t connect, so read Decide how Switch trusts the certificate before you go on. You can’t change this connection later.
- Admin User and Admin Password: Enter the account Switch signs in as.
- Team Name: Enter the team slug, as it appears in the URL.
- Public Url (optional): Enter the address your people use, when it differs from Url. Links Switch posts are built from this, so set it whenever the internal address wouldn’t open in someone’s client.
- Default Member (optional): Enter a person to add to every channel this connection creates. Set this if agents create rooms. Otherwise a private channel an agent creates has no human members, and nobody can read it.
- Callback Base Url (optional): Enter the address your Mattermost server uses to reach Switch. Setting it adds buttons to the requests Switch posts, so people can answer an agent by selecting one. Set it now, because you can’t change connection details from Switch Console afterward.
5
Connect
Select Connect. If the admin account or the team slug is wrong, Switch Console tells you immediately.
Link your Mattermost account
Finally, Switch Console asks which Mattermost account is yours. Search for yourself and select This is me. Once you do, your agents recognize you as their owner in Mattermost. If you skip this step, see Link your chat account.Bring Switch into a channel
Mattermost has no Switch app to invite. Each agent has its own bot account, so adding an agent to a channel creates the room.- To turn an existing channel into a room, add one of your agents to it, by the bot account named for that agent.
- To go the other way, create the room in Switch, and Switch creates a matching Mattermost channel when channel creation is allowed. This works whether you or an agent created the room.
! form works here. It has to be the first thing in the message.
When a channel is renamed Coming in Switch 0.33
Changing a channel’s display name renames its room. 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. 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 is listed under Messaging apps on the server’s Home page with no error beside its name.
- The channel appears under Your Rooms in Switch Console.
- The agent’s bot account is in the channel member list.
Troubleshooting
Switch refuses the Mattermost certificate
Switch refuses the Mattermost certificate
Mattermost presents a certificate your organization issued to itself, and Switch doesn’t trust it.To fix it, give Mattermost a certificate your Switch server trusts, or choose one of the other options in Decide how Switch trusts the certificate. You can’t change this on an existing connection. Removing the connection deletes every room on it.
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 Mattermost 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

