Limit Telegram Bot API: Rate Limit, Error 429, Ukuran File, dan Panjang Pesan
Limit Telegram Bot API terlihat sederhana di atas kertas: sekitar 1 pesan per detik di satu chat, 20 pesan per menit di grup, dan kira-kira 30 pesan per detik ke semua chat. Jika dilampaui, API membalas 429 Too Many Requests dengan nilai retry_after. Halaman ini merangkum semua limit Telegram Bot API di satu tempat (kecepatan kirim, paid broadcast, ukuran file, panjang teks, dan update) beserta kode yang menjaga bot tetap di bawah batas.
Rate limit Telegram Bot API untuk mengirim pesan
Bots FAQ resmi mencantumkan limit berikut untuk pengiriman biasa (gratis):
| Cakupan | Limit | Catatan |
|---|---|---|
| Satu chat | ≈ 1 pesan per detik | Lonjakan singkat masih ditoleransi, setelah itu muncul error 429. |
| Satu grup | 20 pesan per menit | Dihitung per grup. |
| Notifikasi massal | ≈ 30 pesan per detik | Hingga 1000 per detik dengan paid broadcast. |
Anggap angka ini sebagai pedoman, bukan kontrak. Telegram menyebut limit bisa berubah, dan flood limit di test environment tidak dinaikkan (bahkan bisa lebih ketat). Kode yang menghormati retry_after tetap aman saat angka berubah, sedangkan angka "30" yang di-hardcode bisa rusak.
429 Too Many Requests dan retry_after
Saat terkena flood limit, responsnya seperti ini:
{
"ok": false,
"error_code": 429,
"description": "Too Many Requests: retry after 17",
"parameters": {"retry_after": 17}
}
retry_after adalah jumlah detik sebelum request boleh diulang. Tunggu minimal selama itu, lalu kirim request yang sama lagi; mengulang langsung hanya memperpanjang blokir. Helper dalam Python dan 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("masih kena rate limit, menyerah")
call("sendMessage", chat_id=123456789, text="Halo")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("masih kena rate limit");
}Atur kecepatan broadcast dengan antrean
Retry hanya memperbaiki request tunggal. Untuk newsletter dan notifikasi, kecepatan pengirimannya sendiri yang harus diatur, misalnya dengan laju global sedikit di bawah 30 pesan per detik:
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: pengguna memblokir bot, hapus dari daftar
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: pengguna memblokir bot, hapus dari daftar
}
await sleep(1000 / perSecond);
}
}Di produksi, jalankan ini di background worker, simpan timestamp per chat agar tidak ada chat yang menerima lebih dari satu pesan per detik, dan hapus chat yang membalas 403 alih-alih mengulanginya. Tanpa paid broadcast, Telegram menyarankan menyebar pengiriman massal dalam rentang lebih panjang, misalnya 8–12 jam.
Paid broadcast: hingga 1000 pesan per detik
Kalau 30 pesan per detik tidak cukup, aktifkan paid broadcast di @BotFather dan kirim "allow_paid_broadcast": true ke metode kirim seperti sendMessage, sendPhoto, atau sendMediaGroup. Bot lalu bisa broadcast hingga 1000 pesan per detik. Setiap pesan di atas 30 per detik yang gratis dikenai 0,1 Telegram Stars dari saldo bot, dan hanya pesan yang berhasil terkirim yang ditagih. Syaratnya ada saldo Stars minimum (Bots FAQ juga menyebut ambang jumlah audiens), jadi cek angka terbaru di dokumentasi resmi sebelum merencanakannya.
Batas ukuran file bot Telegram
| Operasi | Limit |
|---|---|
Unggah file dengan multipart/form-data | 50 MB |
| Unggah foto | 10 MB; lebar + tinggi ≤ 10000, rasio aspek ≤ 20 |
| Kirim foto lewat URL HTTP | 5 MB |
| Kirim file lain lewat URL HTTP | 20 MB (sendDocument lewat URL hanya untuk .PDF dan .ZIP) |
Unduh dengan getFile | 20 MB; link unduhan berlaku minimal 1 jam |
Kirim ulang dengan file_id | Tanpa batas ukuran |
Local Bot API server menghapus dua batasan terbesar: unggahan hingga 2000 MB dan unduhan tanpa batas ukuran, plus webhook lewat HTTP biasa di port mana pun. Panggil logOut sebelum mengarahkan bot ke server sendiri. Untuk mengecek file sebelum diunduh, panggil getFile di Bot API Tester dan lihat file_size serta file_path.
Batas panjang pesan dan konten lainnya
| Item | Limit |
|---|---|
| Teks pesan | 1–4096 karakter setelah parsing entity |
| Caption media | 0–1024 karakter |
Rich message (sendRichMessage) | 32768 karakter UTF-8, 500 blok, 50 media, 20 kolom tabel |
callback_data | 1–64 byte |
| Media group | 2–10 item |
| Jawaban inline query | Hingga 50 hasil |
Teks answerCallbackQuery | 0–200 karakter |
setMyCommands | 100 perintah; perintah 1–32 karakter, deskripsi 1–256 |
Parameter start deep link | Hingga 64 karakter: A-Z a-z 0-9 _ - |
sendData Mini App | Hingga 4096 byte |
callback_data dihitung dalam byte, dan karakter di luar ASCII memakan 2–4 byte di UTF-8, jadi simpan ID pendek di tombol dan detailnya di database. Teks lebih dari 4096 karakter harus dipecah, sebaiknya di pergantian baris:
def split_text(text, limit=4000): # sedikit di bawah 4096 agar aman
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) { // sedikit di bawah 4096 agar aman
const parts = [];
let current = "";
for (let line of text.split(/(?<=\n)/)) { // pecah per baris, simpan "\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;
}Limit update dan webhook
- Update masuk disimpan di server Telegram hingga 24 jam sampai bot menerimanya.
getUpdatesmengembalikan 1–100 update per panggilan (limit, default 100). Pakaitimeoutuntuk long polling dan konfirmasi update denganoffset=update_idterakhir + 1.getUpdatestidak berfungsi selama webhook terpasang (409 Conflict) sampai kamu memanggildeleteWebhook.setWebhookmenerimamax_connections1–100 (default 40) dan hanya port 443, 80, 88, serta 8443. Local Bot API server mengizinkan hingga 100000 koneksi dan port apa pun.
Cara agar bot tetap di bawah limit Telegram Bot API
- Kirim semua pesan lewat satu antrean dengan laju global di bawah 30 per detik dan maksimal satu pesan per detik per chat.
- Tampilkan progres dengan mengedit satu pesan lewat
editMessageText, bukan mengirim banyak pesan baru. - Kirim ulang media dengan
file_id, bukan mengunggahnya lagi. - Patuhi
retry_after, dan jangan pernah mengulang error 403. - Isi
allowed_updatesagar hanya menerima jenis update yang benar-benar kamu tangani.
Panduan terkait: kirim pesan lewat Bot API membahas format dan error per pesan, setting webhook menjelaskan cara menerima update dalam skala besar, dan fitur baru Bot API 10 memperkenalkan rich message beserta limitnya.
Pertanyaan umum
Berapa rate limit Telegram Bot API?
Bots FAQ resmi menyebut tiga angka: hindari lebih dari 1 pesan per detik di satu chat, maksimal 20 pesan per menit di grup, dan sekitar 30 pesan per detik untuk notifikasi massal. Jika dilampaui, API membalas 429 Too Many Requests.
Bagaimana cara mengatasi 429 Too Many Requests di Telegram?
Baca parameters.retry_after dari error, tunggu selama itu (dalam detik), lalu ulangi request yang sama. Agar tidak terus kena limit, kirim lewat antrean yang mengatur kecepatan per chat dan secara global.
Berapa batas ukuran file bot Telegram?
Bot bisa mengunggah file hingga 50 MB (foto hingga 10 MB) dan mengunduh file hingga 20 MB dengan getFile. Kirim lewat URL dibatasi 5 MB untuk foto dan 20 MB untuk file lain. Local Bot API server mengizinkan unggahan hingga 2000 MB dan unduhan tanpa batas ukuran.
Berapa panjang maksimal pesan bot Telegram?
Pesan teks berisi 1–4096 karakter setelah parsing entity, dan caption media 0–1024 karakter, jadi teks yang lebih panjang harus dipecah. Rich message (Bot API 10.1+) mengizinkan hingga 32768 karakter UTF-8.
Bagaimana bot Telegram bisa mengirim lebih dari 30 pesan per detik?
Aktifkan paid broadcast di @BotFather dan kirim allow_paid_broadcast: true. Bot lalu bisa mengirim hingga 1000 pesan per detik; setiap pesan di atas 30 per detik gratis dikenai 0,1 Telegram Stars, hanya untuk broadcast yang berhasil.
Berapa lama Telegram menyimpan update untuk bot?
Update yang belum diterima disimpan hingga 24 jam. getUpdates mengembalikan maksimal 100 update per panggilan; konfirmasi dengan mengirim offset = update_id terakhir + 1.
Panduan terkait
Cara Membuat Bot Telegram: dari BotFather sampai Pesan Pertama
Cara membuat bot telegram langkah demi langkah: daftar di @BotFather, simpan token, cek dengan getMe, lalu kirim pesan pertama lewat curl dan Python.
Cara Deploy Bot Telegram: Hosting di VPS, Docker, dan Serverless
Cara deploy bot Telegram: polling vs webhook, service systemd di VPS, Docker, Cloudflare Workers dengan secret_token, plus checklist sebelum bot online.
Telegram Bot API 10.0–10.5: Pengaturan Bot, Widget, Rich Message, Ephemeral Message, Guest Mode, dan Lainnya
Fitur baru Telegram Bot API 10.0–10.5: setMySettings dan BotFullInfo, widget HTML, rich message, ephemeral message, guest mode, lengkap dengan contoh JSON.
Error Telegram Bot API: Arti Setiap Error dan Cara Mengatasinya
Daftar error Telegram Bot API: 400 chat not found, 403 bot was blocked by the user, 409 Conflict, 429 retry_after. Penyebab, solusi, dan kode penanganan.
Perintah Bot Telegram: setMyCommands, Scope Perintah, dan Deep Link /start
Cara membuat perintah bot Telegram: /setcommands di @BotFather, setMyCommands dengan scope dan bahasa, parameter deep link /start, dan /cmd@bot di grup.
Keyboard Bot Telegram: Inline Keyboard, Tombol Callback, dan Reply Keyboard
Cara membuat tombol bot Telegram: inline keyboard dengan callback_data, answerCallbackQuery, edit pesan setelah tombol ditekan, reply keyboard, ForceReply.
Integrasi n8n Telegram: Hubungkan Bot, Jalankan Workflow, dan Kirim Pesan
Cara menghubungkan n8n ke Telegram: token bot sebagai Access Token, webhook Telegram Trigger via HTTPS publik, kirim pesan via chat id, dan solusi error.
Kirim Pesan Bot Telegram dengan Telegram Bot API (sendMessage)
Kirim pesan bot telegram lewat Bot API: contoh sendMessage dengan curl, Python, dan JavaScript, format HTML/MarkdownV2, tombol inline, dan solusi error.
Telegram Bot Token: Cara Mendapatkan, Mengecek, dan Mencabut Token
Cara mendapatkan token bot telegram dari @BotFather, melihat token bot lama, mengecek dengan getMe, dan me-revoke token yang bocor. Lengkap dengan contoh.
Webhook Telegram Bot: Cara Setting setWebhook, Secret Token, dan Mengatasi Error
Panduan webhook telegram bot: syarat HTTPS dan port, setWebhook dengan secret_token, cek getWebhookInfo, deleteWebhook, serta solusi error 409 dan n8n.
Chat ID Telegram Dimana? Cara Mendapatkan Chat ID User, Grup, dan Channel
Chat id telegram dimana? Cara mendapatkan chat id user, grup, supergroup, dan channel lewat getUpdates, plus solusi saat result kosong atau error 409.
Bot Inline Telegram: Cara Mengaktifkan Mode Inline dan Menjawab Inline Query
Cara membuat bot inline Telegram: aktifkan mode inline lewat @BotFather atau setMySettings, tangani update inline_query, lalu balas via answerInlineQuery.
Pembayaran Telegram Stars untuk Bot: Invoice, Pre-Checkout, Refund, dan Langganan
Cara menerima pembayaran Telegram Stars di bot: sendInvoice dengan XTR, pre_checkout_query, successful_payment, refund, langganan, plus kode Python/JS.
Server Test Telegram: Cara Test Bot di Lingkungan Test Telegram
Cara memakai server test Telegram untuk bot: login ke lingkungan test, buat bot test, panggil Bot API lewat /test/, lalu aktifkan TEST di tester kami.
Widget Telegram untuk Website: Login dengan Telegram, Embed Post, Komentar, dan Tombol Share
Pasang widget telegram untuk website: login dengan Telegram (OIDC), Login Widget lama dengan cek hash, embed post, komentar channel, dan tombol share.
API JavaScript TelegramWidget: Referensi, Event, Kode Error, dan Batasan
Referensi API JavaScript TelegramWidget: properti, request(), event, kode error, variabel CSS, widget_query dan answerWidgetQuery, plus semua batasannya.
Contoh Widget Telegram: Kode HTML dan Bot Python Lengkap
Contoh widget telegram lengkap dengan kode: kartu pesanan statis, counter dengan request widget_query, polling live sebagai widget shared, preview lokal.
Widget Telegram: HTML Interaktif di Dalam Pesan Bot
Widget telegram (Bot API 10.4): apa itu, cara kerja sendWidget, chat_data dan public_data, di mana bisa dipakai saat ini, dan bedanya dengan Mini App.
Cara Tes Telegram Mini App: Dari Mock di Browser sampai Telegram Asli
Cara tes Telegram Mini App: mode mock di browser, localhost lewat tunnel HTTPS, test environment, DevTools per platform, dan validasi initData di server.