Username and Avatar Spoofing
Relevant source files
The following files were used as context for generating this wiki page:
Username and avatar spoofing is a core feature of matterbridge that allows the bridge to preserve the identity of the original sender when relaying messages across different chat protocols. Instead of appearing as a generic "bot" user, the bridge dynamically sets the sender's display name and profile picture to match the user who sent the message on the source platform.
This functionality is primarily implemented using webhooks or specific API capabilities (like Mattermost's Post.Props or Discord's Webhook execution) that allow a single connection to represent multiple distinct identities.
Sources: README.md:65, bridge/mattermost/mattermost.go:124-127
Architecture and Data Flow
The spoofing mechanism relies on passing identity metadata along with the message text through the bridge's internal routing. When a message is received from a source, matterbridge extracts the sender's username and the URL to their avatar.
Message Processing Flow
The following diagram illustrates how identity data is preserved from a source bridge to a destination bridge that supports spoofing.
In the Mattermost implementation, for instance, the bridge can cache avatars and map file SHAs to specific users to ensure the bridged identities remain consistent.
Sources: bridge/mattermost/mattermost.go:120-123, contrib/api.yaml:70-90
Configuration and API Integration
The bridge uses specific data structures to handle spoofed identity information. The IncomingMessage and OutgoingMessage objects in the API definition explicitly include fields for these attributes.
Identity Data Structures
| Field | Type | Description | Example |
|---|---|---|---|
username | string | The human-readable name to be spoofed on the destination. | alice |
avatar | string | A URL pointing to the image to be used as the profile picture. | https://gravatar.com/avatar/... |
Sources: contrib/api.yaml:70-76, contrib/api.yaml:113-119
Protocol-Specific Implementation
Mattermost
Mattermost utilizes matterhook or the native API. When sending via webhooks, the sendWebhook function is invoked, which packages the message along with the identity metadata. The bridge also supports PrefixMessagesWithNick, an alternative to spoofing where the sender's name is prepended to the message text if native spoofing is not available or desired.
Sources: bridge/mattermost/mattermost.go:124-127, bridge/mattermost/mattermost.go:157-160
Discord
Discord implementation often leverages webhooks to execute spoofing. The discordgo library and Matterbridge's internal webhook.go (referenced in context) handle the execution of these webhooks where the username and avatar_url parameters are passed to the Discord API to override the default bot identity.
Sources: README.md:315, bridge/discord/webhook.go
Implementation Details
The implementation involves mapping remote identities to local bridge calls.
Avatar Caching
In the Mattermost bridge, there is a specific event EventAvatarDownload that triggers the cacheAvatar function. This allows the bridge to manage remote avatars efficiently and potentially host them locally or via SHAs if the destination protocol requires it.
Sources: bridge/mattermost/mattermost.go:120-123
Conclusion
Username and avatar spoofing is essential for maintaining context in bridged conversations. By utilizing webhooks and flexible API parameters, matterbridge ensures that users on one platform can clearly identify their counterparts on another, rather than seeing all bridged messages as originating from a single bot account.
Sources: README.md:65, bridge/mattermost/mattermost.go:157-160