Telegram Bridge

Telegram Bridge connects one public EdgeChat group to one Telegram group chat. Once connected, regular text, Unicode Emoji, images, videos, and files are synchronized in both directions. Telegram users do not need EdgeChat accounts.

Prerequisites

1. Create a Bot with Telegram's @BotFather and obtain its Bot Token.
2. Add the Bot to the target group or supergroup.
3. Disable group privacy mode for the Bot in @BotFather, or make the Bot a group administrator, so it can receive ordinary group messages.
4. Obtain the target Telegram group ID. Group IDs are negative; supergroup IDs usually start with -100.

The Bot Token does not need to be stored in wrangler.toml or GitHub Secrets. After an administrator enters it in the EdgeChat admin panel, the Worker encrypts it with the existing server-side keyring and stores it in D1. The frontend cannot read the Token or Webhook Secret back.

Connect the Bot

1. Sign in to EdgeChat with an administrator account.
2. Open "Telegram Bridge" in the admin panel.
3. Enter the Bot Token and click "Connect Bot."
4. EdgeChat calls Telegram getMe to validate the Token and automatically configures a Webhook for the current site.

Updating the Bot Token also generates a new Webhook Secret and reconfigures the Webhook.

Create a Group Mapping

1. Select a public EdgeChat group.
2. Enter the target Telegram group ID.
3. Save the mapping.

The first version uses a one-to-one relationship: one public EdgeChat group can connect to only one Telegram group, and one Telegram group can connect to only one public EdgeChat group. Mappings can be paused, resumed, or deleted. Private groups and direct messages cannot be connected.

Synchronization Rules

• Regular Telegram text messages are stored as external-sender messages and continue through EdgeChat's existing persistence, real-time broadcast, and unread-notification flow.
• Telegram images, videos, and regular files up to 16 MiB are downloaded immediately, encrypted, and copied to Cloudflare R2. EdgeChat no longer depends on the Telegram file URL afterward.
• For Telegram users, EdgeChat stores only the display name, Telegram user ID, and source metadata. It does not create a local account.
• EdgeChat uses one sender model in the UI and shows a small TG badge for Telegram sources.
• After an EdgeChat message is saved successfully, it is forwarded asynchronously to the mapped Telegram group.
• Messages sent from EdgeChat to Telegram use a bold username followed by a blank line before the message body.
• EdgeChat sends images with sendPhoto, videos with sendVideo, voice notes with sendVoice, audio files with sendAudio, and other files with sendDocument.
• Messages originating from Telegram are not forwarded back to Telegram, preventing loops.
• Telegram Webhook retries are deduplicated by group ID and message ID, so the same message is not stored or broadcast twice.

File Storage and Limits

The Bridge uses a 16 MiB file limit in both directions. Incoming Telegram files are checked using their declared size before download and their actual byte size afterward. Outgoing EdgeChat files are also checked before reading from R2 and uploading to Telegram.

• Telegram to EdgeChat: oversized attachments are not downloaded. The original caption is still synchronized; if there is no caption, EdgeChat displays "Attachment exceeds 16 MB and was not synchronized."
• EdgeChat to Telegram: the local message is still sent successfully. Oversized attachments are skipped and logged as a Bridge warning, while the message text is still synchronized.
• Without an R2 binding: text messages continue to synchronize in both directions, but no file download or read is attempted. Incoming Telegram messages are marked to indicate that file storage is unavailable and the attachment was not synchronized.
• Telegram files are encrypted with EdgeChat's existing attachment key before being written to R2. Downloads still require an EdgeChat Session and message-access authorization.
• The Bot Token never appears in an R2 Key, browser download URL, or API response.
• R2 objects use the format telegram/{chat_id}/{message_id}-{uuid}.{ext}. Message deletion and the existing garbage collector continue to remove unreferenced objects.

Current Limitations

The current version supports regular text, Unicode Emoji, Telegram display names, images, videos, voice notes, audio, and regular files. It does not yet support stickers, animations, oversized files, message edits, recalls, reply relationships, or topic mapping.

Key Rotation

The Telegram Bot Token and Webhook Secret rely on EdgeChat's server-side encryption keyring. When rotating the active key, you may add a new key, but you must retain every old key ID that is still referenced by historical ciphertext. Deleting an old key makes existing Telegram configuration encrypted with that key impossible to decrypt.

Troubleshooting

• The admin panel reports an invalid Token: confirm that the full Token was entered without extra spaces.
• A group mapping cannot be saved: confirm that the Bot has joined the target group, the group ID is negative, and the target is a group or supergroup rather than a channel.
• Telegram messages do not appear in EdgeChat: check the Bot's group privacy mode, administrator permissions, and whether the mapping is enabled.
• EdgeChat messages do not appear in Telegram: confirm that the Bot is still in the target group and can send messages.
• Files are not synchronized: confirm that the file is no larger than 16 MiB and is an image, video, voice note, audio file, or regular file.
• Synchronization stopped after a domain change: save the Bot Token again in the admin panel so the Webhook is configured for the current domain.