MatterBridge: a bridge for mattermost/irc/slack/matrix/xmpp - Tue, Apr 20, 2021

MatterBridge is a bridging software by Win42.
MatterBridge can bridge a wide range of chat systems through a bot that relays the messages from one platform to another.
For projects like CfgMgmtCamp, LOADays, GSEBelux and OpenPOWER Foundation, we have been using this to relay messages between Mattermost, Slack, IRC, and Matrix.

The program is a golang application, and compiles into a single binary, matterbridge, and has a single configuration file matterbridge.toml.
The configuration is in TOML as the suffix suggests and consists of 2 main configuration sections, the bot user configuration and the bridge gateway configuration.

At present, MatterBridge v1.22.1, is a relay bridge, this means that it relays messages as the bot user, in contract to puppet bridges, where the bridge creates puppeted users on other platforms and then relays messages through the puppets.

BOT User configuration

You will need to create bot user accounts on all platforms you want to connect to.
For IRC, Mattermost, Matrix, Rocket.Chat and other open platforms, this means this means added a new user.

IRC

For IRC you should create a registerd user following the NickServ registration rules. On FreeNode this is achieved by registering your bot account as a normal user, in this example bridgebot and the very secure password someverylongandsecurepassword.

[irc]
	[irc.freenode]
		Server="irc.freenode.net:6697"
		Nick="bridgebot"
		NickServNick="bridgebot"
		NickServPassword="someverylongandsecurepassword"
		UseTLS=true
		UseSASL=true
		SkipTLSVerify=false
		MessageDelay=100
		MessageQueue=100
		MessageLength=1200
		MessageSplit=false
		RejoinDelay=10
		ColorNicks=true
		ShowJoinPart=false
		NoSendJoinPart=false
		StripNick=false
		ShowTopicChange=false
		RemoteNickFormat="[{PROTOCOL}] <{NICK}> "

MatterMost

In MatterMost, you need to create a normal dedicated user that interacts with MatterMost as the bot. In this example the user is bridgebot and the password is someverylongandsecurepassword on your team chatteam.

[mattermost]
	[mattermost.mymattermostinstance]
		Server="chat.example.com"
		Team="chatteam"
		Login="bridgebot"
		Password="someverylongandsecurepassword"
		PrefixMessagesWithNick=true
		RemoteNickFormat="[{PROTOCOL}] <{NICK}> "

Slack

In Slack we need to create a classic bot, that has the bot oauth scope. This is achieved by adding a new Classic Application to your team, here is a direct link to the Slack Classic App creation page. Add the bot scope in Oauth2 & Permissions, remeber NOT to get tempted into accepting the granular permission suggestion or updated scopes, this will convert your app from a classic to a new app, and new apps do not have the bot scope. Install the App into your workspace, at which point it will generate 2 api keys, the bot token starting with xoxb is the one you need in your configuration.

[slack]
	[slack.myslackteamname]
		Token="xoxb-"
		PrefixMessagesWithNick=true
		RemoteNickFormat="[{PROTOCOL}] <{NICK}> "

Gateway Configuration

Gateways are the connections between the different platforms using the bot user account to relay messages inbetween these. The bot user relays messages from one to the other, and does not relay messages from itself, to avoid message relay recursion, this means that in a 3-way relay, MatterMost<->IRC<->Slack, you need to define the 3 gateways.

1. MatterMost<->IRC
2. Slack<->IRC
3. MatterMost<->Slack

Here is an example, all channels are without a #, unless like IRC this is part of the channel name. The account name is the account name as defined in the bot user section. Each gateway must have a unique name which is the internal identifier.

[[gateway]]
	name="unique-gateway-name"
	enable=true
	[[gateway.inout]]
		account="irc.freenode"
		channel="#mychannelircname"
	[[gateway.inout]]
		account="mattermost.mymattermostinstance"
		channel="mychannelmmname"

Back to Home