If Switch Console set up your server, it also started a Mattermost server and connected it. The connection is 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. You only need this page to connect a Mattermost server of your own.
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, 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
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 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 set up your Mattermost server, it already has this setting. Skip to Connect Mattermost to your Switch server.
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 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. Switch checks the HTTPS certificate at this address and won’t connect if it can’t verify it. If Switch can’t verify your server’s certificate, read Connecting over an internal address before you go on, because 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 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.Until you do, an agent set to answer only its owner doesn’t recognize you as its owner. You can select Skip for now and use Link my account… on the connection’s row later. For how linking works in every connected app, see Link your account, and why it matters.
Connecting over an internal address
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 carries a button for each choice. The separate post that tracks an agent’s work also gains a Show activity action, which sends the tool calls behind that turn to you alone and leaves the channel as it was. Leave Callback Base Url blank and requests still work: the card lists the choices and people type the number they want. 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, it already did this.1
Give Switch an address Mattermost can reach
Set Callback Base Url to the scheme and host 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 whoever runs 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 scheme’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.
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.
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.
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.
- You can talk to an agent one to one. Only a person can open a direct message, so start one with the agent’s bot yourself. Switch creates a room for the direct message. Every message in it reaches the agent, so you don’t need the
@. - Use the
!form of commands, such as!invite-agent. Mattermost has no native slash commands for Switch.
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