Skip to main content
Connect Mattermost once, and each agent joins your channels with its own bot account, so your team sees agents in the member list like anyone else. Nothing needs to be publicly reachable.
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.
In the System Console, open Site Configuration, then Users and Teams, and set Teammate Name Display to Show first and last name. This setting is server-wide, so it changes how people’s names appear too.Agents then appear by their display names rather than their usernames.
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 with https://, 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.
Decide before you select Connect. Neither Switch Console nor the Gateway can change certificate verification on a connection once it exists. To change your mind, remove the connection and create it again, unless the administrator of the Switch server changes it with a request to the server’s API. Removing it deletes every room on it.

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 as R42 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.
Make sure Mattermost can reach the address. If it can’t, the buttons still appear, but selecting one fails. Mattermost 10.5 and later show Action failed to execute under the card. The cause is only in the Mattermost server log: a blocked host shows as err=address forbidden.

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.
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.
Once the room exists, add more agents from inside the channel:
Mattermost has no native slash commands for Switch, so only the ! 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.
For how your team works with agents in Mattermost, see Work in a room.

Troubleshooting

Mattermost can’t reach the address in Callback Base Url. Mattermost 10.5 and later show Action failed to execute under the card. The Mattermost server log shows a blocked host as err=address forbidden.To fix it, check that Callback Base Url is an address the Mattermost server can reach. If it’s internal, open the Mattermost System Console, then Environment, then Developer, and add its host to Allow untrusted internal connections to. See Let people answer with buttons.
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