Telegram Bot API

Limit Telegram Bot API: Rate Limit, Error 429, Ukuran File, dan Panjang Pesan

· 6 menit baca

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):

CakupanLimitCatatan
Satu chat≈ 1 pesan per detikLonjakan singkat masih ditoleransi, setelah itu muncul error 429.
Satu grup20 pesan per menitDihitung per grup.
Notifikasi massal≈ 30 pesan per detikHingga 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.

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

OperasiLimit
Unggah file dengan multipart/form-data50 MB
Unggah foto10 MB; lebar + tinggi ≤ 10000, rasio aspek ≤ 20
Kirim foto lewat URL HTTP5 MB
Kirim file lain lewat URL HTTP20 MB (sendDocument lewat URL hanya untuk .PDF dan .ZIP)
Unduh dengan getFile20 MB; link unduhan berlaku minimal 1 jam
Kirim ulang dengan file_idTanpa 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

ItemLimit
Teks pesan1–4096 karakter setelah parsing entity
Caption media0–1024 karakter
Rich message (sendRichMessage)32768 karakter UTF-8, 500 blok, 50 media, 20 kolom tabel
callback_data1–64 byte
Media group2–10 item
Jawaban inline queryHingga 50 hasil
Teks answerCallbackQuery0–200 karakter
setMyCommands100 perintah; perintah 1–32 karakter, deskripsi 1–256
Parameter start deep linkHingga 64 karakter: A-Z a-z 0-9 _ -
sendData Mini AppHingga 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 parts
function 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

Cara agar bot tetap di bawah limit Telegram Bot API

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.

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.