SyncBot - Extensible Message Bridge

A bidirectional message bridge that synchronizes communication across Discord and Telegram (and in the future, platforms like Signal). It runs on standard python applications and is optimized for Heroku deployment.

Architecture

Platform integrations are abstracted through BasePlatformAdapter to allow dropping in any new chat service easily. Messages conform to a UniversalMessage data standard, routed by the BridgeRouter and managed by the BridgeOrchestrator. A DeduplicationCache (Redis) prevents echo loops across platforms.

---

🚀 Setup & Deployment on Heroku

The easiest way to host this bridge is utilizing a Heroku Worker dyno.

1. Create the App

heroku create
git push heroku main

2. Provision Redis Add-On

The deduplication cache requires Redis. Use the free/hobby tier:

heroku addons:create heroku-redis:eco

3. Set Config Vars (Environment Variables)

Configure bot authentication tokens:

heroku config:set DISCORD_TOKEN="YOUR_DISCORD_BOT_TOKEN"
heroku config:set TELEGRAM_TOKEN="YOUR_TELEGRAM_BOT_TOKEN"

Configure CHANNEL_PAIRS parameter: The bridge routes dynamically based on a JSON configuration of pairs.

heroku config:set CHANNEL_PAIRS='{"pairs":[{"id":"pair_1","platforms":{"discord":"DISCORD_CHANNEL_ID","telegram":"TELEGRAM_CHAT_ID"}}]}'

Notes on CHANNEL_PAIRS JSON structure:

• A bridge requires minimum two platforms in a pair to forward anything.
• Discord channel IDs are integers but must be supplied as string values.
• Telegram chat IDs (including groups) often start with -100 and must be supplied as string values.

4. Enable Dyno

Scale your worker dyno (this repo runs purely on a worker, NO web dyno is needed):

heroku ps:scale worker=1

5. View Logs

To monitor message bridging or diagnose errors:

heroku logs --tail

---

🛠 Adding a New Platform Adapter

Adding a platform like WhatsApp or Slack is done entirely natively without altering core components.

1. Create Adapter: Create a new module e.g. adapters/slack_adapter.py.
2. Inherit: Have your adapter inherit from adapters.base.BasePlatformAdapter.
3. Implement Abstract Methods: Implement connect(), disconnect(), and send_message().
4. Call handle_incoming_message: Wrap incoming events into the UniversalMessage struct and pass into self.handle_incoming_message(uni_msg, source_channel_id, message_id).
5. Add to Config: Update config.py to read the API tokens needed.
6. Register: Add it to the orchestrator load cycle inside bot.py.

🔮 Future Signal Support

An interface stub at adapters/signal_adapter.py is prepared for Signal integration.

To implement:

1. Choose an API layer (e.g., self-host bbernhard/signal-cli-rest-api via Docker, or use CallMeBot).
2. Override methods in signal_adapter.py to execute REST API calls using Python's aiohttp.
3. Set SIGNAL_ENABLED=true in Heroku Config Vars, supplying SIGNAL_PHONE_NUMBER and SIGNAL_API_URL.
4. Uncomment the orchestrator loading code in bot.py.
5. Add signal mapped channels inside your CHANNEL_PAIRS Config Var: {"signal": "GROUP_ID"}.