Configuration Guide
Relevant source files
The following files were used as context for generating this wiki page:
Matterbridge is a versatile chat bridge that enables communication between a wide array of chat protocols, including Discord, IRC, Mattermost, Slack, and Telegram. The system relies on a central configuration file, typically matterbridge.toml, to define server connections (bridges) and routing logic (gateways).
The configuration architecture is hierarchical, starting from global settings and moving down to specific account credentials and granular message routing rules between different platforms.
Sources: README.md:1-50, vendor/github.com/lrstanley/girc/README.md:80-85
Command Line Interface (CLI)
Before modifying the configuration file, users interact with the Matterbridge binary via command-line flags. These flags control which configuration file is loaded and the logging verbosity of the application.
CLI Parameters
| Flag | Type | Default | Description |
|---|---|---|---|
-conf | string | matterbridge.toml | Path to the TOML configuration file. |
-debug | boolean | false | Enables verbose debug logging for troubleshooting. |
-gops | boolean | false | Enables the gops agent for runtime profiling. |
-version | N/A | N/A | Displays the current version of Matterbridge. |
Sources: README.md:275-285
Configuration Format: TOML
Matterbridge uses the TOML (Tom's Obvious, Minimal Language) format for its configuration. TOML is designed to be human-readable while providing a clear mapping to hash tables. Matterbridge leverages the go-toml library to unmarshal this data into Go structures.
The diagram below illustrates how a TOML file is structured and parsed into the configuration tree used by the bridge logic:
This diagram shows the flow from the raw configuration file through the parser into logical functional blocks.
Sources: vendor/github.com/pelletier/go-toml/README.md:40-60, README.md:210-250
Configuration Blocks
The configuration is divided into three primary sections: [general], protocol-specific blocks (e.g., [irc], [slack]), and [[gateway]].
General Settings
The [general] block defines settings that apply globally across all bridges. One of the most common settings is RemoteNickFormat, which dictates how usernames from one protocol appear on another.
Protocol and Account Definitions
Each chat protocol has its own block. Inside these blocks, unique "accounts" are defined. For example, under [irc], you can define an account named [irc.my-server].
Gateways and Routing
The [[gateway]] block (a TOML array of tables) defines the actual bridging logic. Each gateway specifies which accounts and channels are linked.
This sequence diagram demonstrates how a message originates in one protocol and is routed by the gateway to another.
Sources: README.md:215-270, contrib/api.yaml:60-80
Advanced Routing: InOut Logic
Inside a gateway, Matterbridge uses [[gateway.inout]], [[gateway.in]], and [[gateway.out]] to define the direction of message flow.
- inout: Messages are sent to and received from this account/channel.
- in: Messages are only received from this account/channel.
- out: Messages are only sent to this account/channel.
Example Configuration Snippet
[irc.libera]
Server="irc.libera.chat:6667"
Nick="bridgebot"
[mattermost.work]
Server="mattermost.company.com"
Team="myteam"
Login="bot-user"
Password="password123"
[[gateway]]
name="mygateway"
enable=true
[[gateway.inout]]
account="irc.libera"
channel="#testing"
[[gateway.inout]]
account="mattermost.work"
channel="off-topic"
Sources: README.md:215-235
API Data Model
When using the Matterbridge API, messages follow a specific structure that mirrors the internal configuration properties. Fields like gateway, account, and channel must match the values defined in the .toml file.
Incoming Message Fields (API)
| Property | Type | Description |
|---|---|---|
username | string | The human-readable name of the sender. |
text | string | The content of the message. |
gateway | string | The name of the gateway defined in the configuration. |
account | string | Unique account name (e.g., slack.myteam). |
channel | string | The channel name on the sending bridge. |
event | string | Specific matterbridge event type. |
Sources: contrib/api.yaml:50-100
Conclusion
The configuration of Matterbridge is centered around the concept of mapping discrete protocol accounts to unified gateways. By leveraging TOML's structured blocks and the inout routing logic, administrators can create complex webs of communication between disparate chat platforms while maintaining control over message formats and directions. This flexibility allows Matterbridge to serve as a bridge for almost any chat protocol currently in use.
Sources: README.md:80-120, vendor/github.com/lrstanley/girc/README.md:80-90