API 代理

透明的 Telegram API 代理，捕获机器人发出的消息

BotMux 在 /tgapi/ 提供 Telegram API 代理，透明转发请求到 api.telegram.org 并捕获发出的消息。代理还会拦截多个管理方法，使您的后端可以使用标准 Telegram Bot API 而不会与 BotMux 的内部状态冲突。

​

为什么使用 API 代理？

Telegram 的 getUpdates 只返回收到的消息——机器人自身发送的消息不包含在内。API 代理通过拦截发送方法并将发出的消息保存到数据库来解决这个问题。

​

设置

更改后端的 API 基础 URL：

# 之前（直连）
https://api.telegram.org/bot{TOKEN}/sendMessage

# 之后（通过 BotMux 代理）
http://localhost:8080/tgapi/bot{TOKEN}/sendMessage

代理将所有请求转发到 Telegram 并原样返回响应，但被拦截的方法除外，这些方法由 BotMux 内部处理。

​

文件下载代理

BotMux 还提供文件下载端点，可作为 Telegram 机器人库的 base_file_url 直接替换：

# Telegram 默认
https://api.telegram.org/file/bot{TOKEN}/{file_path}

# 通过 BotMux 代理
http://localhost:8080/tgapi/file/bot{TOKEN}/{file_path}

此端点从 Telegram 下载文件并流式传输给客户端。WebP 文件（贴纸）会自动转换为 PNG 以兼容浏览器。

​

捕获的发送方法

方法	说明
sendMessage	文本消息
sendPhoto	图片
sendAudio	音频文件
sendDocument	文档
sendVideo	视频
sendAnimation	GIF/动画
sendVoice	语音消息
sendVideoNote	视频笔记
sendSticker	贴纸
sendLocation	位置
sendVenue	地点
sendContact	联系人
sendPoll	投票
sendDice	骰子
forwardMessage	转发消息
copyMessage	复制消息
editMessageText	编辑文本消息
editMessageCaption	编辑标题
editMessageMedia	编辑媒体

当启用代理模式时，API 代理 URL 会显示在机器人详情视图中（点击复制）。

​

被拦截的方法

以下 Telegram Bot API 方法被代理拦截，由 BotMux 内部处理而不是转发到 Telegram：

方法	行为
setWebhook	将 webhook URL 注册为 BotMux 中机器人的后端 URL 并启用代理模式。未知令牌的自动注册需要设置 BOTMUX_ALLOW_AUTO_REGISTER=1 环境变量。Webhook URL 必须使用 HTTPS（除非设置 BOTMUX_STRICT_WEBHOOK=1，否则仅允许回环地址使用 HTTP）。支持 url 和 drop_pending_updates 参数。
deleteWebhook	清除后端 URL 并禁用机器人的代理模式。支持 drop_pending_updates。
getWebhookInfo	返回 BotMux 的内部 webhook 状态，包括配置的后端 URL 和待处理的更新数量。
getUpdates	当启用长轮询时，从 BotMux 的内部队列返回更新，而不是直接轮询 Telegram。对于 BotMux 已知的任何其他机器人，返回空结果以防止冲突错误。
logOut	返回成功而不转发到 Telegram。转发会导致令牌被禁用 10 分钟，破坏 BotMux 的轮询。
close	返回成功而不转发到 Telegram。转发会关闭 Telegram 端的机器人实例。

当设置 BOTMUX_ALLOW_AUTO_REGISTER=1 时，setWebhook 拦截实现了零配置迁移：将您现有的机器人后端指向 BotMux 的 API 代理 URL，BotMux 将自动注册机器人并开始将更新转发到您的后端。