Telegram

Telegram 官方 Bot API。getUpdates 长轮询接收 + REST 发送，支持文本 / 图片 / 视频 / 语音 / 文件。无需公网回调，但需要能访问 api.telegram.org 的环境。

适配器类型："telegram"　源码：src/adapter/telegram/ 协议：Telegram 官方 Bot API（getUpdates 长轮询接收 + REST 发送）。

说明

特点

• getUpdates 长轮询接收，无需公网 IP 或 HTTPS 回调
• 支持文本、图片、语音、视频、文件、贴纸
• 支持内联键盘按钮回调（callback_query）
• 富媒体支持 file_id / 公网 url / base64 三种方式

原理

• 接收：GET https://api.telegram.org/bot{token}/getUpdates 长轮询（timeout=50s）
• 发送：POST https://api.telegram.org/bot{token}/{method}
• 多段消息按顺序依次发送，媒体前的文本自动作为 caption

前提

• 从 @BotFather 创建机器人并获取 token
• 运行环境能访问 api.telegram.org（国内需海外服务器或代理）

安装

适配器安装

van adapter install telegram

依赖库

无额外依赖（纯 HTTP + 内置 fetch）。

配置

{
  "botId": "TG-Bot",
  "type": "telegram",
  "token": "123456789:AAExXXX",
  "pollTimeout": 50,
  "reconnectDelay": 3000
}

配置项	必填	说明
token	✅	BotFather 申请的机器人令牌
pollTimeout	可选	长轮询超时秒数，默认 50（Telegram 上限 50）
reconnectDelay	可选	轮询出错重试间隔毫秒，默认 3000

接收事件

Telegram 更新类型	框架事件	说明
message（私聊）	private_message	用户私聊机器人
message（群/超级群/频道）	group_message	群消息，groupId = 负数 chat.id
edited_message	private_message / group_message	编辑过的消息
channel_post	group_message	频道发布
callback_query	notice	内联键盘按钮回调
my_chat_member 等	notice	机器人自身成员状态变化

消息段

类型	消息段
文本	text
图片	image（data.file_id 取最大尺寸）
语音	record
视频	video
文件	file（file_id + name）
贴纸	text（[贴纸emoji]）

API 调用

发送消息

Telegram 不区分群/私聊的发送端点，按 chat_id 路由：

// 私聊
await bot.callApi("send_private_msg", { user_id: 123456789, message: "你好" })

// 群聊
await bot.callApi("send_group_msg", { group_id: -1001234567890, message: "大家好" })

// 通用
await bot.callApi("send_msg", { chat_id: 123456789, message: "通用发送" })

Telegram 机器人不能主动私聊用户：必须用户先给机器人发过消息。

富媒体

// 图片：file_id（推荐）/ 公网 url / base64:// 均可
{ type: "image", data: { file_id: "AgACAgUAAxkD..." } }
{ type: "image", data: { url: "https://example.com/a.jpg" } }
{ type: "image", data: { file: "base64://iVBOR..." } }

// 语音 / 视频 / 文件
{ type: "record", data: { file_id: "AwAC..." } }
{ type: "video",  data: { file_id: "BAAC..." } }
{ type: "file",   data: { file_id: "BQAC...", name: "a.pdf" } }

其他

action	说明
get_me	返回机器人自身信息

常见问题

• token 从哪来：Telegram 里找 @BotFather → /newbot 创建机器人。
• 机器人收不到群消息：把机器人拉进群后，群内成员需先 @ 机器人或直接发消息触发；超级群还要把机器人设为管理员才能看所有消息。
• 409 Conflict：有另一个进程在用同一个 token 轮询，停掉旧的即可。
• 401 Unauthorized：token 填错了。
• 国内连不上：Telegram 被墙，需海外环境/代理运行。

相关项目

• Telegram Bot API 官方文档：https://core.telegram.org/bots/api