Matrix & Mattermost Bridges

Relevant source files

The following files were used as context for generating this wiki page:

• bridge/matrix/matrix.go
• bridge/mattermost/mattermost.go
• README.md
• contrib/api.yaml
• vendor/github.com/matterbridge/gomatrix/README.md

The Matrix and Mattermost bridges are core components of the Matterbridge ecosystem, enabling bidirectional communication between these platforms and other supported protocols. These bridges act as specialized connectors that translate platform-specific events—such as messages, edits, deletions, and file uploads—into a common internal format for the Matterbridge gateway to distribute.

The implementation relies on third-party SDKs: gomatrix for Matrix connectivity and matterclient combined with matterhook for Mattermost. These bridges support various authentication methods, including login/password and token-based access, and provide features like username spoofing, threaded conversations, and attachment handling.

Sources: README.md:1-50, bridge/matrix/matrix.go:73-100, bridge/mattermost/mattermost.go:68-100

Matrix Bridge Architecture

The Matrix bridge is implemented via the Bmatrix struct, which manages the lifecycle of a connection to a Matrix homeserver. It utilizes the gomatrix client to sync events and send message data.

Connection and Authentication

The bridge supports two primary connection flows: using existing credentials (MxID and Token) or performing a fresh login with a username and password.

Event Handling

The handlematrix function sets up a DefaultSyncer to listen for specific Matrix event types. When an event is received, it is processed into a config.Message and sent to the Remote channel.

Event Type	Action
m.room.message	Processed as standard message, edit, or reply.
m.room.redaction	Processed as a message deletion.
m.room.member	Used to cache display names for joins.

Sources: bridge/matrix/matrix.go:273-281, bridge/matrix/matrix.go:343-355

Message Transmission Flow

When sending a message to Matrix, the bridge handles formatting (Markdown to HTML), user spoofing, and file uploads.

Mattermost Bridge Architecture

The Mattermost bridge uses the Bmattermost struct and can operate via Webhooks (Incoming/Outgoing) or the official API (via matterclient).

Connectivity Modes

Mattermost can be configured in several ways depending on the available integration points:

1. Webhooks: Uses WebhookURL for sending and WebhookBindAddress for receiving.
2. API Token: Uses a pre-generated bot token.
3. Login/Password: Traditional user authentication.
4. Plugin Mode: Operates as a Mattermost plugin (bypasses standard network connection).

Sources: bridge/mattermost/mattermost.go:70-104

Threading and Message Relations

The bridge handles Mattermost's threading model by managing RootId. If a parent message is not found, it falls back to a "[thread]" prefix in the message text.

Feature Comparison

Both bridges implement standard Bridger interfaces but have platform-specific logic for attachments and formatting.

Feature	Matrix Implementation	Mattermost Implementation
Formatting	Markdown converted to HTML (org.matrix.custom.html)	Native Markdown support
Spoofing	Temporary m.room.member state events	Webhook username and icon_url
Files	mxc:// URI handling and content repo uploads	Multi-part file uploads via API
Deletions	m.room.redaction events	API DeleteMessage
Edits	m.new_content with m.relates_to	API EditMessage

Sources: bridge/matrix/matrix.go:136-160, bridge/matrix/matrix.go:419-480, bridge/mattermost/mattermost.go:158-200

Data Structures

Matrix Message Types

Matrix uses specific JSON structures for specialized message types like edits and replies.

// bridge/matrix/matrix.go:46-64
type SubTextMessage struct {
	MsgType       string `json:"msgtype"`
	Body          string `json:"body"`
	FormattedBody string `json:"formatted_body,omitempty"`
	Format        string `json:"format,omitempty"`
}

type EditedMessage struct {
	NewContent SubTextMessage  `json:"m.new_content"`
	RelatedTo  MessageRelation `json:"m.relates_to"`
	matrix.TextMessage
}

API Message Schema

The external API interacts with these bridges using a standardized schema defined in the project's OpenAPI specification.

Field	Description	Example
username	Human-readable sender name	alice
text	Content of the message	Hello world
gateway	Configured gateway name	mygateway
extra	Object for files (base64)	{ "file": [...] }

Sources: contrib/api.yaml:70-120

Summary

The Matrix and Mattermost bridges provide robust integration into their respective ecosystems. The Matrix bridge focuses on heavy state management (member profiles for spoofing and room mapping), while the Mattermost bridge provides flexible connectivity options ranging from simple webhooks to deep API integration. Both ensure that features like message threading and file attachments are preserved across the bridge gateway.

Sources: bridge/matrix/matrix.go:20, bridge/mattermost/mattermost.go:20