Discord Bridge Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Discord Bridge Integration in Matterbridge facilitates bi-directional message synchronization between Discord servers and other supported chat protocols. It leverages the discordgo library to interface with the Discord API, supporting features like message relaying, file uploads, user mentions, and webhook integration for enhanced message presentation.
The integration is designed to handle Discord-specific nuances such as Guild (Server) identification, channel mapping, and the distinction between standard bot user interactions and webhook-based messaging. This ensures that users on other platforms can interact seamlessly with Discord users, preserving the context of conversations across different environments.
Sources: README.md, bridge/discord/discord.go:1-35
Core Architecture and Connection Logic
The integration is encapsulated within the Bdiscord struct, which manages the lifecycle of the connection, user/member mappings, and channel information.
Connection Initialization
The connection process involves authenticating via a Discord Bot Token. Matterbridge identifies the specific Discord Guild (Server) defined in the configuration and retrieves the available channels. It also requests privileged intents for guild member tracking to correctly handle nicknames and mentions.
Sources: bridge/discord/discord.go:61-125
Key Data Structures
The following structures are central to the Discord bridge implementation:
| Component | Description |
|---|---|
Bdiscord | Main bridge struct containing the session, guild ID, and member caches. |
discordgo.Session | The underlying low-level binding to the Discord API. |
transmitter.Transmitter | Handles the logic for sending messages via Discord Webhooks. |
lru.Cache | Used for tracking file uploads to facilitate message deletion. |
Sources: bridge/discord/discord.go:28-50, vendor/github.com/bwmarrin/discordgo/README.md
Message Handling and Flow
Matterbridge distinguishes between two primary methods for sending messages to Discord: standard Bot User messages and Webhooks.
Outgoing Message Flow
When a message is received from a gateway (e.g., from Mattermost), the bridge determines the appropriate Discord delivery method based on the configuration.
Sources: bridge/discord/discord.go:210-238
Message Features and Transformations
- File Uploads: Files from other bridges are converted into
discordgo.Fileobjects and uploaded natively to Discord channels. - Mentions: The bridge performs user mention translation, converting human-readable nicks into Discord
<@ID>format. - Clipped Messages: Messages exceeding the
MessageLength(1950 characters) are automatically clipped using a helper function. - Event Handling: Support for standard events like
EventUserTyping,EventUserAction(formatted as italics), andEventMsgDelete.
Sources: bridge/discord/discord.go:16-17, bridge/discord/discord.go:230-310
Webhook Management
The Discord bridge utilizes webhooks to spoof user avatars and usernames, providing a more integrated "native" feel for bridged messages.
- AutoWebhooks: If enabled, the bridge automatically manages webhooks in the target channels, creating or refreshing them as needed.
- Manual Webhooks: Users can provide a specific
WebhookURLper channel in the configuration. - Transmitter: The
transmittercomponent manages the mapping of channel IDs to specific webhook tokens and IDs.
Sources: bridge/discord/discord.go:46-48, bridge/discord/discord.go:136-160
Configuration Options
The behavior of the Discord bridge is governed by several configuration settings defined in the bridge section of matterbridge.toml.
| Option | Type | Description |
|---|---|---|
Token | String | The Discord Bot application token. |
Server | String | The Name or ID of the Discord Server (Guild). |
AutoWebhooks | Boolean | Enables automatic management of webhooks for message relay. |
ShowUserTyping | Boolean | Relays typing notifications to Discord. |
RemoteNickFormat | String | Template for displaying nicks from other protocols. |
Sources: README.md, bridge/discord/discord.go:64-100
API Integration
While the Discord bridge is a native integration, it interacts with the broader Matterbridge API. The API defines how messages are structured when moving through the system, including metadata like gateway, username, and avatar.
# Simplified message structure used by the bridge
config.IncomingMessage:
properties:
text: Content of the message
username: Human-readable username
channel: Discord channel name
protocol: "discord"
extra: Metadata for files and attachments
Sources: contrib/api.yaml:65-125
Conclusion
The Discord Bridge Integration provides a robust link between Discord's complex ecosystem and other chat services. By combining low-level API access through discordgo with high-level features like automated webhook management and file handling, it ensures that cross-platform communication remains feature-rich and reliable.
Sources: bridge/discord/discord.go:1-30, README.md