Attachment & File Handling

Relevant source files

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

• bridge/helper/helper.go
• bridge/helper/lottie_convert.go
• bridge/discord/helpers.go
• bridge/msteams/handler.go
• vendor/github.com/mattermost/mattermost-server/v6/model/client4.go
• README.md

Matterbridge provides a robust system for handling attachments and file transfers across diverse chat protocols. It allows files uploaded on one platform (e.g., Discord or MS Teams) to be downloaded, optionally processed, and subsequently uploaded to other bridged platforms (e.g., Mattermost or Slack).

This system manages the entire lifecycle of a file during the bridging process, including URL resolution, data retrieval, format conversion for specific assets like Telegram stickers, and integration with external Media CDNs.
Sources: README.md:122, bridge/helper/helper.go

Core File Processing Logic

The central logic for file handling resides in the bridge/helper package. This package defines how incoming files are converted into a standardized RemoteFile structure that can be understood by all bridge implementations.

Standardized Bridging Flow

When a bridge receives a message with an attachment, it typically follows a sequence of downloading the data and wrapping it in a Message object's Extra field.

The diagram above illustrates the typical flow of an attachment from a source bridge to a target bridge via the gateway.
Sources: bridge/helper/helper.go:72-136, bridge/helper/lottie_convert.go

Key Helper Functions

Function	Purpose	Location
DownloadFile	Performs HTTP GET to retrieve raw file bytes from a URL.	bridge/helper/helper.go:33
HandleDownloadData	Processes downloaded bytes, manages file naming, and handles MediaCDN uploads.	bridge/helper/helper.go:72
HandleUploadFile	Helper for target bridges to upload files to their respective platforms.	bridge/helper/helper.go:138
LottieToWebp	Converts Telegram Lottie stickers (.tgs) to WebP format.	bridge/helper/lottie_convert.go:13

Protocol-Specific Implementations

Each bridge implements specific logic to interface with its platform's unique file handling API or CDN.

Discord

Discord attachments are handled by fetching the attachment URL provided by the discordgo library. If a file exceeds size limits or if a MediaCDN is configured, the helper functions manage the redirection.
Sources: bridge/discord/helpers.go:89-105

Microsoft Teams

MS Teams file handling is more complex as it requires interacting with Microsoft Graph to resolve the actual download URL for files stored in OneDrive or SharePoint.

The sequence shows how MS Teams bridges resolve the internal web URL to a direct download link before processing.
Sources: bridge/msteams/handler.go:14-32

Mattermost

Mattermost utilizes a dedicated Client4 to manage file operations, providing specialized endpoints for multipart uploads and file information retrieval.

• UploadFile: Uses multipart/form-data to send files to a specific channel.
• GetFile: Retrieves raw bytes using a file ID.
• GetFileInfo: Fetches metadata (size, name, extension) for a given file.
  Sources: vendor/github.com/mattermost/mattermost-server/v6/model/client4.go:1483-1520

Media Conversion: Lottie to WebP

Telegram uses the Lottie format (.tgs) for animated stickers, which is not natively supported by most other chat platforms. Matterbridge includes a conversion utility that uses an external lottie2webp tool to transform these assets into WebP images.

func LottieToWebp(data []byte) ([]byte, error) {
    // ... logic to write to temp file
    // ... execute lottie2webp
    // ... return webp bytes
}

If the conversion fails, the bridge will typically fall back to sending the original file or a notification of failure.
Sources: bridge/helper/lottie_convert.go:13-64

External Media Storage (MediaCDN)

If configured in the general settings, Matterbridge can upload all intercepted attachments to a web-accessible directory or a CDN instead of passing the raw bytes directly to other bridges.

• When MediaCDN is active, HandleDownloadData uploads the file to the specified location.
• The Message.Extra field is then populated with the new CDN URL.
• Target bridges can then choose to either post the link or download the file from the CDN to re-upload.
  Sources: bridge/helper/helper.go:102-120

Conclusion

Attachment and file handling in Matterbridge is a coordinated effort between generic helper functions and protocol-specific handlers. By standardizing file metadata into the RemoteFile structure and providing utilities for common tasks like downloading and format conversion, the system ensures that media can flow seamlessly between incompatible chat ecosystems.