Telegram Bridge Integration
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Telegram Bridge Integration is a native implementation within the Matterbridge ecosystem that enables bidirectional communication between Telegram and other supported chat protocols. It leverages the telegram-bot-api to interact with Telegram's servers, allowing users to synchronize messages, attachments, and edits across different platforms.
The bridge functions by acting as a Telegram Bot, receiving updates from the Telegram API via a long-polling mechanism and forwarding them to the central Matterbridge Gateway. Conversely, it receives messages from the gateway and translates them into Telegram-specific formats, supporting various parse modes like HTML and Markdown.
Sources: README.md:104, bridge/telegram/telegram.go:41-52, vendor/github.com/matterbridge/telegram-bot-api/v6/README.md
Core Architecture
The Telegram bridge is structured around the Btelegram struct, which maintains the connection state, configuration, and an avatar cache for user identity mapping.
Component Overview
The bridge implements the bridge.Bridger interface, requiring standard methods for connection management and message handling.
| Component | Responsibility |
|---|---|
Btelegram | Main bridge structure holding the BotAPI instance and configuration. |
tgbotapi | External library providing Go bindings for the Telegram Bot API. |
avatarMap | A local cache mapping UserID to avatar SHAs to optimize identity management. |
MediaConvertTgs | Integration with lottie backends to handle Telegram's animated stickers. |
Sources: bridge/telegram/telegram.go:24-29, bridge/telegram/telegram.go:31-40
Connection Lifecycle
The bridge initializes by validating optional media conversion capabilities before establishing a connection using a bot token provided in the configuration.
The bridge uses a timeout of 60 seconds for its update polling to ensure responsive message retrieval.
Sources: bridge/telegram/telegram.go:31-52
Message Handling and Formatting
Matterbridge supports multiple message formats for Telegram, allowing administrators to control how text appears to Telegram users.
Message Translation Flow
When a message arrives at the bridge from the gateway, it undergoes several transformations:
- ID Extraction: Chat IDs and optional Topic IDs are parsed from the channel string.
- Event Filtering: Specific events like
EventAvatarDownloadorEventMsgDeleteare handled. - Format Application: The text is processed based on
MessageFormat(HTML, Markdown, or MarkdownV2). - Parent Mapping: Reply contexts are resolved for threaded conversations.
Sources: bridge/telegram/telegram.go:94-135
Parse Modes
The bridge supports the following formatting options via the TGGetParseMode function:
| Format Mode | Parse Mode Constant | Description |
|---|---|---|
HTML | tgbotapi.ModeHTML | Standard Telegram HTML tags. |
Markdown | tgbotapi.ModeMarkdown | Basic Telegram Markdown. |
MarkdownV2 | MarkdownV2 | Advanced Telegram Markdown V2 syntax. |
htmlnick | tgbotapi.ModeHTML | Escapes the message body but treats the nick as HTML. |
Sources: bridge/telegram/telegram.go:65-81
Media and File Handling
The Telegram bridge provides native support for uploading files and media groups. It integrates with helper functions to process attachments from other bridges (such as Slack or Discord).
Upload Logic
- Single File: Uses
handleUploadFileto dispatch documents or images. - Media Groups: The
sendMediaFilesfunction allows multiple media items to be sent in a single Telegram album usingMediaGroupConfig. - TGS Conversion: If
MediaConvertTgsis configured, the bridge checks for compatible backends to convert animated stickers before relaying them.
Sources: bridge/telegram/telegram.go:32-38, bridge/telegram/telegram.go:127-130, bridge/telegram/telegram.go:167-184
ID Resolution for Topics and Chats
Telegram channels in Matterbridge configuration follow a specific syntax to support Supergroups with topics.
- Standard Chat: A simple numeric ID (e.g.,
12345678). - Topic-enabled: Format of
ChatID/TopicID(e.g.,12345678/99).
The getIds function splits these strings to route messages to the correct sub-thread within a Telegram group.
Sources: bridge/telegram/telegram.go:83-110
Gateway Integration
The Telegram bridge is registered within the global BridgeMap, allowing the Router to instantiate it whenever a [telegram] section is defined in the matterbridge.toml configuration.
Conclusion
The Telegram Bridge Integration provides a robust, native link to the Telegram ecosystem. By supporting complex features like message threading (via Topic IDs), multiple parse modes for rich text, and native media group uploads, it ensures that communication across bridged platforms remains as seamless and contextually accurate as possible.
Sources: bridge/telegram/telegram.go:1-196