本文档由 AI 编写，已经人工审核。

Telegram

Telegram 驱动器使用 python-telegram-bot 通过长轮询接收消息，并通过 Bot API 发送消息。

准备工作

1. 在 Telegram 上联系 @BotFather，使用 /newbot 命令创建一个新 Bot。
2. 复制 BotFather 给你的 Bot Token。
3. 将 Bot 添加到你的群组，并赋予其读取消息的权限。
4. 获取群组的 Chat ID（提示：将群内消息转发给 @userinfobot，或通过 Bot API 的 /getUpdates 接口查询）。

配置项

在 config.json 的 telegram.<实例ID> 下添加：

键	是否必填	默认值	说明
bot_token	是	—	来自 @BotFather 的 Bot Token
max_file_size	否	52428800（50 MB）	发送附件时单个文件的最大字节数
rich_header_host	否	"https://richheader.siiway.top"	Cloudflare 富头部 Worker 的基础 URL（见 富头部）
avatar_proxy_host	否	—	Cloudflare 头像代理 Worker 的基础 URL（见 头像代理）
photo_padding_color	否	"#000000"	极端宽高比照片的填充颜色。设为 null 禁用填充
sanitize_accidental_mentions	否	true	在桥接消息的 @ 后插入零宽空格，防止意外触发 Telegram 提及
enable_recall	否	true	是否启用消息撤回同步。启用后：其他平台的撤回会通过 delete_message 应用到 Telegram；同时可回复消息并发送 /recall 主动通知撤回。注意：Telegram Bot API 无法自动检测用户删除消息，故需 /recall 命令代替。设为 false 可禁用撤回应用与 /recall 命令。
media_proxy	否	—	仅用于获取媒体/附件的代理 URL。未设置时默认跟随 proxy。
proxy	否	—	所有 Telegram API 请求的代理 URL（例如：http://proxy.example.com:8080 或 socks5://proxy.example.com:1080）。设置为 null 可显式禁用此实例的代理（忽略全局代理设置）。

{
  "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"
    }
  }
}

规则频道键

在 rules.json 的 channels 或 from/to 下使用：

键	说明
chat_id	Telegram 聊天 ID。群组使用负数（如 "-1002206757362"）

{
  "tg_main": { "chat_id": "-1002206757362" }
}

接收的消息类型

Telegram 类型	附件类型
图片（Photo）	image
视频（Video）	video
语音（Voice）	voice
音频（Audio）	voice
文件（Document）	file
动图/GIF（Animation）	video

带媒体的消息可能包含说明文字（Caption），该文字作为消息文本处理。

发送

附件类型	Telegram API 方法
image	send_photo
voice	send_voice
video	send_video
file	send_document

消息文本作为第一个附件的 Caption 发送。若没有附件（或所有附件均失败），则以普通 send_message 发送。后续附件不再携带文本。

富头部

当 msg_format 中包含 <richheader title="..." content="..."/> 标签，且已配置 rich_header_host 时，NextBridge 会在 Telegram 消息文本上方显示一张小型链接预览卡片。卡片包含发送者的头像、名称（title）和副标题（content），视觉上紧凑且与消息正文明显区分。

其工作原理是通过 Cloudflare Worker 提供一个包含 Open Graph 元标签的微型 HTML 页面。Telegram 获取这些标签后，以 prefer_small_media 样式将其渲染为显示在文字上方的链接预览卡片。

Cloudflare Worker 部署步骤

公共地址

我们提供一个公共地址，https://richheader.siiway.top。你可以直接使用它。

1. 进入 Cloudflare 控制台 → Workers & Pages → 创建。
2. 将 cloudflare/richheader-worker.js 的内容粘贴到编辑器中并部署。
3. 复制 Worker 的 URL（如 https://richheader.yourname.workers.dev）。
4. 将该 URL 设置为 Telegram 实例配置中的 rich_header_host。

msg_format 示例

{
  "my_tg": {
    "chat_id": "-100987654321",
    "msg": {
      "msg_format": "<richheader title=\"{user}\" content=\"id: {user_id}\"/> {msg}"
    }
  }
}

回退行为

条件	行为
未配置 rich_header_host	加粗/斜体 HTML 头部文字附加在消息文本前
消息包含媒体附件	同上（Telegram 的媒体 Caption 不支持链接预览）

头像代理

当配置了 avatar_proxy_host 时，NextBridge 会使用 Cloudflare Worker 代理 Telegram 用户头像，避免在 URL 中暴露 bot token。该 Worker 仅提供头像图片（jpeg、png、gif、webp），且只允许访问以 photos/ 或 profile_photos/ 开头的路径。

Cloudflare Worker 部署步骤

1. 进入 Cloudflare 控制台 → Workers & Pages → 创建。
2. 将 cloudflare/tg-avatar-proxy.js 的内容粘贴到编辑器中并部署。
3. 在 Worker 设置中添加 BOT_TOKEN 环境变量（使用与 Telegram 实例相同的 bot token）。
4. 复制 Worker 的 URL（如 https://tg-avatar-proxy.yourname.workers.dev）。
5. 将该 URL 设置为 Telegram 实例配置中的 avatar_proxy_host。

回退行为

条件	行为
未配置 avatar_proxy_host	消息中不包含头像 URL

消息编辑同步

当 Telegram 消息被编辑后，NextBridge 会检测到变更，并自动更新其他平台上对应的桥接消息。

其他平台的编辑会通过 edit_message_text 应用到 Telegram。若原始消息是通过富头部链接预览发送的，编辑时会使用相同的 rich_header_host URL 重新构建预览卡片。若未配置 rich_header_host，则回退为加粗/斜体 HTML 头部。

编辑同步仅同步文本内容。Telegram Bot API 不支持替换已发送消息的媒体附件。

消息撤回同步

其他平台（Discord/QQ）上的撤回会通过 delete_message 应用到 Telegram，删除对应的桥接消息。

重要限制： Telegram Bot API 无法检测用户删除消息——它不会推送任何删除事件。因此普通删除操作无法被自动检测或桥接到其他平台。

/recall 命令（撤回通知）： 作为上述限制的变通方案，可以回复想要撤回的消息并发送 /recall，主动通知 NextBridge 发生了撤回。NextBridge 会：

• 将撤回桥接到其他平台，删除对应的桥接消息；
• 尽力删除 Telegram 上的原始消息以及该 /recall 命令消息本身（需要 Bot 具备删除权限，通常要求在群内为管理员，且消息在可删除的时间范围内）。

若未回复任何消息就发送 /recall，Bot 会回复用法提示。

将 enable_recall 设为 false 可禁用将撤回应用到 Telegram，同时也会禁用 /recall 命令。

注意事项

• Telegram Bot 无法主动发起对话，请确保在运行 NextBridge 前 Bot 已在目标群组中。
• Bot 自身发送的消息不会被回显（Telegram 不会将 Bot 消息的事件推送给 Bot 自身）。