Telegram Bot API 限制汇总:发送频率、429 错误、文件大小与消息长度
Telegram Bot API 的频率限制看起来很简单:同一个聊天每秒约 1 条消息,群组每分钟 20 条,所有聊天合计每秒约 30 条。超出后 API 会返回 429 Too Many Requests,并附带 retry_after 值。本文把 Telegram Bot API 的各项限制集中整理在一起(发送频率、付费广播、文件大小、文本长度和更新),并附上让机器人始终不超限的代码。
Telegram Bot API 发送消息的频率限制
官方 Bots FAQ 列出的普通(免费)发送限制如下:
| 范围 | 限制 | 说明 |
|---|---|---|
| 单个聊天 | 约每秒 1 条 | 短时间突发可以容忍,之后开始出现 429 错误。 |
| 单个群组 | 每分钟 20 条 | 按每个群聊分别计算。 |
| 群发通知 | 约每秒 30 条 | 开启付费广播后最高每秒 1000 条。 |
这些数字应视为参考值,而不是承诺。Telegram 说明限制可能调整,而且测试环境的频率限制并没有放宽(甚至可能更严格)。遵循 retry_after 的代码,能扛住那些会让写死的“30”失效的变化。
429 Too Many Requests 与 retry_after
触发频率限制时,响应如下:
{
"ok": false,
"error_code": 429,
"description": "Too Many Requests: retry after 17",
"parameters": {"retry_after": 17}
}
retry_after 表示距离可以重新发送还剩多少秒。至少等待这么久,再重新发送同一个请求;立即重试只会延长封禁时间。Python 和 JavaScript 的辅助函数:
import time
import requests
API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours"
def call(method, max_attempts=5, **params):
for _ in range(max_attempts):
r = requests.post(f"{API}/{method}", json=params, timeout=30).json()
if r["ok"]:
return r["result"]
if r["error_code"] != 429:
raise RuntimeError(f'{r["error_code"]}: {r["description"]}')
time.sleep(r.get("parameters", {}).get("retry_after", 1) + 0.5)
raise RuntimeError("仍被限流,放弃重试")
call("sendMessage", chat_id=123456789, text="你好")const API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours";
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
async function call(method, params, maxAttempts = 5) {
for (let i = 0; i < maxAttempts; i++) {
const res = await fetch(`${API}/${method}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(params),
});
const data = await res.json();
if (data.ok) return data.result;
if (data.error_code !== 429) throw new Error(data.description);
await sleep(((data.parameters?.retry_after ?? 1) + 0.5) * 1000);
}
throw new Error("仍被限流");
}用队列控制群发速度
重试只能解决单个请求的问题。做消息推送和通知时,必须控制发送本身的节奏,例如把全局速度控制在略低于每秒 30 条:
def broadcast(chat_ids, text, per_second=25):
for chat_id in chat_ids:
try:
call("sendMessage", chat_id=chat_id, text=text)
except RuntimeError as e:
print(chat_id, e) # 403:用户屏蔽了机器人,从列表中移除
time.sleep(1 / per_second)async function broadcast(chatIds, text, perSecond = 25) {
for (const chatId of chatIds) {
try {
await call("sendMessage", { chat_id: chatId, text });
} catch (e) {
console.log(chatId, e.message); // 403:用户屏蔽了机器人,从列表中移除
}
await sleep(1000 / perSecond);
}
}在生产环境中,应把这段逻辑放到后台任务中运行,为每个聊天记录上次发送时间,保证每个聊天每秒不超过 1 条;返回 403 的聊天直接移除,不要重试。不使用付费广播时,Telegram 建议把大规模群发分散到更长的时间段,例如 8–12 小时。
付费广播:每秒最多 1000 条
如果每秒 30 条不够用,可以在 @BotFather 中开启付费广播,并在 sendMessage、sendPhoto、sendMediaGroup 等发送方法中传入 "allow_paid_broadcast": true。之后机器人每秒最多可以群发 1000 条消息。超出免费的每秒 30 条的部分,每条从机器人余额中扣除 0.1 Telegram Stars,只对成功发出的消息计费。开通需要满足最低 Stars 余额要求(Bots FAQ 还提到了用户规模门槛),规划之前请先在官方文档中确认最新数字。
Telegram 机器人文件大小限制
| 操作 | 限制 |
|---|---|
通过 multipart/form-data 上传文件 | 50 MB |
| 上传照片 | 10 MB;宽 + 高 ≤ 10000,宽高比 ≤ 20 |
| 通过 HTTP URL 发送照片 | 5 MB |
| 通过 HTTP URL 发送其他文件 | 20 MB(通过 URL 调用 sendDocument 仅支持 .PDF 和 .ZIP) |
通过 getFile 下载 | 20 MB;下载链接至少有效 1 小时 |
通过 file_id 重新发送 | 不限大小 |
本地 Bot API 服务器可以解除两项最大的限制:上传最大 2000 MB,下载不限大小,另外 Webhook 可以使用任意端口的普通 HTTP。把机器人切换到自建服务器之前,需要先调用 logOut。下载前想先检查文件,可以在 Bot API Tester 的 getFile 中调用,查看 file_size 和 file_path。
消息长度及其他内容限制
| 项目 | 限制 |
|---|---|
| 消息文本 | 解析实体后 1–4096 个字符 |
| 媒体说明文字(caption) | 0–1024 个字符 |
富文本消息(sendRichMessage) | 32768 个 UTF-8 字符、500 个块、50 个媒体、表格 20 列 |
callback_data | 1–64 字节 |
| 媒体组 | 2–10 项 |
| 内联查询结果 | 最多 50 条 |
answerCallbackQuery 文本 | 0–200 个字符 |
setMyCommands | 100 条命令;命令 1–32 个字符,描述 1–256 个字符 |
深度链接 start 参数 | 最多 64 个字符:A-Z a-z 0-9 _ - |
Mini App sendData | 最多 4096 字节 |
callback_data 按字节计算,非 ASCII 字符在 UTF-8 中每个占 2–4 字节(中文一般占 3 字节),所以按钮里只放一个短 ID,详细信息存到数据库中。超过 4096 个字符的文本必须拆分,最好按换行拆:
def split_text(text, limit=4000): # 比 4096 略小,留出余量
parts, current = [], ""
for line in text.splitlines(keepends=True):
if current and len(current) + len(line) > limit:
parts.append(current)
current = ""
while len(line) > limit:
parts.append(line[:limit])
line = line[limit:]
current += line
if current:
parts.append(current)
return partsfunction splitText(text, limit = 4000) { // 比 4096 略小,留出余量
const parts = [];
let current = "";
for (let line of text.split(/(?<=\n)/)) { // 按行拆分,保留 "\n"
if (current && current.length + line.length > limit) {
parts.push(current);
current = "";
}
while (line.length > limit) {
parts.push(line.slice(0, limit));
line = line.slice(limit);
}
current += line;
}
if (current) parts.push(current);
return parts;
}更新与 Webhook 的限制
- 机器人收到之前,传入的更新最多在 Telegram 服务器上保存 24 小时。
getUpdates每次返回 1–100 条更新(limit,默认 100)。用timeout实现长轮询,用offset= 最后一个update_id+ 1 确认已处理的更新。- 设置了 Webhook 时
getUpdates无法使用(409 Conflict),需先调用deleteWebhook。 setWebhook的max_connections取值 1–100(默认 40),端口只能是 443、80、88 和 8443。本地 Bot API 服务器允许最多 100000 个连接和任意端口。
如何避免超出 Telegram Bot API 限制
- 所有消息都经过同一个队列发送,全局速度低于每秒 30 条,每个聊天每秒最多 1 条。
- 显示进度时用
editMessageText编辑同一条消息,而不是连续发送新消息。 - 媒体文件通过
file_id重新发送,不要重复上传。 - 遵循
retry_after,403 错误永远不要重试。 - 传入
allowed_updates,只接收实际会处理的更新类型。
相关教程:Telegram Bot API 发送消息教程介绍了格式设置和单条消息的报错,Webhook 设置教程讲解如何大规模接收更新,Bot API 10 新功能介绍了富文本消息及其限制。
常见问题
Telegram Bot API 的频率限制是多少?
Telegram 的 Bots FAQ 给出了三个数字:同一个聊天中每秒不要超过 1 条消息,群组中每分钟不超过 20 条,群发通知整体约每秒 30 条。超出后会返回 429 Too Many Requests。
Telegram 返回 429 Too Many Requests 怎么办?
从错误中读取 parameters.retry_after,等待相应的秒数后重新发送同一个请求。要从根本上避免触发限制,应通过队列发送,同时控制单个聊天和全局的发送速度。
Telegram 机器人的文件大小限制是多少?
机器人上传文件最大 50 MB(照片最大 10 MB),通过 getFile 下载文件最大 20 MB。通过 URL 发送时,照片限 5 MB,其他文件限 20 MB。使用本地 Bot API 服务器时,上传上限为 2000 MB,下载不限大小。
Telegram 机器人一条消息最多多少字?
文本消息在解析实体后为 1–4096 个字符,媒体说明文字为 0–1024 个字符,更长的文本需要拆分。富文本消息(Bot API 10.1 起)最多支持 32768 个 UTF-8 字符。
Telegram 机器人如何每秒发送超过 30 条消息?
在 @BotFather 中开启付费广播,并在请求中传入 allow_paid_broadcast: true。之后机器人每秒最多可发送 1000 条消息;超出免费的每秒 30 条的部分,每条收取 0.1 Telegram Stars,只对成功发出的消息计费。
Telegram 会为机器人保存更新多久?
未被取走的更新最多保存 24 小时。getUpdates 每次最多返回 100 条更新;把 offset 设为最后一个 update_id + 1 即可确认已处理的更新。
相关教程
Telegram 机器人教程:从零创建 Telegram 机器人并发送第一条消息
Telegram 机器人教程:在 @BotFather 中用 /newbot 创建机器人并获取 Token,用 getMe 验证,再通过 getUpdates 找到 chat_id,用 curl 和 Python 发出第一条消息,附常见问题排查。
Telegram 机器人部署教程:VPS、Docker 与 Serverless 托管方案
Telegram 机器人部署与托管指南:轮询还是 Webhook,VPS 上的 systemd 服务、Docker 部署、带 secret_token 校验的 Cloudflare Workers,以及上线检查清单。
Telegram Bot API 10.0–10.5 新功能:机器人设置、小组件、富文本消息、临时消息、访客模式等
Telegram Bot API 10.0–10.5 更新了什么:setMySettings 与 BotFullInfo、HTML 小组件、富文本消息、临时消息、访客模式,附 JSON 示例与升级清单。
Telegram Bot API 错误码大全:每种报错的含义与解决方法
Telegram Bot API 常见错误详解:400 chat not found、403 bot was blocked by the user、409 Conflict、429 retry_after,逐一说明原因、解决方法,并附错误处理代码。
Telegram 机器人命令:setMyCommands、命令作用域与 /start 深层链接
Telegram 机器人命令配置教程:@BotFather /setcommands、按作用域和语言调用 setMyCommands、/start 深层链接参数,以及群组中的 /cmd@bot 用法。
Telegram 机器人键盘教程:内联键盘、回调按钮与回复键盘
Telegram 机器人按钮教程:用 callback_data 创建内联键盘、answerCallbackQuery 应答、点击后编辑消息,以及回复键盘和 ForceReply,附完整 Python 与 JS 示例。
n8n Telegram 集成教程:连接机器人、触发工作流并发送消息
n8n 对接 Telegram 机器人:把 bot token 填入 Access Token,Telegram Trigger 通过公网 HTTPS Webhook 接收消息,按 chat id 发送消息,以及常见报错的解决方法。
Telegram Bot API 发送消息教程:sendMessage 参数、格式、按钮与错误处理
Telegram Bot API 发送消息中文教程:sendMessage 参数说明,curl、Python、JavaScript 示例,HTML 与 MarkdownV2 格式、内联按钮、群组和频道发送,以及 400、403、429 错误处理。
Telegram Bot Token 怎么获取:获取、查看、验证和撤销机器人 Token
Telegram Bot Token 怎么获取?用 @BotFather 的 /newbot 获取新 Token,在 /mybots 中查看已有 Token,用 getMe 检查是否有效,泄露后及时撤销,并配合 chat_id 接入 n8n 等工具。
Telegram Bot Webhook 设置教程:用 setWebhook 配置 Webhook URL 和 secret_token
Telegram Bot API setWebhook 中文教程:Webhook URL 的 HTTPS 与端口要求、secret_token 请求头校验、用 getWebhookInfo 排错、用 deleteWebhook 切回轮询,以及 409 等常见错误的解决方法。
Telegram chat id 获取教程:查看用户、群组、频道和话题的聊天 ID
Telegram chat id 获取教程:用 getUpdates 查看私聊、群组、超级群组、频道和论坛话题的聊天 ID,讲清负数和 -100 前缀的含义,并排查 result 为空、409 Conflict 等常见问题,附 Python 示例。
Telegram 内联机器人教程:开启 Inline 模式并用 answerInlineQuery 响应查询
Telegram 内联机器人(inline bot)开发教程:用 @BotFather 或 setMySettings 开启 Inline 模式,处理 inline_query 更新,并通过 answerInlineQuery 返回结果。
Telegram 机器人 Stars 支付教程:发票、预结账确认、退款与订阅
Telegram 机器人接入 Stars 支付:用 XTR 调用 sendInvoice,处理 pre_checkout_query 和 successful_payment,退款与订阅,附 Python/JS 代码。
Telegram 测试服务器:如何在 Telegram 测试环境中测试机器人
Telegram 测试服务器中文教程:如何登录测试环境、创建测试机器人、通过 /test/ 调用 Bot API,以及在 Bot API Tester 中开启 TEST 开关测试 Telegram 机器人。
Telegram 网站小部件教程:用 Telegram 登录网站、嵌入帖子、评论区与分享按钮
在网站上接入 Telegram:新版 Telegram 登录(OpenID Connect)、旧版 Login Widget 及 hash 校验代码、嵌入 Telegram 帖子、评论区小部件和分享按钮,附常见问题排查。
TelegramWidget JavaScript API:属性、事件、错误码与限制参考
TelegramWidget JavaScript API 中文参考:属性、request()、事件、错误码、CSS 变量,widget_query 与 answerWidgetQuery 的用法,以及小组件的全部限制。
Telegram Widget 示例:完整的小组件 HTML 与 Python 机器人代码
可直接运行的 Telegram widget 示例:静态订单卡片、用 widget_query 通信的计数器、共享小组件实时投票,以及本地预览与体积检查脚本,附完整 Python 代码。
Telegram 小组件(Widget)入门:在机器人消息中运行交互式 HTML
Telegram 小组件(Bot API 10.4)是什么:sendWidget 怎么发送、chat_data 与 public_data 状态如何运作、目前在哪里可用,以及与 Mini App 的区别。
Telegram Mini App 测试教程:从浏览器模拟到真实 Telegram 客户端
Telegram Mini App 测试全流程:浏览器模拟模式、通过 HTTPS 隧道在 localhost 调试、测试环境、各平台打开 DevTools 的方法,以及服务器端 initData 校验代码。