Telegram
This document was written by AI and has been manually reviewed.
Telegram#
The Telegram driver uses python-telegram-bot with long polling to receive messages and the Bot API to send.
Setup#
Message @BotFather on Telegram and create a new bot with /newbot.
Copy the bot token it gives you.
Add the bot to your group and give it permission to read messages.
Get the group’s chat ID (tip: forward a message to @userinfobot, or use the bot API /getUpdates endpoint).
Config keys#
Add under telegram.<instance_id> in config.json:
| bot_token | Yes | — | Bot token from @BotFather |
| max_file_size | No | 52428800 (50 MB) | Maximum bytes per attachment when sending |
| rich_header_host | No | "https://richheader.siiway.top" | Base URL of your Cloudflare rich-header worker (see Rich Header) |
| avatar_proxy_host | No | — | Base URL of your Cloudflare avatar proxy worker (see Avatar Proxy) |
| proxy | No | — | Proxy URL for all Telegram API requests (e.g., http://proxy.example.com:8080 or socks5://proxy.example.com:1080). Set to null to explicitly disable proxy for this instance (ignores global proxy setting). |
{
"telegram": {
"tg_main": {
"bot_token": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
"max_file_size": 52428800,
"rich_header_host": "https://richheader.siiway.top",
"avatar_proxy_host": "https://tg-avatar-proxy.yourname.workers.dev"
}
}
}Rule channel keys#
Use under channels or from/to in rules.json:
| chat_id | Telegram chat ID. Use a negative number for groups (e.g. "-1002206757362") |
{
"tg_main": { "chat_id": "-1002206757362" }
}Received message types#
| Photo | image |
| Video | video |
| Voice | voice |
| Audio | voice |
| Document | file |
| Animation (GIF) | video |
Media messages may include a caption, which becomes the message text.
Sending#
| image | send_photo |
| voice | send_voice |
| video | send_video |
| file | send_document |
The message text is sent as the caption of the first attachment. If there are no attachments (or all fail), it is sent as a plain send_message. Text for subsequent attachments is omitted.
Rich Header#
When a msg_format contains a <richheader title="..." content="..."/> tag and rich_header_host is configured, NextBridge shows a small link-preview card above the message text on Telegram. The card displays the sender’s avatar, name (title), and a secondary line (content) — visually compact and distinct from the message body.
This works by serving a tiny HTML page with Open Graph meta tags from a Cloudflare Worker. Telegram fetches those tags and renders the result as a prefer_small_media link preview shown above the text.
Cloudflare Worker setup#
We provide a public endpoint, https://richheader.siiway.top. Feel free to use it.
Go to the Cloudflare dashboard → Workers & Pages → Create.
Paste the contents of cloudflare/richheader-worker.js into the editor and deploy.
Copy the worker’s URL (e.g. https://richheader.yourname.workers.dev).
Set rich_header_host in your Telegram instance config to that URL.
msg_format example#
{
"my_tg": {
"chat_id": "-100987654321",
"msg": {
"msg_format": "<richheader title=\"{user}\" content=\"id: {user_id}\"/> {msg}"
}
}
}Fallback behaviour#
| rich_header_host is not set | Bold/italic HTML header prepended to the message text |
| Message includes media attachments | Same bold/italic HTML fallback (Telegram captions cannot carry link previews) |
Avatar Proxy#
When avatar_proxy_host is configured, NextBridge uses a Cloudflare Worker to proxy Telegram user avatars, avoiding exposure of the bot token in URLs. The worker only serves avatar images (jpeg, png, gif, webp) from paths starting with photos/ or profile_photos/.
Cloudflare Worker setup#
Go to the Cloudflare dashboard → Workers & Pages → Create.
Paste the contents of cloudflare/tg-avatar-proxy.js into the editor and deploy.
Set the BOT_TOKEN environment variable in the worker settings (use the same bot token as your Telegram instance).
Copy the worker’s URL (e.g. https://tg-avatar-proxy.yourname.workers.dev).
Set avatar_proxy_host in your Telegram instance config to that URL.
Fallback behaviour#
| avatar_proxy_host is not set | Avatar URLs are not included in messages |
Notes#
Telegram bots cannot initiate conversations with users. Make sure the bot is already in the target group before running NextBridge.
The bot’s own messages are not echoed back (Telegram does not send bot message events to the bot itself).