IRC & XMPP Integrations
Relevant source files
The following files were used as context for generating this wiki page:
Matterbridge provides native support for bridging chat communications between different protocols, with IRC and XMPP serving as core supported integrations. These integrations allow messages, user identities, and metadata to be synchronized across diverse chat platforms, enabling unified communication channels.
The system utilizes specialized Go libraries to handle the low-level protocol requirements of each service, such as girc for IRC and go-xmpp for XMPP. These integrations are configured via a central TOML file and managed through a gateway system that routes messages based on defined account and channel mappings.
Sources: README.md:1-50, README.md:120-135
Architecture and Protocol Handling
The architecture relies on a series of protocol-specific bridges that translate native chat events into a common internal format used by Matterbridge.
IRC Integration
The IRC implementation is built upon the girc library, which provides a flexible, event-based framework for interacting with IRC servers. It supports modern IRC features including IRCv3 specifications like SASL authentication and message tags.
Key features of the IRC integration include:
- Event-based triggering: Handling of standard IRC commands and CTCP responses.
- State Tracking: Monitoring of channel users, away status, and server capabilities (ISUPPORT).
- Rate Limiting: Built-in protection against message flooding to prevent server kicks.
- Nick Management: Automated detection and prevention of nickname collisions.
Sources: vendor/github.com/lrstanley/girc/README.md:20-50, README.md:280-295
XMPP Integration
XMPP support allows Matterbridge to connect to Jabber/XMPP servers. It is categorized as a natively supported protocol and is often used for open, decentralized communication.
| Feature | Protocol Support |
|---|---|
| Native Support | Both IRC and XMPP |
| Library Used (IRC) | github.com/lrstanley/girc |
| Library Used (XMPP) | github.com/mattn/go-xmpp |
| Multi-Gateway | Supported for both |
Sources: README.md:120-135, README.md:280-310
Data Flow and Message Routing
Messages from IRC or XMPP are received by the bridge, processed, and then forwarded through a gateway to other connected protocols.
The diagram shows how protocol-specific messages are ingested by their respective bridges before being routed by the Gateway.
Sources: README.md:140-160, contrib/api.yaml:30-60
Configuration
Both integrations are configured within the matterbridge.toml file. Each protocol requires a server address and specific credentials or identifiers.
Configuration Parameters
| Parameter | Protocol | Description |
|---|---|---|
Server | Both | The address and port of the chat server (e.g., irc.libera.chat:6667) |
Nick | IRC | The nickname the bot will use on the network |
Password | Both | Authentication password for the account |
UseTLS | Both | Whether to use encrypted connections (implied by port or explicit setting) |
Sources: README.md:210-230, vendor/github.com/lrstanley/girc/README.md:40-45
Example Bridge Configuration
[irc.libera]
Server="irc.libera.chat:6667"
Nick="bridgebot"
[[gateway]]
name="bridge-gateway"
enable=true
[[gateway.inout]]
account="irc.libera"
channel="#target-channel"
Sources: README.md:215-225
Protocol-Specific Details
IRCv3 and SASL
The IRC integration supports SASL PLAIN and EXTERNAL mechanisms for secure authentication during the connection phase. It also handles message tags such as account-tag, which provides better identity tracking across the bridge.
Sources: vendor/github.com/lrstanley/girc/README.md:30-38
Message Metadata
When messages are bridged from IRC or XMPP, Matterbridge attempts to preserve as much metadata as possible, including:
- Username and Avatar Spoofing: Matching the remote user's identity on the target platform.
- RemoteNickFormat: Customizing how the origin protocol and user appear (e.g.,
[{PROTOCOL}] <{NICK}>).
Sources: README.md:80-95, README.md:215-220
API and Extensibility
The Matterbridge API can also interact with these integrations. For instance, a POST request to /api/message can inject a message into a gateway that includes an IRC or XMPP account.
The sequence shows an API-originated message being routed through a gateway to an IRC channel.
Sources: contrib/api.yaml:20-40, vendor/github.com/olahol/melody/README.md:30-50
Summary
The IRC and XMPP integrations in Matterbridge provide robust connectivity to legacy and decentralized chat networks. By leveraging specialized libraries like girc, the project ensures support for modern standards such as IRCv3 and SASL while maintaining a simple, unified configuration interface for the user. These integrations are essential for users seeking to bridge enterprise or modern chat apps with established open-source chat communities.