42wim/matterbridge

Project Overview

Matterbridge connects over 20 chat platforms through a single running process. You configure it via a TOML file, start the binary, and messages flow between platforms in real time. Supported networks include Slack, Discord, Telegram, IRC, Mattermost, Matrix, Rocket.Chat, Microsoft Teams, XMPP, Zulip, WhatsApp, Mumble, Twitch, Keybase, VK, Nextcloud Talk, Gitter, and ssh-chat — with a REST API for custom integrations.

The name trips people up. Despite "Matterbridge," you do not need Mattermost at all. The project started as a Mattermost-to-IRC relay and grew from there. Today Mattermost is just one backend among many.

The project ships as a single self-contained Go binary with no runtime dependencies. If your organization runs both a Slack workspace and a Discord server and needs messages to flow between them, Matterbridge is one of the quickest paths to that outcome.

With roughly 7,500 GitHub stars and 6.6% star growth over the last ~6 months as of 2026-06-13, it has a stable user base. Adoption over the last ~6 months is significantly down, which likely reflects a maturing, stable user base rather than project decline — but evaluate whether active new-protocol development aligns with your specific needs before committing.

Key Challenges Addressed

Multi-platform fragmentation. Teams split across Slack, Discord, and IRC have no native way to see each other's messages. Matterbridge acts as a relay daemon — each platform sees its own bridge bot posting messages from the others.

Identity mapping. When a Telegram user writes a message, the Discord side needs a readable attribution. Matterbridge formats this consistently using configurable RemoteNickFormat templates, so you can display something like [Telegram] alice: hello in the bridged channel.

Single-instance management. Running five separate point-to-point bridge bots means five codebases to maintain. Matterbridge consolidates them into one config file and one process, simplifying deployment and monitoring.

No vendor lock-in. Because it sits as a relay layer outside all platforms, migrating your team from Slack to Matrix doesn't require rebuilding your bridge infrastructure — just update the TOML config.

Getting Started

Install with Go 1.21+:

go install github.com/42wim/matterbridge@latest

Or download a prebuilt binary from the releases page.

A minimal two-platform bridge config in matterbridge.toml:

[irc]
[irc.libera]
Server="irc.libera.chat:6667"
Nick="matterbridge"

[discord]
[discord.myserver]
Token="YOUR_DISCORD_BOT_TOKEN"

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

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

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

Start it:

matterbridge -conf matterbridge.toml

Sharp edges to catch before you go further:

• Discord bots require Message Content Intent enabled in the Discord Developer Portal. Without it, the bot receives empty message bodies and silently drops all bridged content — enable it under Bot → Privileged Gateway Intents before generating your token.
• WhatsApp bridging uses the WhatsApp Web multi-device API. WhatsApp's terms of service technically prohibit automated clients; if your session gets flagged, WhatsApp logs it out and the bridge goes silent with nothing in the logs beyond a generic disconnection notice.
• Matrix bridging requires an existing Matrix homeserver with a pre-registered application service. A bot token alone is not enough — read the Matrix application service documentation before attempting this backend.
• A duplicate account name or invalid TOML section causes a startup panic with a minimal error message. Validate your config with a TOML linter before running.

Features and Use Cases

Multi-gateway routing. A single config file can run multiple independent gateways. Gateway A bridges Slack ↔ Discord, Gateway B bridges Telegram ↔ IRC, and neither bleeds into the other. This lets different teams use their preferred platforms while still sharing cross-team channels.

Samechannel bridging. The SameChannelGateway shorthand bridges identically named channels across multiple instances of the same platform — useful for connecting two Mattermost instances or multiple IRC networks without writing out every [[gateway.inout]] block.

Media relay. Images, files, and voice messages cross platform boundaries where the API supports it. The bridge uploads the file to the destination platform and posts the URL or attachment inline.

REST API. Matterbridge exposes a simple HTTP REST API at a configurable port. You can POST messages into a gateway from any HTTP client, letting external scripts or CI/CD pipelines inject notifications without needing a native platform bot integration.

Message filtering. Per-gateway IgnoreNicks, IgnoreMessages, and message transformation options let you suppress relay bots, trim noise, or reformat message text before it crosses to the other side.

Ecosystem and Dependencies

Matterbridge imports a platform-specific client library for each supported protocol. Key dependencies include bwmarrin/discordgo for Discord API access, the nlopes/slack client for Slack RTM, and matrix-org/gomatrix for Matrix homeserver communication.

Each platform library tracks its upstream API independently. When Discord or Slack ships a breaking API change, the upstream library needs to update before Matterbridge catches up. In practice this lag has occasionally left users on older Matterbridge versions when a platform updates its bot API — check the Matterbridge release notes when a platform backend starts misbehaving before debugging your own config.

For teams running a Matrix homeserver, Matterbridge's Matrix support integrates with any homeserver that implements the application service spec. For heavier Matrix use cases, the dedicated Matrix bridge ecosystem (see Comparison section) offers deeper feature parity at the cost of narrower platform support.

Architectural Overview

Matterbridge is structured around a central router that passes messages between bridges. Each bridge is a platform-specific implementation of the Bridger interface:

Platform API ↔ Bridge adapter ↔ Router ↔ Bridge adapter ↔ Platform API

The router reads gateway config to determine which accounts route to which channels, then forwards incoming config.Message structs from the source bridge to all configured destination bridges. Each bridge serializes those structs back into platform-native API calls.

Each bridge runs in goroutines — one reading from the remote platform, one writing. The router uses Go channels for dispatch, so a slow or disconnected destination does not block message delivery to healthy ones.

The config model is declarative: gateways define the routing topology, and the bridges handle platform-specific details. Adding a new platform means implementing the Bridger interface — the router stays unchanged. This clean separation is why Matterbridge can support 20+ platforms without the codebase becoming unmanageable.

Pros and Cons

Single binary with no external runtime dependencies — deploys on any Linux, macOS, or Windows host without a container or language runtime.

Supports more protocols than any other general-purpose bridge tool. If you need to connect niche platforms like ssh-chat, Mumble, or VK alongside mainstream ones, Matterbridge is the only option.

Config-driven routing makes topology changes a file edit plus a process restart. No database migrations, no web admin panel required.

The REST API is underutilized but genuinely useful — it lets monitoring systems, bots, and CI pipelines post to chat without platform-specific integrations.

On the downside: there is no persistence layer. If the process crashes, messages sent during downtime are lost with no replay mechanism.

WhatsApp, Keybase, and some other backends rely on unofficial or terms-of-service-gray-area client libraries. These can break without warning when the platform pushes an update, and recovery depends on upstream library maintainers.

All bridged messages post under the bot account. Destination platforms see one account posting everything, which can confuse moderation tools and per-user rate limits on high-traffic channels.

The adoption trend over the last ~6 months is significantly negative. New protocol support and bug fixes continue, but the pace of major feature development has slowed. Budget time for occasional maintenance when platform APIs change.

Comparison and Alternatives

For teams building on Matrix as a backbone, matrix-org/matrix-appservice-irc is the production-hardened IRC bridge maintained by the Matrix core team. It goes deep on Matrix-side features — room state sync, IRC channel membership mirroring — but bridges exactly one protocol pair.

tulir/mautrix-telegram takes the same single-protocol approach for Telegram, with double-puppeting and full message history sync. If your use case is specifically Telegram ↔ Matrix with high fidelity, mautrix-telegram delivers a substantially better user experience than Matterbridge's relay model.

For Discord-to-IRC specifically, reactiflux/discord-irc is the oldest point solution with a proven track record. It handles exactly two protocols and requires Node.js, but if Discord ↔ IRC is your only bridge requirement, it is simpler to configure and debug than Matterbridge.

bitlbee/bitlbee takes a fundamentally different approach: it exposes all IM networks as an IRC server. Your existing IRC client connects to BitlBee and sees Telegram or XMPP contacts as IRC channels. If your team is IRC-native and wants to consume other networks through an IRC interface rather than relay between platforms, BitlBee fits better.

The best overall alternative is tulir/mautrix-telegram. Its double-puppeting support, active maintenance by a core Matrix ecosystem contributor, and full message history sync make it the most mature single-protocol bridge available — and if Telegram is your primary bridging target, it outperforms Matterbridge's relay approach on every user-visible dimension.

Conclusion

If you need to bridge three or more chat platforms without committing to a full Matrix homeserver deployment, Matterbridge is the right tool — deploy the single Go binary, write a TOML config, and messages flow between Slack, Discord, Telegram, IRC, and more in an afternoon. The official documentation and config examples cover every supported platform with working minimal configs.

Do not use Matterbridge's WhatsApp backend in production without reading WhatsApp's Terms of Service first — automated clients can have their sessions silently revoked, leaving the bridge disconnected with no log-level error to alert you. Before backgrounding any Matterbridge instance, run matterbridge -conf matterbridge.toml in an interactive terminal and verify every account handshake logs a successful connection before you hand it off to a process manager.