Advanced Configuration & Examples
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Advanced configuration in Matterbridge allows users to move beyond simple point-to-point bridging and implement complex messaging workflows between multiple protocols. By leveraging the [general] settings, specific protocol accounts, and versatile [[gateway]] definitions, administrators can control message formatting, nickname spoofing, and multi-channel routing.
The configuration system is primarily driven by a TOML-based file structure (typically matterbridge.toml). This allows for modular definitions where protocols are configured once and then referenced across various gateways to create a unified chat environment.
Sources: README.md:120-130, vendor/github.com/pelletier/go-toml/README.md:1-10
Configuration Architecture
The architecture of Matterbridge configuration is hierarchical, moving from global settings to specific gateway definitions. The core logic relies on defining "Accounts" (instances of a protocol) and "Gateways" (the logic that binds accounts together).
Component Relationships
The following diagram illustrates how different configuration sections interact to form a functional bridge:
This diagram shows the relationship between global settings, protocol accounts, and the gateways that route messages.
Sources: README.md:143-180, bridge/config/config.go
Gateway Logic and Routing
Gateways are the primary mechanism for message routing. A gateway can contain multiple [[gateway.inout]] blocks, which define participating accounts and their respective channels.
Bidirectional Synchronization
When multiple accounts are listed under the same gateway, messages received from one account are automatically broadcast to all other accounts within that gateway.
The diagram demonstrates the bidirectional nature of a standard Matterbridge gateway where messages are synced across all members.
Sources: README.md:143-180, bridge/config/config.go
Data Structures for Messaging
Messages handled by the configuration logic are structured to ensure metadata is preserved across different protocols.
| Field | Type | Description |
|---|---|---|
username | string | Human-readable username from the source |
text | string | Content of the message |
gateway | string | Name of the configured gateway |
account | string | Unique name format [protocol].[slug] |
protocol | string | Chat protocol (e.g., slack, irc) |
timestamp | string | Message timestamp |
Sources: contrib/api.yaml:68-120
Advanced Formatting and Nicknames
Advanced users can customize how nicknames appear on remote bridges using RemoteNickFormat. This supports variables such as {NICK}, {PROTOCOL}, and {BRIDGE}.
Example: Multi-Protocol Nickname Formatting
[general]
# Format: [Protocol/Bridge] <Username>
RemoteNickFormat="[{PROTOCOL}/{BRIDGE}] <{NICK}> "
[slack.test]
Token="yourslacktoken"
PrefixMessagesWithNick=true
Sources: README.md:164-180, bridge/config/config.go
API Integration
Matterbridge exposes a read/write API that functions as a specialized "protocol" within the configuration. This allows external scripts to interact with the bridged networks as if they were another chat client.
API Endpoints
| Endpoint | Method | Description |
|---|---|---|
/api/messages | GET | List new messages from the bridge |
/api/message | POST | Send a message to a gateway |
/api/stream | GET | Real-time SSE stream of messages |
/api/health | GET | Health check for the bridge server |
Sources: contrib/api.yaml:14-60
API Message Flow
Sequence diagram showing an external application sending a message through Matterbridge to a remote chat protocol.
Sources: contrib/api.yaml:23-45, README.md:95-105
Complex Example: Multi-Account Bridge
The following configuration demonstrates bridging Mattermost and IRC while applying specific account-level settings and remote nick formatting.
[irc.libera]
Server="irc.libera.chat:6667"
Nick="yourbotname"
[mattermost.work]
Server="yourserver.tld"
Team="yourteam"
Login="yourlogin"
Password="yourpass"
RemoteNickFormat="[{PROTOCOL}] <{NICK}> "
[[gateway]]
name="mygateway"
enable=true
[[gateway.inout]]
account="irc.libera"
channel="#testing"
[[gateway.inout]]
account="mattermost.work"
channel="off-topic"
Sources: README.md:143-162, vendor/github.com/lrstanley/girc/README.md
Conclusion
Advanced configuration in Matterbridge enables high-fidelity communication across disparate platforms by utilizing structured TOML definitions and a flexible gateway system. Through the use of custom nickname formats, account slugs, and API integration, Matterbridge acts as a powerful middleware for unified chat operations.
Sources: README.md:1-20, bridge/config/config.go