Matterbridge

Last reviewed Sep 13, 2026 · 889 words

The mistake people make with Matterbridge is expecting it to be a chat server. It is a relay: a single Go binary that logs into two or more chat platforms as a bot and copies messages between them in real time, with no message store, no history, and no accounts of its own. Used for that, it is excellent, runs on 64 MB of RAM, and is the reason many open source projects still have a working IRC channel that Discord users can talk to. Used as a way to "merge" communities into one system, it will disappoint, because each side keeps its own history and the bridge only relays what happens while it is running.

What crosses the bridge and what does not

Text crosses cleanly, prefixed with the sender's name and origin, so an IRC user sees [discord] <alice> hello and a Discord user sees [irc] <bob> hi. Files and images cross on platforms that support uploads; on IRC they become a link. Edits and deletes cross where both sides support them, which in practice means Discord, Slack, Matrix, Telegram, and Mattermost, not IRC or XMPP. Threads mostly do not cross, and reactions do not cross at all. Mentions are relayed as text, so an @-mention on Discord does not ping anyone on Matrix.

Anything said while the bridge is down is gone as far as the other side is concerned. There is no catch-up on restart. If your communities need shared history, you want a real Matrix bridge or, for IRC specifically, matrix-appservice-irc, both of which puppet users into a Matrix room that keeps a permanent record. Those are heavier to run and tied to Matrix; Matterbridge is the one that works in an hour with any 2 of its 15-plus protocols.

The whole configuration is one TOML file

Accounts are declared per protocol, then gateways wire channels together:

[irc.libera]
Server = "irc.libera.chat:6697"
Nick = "projectbridge"
UseTLS = true
RemoteNickFormat = "[{PROTOCOL}] <{NICK}> "

[discord.main]
Token = "Bot your-bot-token"
Server = "123456789012345678"
RemoteNickFormat = "[{PROTOCOL}] **{NICK}**: "

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

  [[gateway.inout]]
  account = "irc.libera"
  channel = "#project"

  [[gateway.inout]]
  account = "discord.main"
  channel = "general"

inout relays both directions; in and out make a channel send-only or receive-only, which is how you mirror an announcements channel to 4 platforms without accepting replies. Run it with the official image and mount the file:

docker run -d --name matterbridge --restart unless-stopped \
  -v $PWD/matterbridge.toml:/etc/matterbridge/matterbridge.toml:ro \
  42wim/matterbridge

Or just download the static binary from the releases page and run it under systemd. There is no database, no port to expose (unless you enable the API or webhook receivers), and no state beyond the config.

Every platform has one quirk that costs an hour

Discord needs a bot application with the Message Content intent switched on in the developer portal, or every relayed message arrives empty. Telegram bots default to privacy mode, which hides group messages from them; disable it with BotFather or the bot only sees commands. IRC networks rate-limit and will disconnect a bot that relays a paste burst; set MessageDelay and MessageQueue on the IRC account. Slack wants a proper app with the right scopes rather than a legacy token. Matrix works best with a dedicated bot account rather than your own, and does not render the sender name inside the message unless you use RemoteNickFormat deliberately. Each of these is documented in the project wiki, none is a bug, and all of them cost me a debugging session the first time.

Maintenance pace, and why that is acceptable here

Matterbridge has 7,558 stars, Apache-2.0 licensing, and a development pace that has slowed to bug fixes and platform-API catch-up rather than new features. For a bridge that is a reasonable state: the protocols it supports are stable, the binary has no dependencies to rot, and when a platform changes its bot API the fix is typically a one-line dependency bump. The risk is a platform making a breaking change and the fix landing slowly. Discord and Telegram have been the ones to watch. If your bridge is load-bearing for a company, budget for building from source occasionally.

Where it fits in a team chat setup

The common self-hoster pattern is a Mattermost or Rocket.Chat instance for the team, bridged to the Discord or Telegram channel where the community already is, so staff never leave their own tool. The second common pattern is a project's IRC channel bridged to Discord and Matrix so nobody has to argue about which one is the real chat. The team chat category covers the server side of that choice.

What I'd do

Run the static binary under systemd on the same box as your chat server, one TOML file in version control, bot accounts with names that make their bridge nature obvious, and RemoteNickFormat set so nobody mistakes a relayed message for a native one. Start with 2 platforms and one gateway. Add an out-only gateway for announcements before adding a third platform. If someone asks for shared history or threads, stop stretching Matterbridge and stand up Matrix with proper bridges instead.