{"id":23155943,"url":"https://github.com/hyp3rd/telegram-discord-bridge","last_synced_at":"2025-08-17T23:32:18.586Z","repository":{"id":153156895,"uuid":"628312939","full_name":"hyp3rd/telegram-discord-bridge","owner":"hyp3rd","description":"A bridge to forward messages from those pesky Telegram channels to a shiny Discord server, because why not?","archived":false,"fork":false,"pushed_at":"2025-08-12T17:18:38.000Z","size":461,"stargazers_count":29,"open_issues_count":3,"forks_count":10,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-12T17:28:58.617Z","etag":null,"topics":["bot","discord","openai","python","telegram","telegram-bot","telegram-to-discord","telegram-to-discord-bot"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hyp3rd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["hyp3rd"]}},"created_at":"2023-04-15T15:01:12.000Z","updated_at":"2025-08-12T16:39:51.000Z","dependencies_parsed_at":"2024-05-05T12:22:47.464Z","dependency_job_id":"056f2a97-731b-4518-a4c3-38714e4b6bae","html_url":"https://github.com/hyp3rd/telegram-discord-bridge","commit_stats":null,"previous_names":[],"tags_count":44,"template":false,"template_full_name":null,"purl":"pkg:github/hyp3rd/telegram-discord-bridge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyp3rd%2Ftelegram-discord-bridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyp3rd%2Ftelegram-discord-bridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyp3rd%2Ftelegram-discord-bridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyp3rd%2Ftelegram-discord-bridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyp3rd","download_url":"https://codeload.github.com/hyp3rd/telegram-discord-bridge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyp3rd%2Ftelegram-discord-bridge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270922510,"owners_count":24668567,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-17T02:00:09.016Z","response_time":129,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bot","discord","openai","python","telegram","telegram-bot","telegram-to-discord","telegram-to-discord-bot"],"created_at":"2024-12-17T21:12:01.713Z","updated_at":"2025-08-17T23:32:18.555Z","avatar_url":"https://github.com/hyp3rd.png","language":"Python","funding_links":["https://github.com/sponsors/hyp3rd"],"categories":[],"sub_categories":[],"readme":"# Telegram - Discord Bridge\n\n[![Pylint](https://github.com/hyp3rd/telegram-discord-bridge/actions/workflows/pylint.yml/badge.svg)][pylint_badge]\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\nA `Python` bridge to forward messages from any Telegram **channel** to your **Discord** server, because why not? It is highly customizable and allows you to configure various settings, such as forwarding messages with specific hashtags, mentioning roles or users in Discord, and more.\n\n## Features\n\n- Relocate messages from a multitude of Telegram channels\n- Shove forwarded messages into a designated Discord channel\n- It deals with Media and URL previews on your behalf (photos, videos, documents) from Telegram to Discord\n- **The forwarding is configurable based on allowed or excluded hashtags, keeping irrelevant content away**\n- **It handles connectivity and APIs outages for you, reconnecting automatically and forwarding the messages that were missed**\n- It is customizable mention settings, including mentioning roles or users in Discord when forwarding messages\n- It maintains the history, storing a map of the forwarded messages, allowing you to track correspondence between Telegram and Discord, **making possible replies**.\n- **It supports OpenAI's API to generate suggestions and sentiment analyses based on the text you're forwarding.**\n- It can run as a daemon and handle any shutdown gracefully, including `SIGTERM` and `SIGINT` signals. It will also save the state of the bridge, so you can resume from where you left off\n- You can enable logging to the file system, which will handle the rotation for you.\n- You can enable the management API to control the bridge remotely, including the ability to log in to Telegram via MFA.\n- You can enable the anti-spam feature to prevent the bridge from forwarding the same message multiple times, or let an AI model flag suspicious messages.\n\n## Architecture\n\n```mermaid\nflowchart LR\n    TG[Telegram] --\u003e|messages| BRIDGE\n    BRIDGE --\u003e|forwards| DC[Discord]\n    BRIDGE --\u003e API[Management API]\n    API --\u003e CFG[Config]\n```\n\nThe bridge listens to Telegram channels and relays content to Discord. A management API exposes runtime controls and interacts\nwith the configuration layer.\n\n## Installation\n\nFirst, you need to clone this repository:\n\n```bash\ngit clone https://github.com/hyp3rd/telegram-discord-bridge.git\ncd telegram-discord-bridge\n```\n\nNext, follow the instructions here (don't worry, they won't bite):\n\n1. Install **Python 3.10** or higher and set up a virtual environment;\n2. Install the dependencies: `pip install -r requirements.txt`\n3. Set up a [**Telegram Application**](https://core.telegram.org/api/obtaining_api_id) and obtain the API creds.\n4. Set up a Discord bridge with the necessary permissions to read and write the messages, and obtain the bridge token.\n\nNow craft a new `config.yml` file in the root directory, starting from the `config-example.yml` file.\n**Keep in mind** that in the example below the angular brackets are indicating a placeholder `\u003c\u003e`, **remove them.**\n\n```yaml\n---\n# Basic application configuration\napplication:\n  name: \"hyp3rbridg3\"\n  version: \"1.0.0\"\n  description: \"A Python bridge to forward messages from those pesky Telegram channels to a shiny Discord channel, because why not?\"\n  # Whether to enable debug mode, it will increase the verbosity of the logs and the exceptions will be raised instead of being logged\n  debug: True\n  # healthcheck interval in seconds\n  healthcheck_interval: 10\n  # The time in seconds to wait before forwarding each missed message\n  recoverer_delay: 60\n  # Enable the anti-spam feature\n  anti_spam_enabled: True\n  # The time in seconds to wait before forwarding a message with the same content\n  anti_spam_similarity_timeframe: 60\n  # Anti spam similarity threshold (set 0 to 1, with 1 being identical)\n  anti_spam_similarity_threshold: 0.8\n  # Anti spam strategy: heuristic or ml (requires OpenAI configuration)\n  anti_spam_strategy: heuristic\n\n# Management API configuration\napi:\n  enabled: True\n  # Enable the Telegram MFA login via the management API\n  telegram_login_enabled: True\n  # Credentials are handled via the in-memory secret manager\n  # The Telegram auth request expiration in seconds\n  telegram_auth_request_expiration: 300\n  # Allow CORS requests from these origins\n  cors_origins: [\"*\"]\n\n# logger setup\nlogger:\n  level: \"DEBUG\" # NOTSET, DEBUG, INFO, WARNING, ERROR, CRITICAL\n  file_max_bytes: 10485760 # 10MB\n  file_backup_count: 5\n  # format: \"%(asctime)s - %(name)s - %(levelname)s - %(message)s\"\n  format: \"%(asctime)s %(levelprefix)s %(message)s\"\n  date_format: \"%Y-%m-%d %H:%M:%S\"\n  # Whether to log to console or not\n  console: True # set to true to enable console logging and disable file based logging\n\n# Telegram configuration\ntelegram:\n  # Your Telegram phone number | With quotes\n  phone: \"\u003cyour phone number\u003e\"\n  # Your Telegram password (Two-step verification) | With quotes\n  password: \"\u003cyour password\u003e\"\n  # This has to be an integer. Read more [here](https://core.telegram.org/api/obtaining_api_id) | No quotes\n  api_id: \u003cyour api id\u003e\n  # Long 32 characters hash identifier. Read more [here](https://core.telegram.org/api/obtaining_api_id) | With quotes\n  api_hash: \"\u003cyour api hash\u003e\"\n  # Whether to log the conversations that aren't available for forwarding (private chats, etc.)\n  log_unhandled_dialogs: False\n  # Subscribe to EditMessage events to update the message on Discord\n  subscribe_to_edit_events: True\n  # Subscribe to DeleteMessage events to delete the message on Discord\n  subscribe_to_delete_events: True\n\n# Discord configuration\ndiscord:\n  # Discord Bot Token. Go create a bridge on discord. | No quotes\n  bot_token: \"\u003cyour bot token\u003e\"\n  # built-in roles in discord, they need special attention when parsing thee name to mention\n  built_in_roles: [\"everyone\", \"here\", \"@Admin\"]\n  # Discord Client max tolerable latency\n  max_latency: 0.5\n\n# OpenAI configuration\nopenai:\n  enabled: False\n  # OpenAI API Key and Organization. Read more [here](https://beta.openai.com/docs/api-reference)\n  api_key: \"\u003cyour openai api key\u003e\"\n  organization: \"\u003cyour openai organization\u003e\"\n  # The prompt to use for OpenAI, the #text_to_parse will be appended to this prompt\n  sentiment_analysis_prompt:\n    - \"Analyze the following text to determine its sentiment: #text_to_parse.\\n\\n\"\n    - \"\u003cadd the rest of your prompt, if any, here\u003e.\\n\\n\"\n    - \"\u003cadd the rest of your prompt, if any, here\u003e.\\n\\n\"\n\n# The channels map to discord channels.\ntelegram_forwarders:\n  - forwarder_name: \"\u003cforwarder_name\u003e\"\n    tg_channel_id: \u003ctg channel id\u003e\n    discord_channel_id: \u003cdiscord channel id\u003e\n    strip_off_links: False # whether to strip off links from the message\n    send_as_embed: False # whether to send messages as Discord embeds\n    mention_everyone: True\n    forward_everything: False # whether forwarding everything regardless the hashtag\n    forward_hashtags:\n      - name: \"#example1\"\n        override_mention_everyone: True\n      - name: \"#example6\"\n\n  - forwarder_name: \"\u003cforwarder_name\u003e\"\n    tg_channel_id: \u003ctg channel id\u003e\n    discord_channel_id: \u003cdiscord channel id\u003e\n    strip_off_links: False # whether to strip off links from the message\n    send_as_embed: False # whether to send messages as Discord embeds\n    mention_everyone: False\n    forward_everything: False # whether forwarding everything regardless the hashtag\n    mention_override: # tags can be hashtags or any substring\n      - tag: \"#important\"\n        roles: [\"everyone\", \"here\", \"@Admin\"]\n      - tag: \"+++\"\n        roles: [\"Trading\", \"here\"]\n    forward_hashtags:\n      - name: \"#example3\"\n        override_mention_everyone: True\n      - name: \"#example4\"\n    excluded_hashtags:\n      - name: \"#sponsored\"\n      - name: \"#sponsor\"\n```\n\nFinally, start the bridge and watch the magic happen:\n\n```bash\npython forwarder.py --start  # it will start the bridge in the foreground\n```\n\n```bash\npython forwarder.py --start --background  # it will start the bridge in background, requires the `Logger` console set to False\n```\n\nYou can control the process with a stop command:\n\n```bash\npython forwarder.py --stop\n```\n\n## Usage\n\nOnce the script gets going, it will eavesdrop on new messages in the specified Telegram channels. Messages can be filtered based on hashtags, and you can configure the bridge to mention specific roles or users in Discord when forwarding messages. The bridge supports built-in Discord roles like \"@everyone\" and \"@here\" and custom role names.\n\nIn addition to text messages, the bridge can forward media files such as photos, videos, and documents from Telegram to Discord. The bridge also handles replies to messages and embeds them as Discord replies, maintaining a mapping of forwarded messages for easier correspondence tracking between the two platforms.\n\n## Management API\n\nWhen `api.enabled` is set, the bridge exposes a FastAPI service on port `8000` for basic process control and configuration.\n\n```bash\n# Check health\ncurl http://localhost:8000/api/v1/bridge/health\n\n# Start or stop the bridge\ncurl -X POST http://localhost:8000/api/v1/bridge/start\ncurl -X POST http://localhost:8000/api/v1/bridge/stop\n\n# Fetch current configuration summary\ncurl http://localhost:8000/\n```\n\n## Run it in Docker\n\nYou can run the bridge in a Docker container. Pre-built images are published to [GitHub Packages](https://github.com/hyp3rd/telegram-discord-bridge/pkgs/container/bridge).\n\n```bash\n# pull the latest published image\ndocker pull ghcr.io/hyp3rd/bridge:v1.2.5\n\n# run the bridge mounting your configuration\ndocker run -p 8000:8000 -v $(pwd)/config.yml:/app/config.yml:ro ghcr.io/hyp3rd/bridge:v1.2.5\n```\n\nTo build the image from source:\n\n```bash\ndocker build -t ghcr.io/hyp3rd/bridge:v1.2.5 .\n```\n\nOr spin it up with Docker Compose:\n\n```bash\ndocker compose up -d\n```\n\n### Limitations\n\nThe bridge now ships with pluggable storage backends for message history. By default it keeps mappings in a local JSON file but you can switch to a SQLite database via configuration. JSON files are automatically rotated when they exceed the configured size, and log files honour the same rotation and optional compression settings.\n\n## Versioning and Release Notes\n\nThis project adheres to [Semantic Versioning](https://semver.org). Release changes are documented in [CHANGELOG.md](CHANGELOG.md).\nDocker images are tagged with the same version number and published to GitHub's container registry.\n\n## Contributing\n\nContributions are welcome! Read the [CONTRIBUTING](CONTRIBUTING.md) guidelines for details on setting up your environment and\nsubmitting pull requests. Feature requests can be filed through GitHub issues using the \"enhancement\" label.\n\nIf you're new to the project, look for issues marked `good first issue` or `help wanted` in the tracker—they're perfect entry\npoints for newcomers.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\nThis project is a masked vigilante inspired by the base idea of [Telegram-To-Discord-Forward-Bot](https://github.com/kkapuria3/Telegram-To-Discord-Forward-Bot) by [kkapuria3](https://github.com/kkapuria3/).\n\n## DISCLAIMER\n\nThis project is not affiliated with Telegram or Discord. It is an open-source project developed by a single person in their spare time. It is provided as-is, with no warranty whatsoever.\n**Use it at your own risk.**\n\n## Author\n\nI'm a surfer, a crypto trader, and a software architect with 15 years of experience designing highly available distributed production environments and developing cloud-native apps in public and private clouds. Just your average bloke. Feel free to connect with me on LinkedIn, but no funny business.\n\n[![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge\u0026logo=linkedin\u0026logoColor=white)](https://www.linkedin.com/in/francesco-cosentino/)\n\n[pylint_badge]: https://github.com/hyp3rd/telegram-discord-bridge/actions/workflows/pylint.yml\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyp3rd%2Ftelegram-discord-bridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyp3rd%2Ftelegram-discord-bridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyp3rd%2Ftelegram-discord-bridge/lists"}