Telegram Bot API

Giới hạn Telegram Bot API: rate limit, lỗi 429, dung lượng file và độ dài tin nhắn

· 6 phút đọc

Trên giấy, giới hạn Telegram Bot API khá đơn giản: khoảng 1 tin nhắn mỗi giây trong một chat, 20 tin mỗi phút trong một group và chừng 30 tin mỗi giây trên tất cả các chat. Vượt ngưỡng, API trả về 429 Too Many Requests kèm giá trị retry_after. Bài này gom các giới hạn của Telegram Bot API về một chỗ (tốc độ gửi, paid broadcast, dung lượng file, độ dài văn bản và update) cùng code giúp bot luôn nằm trong ngưỡng cho phép.

Rate limit của Telegram Bot API khi gửi tin nhắn

Bots FAQ chính thức liệt kê các giới hạn sau cho việc gửi tin miễn phí thông thường:

Phạm viGiới hạnGhi chú
Một chat≈ 1 tin nhắn mỗi giâyGửi dồn ngắn vẫn được, sau đó bắt đầu lỗi 429.
Một group20 tin nhắn mỗi phútTính riêng cho từng group.
Thông báo hàng loạt≈ 30 tin nhắn mỗi giâyTới 1000 tin mỗi giây với paid broadcast.

Hãy coi các con số này là khuyến nghị chứ không phải cam kết. Telegram lưu ý giới hạn có thể thay đổi, và trong môi trường test giới hạn flood không được nới (thậm chí còn chặt hơn). Code tôn trọng retry_after sẽ sống sót qua những thay đổi mà con số "30" viết cứng trong code không chịu nổi.

Lỗi 429 Too Many Requests và retry_after

Khi chạm giới hạn flood, phản hồi trông như sau:

{
  "ok": false,
  "error_code": 429,
  "description": "Too Many Requests: retry after 17",
  "parameters": {"retry_after": 17}
}

retry_after là số giây còn lại trước khi được gửi lại request. Hãy chờ ít nhất chừng đó rồi gửi lại đúng request cũ; thử lại ngay lập tức chỉ kéo dài thời gian bị chặn. Hàm hỗ trợ bằng Python hoặc 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("vẫn bị giới hạn tốc độ, dừng lại")

call("sendMessage", chat_id=123456789, text="Xin chào")
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("vẫn bị giới hạn tốc độ");
}

Điều tiết gửi hàng loạt bằng hàng đợi

Retry chỉ cứu từng request riêng lẻ. Với bản tin và thông báo, bạn phải điều tiết chính việc gửi, ví dụ giữ tốc độ chung thấp hơn 30 tin mỗi giây một chút:

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: người dùng đã chặn bot, bỏ khỏi danh sách
        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: người dùng đã chặn bot, bỏ khỏi danh sách
    }
    await sleep(1000 / perSecond);
  }
}

Trên production, hãy chạy đoạn này trong background worker, lưu mốc thời gian theo từng chat để không chat nào nhận quá một tin mỗi giây, và loại các chat trả về 403 thay vì thử lại. Nếu không dùng paid broadcast, Telegram khuyên nên rải đợt gửi lớn ra khoảng thời gian dài hơn, chẳng hạn 8–12 giờ.

Nếu 30 tin mỗi giây chưa đủ, hãy bật paid broadcast trong @BotFather và truyền "allow_paid_broadcast": true vào các method gửi như sendMessage, sendPhoto hay sendMediaGroup. Bot khi đó có thể gửi tới 1000 tin mỗi giây. Mỗi tin vượt mức miễn phí 30 tin/giây tốn 0,1 Telegram Stars từ số dư của bot, và chỉ tin gửi thành công mới bị tính phí. Điều kiện sử dụng gồm số dư Stars tối thiểu (Bots FAQ còn nhắc tới ngưỡng số người dùng), nên hãy xem tài liệu chính thức để biết con số hiện tại trước khi lên kế hoạch.

Giới hạn dung lượng file của bot Telegram

Thao tácGiới hạn
Upload file bằng multipart/form-data50 MB
Upload ảnh10 MB; chiều rộng + chiều cao ≤ 10000, tỉ lệ khung hình ≤ 20
Gửi ảnh qua HTTP URL5 MB
Gửi file khác qua HTTP URL20 MB (sendDocument qua URL chỉ hoạt động với .PDF và .ZIP)
Tải xuống bằng getFile20 MB; link tải có hiệu lực ít nhất 1 giờ
Gửi lại bằng file_idKhông giới hạn dung lượng

Local Bot API server gỡ bỏ hai hạn chế lớn nhất: upload tới 2000 MB và tải xuống không giới hạn dung lượng, kèm webhook qua HTTP thường trên bất kỳ cổng nào. Hãy gọi logOut trước khi chuyển bot sang server của riêng bạn. Muốn kiểm tra file trước khi tải, gọi getFile trong Bot API Tester và xem file_size cùng file_path.

Độ dài tin nhắn và các giới hạn nội dung khác

MụcGiới hạn
Văn bản tin nhắn1–4096 ký tự sau khi parse entity
Caption của media0–1024 ký tự
Rich message (sendRichMessage)32768 ký tự UTF-8, 500 block, 50 media, 20 cột bảng
callback_data1–64 byte
Media group2–10 phần tử
Trả lời inline queryTối đa 50 kết quả
Văn bản answerCallbackQuery0–200 ký tự
setMyCommands100 lệnh; tên lệnh 1–32 ký tự, mô tả 1–256
Tham số start của deep linkTối đa 64 ký tự: A-Z a-z 0-9 _ -
sendData của Mini AppTối đa 4096 byte

callback_data được tính bằng byte, và ký tự ngoài ASCII (kể cả chữ tiếng Việt có dấu) chiếm 2–4 byte mỗi ký tự trong UTF-8, nên hãy lưu một id ngắn trong nút và để chi tiết trong database. Văn bản dài hơn 4096 ký tự phải chia nhỏ, tốt nhất là cắt theo dòng:

def split_text(text, limit=4000):  # thấp hơn 4096 một chút cho an toàn
    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) { // thấp hơn 4096 một chút cho an toàn
  const parts = [];
  let current = "";
  for (let line of text.split(/(?<=\n)/)) { // chia theo dòng, giữ lại "\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;
}

Giới hạn update và webhook

Cách giữ bot trong giới hạn Telegram Bot API

Bài liên quan: API gửi tin nhắn Telegram nói về định dạng và lỗi khi gửi từng tin, cài webhook Telegram bot giải thích cách nhận update ở quy mô lớn, còn có gì mới trong Bot API 10 giới thiệu rich message và giới hạn của chúng.

Câu hỏi thường gặp

Rate limit của Telegram Bot API là bao nhiêu?

Bots FAQ của Telegram đưa ra ba con số: không quá 1 tin nhắn mỗi giây trong một chat, không quá 20 tin nhắn mỗi phút trong một group, và khoảng 30 tin nhắn mỗi giây khi gửi thông báo hàng loạt. Vượt ngưỡng sẽ nhận lỗi 429 Too Many Requests.

Sửa lỗi 429 Too Many Requests trong Telegram thế nào?

Đọc parameters.retry_after trong phản hồi lỗi, chờ đúng số giây đó rồi gửi lại request. Để không chạm giới hạn nữa, hãy gửi qua một hàng đợi có điều tiết tốc độ theo từng chat và trên toàn bot.

Giới hạn dung lượng file của bot Telegram là bao nhiêu?

Bot upload được file tới 50 MB (ảnh tới 10 MB) và tải file tới 20 MB bằng getFile. Gửi qua URL giới hạn 5 MB với ảnh và 20 MB với file khác. Local Bot API server cho upload tới 2000 MB và tải xuống không giới hạn dung lượng.

Tin nhắn của bot Telegram dài tối đa bao nhiêu?

Tin nhắn văn bản chứa 1–4096 ký tự sau khi parse entity, caption của media 0–1024 ký tự, nên văn bản dài hơn phải chia nhỏ. Rich message (Bot API 10.1+) cho phép tới 32768 ký tự UTF-8.

Làm sao để bot Telegram gửi hơn 30 tin nhắn mỗi giây?

Bật paid broadcast trong @BotFather và truyền allow_paid_broadcast: true. Bot khi đó gửi được tới 1000 tin mỗi giây; mỗi tin vượt mức miễn phí 30 tin/giây tốn 0,1 Telegram Stars, chỉ tính phí với tin gửi thành công.

Telegram lưu update của bot trong bao lâu?

Update chưa được nhận sẽ được lưu tối đa 24 giờ. getUpdates trả về tối đa 100 update mỗi lần gọi; xác nhận đã nhận bằng cách truyền offset bằng update_id cuối cùng + 1.

Cách tạo bot Telegram từ A đến Z: BotFather, token và tin nhắn đầu tiên

Tạo bot Telegram miễn phí với @BotFather: chọn username, lấy token, kiểm tra bằng getMe, tìm chat id và gửi tin nhắn đầu tiên bằng curl, Python.

Cách deploy bot Telegram: VPS, Docker và hosting serverless

Cách deploy bot Telegram: chọn polling hay webhook, chạy service systemd trên VPS, Docker, Cloudflare Workers với secret_token và checklist lên production.

Telegram Bot API 10.0–10.5: cài đặt bot, widget, rich message, tin nhắn ephemeral, guest mode và hơn thế

Tổng hợp thay đổi Telegram Bot API 10.0–10.5: setMySettings, BotFullInfo, widget HTML, rich message, tin nhắn ephemeral, guest mode, kèm ví dụ JSON.

Lỗi Telegram Bot API: ý nghĩa từng lỗi và cách khắc phục

Giải thích lỗi Telegram Bot API: 400 chat not found, 403 bot was blocked by the user, 409 Conflict, 429 retry_after. Nguyên nhân, cách sửa và code xử lý.

Lệnh bot Telegram: setMyCommands, scope của lệnh và deep link cho /start

Cài lệnh cho bot Telegram: /setcommands trong @BotFather, setMyCommands theo scope và ngôn ngữ, tham số deep link của /start và lệnh /cmd@bot trong nhóm.

Bàn phím bot Telegram: inline keyboard, nút callback và reply keyboard

Thêm nút bấm cho bot Telegram: inline keyboard với callback_data, answerCallbackQuery, sửa tin nhắn sau khi bấm, reply keyboard và ForceReply, có code mẫu.

Tích hợp n8n với Telegram: kết nối bot, kích hoạt workflow và gửi tin nhắn

Kết nối n8n với Telegram: dùng token bot làm Access Token, Telegram Trigger cần webhook HTTPS công khai, gửi tin nhắn theo chat id và cách sửa lỗi hay gặp.

API gửi tin nhắn Telegram: hướng dẫn sendMessage với curl, Python và JavaScript

Dùng API gửi tin nhắn Telegram qua sendMessage: ví dụ curl, Python requests, JavaScript fetch, định dạng HTML, MarkdownV2, nút inline và lỗi 400, 403, 429.

Cách lấy token bot Telegram: tìm lại, kiểm tra bằng getMe và thu hồi khi bị lộ

Cách lấy token bot Telegram từ @BotFather, xem lại token của bot cũ, kiểm tra bằng getMe, sửa lỗi 401 Unauthorized và thu hồi token khi bị lộ.

Webhook Telegram bot: cài setWebhook, bảo mật bằng secret_token và dùng với n8n

Cài webhook Telegram bot từng bước: yêu cầu HTTPS và cổng, setWebhook với secret_token, kiểm tra getWebhookInfo, sửa lỗi 409 Conflict và webhook n8n.

Chat id Telegram lấy ở đâu? Cách lấy chat id cho người dùng, group, kênh và topic

Chat id Telegram lấy ở đâu: cách lấy chat id bot cho chat riêng, group, supergroup, kênh và topic bằng getUpdates, kèm cách sửa lỗi result rỗng, 409.

Bot inline Telegram: cách bật inline mode và trả lời inline query

Hướng dẫn làm bot inline Telegram: bật inline mode qua @BotFather hoặc setMySettings, xử lý update inline_query và trả kết quả bằng answerInlineQuery.

Thanh toán Telegram Stars cho bot: hóa đơn, pre-checkout, hoàn tiền và thuê bao

Nhận thanh toán Telegram Stars trong bot: sendInvoice với XTR, pre_checkout_query, successful_payment, hoàn tiền, gói thuê bao và code Python/JS.

Test server Telegram: cách test bot trong môi trường thử nghiệm của Telegram

Cách dùng test server Telegram: đăng nhập môi trường test, tạo bot test, gọi Bot API qua /test/ và bật chế độ TEST trong công cụ tester của chúng tôi.

Widget Telegram cho website: Login Widget, nhúng bài đăng, bình luận và nút chia sẻ

Đăng nhập bằng Telegram trên website: Telegram Login mới (OIDC), Login Widget cũ kèm code kiểm tra hash, nhúng bài đăng, bình luận và nút chia sẻ.

TelegramWidget JavaScript API: thuộc tính, sự kiện, mã lỗi và giới hạn

Tra cứu TelegramWidget JavaScript API: thuộc tính, request(), sự kiện, mã lỗi, biến CSS, widget_query, answerWidgetQuery và mọi giới hạn của widget.

Ví dụ widget Telegram: HTML hoàn chỉnh và code bot Python

Ví dụ widget Telegram chạy được kèm code đầy đủ: thẻ đơn hàng tĩnh, bộ đếm dùng widget_query, bình chọn trực tiếp dạng widget dùng chung và stub xem thử.

Widget Telegram: HTML tương tác ngay trong tin nhắn của bot

Widget Telegram (Bot API 10.4) là gì: cách sendWidget, chat_data và public_data hoạt động, widget chạy ở đâu và khác Mini App như thế nào.

Cách test Telegram Mini App: từ mock trên trình duyệt đến Telegram thật

Hướng dẫn test Telegram Mini App: chạy mock trên trình duyệt, localhost qua tunnel HTTPS, môi trường test, DevTools từng nền tảng và xác thực initData.