Telegram Bot API

Bot API 可向个人、群组或频道发送消息。本文依据 Telegram 官方 Bot API 整理，核验日期为 2026-09-14；当前网络环境无法稳定访问 Telegram 官方站点，也未使用真实 Bot 执行发送验证，因此验证等级保持“官方资料整理”。

能力边界

问题	结论
能发给谁	已启动 Bot 的用户、Bot 已加入的群组，以及授予相应权限的频道
Bot 能否主动私聊陌生用户	不能，用户必须先启动 Bot 或与 Bot 建立会话
群里能看到哪些消息	受 Privacy Mode、管理员权限、命令、提及和回复关系影响
频道发送需要什么	将 Bot 添加为频道管理员，并授予发布消息所需权限
是否有独立 Web 配置页	核心创建和设置通过 Telegram 客户端内的官方 @BotFather 完成
Bot API 是否自带 AI	不提供；AI 模型是业务服务，可选接在收消息和 sendMessage 之间

仅做通知时不需要关闭 Privacy Mode。需要双向消息、Webhook 和 AI 对话时参阅对话 Bot。

准备条件

1. 部署环境和管理员客户端能够访问 Telegram 与 api.telegram.org；部分网络区域可能需要组织批准的稳定出口方案。
2. 可在 Telegram 客户端中确认官方 @BotFather 账号并与其对话。
3. 目标用户已主动 Start，或 Bot 已加入目标群组/频道。
4. 频道场景由频道管理员授予 Bot 发布消息权限；群组场景确认 Bot 没有被限制发言。
5. 已通过 Update、业务绑定或频道用户名取得目标 chat_id，不使用显示名称猜测 ID。
6. Bot Token 只保存在服务端，HTTP 客户端和代理日志不会记录包含 Token 的 URL。

如何判断机器人是否有权限

先调用 getMe 验证 Token 和 Bot 身份：

curl 'https://api.telegram.org/botBOT_TOKEN/getMe'

返回 ok=true 只证明 Token 有效。再对目标会话调用 getChatMember，其中 user_id 使用 getMe 返回的 Bot ID：

curl 'https://api.telegram.org/botBOT_TOKEN/getChatMember?chat_id=CHAT_ID&user_id=BOT_USER_ID'

• 私聊：用户未 Start 时，Bot 通常不能主动建立会话。
• 群组：状态不能是 left 或 kicked，并检查群是否限制 Bot 发言。
• 频道：Bot 通常需要管理员身份和 can_post_messages 权限。
• getMe.can_read_all_group_messages=true 表示 Bot Privacy Mode 已关闭；它不是发送权限，也不应为了通知场景主动开启。

配置步骤

1. 创建并保存 Bot

1. 在 Telegram 客户端打开官方 @BotFather，发送 /newbot。
2. 设置展示名称和以 bot 结尾的唯一用户名。
3. 将 Bot Token 写入服务端 Secret 管理，不粘贴到网页调试器、聊天或仓库。
4. 可通过 /setdescription、/setabouttext 和 /setcommands 完善说明与命令列表。

2. 建立目标会话

• 私聊：让用户打开 Bot 并点击 Start，服务端从收到的 Update 保存 message.chat.id。
• 群组：把 Bot 加入测试群，发送一条 /start 或 /ping，从 Update 取得群 chat.id。
• 频道：由管理员将 Bot 添加为管理员并授予发布权限；公开频道可在部分 API 中使用 @channelusername，生产系统仍应保存平台返回的稳定 ID。

群组升级为超级群后 ID 可能变化，处理 Update 中的迁移字段并更新业务绑定。

3. 验证 Token、权限和发送

1. 调用 getMe，确认 ok=true、Bot ID 和用户名符合预期。
2. 调用 getChatMember 检查 Bot 在目标群或频道中的状态与权限。
3. 调用 sendMessage 发送最小纯文本。
4. 检查响应 ok=true 和 result.message_id，并在客户端确认消息出现。

凭据说明

字段	必需	说明
BOT_TOKEN	是	@BotFather 生成的机器人令牌
CHAT_ID	是	个人、群组或频道标识

最小请求

JavaScript 示例需要 Node.js 20 或更新版本；Python 示例需要安装 requests。

curl

curl -X POST 'https://api.telegram.org/botBOT_TOKEN/sendMessage' \
  -H 'Content-Type: application/json' \
  -d '{"chat_id":"CHAT_ID","text":"通知渠道连通性测试"}'

JavaScript

const response = await fetch(
  `https://api.telegram.org/bot${process.env.BOT_TOKEN}/sendMessage`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      chat_id: process.env.CHAT_ID,
      text: '通知渠道连通性测试',
    }),
  },
);

if (!response.ok) throw new Error(`HTTP ${response.status}`);
const result = await response.json();
if (!result.ok) throw new Error(JSON.stringify(result));
console.log(result);

Python

import os
import requests

response = requests.post(
    f"https://api.telegram.org/bot{os.environ['BOT_TOKEN']}/sendMessage",
    json={"chat_id": os.environ["CHAT_ID"], "text": "通知渠道连通性测试"},
    timeout=15,
)
response.raise_for_status()
result = response.json()
if not result.get("ok"):
    raise RuntimeError(result)
print(result)

验证结果

检查响应中的 ok 是否为 true，并保存 result.message_id 与聊天标识用于排查。目标客户端还应实际看到测试消息。HTTP 200 但 ok=false 仍是业务失败。

消息、格式和频率限制

• sendMessage.text 在实体解析后为 1 到 4096 个字符。长内容应按字符和格式边界切分，不能从 UTF-8 字节中间截断。
• MarkdownV2 和 HTML 使用各自严格的实体与转义规则；格式失败时先退回纯文本。
• 图片、文件和媒体组使用独立方法，文件大小与上传方式以 Bot API 当前文档为准。
• 官方 FAQ 建议避免对同一聊天持续超过约 1 条/秒；群组还存在更严格的每分钟限制。收到 429 时读取 parameters.retry_after 后退避。
• 批量广播要排队和限速，不能用多个 Bot Token 规避平台限制。

安全建议

• Bot Token 泄露后立即通过 @BotFather 撤销并重新生成。
• 群组或频道只授予机器人发送消息所需的权限。
• 不记录完整 Token，也不要把含 Token 的请求 URL 写入访问日志。
• 不为了通知投递关闭 Privacy Mode；关闭前完成群消息数据和隐私评估。
• 发送请求设置超时，对 429 和临时 5xx 有限重试，参数和权限错误不重试。

常见问题

chat not found：机器人尚未进入目标会话，或 chat_id 不正确。

机器人无法主动私聊用户：用户通常需要先与机器人开始会话。

格式解析失败：使用 Markdown 或 HTML 时检查转义规则；先退回纯文本定位问题。

Forbidden: bot was blocked by the user：停止向该用户重试并更新订阅状态，不能通过重新生成 Token 绕过用户选择。

频道返回权限错误：用 getChatMember 检查 Bot 是否为管理员以及 can_post_messages，同时确认 chat_id 指向正确频道。

群升级后突然 chat not found：检查 Update 中的群迁移信息，更新保存的超级群 ID。

返回 429：读取 retry_after，暂停对应 Bot 或聊天的发送队列并退避。

官方资料

• Telegram Bot API
• Telegram Bots 入门
• Telegram Bots FAQ