How to setup Matterbridge with Mattermost and Slack (and others!)

Table of Contents

This is a “how to” but more aimed at folks that understand straight forward instructions like “put this in /usr/bin” without needing someone to completely tell them how to mv file /usr/bin.

If you want to jump into the actual how to, click here.

A bit of history

When I was a young lad back in the early 2000’s, AIM and Yahoo! Chatrooms were all the rage. Sure, there was ICQ, MSN, and of course IRC, but unless you were a 1337h@X0r chatting with your 1337 friends, you were on the normie services to chat with the hotties and cool kids from your local scene. While those were the cooler places to be, I always wondered what it would be like to link everyone together in a harmonoious fashion. Enter Trillain.

Trillain

Trillain while not the only chat client bridge, it was one of the more popular for folks that just wanted things to “kinda work” out of the box. It wasn’t completely free, but most of the features young Caleb needed were so it wasn’t too terrible. I was actually unaware until writting this post that it is still being updated to this day (or at least for Windows as of 18 August 2023) which is kind of mind boggling! I thought most normies were on Facebook and Instagram which already bridge themselves 🧐

2020 and the plague of collaboration tools

When we all started working from home, chat tools became the big market share of the internet (not that they hadn’t been for teams already collabing, but more so since everyone was having to do it). Slack and Discord became house-hold names and some of use cool kids already knew about Mattermost. Some of use super nerds were still using IRC (I mean, IRC is literally the best communication platform for instant messaging, I’ll die on this hill) for day to day nerdy communications and keeping the back channels open between companies (think The Sum of All Fears) even when there isn’t a formal line of communication.

Needless to say, there has been a fight for the “one true messaging app” since messaging started. This is just a brief (albiet very, very truncated) history from yours truly on messaging apps from the early 2000’s to today. With no true winner of within the messaging realm, it appears we have a little while to go where things are fragmented due to company choices, purchasing influence, and collaberation needs.

MatterBridge to the rescue

Okay, so let’s get started on the actual meat and potatoes of this post. My company was split between users in our self-hosted Mattermost server and 5 (yes… f-i-v-e) different Slack servers. How do we bring the nerds together with the staff to fix issues when they’re all seperated? Easy. Matterbridge!

Matterbridge is a tool (written in Go) that allows you to chat on most any chat client software to any other client software through the aid of the Matterbridge bot. This is something you must host and configure, but it isn’t too terribly difficult.

Mattermost portion

To get your Mattermost portion working, you’ll need to be an admin/superuser on your instance. This is so you can create a dedicated user for the Matterbridge bot to utilize if that is how you add users to your install Mattermost.

Also, it is recommended to use keys instead of username/password for more security, but I’ll leave that portion to your personal taste. For us, we use keys.

User Screenshot

To start that process, you’ll need to create a Mattermost account for your bot. This can be done in so many different ways that it is hard to write a how to guide specifically for that process. We use Gitlab integration to MM, so I created a Gitlab user which is linked into our Mattermost, logged into that account, and created my key by clicking on the avatar in the top right hand corner, going to profile, then selecting security and Personal Access Tokens. You’ll need to create a new token.

Token Screenshot

Once you have that portion done, you can download Matterbridge to whatever Linux operating system you are utilizing. I usually just download the pre-compiled binary, put it in /usr/bin/ and chmod +x matterbridge so I can call it from anywhere in the system. You will need either root or sudo to do that portion.

Mattermost Config in matterbridge.toml

Here is the Mattermost portion of the matterbridge.toml file. Change it to suit your needs, but if you have a co-worker that already setup a server (hello Marilyn!), it may already be in place.

For the rest of you, copy and paste this into a matterbridge.toml file and place it somewhere easy to find like /opt/matterbridge

[mattermost.companysysadmin]
#The mattermost hostname. (do not prefix it with http or https)
Server="mattermost.company.org:443"
#the team name as can be seen in the mattermost webinterface URL
#in lowercase, without spaces
Team="sysadmins"
Token="MATTERMOSTKEY"
RemoteNickFormat="[{PROTOCOL}] <{NICK}> "
PrefixMessagesWithNick=true
PreserveThreading=true

After you have this in place, make sure your newly created bot user is in the channel that you would like to monitor. There is more config for that but we’ll get there later.

The Slack portion

It’s important that you create a Slack App (Classic). Don’t use the Create New App button, and don’t opt in to the granular permissions feature.

Okay, same drill except different. For Slack, you have to create an actual bot using the API. To do this, you’ll navigate to Slack’s Your Apps page and log into an account that you can add a bot to without issues. Admin rights are suggested, but I was able to complete this without them. Not sure if that’s cool or not, but screw it, if it works it works!

Slack App Creation

Use THIS LINK to create a Slack App (Classic). Choose any name for your app and select the desired workspace, and then submit. ⚠️ USE THE LINK AND DON’T CLICK THE Create New App BUTTON.

Slack Classic App

Navigate to the App Home page via the menu on the left. Click Add Legacy Bot User, fill in the bot’s details, and submit.

Slack App Home

Granting Scopes

Now we’re gonna give our bot a few scopes to give it access to the features it will need in order to pass our messages between our servers.

In your Slack App (Classic) app page, click on OAuth & Permissions on the left, scroll to Scopes but *DO NOT click Update Scopes. Instead, click Add an OAuth Scope

Add the following scopes:

    Modify your public channels (channels:write)
    Send messages as <App name> (chat:write:bot)
    Send messages as user (chat:write:user)
    Access users profile and workspace profile fields (users.profile:read)

Slack Scopes

Scroll to the top of that same OAuth & Permissions page and click the Install to Workspace button. The next page, click Allow. You’ll be taken to the creditials page where you’ll find your Bot User OAuth Token. Copy that and keep it safe.

Slack Config in matterbridge.toml

This will need to be modified by all (sorry Marilyn) to suit your setup. Simply add the below to the end of the matterbridge.toml file we created last time directly under the Mattermost config:

[slack]
[slack.companyslack]
Token="SLACKKEY"
RemoteNickFormat="{BRIDGE} - @{NICK}"
# this will maps threads from other bridges on slack threads
PreserveThreading=true

Go back to your Slack and invite the bot user to whichever channel you want it to monitor (much like our Mattermost setup) by entering the channel and processing a /invite @<botname>. If you want to do this for multiple channels, you can, but you will have to setup a bridge for each channel from Slack to MM.

Let’s make it all work

So the rest of this process is basically linking the two services. It’s pretty straight forward. To do this, we will setup a gateway. I named mine slack2mm since I also can create one for our OLD XMPP service sometime if anyone really wanted me to…

Then we’re basically setting our accounts up as a gateway.inout for both Mattermost and Slack. Note: you can setup one to just output to the other, but my use case does not need that. Simply just make one gateway.in and the other gateway.out.

The below code is pretty easy to understand, you set the account from earlier, put in the channel you want to share in between them, and save it. Make sure to set it up for each service you want to share it with. You can have as many back and forth with the SAME channel as you can code:

[[gateway]]
name="slack2mm"
enable=true

[[gateway.inout]]
account="mattermost.companysysadmin"
channel="general-chatter"

[[gateway.inout]]
account="slack.companyslack"
channel="general"

Bringing it all together

The full code:

[mattermost.companysysadmin]
#The mattermost hostname. (do not prefix it with http or https)
Server="mattermost.company.org:443"
#the team name as can be seen in the mattermost webinterface URL
#in lowercase, without spaces
Team="sysadmins"
Token="MATTERMOSTKEY"
RemoteNickFormat="[{PROTOCOL}] <{NICK}> "
PrefixMessagesWithNick=true
PreserveThreading=true

[slack]
[slack.companyslack]
Token="SLACKKEY"
RemoteNickFormat="{BRIDGE} - @{NICK}"
# this will maps threads from other bridges on slack threads
PreserveThreading=true

[[gateway]]
# main gateway
name="slack2mm"
enable=true

[[gateway.inout]]
# mattermost gateway
account="mattermost.companysysadmin"
channel="general-chatter"

[[gateway.inout]]
# slack gateway
account="slack.companyslack"
channel="general"

As an added bonus, I build a systemd service for my install at work so when I reboot our system, it automatically starts matterbridge back up! Here’s the code for that, modify it to your needs and file locations. Place this script in /etc/systemd/system/matterbridge.service:

[Unit]
Description=Matterbridge daemon
After=network-online.target

[Service]
Type=simple
ExecStart=/usr/bin/matterbridge -conf /opt/matterbridge/matterbridge.toml
Restart=always
RestartSec=5s
User=root

[Install]
WantedBy=multi-user.target

Do a systemd enable matterbridge and systemd start matterbridge then you should be golden Ponyboy. Should you have any questions on how to configure other services, please consult the Matterbridge Wiki. For anything post specific, comment below.