Skip to main content

​
Telegram 接入

Telegram 是 PAI 推荐的首选平台，支持完整的文本和图片消息处理，可通过 Webhook 或轮询两种模式工作。

​
创建 Bot

1

联系 BotFather

在 Telegram 中搜索 @BotFather 并发送 /newbot
2

设置 Bot 名称

按提示输入 Bot 的显示名称和用户名（用户名必须以 bot 结尾）
3

获取 Token

BotFather 会返回一个 Bot Token，格式如 123456789:ABCdefGHIjklMNOpqrsTUVwxyz，妥善保存

​
环境变量配置

​
TELEGRAM_BOT_TOKEN
string
required
从 BotFather 获取的 Bot Token
​
TELEGRAM_WEBHOOK_SECRET
string
Webhook 验证密钥，用于校验入站请求的合法性。建议在生产环境中设置
​
TELEGRAM_POLLING_ENABLED
boolean
default:"false"
是否启用轮询模式。设为 true 时使用轮询代替 Webhook，适合本地开发
​
TELEGRAM_POLLING_INTERVAL
integer
default:"1"
轮询间隔（秒）
​
TELEGRAM_POLLING_TIMEOUT
integer
default:"30"
轮询超时时间（秒），使用 long polling 减少请求频率
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
TELEGRAM_WEBHOOK_SECRET=your-webhook-secret
TELEGRAM_POLLING_ENABLED=false

​
Webhook 模式

Webhook 是生产环境推荐的模式。Telegram 会将消息主动推送到你配置的 URL。 端点： POST /webhook/telegram

​
设置 Webhook

使用 Telegram Bot API 设置 Webhook 地址： 
curl -X POST "https://api.telegram.org/bot<YOUR_TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-domain.com/webhook/telegram", "secret_token": "your-webhook-secret"}'
Webhook URL 必须使用 HTTPS。本地开发时可使用 ngrok 等工具创建隧道。

​
轮询模式

轮询模式适合本地开发和调试，无需公网 HTTPS 地址。 
TELEGRAM_POLLING_ENABLED=true
TELEGRAM_POLLING_INTERVAL=1
TELEGRAM_POLLING_TIMEOUT=30
启用后，PAI 会定期调用 getUpdates 拉取新消息。
轮询模式和 Webhook 模式互斥。启用轮询后，已设置的 Webhook 会被自动移除。

​
功能支持

​
文本消息

接收用户发送的文本消息，经 AI 处理后回复文本响应。

​
图片消息

支持接收用户发送的照片：
  1. Telegram 会为每张图片生成多个尺寸的 file_id
  2. PAI 选取最高分辨率版本
  3. 通过 Telegram getFile API 获取文件下载 URL
  4. 将 URL 写入 UnifiedMessage.image_urls 供多模态处理

​
文件 URL 获取

Telegram 的文件通过 file_id 引用，PAI 自动调用 Bot API 将其转换为可访问的 HTTP URL，用于后续的图片识别等处理。

​
消息处理示例

用户发送消息
    │
    ▼
Telegram 推送到 POST /webhook/telegram
    │
    ▼
验证 secret_token
    │
    ▼
解析为 UnifiedMessage(platform_id="telegram", content=..., image_urls=[...])
    │
    ▼
AI 核心管线处理
    │
    ▼
UnifiedSender → Telegram sendMessage API → 用户收到回复