Telegram Bot API

Telegram Bot API 限制汇总:发送频率、429 错误、文件大小与消息长度

· 6 分钟阅读

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 小时。

如果每秒 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_data1–64 字节
媒体组2–10 项
内联查询结果最多 50 条
answerCallbackQuery 文本0–200 个字符
setMyCommands100 条命令;命令 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 parts
function 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 Bot API 限制

相关教程: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 校验代码。