Delta Chat ↔ Telegram Bridge Bot

A bot that acts as a bridge between Delta Chat groups and Telegram groups. It relays messages sent in mapped Telegram groups to corresponding Delta Chat groups, and vice-versa.

Built using deltabot-cli-py and python-telegram-bot (asyncio).

Key Features

• Bidirectional Group Bridging: Sync messages between Telegram groups and Delta Chat groups.
• Bidirectional Deletion Sync: Sync message deletions between both platforms with built-in safety guards.
• Bidirectional Edit Handling: Edits are synced in-place in both directions. Telegram → Delta Chat edits are processed via the message editing protocol (with delete-and-resend fallback), and Delta Chat → Telegram edits are synced using Telegram's API for editing text and captions.
• Public Telegram Channels: Bridge any public channel to a Delta Chat broadcast group.
• Channel Sync Command (/channelssync): Force-refresh names and avatars of all bridged channels from Telegram (supports both Bot API and Userbot).
• Historical Context: Automatically pre-fills newly bridged channels with the last 3 historical posts.
• Userbot Mode: Bridge channels without needing administrator permissions.
• Watchdog Protection: Automatic detection and recovery from both Userbot and Telegram Bot API polling connection hangs/errors.
• Login Code Forwarding: Automatic delivery of Telegram login codes to the admin.
• Automatic Transport Failover: Link multiple mail relays to a single account. The bot automatically detects message delivery failures via raw core events, rotates configured_addr to the next transport in round-robin fashion, and schedules a resend of the message using exponential backoff (5s, 10s, 20s, 40s...) via an asynchronous timer thread (up to a maximum of 10 attempts per message) to prevent loop propagation and CPU spikes.
• Transport Statistics: Detailed tracking of messages sent and received per relay, viewable via /transports.
• Rate Limiting & Safety: Global outgoing limits and bulk-deletion protection with admin notifications.
• Automatic Updates: Self-updating via a simple script and cron job.
• Admin-Only Management: Securely bridge channels and groups with restricted access.

Prerequisites

• Python 3.9+ (for local/venv setup)
• Telegram Bot token (create a new bot and obtain one from @BotFather)
• Delta Chat account (can be automatically created during setup by providing a valid email address, e.g. from one of public chatmail relays, and a random password)

Installation

1. Clone or navigate to this directory:

   cd deltachat_telegram_bridge
   

2. Create a virtual environment and install dependencies:

   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   

Setup and Running (Local / venv)

1. Initialize the Delta Chat account Configure your bot's Delta Chat account using init dc:

   venv/bin/python bot.py init dc YOUR_DELTA_CHAT_EMAIL YOUR_EMAIL_PASSWORD
   

   This saves the account configuration locally, by default in your OS config directory under tgbridge (e.g. on linux it is located at ~/.config/tgbridge, on macOS it is located at ~/Library/Application\ Support/tgbridge etc).

2. Initialize the Telegram Token Configure your bot's Telegram API token. You can pass it as an argument or enter it interactively to keep it out of your command history:

   venv/bin/python bot.py init tg
   

   This saves the token locally in the bridge.db database.

3. Start the bridge bot Once initialized, run the serve command to start the relay:

   venv/bin/python bot.py serve
   

Setup with Docker Compose (Recommended)

Important

Breaking Change (June 2026): The bot's execution user inside the Docker container has been changed to root (matching other Delta Chat bots). All configuration and runtime data are now centralized under a single ./data directory on the host to make backups simpler and cleaner.

If you are migrating from an older installation:

1. Stop the bot: docker compose down
2. Create the ./data directory: mkdir -p data
3. Move your existing data to the new structure:

   mv bridge.db data/bridge.db
   mv userbot_session.session data/userbot_session.session
   # If you had account configuration in ~/.config/tgbridge:
   mv ~/.config/tgbridge data/tgbridge
   

4. Pull the latest code and start the bot: ./update.sh (or docker compose up -d --build).

Instead of using a local virtual environment, you can run the bot using Docker Compose:

1. Initialise the database and accounts using docker compose run:

   docker compose run --rm bridge python bot.py init dc me@example.com MyPassword
   docker compose run --rm bridge python bot.py init tg
   

2. Start the bridge:

   docker compose up -d
   

3. To update the bot manually after pulling new code:

   docker compose up -d --build
   

   Your configuration and message history will be preserved since they are stored in the mounted ./data directory.

Configuration (Environment Variables)

The bot supports customizing message retention and attachment size limits via environment variables. If you are using Docker Compose, you can define these in the .env file in the same directory as docker-compose.yml:

Environment Variable	Description	Default Value
DELETE_DEVICE_AFTER	Local message retention duration (in seconds). Delta Chat core automatically deletes messages older than this.	604800 (7 days)
MAX_ATTACHMENT_SIZE_MB	Maximum size of attachments to download and relay (in megabytes). Files larger than this will be skipped.	50

Setting Environment Variables

Create or edit the .env file in the project root:

# Retain messages on device for 3 days (259200 seconds)
DELETE_DEVICE_AFTER=259200

# Set maximum attachment size limit to 20 MB
MAX_ATTACHMENT_SIZE_MB=20

Apply the changes by restarting the container:

docker compose down
docker compose up -d

Note: The local message retention duration (DELETE_DEVICE_AFTER) is applied to all active Delta Chat accounts on startup.

Automatic Updates

The repository includes an update.sh script that automates the update process. It performs the following steps:

1. Runs git fetch to check for new commits on the remote repository.
2. Compares the local version with the remote version.
3. If new changes are found, it runs git pull, rebuilds the Docker container (--build), and cleans up old images.

Setting up a Cron Job

To have the bot automatically check for updates every 15 minutes, you can set up a cron job:

1. Open your crontab:

   crontab -e
   

2. Add the following line (replace /path/to/ with the actual absolute path to the project directory):

   */15 * * * * /path/to/deltachat_telegram_bridge/update.sh >> /path/to/deltachat_telegram_bridge/update.log 2>&1
   

Tip

You can find the absolute path by running realpath update.sh inside the directory.

1. Maintenance and Cleanup:

   To stop the bot and remove containers:

   docker compose down
   

   To remove old, unused images (reclaim disk space):

   docker image prune -f
   

   To view logs in real-time:

   docker compose logs -f
   

Usage: Bridging Groups

The bot needs to be added to the Telegram group. When you bridge from Telegram, the bot automatically creates the corresponding Delta Chat group.

Note: By default, management commands (/bridge, /unbridge, /id) are restricted to group admins. However, if you configure a global admin using init admin_dc or init admin_tg, only the configured bot owner (and designated sub-admins) will be able to manage the bot. The bot's help message will indicate its current state as Mode: Private (bot owner only) or Mode: Public (group admins only).

Important: You must disable Group Privacy for your Telegram bot via @BotFather → Bot Settings → Group Privacy → Turn off. Otherwise the bot cannot read normal group messages. After changing this, re-add the bot to the group.

From Telegram (recommended)

1. Add your Telegram bot to the target Telegram group.
2. Send /bridge in the group (admin only). The bot will automatically create a Delta Chat group with the same name and avatar, link them, and reply with an invite link to join the DC group.
3. To remove the bridge, send /unbridge in the Telegram group.

From Delta Chat (advanced)

1. Get the Telegram Group ID by sending /id in the TG group.
2. Add your Delta Chat bot to the target Delta Chat group.
3. Send /bridge -100123456789 in the DC group (owner only in private mode).
4. To remove the bridge, send /unbridge in the DC group.

Note: Group mappings are saved locally in the bridge.db SQLite file (or data/bridge.db when using Docker).

Reactions: For reaction bridging (TG → DC) to work, the bot must be an administrator in the Telegram group. No special permissions are needed — just the admin role. When a basic group is promoted, Telegram may migrate it to a supergroup (changing the chat ID). The bot detects this automatically and updates its stored mappings.

Security Notes

• The bridge.db (or data/bridge.db when using Docker) file contains your Telegram bot token in plaintext. Protect it with appropriate file permissions (e.g. chmod 600 data/bridge.db).

• Management commands (/bridge, /unbridge, /id) are restricted to group admins or bot owner (see below).

• Messages are rate-limited to 30 messages per minute per chat to prevent flooding.

• Global outgoing limit: The bot enforces a global limit of 60 messages per minute across all Delta Chat interactions to stay within chatmail server limits.

• Deletion Safety Guard: To prevent accidental data loss, the bot limits automatic deletion sync to 5 messages per 60 seconds. Bulk deletions are blocked and reported to the admin. Note: technical deletions (like replacing an old message during an edit fallback) are exempt from this limit.

• Sender names are HTML-escaped before being sent to Telegram to prevent injection.

• Bot messages from both sides are filtered out to prevent echo loops.

Logging and Admin Control

• Set Global Admin (Telegram): Configures a Telegram user ID to receive all bot error logs via direct message. (You can find your Telegram ID by sending /start to the bot in a private message). Important Note: Setting admin_tg locks the Telegram management commands so that only this user can manage the bot (the help text will dynamically change to Mode: Private (bot owner only)).

  docker compose exec bridge python bot.py init admin_tg YOUR_TELEGRAM_ID
  

• Set Global Admin (Delta Chat): Configures a Delta Chat email to receive all bot error logs via direct message. Important Note: Setting admin_dc locks the /bridge and /unbridge commands so that only this user can use them (the help text will dynamically change to Mode: Private (bot owner only)).

  docker compose exec bridge python bot.py init admin_dc admin@example.com
  

• Add Backup Relay (Transport): Link multiple mail servers for automatic failover.

  docker compose stop bridge
  docker compose run --rm bridge python bot.py init transport backup@example.com "PASSWORD"
  docker compose up -d
  

Other Commands

Since the bot depends on deltabot-cli-py, you have access to a variety of other management commands. These commands do not require the --telegram-token argument.

If you are using Docker, run these commands using docker-compose exec bridge python bot.py ... (if the bot is running) or docker-compose run --rm bridge python bot.py ... (if stopped). If you are running locally, use venv/bin/python bot.py ....

Here are the commands (shown for Docker, assuming the container is running):

• Get Invite Link (QR Code data): Print the bot's invitation link so you can add it to Delta Chat groups.

  docker compose exec bridge python bot.py link
  

• List accounts: View the IDs and addresses of configured Delta Chat accounts.

  docker compose exec bridge python bot.py list
  

• Config: View or set configuration options for the bot account.

  docker compose exec bridge python bot.py config
  

• Remove account: Remove a specific Delta Chat account if you accidentally created multiple. Replace ID with the account number (e.g. 2).

  docker compose exec bridge python bot.py --account ID remove
  

• Admin: Generates a setup QR code to join an Admin control group where you can manage the bot remotely.

  docker compose exec bridge python bot.py admin
  

For more details on management commands, see the deltabot-cli-py repository.

Sub-Admins (Private Mode)

In private mode (admin_tg is set), the bot owner can designate sub-admins who can independently manage their own bridges and channels.

Sub-admins can:

• Use /bridge and /unbridge in Telegram groups
• Use /channeladd and /channelremove for channels
• View their own bridges via /stats and /channels

Sub-admins cannot see or manage resources created by the owner or other sub-admins.

Command	Description
/adminadd <user_id>	Add a sub-admin (owner only, private chat)
/adminremove <user_id>	Remove a sub-admin (owner only, private chat)
/admins	List all sub-admins (owner only, private chat)

Channel Bridging (TG Channel → DC Broadcast)

The bot can bridge Telegram channels and groups to Delta Chat broadcast channels (one-way, read-only).

Note: By default, the bot requires being an administrator in a Telegram channel to receive posts. If you cannot make the bot an admin, or you want to bridge a regular group in "stealth" read-only mode, you can enable Userbot Mode.

Setup

1. Add the bot as an admin to the Telegram channel you want to bridge.
   Alternatively, if you cannot add the bot as admin, configure Userbot Mode and use /userbotjoin first.

2. In a private chat with the bot, use /channeladd @channel_username or /channeladd -1001234567890 (numeric ID) to create the bridge.

   • Tip: When you add the bot as an administrator to a channel, it will automatically send a private message to the configured admin_tg with the channel's numeric ID and a ready-to-use bridging command.
   • Tip: If the bot is not an admin but Userbot is configured and has joined the channel, /channeladd will automatically fall back to Userbot mode.

3. The bot will create a DC broadcast channel (with the same name and avatar) and return an invite link for subscribing.

Commands (private chat, admin/sub-admin)

Command	Description
/channeladd <target>	Create a bridge (bot as admin, or Userbot if pre-joined via /userbotjoin)
/channelremove <target>	Remove a channel bridge
/channels	List bridged channels (as admin, private chat)
/channel N	Get invite link for channel by its internal number
/channelqr N	Get QR code image for channel by its internal number
/userbotjoin <link>	Join a channel/group via Userbot (no admin needed)
/groups	List technical account's groups for easy bridging
/transports	Show configured mail relays & usage stats
/addtransport <addr>	Add a backup mail relay (chatmail URI or addr password)
/rmtransport <addr>	Remove a mail relay
/resilient	Toggle resilient sending mode across all relays (admin only)
/donate	Support bot development ❤️

Delta Chat User Commands

Any Delta Chat user (not just admins) can use these commands in a private chat with the bot or in a group:

• /channels — List all available public Telegram channels (shows TG and DC stats).
• /channelN — Get the text invite link for channel #N (e.g., /channel5).
• /channelNqr — Get the QR code invite for channel #N.
• /donate — Support bot development ❤️

Management (Admin only)

• /channeladd @username — Bridge a new channel (admin email check).
• /channelremove N — Remove bridge for channel #N.
• /userbotjoin <link> — Join channel via Userbot (invite link support).
• /channelNqr — Get the QR code image for channel #N (for easy sharing/onboarding).
• /stats — Show bridge statistics for the current chat.
• /resilient — Toggle resilient sending mode across all relays (admin only).
• /help — Show Delta Chat bot help.

Target-Specific Commands in Group Chats

In group chats where multiple bots are present, you can address this bot specifically to prevent other bots from responding. Append the @tg or @tgbridge suffix to any command, for example:

• /help@tg or /help@tgbridge
• /stats@tg or /stats@tgbridge

Userbot Mode (Bridging without Admin permissions)

If you want to bridge channels where you cannot add the bot as an administrator, you can configure Userbot Mode. This allows the bot daemon to act as a regular Telegram client using your personal account.

1. Obtain API Credentials

1. Go to my.telegram.org and log in.
2. Go to API development tools.
3. Create a new application (e.g., "DC-TG-Bridge").
4. Copy your App api_id and App api_hash.

2. Configure Credentials

Run these commands inside your environment (or via docker-compose exec bridge python bot.py ...):

python bot.py init api_id YOUR_API_ID
python bot.py init api_hash YOUR_API_HASH

3. Initialize Interactive Login

This step requires entering your phone number and the SMS/Telegram validation code. If using Docker, you must run it interactively:

docker compose exec bridge python bot.py init userbot

Tip

If Telegram sends a login code to your technical account itself, the bot will automatically capture it and forward it to you via Delta Chat and Telegram.

4. Security Risks

Caution

Using your personal account for Userbot Mode comes with risks:

• Session Security: A file named userbot_session.session will be created. This file is essentially a "master key" to your Telegram account. Never share it. Ensure your server has strict file permissions.
• Account Activity: The bot will join channels on your behalf to read posts.
• API Limits: While safe for moderate use, intensive API operations can theoretically lead to temporary rate limits or account flags from Telegram's anti-spam systems. It is recommended to use a dedicated "feeder" account if you plan to bridge a very large number of channels.

5. Bridge the Channel

Once the Userbot is configured and has joined the channel (via /userbotjoin):

1. In a private chat with the bot, use /channeladd @channel_username or /channeladd -1001234567890.
2. The bot will automatically use the Userbot to resolve the channel and relay messages — no admin rights needed.

Note: /channeladd always tries the Bot API first. If the bot is not an admin and the Bot API fails, it falls back to the Userbot transparently. You don't need to specify which mode to use.

---

Double Bridge Protection

If a channel is bridged via both the core bot (as admin) and Userbot Mode, the bridge will automatically deduplicate messages, ensuring Delta Chat users receive only one copy of each post.

Development and Testing

The repository contains a unit test suite covering database operations, rate limits, and helper logic. Since native Delta Chat C-libraries and account setups are mocked, the tests can be run locally in any standard Python environment.

To run tests locally:

python -m unittest discover -s tests -p "test_*.py" -v

Tests are also executed automatically via GitHub Actions on every push to the master branch.

Changelog

See CHANGELOG.md for a detailed history of changes.