> ## Documentation Index
> Fetch the complete documentation index at: https://docs.botmux.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Telegram API 代理

> 透明代理至 api.telegram.org，支持消息捕获和方法拦截

Telegram API 代理位于 `/tgapi/bot{TOKEN}/{method}`，透明转发所有请求至 `api.telegram.org`。

## 用法

将后端中的 Telegram API 基础 URL 替换为：

```
# 之前
https://api.telegram.org/bot{TOKEN}/{method}

# 之后
http://localhost:8080/tgapi/bot{TOKEN}/{method}
```

## 文件下载

专用文件下载端点位于 `/tgapi/file/bot{TOKEN}/{file_path}`。这使 BotMux 可以直接替换 Telegram 的文件下载 URL，您可以将其配置为机器人库的 `base_file_url`：

```
# 之前
https://api.telegram.org/file/bot{TOKEN}/{file_path}

# 之后
http://localhost:8080/tgapi/file/bot{TOKEN}/{file_path}
```

WebP 文件（贴纸）会自动转换为 PNG。内容类型通过文件扩展名检测，回退到内容嗅探。响应包含 `Cache-Control: public, max-age=86400` 头。

## 身份验证

无需额外身份验证——URL 中的机器人令牌即为授权凭证（与 Telegram API 相同）。

## 消息捕获

对于发送类方法，代理会从 Telegram 响应中提取已发送的消息并保存到数据库。

## 被拦截的方法

多个 Telegram Bot API 方法被 BotMux 拦截并在内部处理，而不是转发到 Telegram：

| 方法               | 行为                                                                                                              |
| ---------------- | --------------------------------------------------------------------------------------------------------------- |
| `setWebhook`     | 在 BotMux 中配置机器人的后端 URL 并启用代理模式。通过 `getMe` 自动注册未知机器人。支持 `url` 和 `drop_pending_updates` 参数。                       |
| `deleteWebhook`  | 清除后端 URL 并禁用代理模式。支持 `drop_pending_updates`。                                                                     |
| `getWebhookInfo` | 返回 BotMux 的内部 webhook 状态（`url`、`pending_update_count`、`has_custom_certificate`、`max_connections`、`ip_address`）。 |
| `getUpdates`     | 当启用长轮询时，从 BotMux 的内部队列返回数据，而不是转发到 Telegram。当机器人由 BotMux 管理但未启用长轮询时，返回空结果以防止冲突错误。                                |
| `logOut`         | 返回 `{"ok": true, "result": true}` 而不转发。防止令牌被禁用 10 分钟。                                                           |
| `close`          | 返回 `{"ok": true, "result": true}` 而不转发。防止 Telegram 端的机器人实例被关闭。                                                  |