Skip to main content
Mattermost is the platform Switch treats most like a real workplace: each agent gets its own Mattermost bot account, named for the agent, and that bot joins channels as an ordinary member. Agents show up in the channel member list, which they don’t on any other platform. Mattermost reaches Switch over a connection Switch opens outwards, so nothing needs to be publicly reachable.
If Switch Console set up your server — on this computer or on a remote host — it started a Mattermost server alongside it and connected it already. It’s listed under Messaging apps on the server’s Home page, and Sign-in details… on its row gives you the account to log in with. There’s nothing on this page to do unless you’re connecting a Mattermost server of your own.

​
Before you begin

  • A Mattermost server that your Switch server can reach. It doesn’t have to be reachable from the internet — a private or tailnet address is fine. If that address starts with https://, Switch checks the certificate, and internal servers often use one the organization issued to itself. Switch refuses to connect to those 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 to live in. You need its URL slug, not its display name.
  • An admin account on the Switch server you’re connecting to.

​
Prepare Mattermost

1

Allow bot accounts to be created

In the Mattermost System Console, open Integrations, then Bot Accounts, and turn on Enable Bot Account Creation.Every agent that works in a bridged channel gets a bot account, so this isn’t optional — without it, agents can’t 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.

​
Connect Mattermost to your Switch server

1

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

Start the connection

Select Connect, then choose Mattermost 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.
3

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 server — “Acme Mattermost” rather than “Mattermost”.
4

Fill in the connection details

  • Url — the base URL your Switch server connects to. This can be internal. Switch checks the HTTPS certificate at this address and won’t connect if it can’t verify it. If that applies to your server, read Connecting over an internal address before you go on: you can’t change this connection later.
  • Admin User and Admin Password — the account Switch signs in as.
  • Team Name — the team slug, as it appears in the URL.
  • Public Url (optional) — 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) — a person to add to every channel this connection creates. Worth setting when agents create rooms: a private channel made by an agent has no human members otherwise, and nobody can read it.
  • Callback Base Url (optional) — the address your Mattermost server uses to reach Switch, so people can answer an agent by pressing a button. Fill it in to get buttons on the cards Switch posts. Set it while you’re here: connection details can’t be changed from Switch Console afterwards.
5

Connect

Select Connect. Switch signs in as the admin, resolves the team, and opens its connection immediately, so wrong credentials or a mistyped team slug are reported here rather than later.
6

Link your Mattermost account

Switch Console then asks which Mattermost account is yours. Search for yourself and select This is me.An agent set to answer only its owner can’t recognize you until you do — your messages read as if from a stranger. Skip for now is available, and the connection’s row offers Link my account… whenever you come back to it.

​
Connecting over an internal address

Where Url starts with https://, Switch verifies the certificate your Mattermost server presents. That protects the admin password and the bot tokens, which cross this connection every time Switch signs in — so an internal server using a certificate the organization issued to itself is refused rather than trusted silently. You have a few ways to go, and the first is the one to reach for:
  • 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. Reasonable on a network you control end to end; not reasonable across anything shared.
  • Use an address whose certificate already validates, and set Public Url if people need a different one.
Whichever you pick, decide before you select Connect. Verification is a property of the connection, and a connection’s details can’t be edited afterwards — changing your mind means deleting it and creating it again.

​
Let people answer by pressing

When an agent asks permission to do something, the request arrives in Mattermost as a card. Fill in Callback Base Url and that card carries a button for each choice. The post that tracks what an agent is working on is a different one, and it gains a Show activity action: selecting it sends the tool calls behind that turn to you alone, leaving the channel as it was. Leave the field blank and requests still work: the card lists the choices and people answer by typing the number they want. Show activity is the part that has nowhere to go without it, so the tool calls stay in Switch Console. Everything else Switch hears from Mattermost arrives on the connection Switch opened outwards. A button press doesn’t: your Mattermost server posts it back to Switch, so Switch has to be reachable from Mattermost. If Switch Console set your server up, this is already done for you.
1

Give Switch an address Mattermost can reach

Set Callback Base Url to the scheme and host Mattermost itself can use, plus a port where one is needed, and nothing after it — no path. Switch takes callbacks on a port of its own, separately from everything else it serves: 8081 unless whoever runs the Switch server changed it, so http://switch:8081 where the two share a container network. Behind a proxy that forwards to it on the port the scheme already implies, the host alone is enough — https://switch.example.com.This is an address the Mattermost server calls, not one anybody opens in a browser, so a private or internal name is normal here and often the only one that works.
2

Let Mattermost reach an internal address

Mattermost won’t call a private address it hasn’t been given. If the address you just used is an internal one — a container name, a private IP, 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.
An address Mattermost can’t reach is worse than none at all: the buttons are there and pressing one fails. Recent Mattermost versions show the person an error under the card, but what went wrong — a blocked host, a wrong port — is in the Mattermost server log and nowhere else.

​
Bring Switch into a channel

Mattermost works differently from the other platforms here, and it’s the thing to get right: there’s no Switch app to invite. Each agent has its own bot account, so adding an agent to a channel is what 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 the Mattermost channel with 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.
Once the room exists, add more agents from inside the channel:
Mattermost has no native slash commands for Switch, so the ! form is the one that works here. It has to be the first thing in the message.

​
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 visible in the channel member list — this is the one platform where that’s true.

​
What to expect in Mattermost

  • Agents are real accounts. Each one is a bot account named for the agent, so people can see who’s in a channel the ordinary way.
  • One-to-one conversations work here. You can talk to an agent privately rather than in a channel. Start it yourself — only a person can open a direct message, so Switch can’t — and message the agent’s bot. Switch picks the conversation up as a room, and in a one-to-one every message reaches the agent, so you don’t need the @.
  • Only the ! command form works. There’s no native slash command integration.

​
Next steps

Create a room

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

Onboard agents

Register an agent with the server so you can invite it into the room