Introduction & Features
Relevant source files
The following files were used as context for generating this wiki page:
Matterbridge is a versatile, multi-protocol chat bridge designed to connect various chat platforms, allowing users to communicate across different ecosystems seamlessly. It acts as a middle-layer gateway that translates and routes messages between diverse protocols such as Discord, Slack, IRC, Matrix, and Mattermost.
The system is built to be extensible, supporting native protocol implementations as well as a REST/Streaming API for third-party integrations. By preserving context such as threading, attachments, and user metadata (avatars/nicknames), Matterbridge ensures a consistent communication experience across bridged channels.
Core Features and Capabilities
Matterbridge provides a robust set of features focused on message fidelity and protocol interoperability.
Primary Capabilities
- Protocol Interoperability: Support for bridging between any combination of supported protocols.
- Multiple Gateways: Ability to configure multiple bridges (gateways) within a single instance.
- Message Synchronization: Support for message edits, deletes, and threading preservation where technically possible by the underlying protocol.
- Metadata Spoofing: Implementation of username and avatar spoofing to maintain user identity across different platforms.
- File Handling: Management of attachments and file transfers between bridged accounts.
Sources: README.md:58-70
Natively Supported Protocols
Matterbridge includes native support for a wide array of chat services:
| Category | Protocols |
|---|---|
| Mainstream Chat | Discord, Slack, Microsoft Teams, Telegram, WhatsApp (Legacy & Multidevice) |
| Open/Federated | Matrix, XMPP, IRC, Gitter |
| Self-Hosted | Mattermost, Rocket.Chat, Zulip, Nextcloud Talk |
| Specialized | Steam (Deprecated), Twitch, Mumble, Ssh-chat, Keybase, VK |
Sources: README.md:72-101
System Architecture
The architecture relies on a "Gateway" concept where multiple "Accounts" (instances of a protocol) are linked together.
Message Flow Architecture
The following diagram illustrates how a message originates in one protocol and is distributed through the Matterbridge gateway to other configured platforms.
This diagram shows the unidirectional flow of a message from a source protocol through the central gateway router to multiple target protocols.
Sources: README.md:200-245, contrib/api.yaml:45-100
API Integration
Matterbridge exposes a read/write API (OpenAPI 3.0.0 specification) that allows external applications to interact with the bridge as a third-party protocol.
API Endpoints
| Endpoint | Method | Summary |
|---|---|---|
/api/health | GET | Checks if the server is alive. |
/api/message | POST | Creates a message on a specific gateway. |
/api/messages | GET | Lists new messages (polling). |
/api/stream | GET | Real-time message streaming via JSON stream. |
Sources: contrib/api.yaml:14-43
Data Models
The system uses standardized structures for incoming and outgoing messages to ensure consistency across disparate protocols.
Incoming Message Schema:
- username: Human-readable sender name.
- text: Content of the message.
- gateway: Target gateway name.
- protocol: Originating chat protocol.
- extra: Metadata for objects that do not fit standard fields (e.g., base64 encoded files).
Sources: contrib/api.yaml:49-100
Content Processing and Formatting
Matterbridge handles complex message formatting, often utilizing Markdown parsing for protocols that support rich text.
Markdown Extensions
The underlying processing (via libraries like Blackfriday) supports several extensions to enhance message rendering:
- Fenced Code Blocks: Explicitly marked code segments with language identifiers.
- Tables: Support for GFM-style tables.
- Autolinking: Automatic conversion of URLs into clickable links.
- Strikethrough: Support for
~~text~~syntax. - Footnotes: Pandoc-style footnote support.
Sources: vendor/github.com/russross/blackfriday/markdown.go:28-56, vendor/github.com/gomarkdown/markdown/README.md:144-175
Implementation Details: IRC Protocol
As an example of deep protocol integration, the IRC implementation (utilizing girc) supports advanced features required for stable bridging:
- SASL Authentication: Supports
PLAINandEXTERNALmechanisms for secure server connections. - Capability Tracking: Handles
account-notify,away-notify, andextended-join. - Collision Handling: Automatic nick collision detection and prevention.
- Rate Limiting: Built-in event and message rate limiting to prevent server bans.
Sources: vendor/github.com/lrstanley/girc/README.md:46-70
Conclusion
Matterbridge serves as a critical infrastructure component for fragmented communication environments. By abstracting protocol-specific complexities into a unified gateway and providing a robust API, it enables seamless cross-platform interaction while maintaining high message fidelity and user identity metadata.