Telegram Bot API

Telegram Bot API limitleri: mesaj gönderme hızı, 429 hatası, dosya boyutu ve mesaj uzunluğu

· 6 dk okuma

Telegram Bot API limitleri kâğıt üzerinde basit görünür: tek bir sohbette saniyede yaklaşık 1 mesaj, bir grupta dakikada 20 mesaj ve tüm sohbetlerde toplam saniyede kabaca 30 mesaj. Bunları aşarsanız API retry_after değeriyle birlikte 429 Too Many Requests döndürür. Bu sayfada Telegram Bot API limitlerini tek yerde topladık: gönderim hızları, ücretli yayınlar, dosya boyutları, metin uzunlukları ve güncellemeler; ayrıca botunuzu bu sınırlar içinde tutan kodlar.

Mesaj gönderiminde Telegram Bot API limitleri

Resmi Bots FAQ sayfası normal, ücretsiz gönderim için şu sınırları verir:

KapsamLimitNot
Tek sohbet≈ saniyede 1 mesajKısa patlamalar tolere edilir, sonra 429 hataları başlar.
Tek grupDakikada 20 mesajHer grup sohbeti için ayrı sayılır.
Toplu bildirimler≈ saniyede 30 mesajÜcretli yayınla saniyede 1000'e kadar.

Bu sayıları bir sözleşme değil, yol gösterici değerler olarak görün. Telegram limitlerin değişebileceğini belirtir ve test ortamında flood limitleri yükseltilmez (orada daha da sıkı olabilir). retry_after'a uyan kod, sabit yazılmış bir "30"u bozacak değişikliklerden etkilenmez.

429 Too Many Requests ve retry_after

Bir flood limitine takıldığınızda yanıt şöyle görünür:

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

retry_after, isteğin tekrarlanabilmesine kalan saniye sayısıdır. En az bu kadar bekleyin, sonra aynı isteği yeniden gönderin; hemen tekrar denemek yalnızca engeli uzatır. Python veya JavaScript ile bir yardımcı fonksiyon:

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("hâlâ rate limit var, vazgeçiliyor")

call("sendMessage", chat_id=123456789, text="Merhaba")
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("hâlâ rate limit var");
}

Toplu gönderimi bir kuyrukla yavaşlatın

Tekrar denemeler tek tek istekleri kurtarır. Bülten ve bildirimlerde ise gönderimin kendisini hızlandırıp yavaşlatmanız gerekir; örneğin genel hızı saniyede 30'un biraz altında tutarak:

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: kullanıcı botu engelledi, listeden çıkarın
        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: kullanıcı botu engelledi, listeden çıkarın
    }
    await sleep(1000 / perSecond);
  }
}

Üretimde bunu arka plandaki bir worker'da çalıştırın, hiçbir sohbete saniyede birden fazla mesaj gitmemesi için sohbet başına bir zaman damgası tutun ve 403 döndüren sohbetleri tekrar denemek yerine listeden çıkarın. Ücretli yayın kullanmıyorsanız Telegram büyük gönderimleri 8–12 saat gibi daha uzun aralıklara yaymanızı önerir.

Saniyede 30 mesaj yetmiyorsa @BotFather'da ücretli yayını açın ve sendMessage, sendPhoto veya sendMediaGroup gibi gönderim metotlarına "allow_paid_broadcast": true ekleyin. Bot bu durumda saniyede 1000 mesaja kadar yayın yapabilir. Ücretsiz 30 mesaj/sn'nin üzerindeki her mesaj botun bakiyesinden 0,1 Telegram Stars düşer ve yalnızca başarıyla gönderilen mesajlar ücretlendirilir. Uygunluk için asgari bir Stars bakiyesi gerekir (Bots FAQ ayrıca bir kitle eşiğinden de söz eder); planlamadan önce güncel sayıları resmi dokümantasyondan kontrol edin.

Telegram bot dosya boyutu limitleri

İşlemLimit
multipart/form-data ile dosya yükleme50 MB
Fotoğraf yükleme10 MB; genişlik + yükseklik ≤ 10000, en-boy oranı ≤ 20
HTTP URL ile fotoğraf gönderme5 MB
HTTP URL ile diğer dosyaları gönderme20 MB (URL ile sendDocument yalnızca .PDF ve .ZIP için çalışır)
getFile ile indirme20 MB; indirme linki en az 1 saat geçerlidir
file_id ile yeniden göndermeBoyut sınırı yok

Yerel Bot API sunucusu en büyük iki kısıtlamayı kaldırır: 2000 MB'a kadar yükleme ve boyut sınırı olmadan indirme; ayrıca herhangi bir portta düz HTTP üzerinden webhook. Botu kendi sunucunuza yönlendirmeden önce logOut çağırın. Bir dosyayı indirmeden önce kontrol etmek için Bot API Tester'da getFile çağırın ve file_size ile file_path'e bakın.

Mesaj uzunluğu ve diğer içerik limitleri

ÖğeLimit
Mesaj metniEntity ayrıştırmasından sonra 1–4096 karakter
Medya açıklaması (caption)0–1024 karakter
Rich mesaj (sendRichMessage)32768 UTF-8 karakter, 500 blok, 50 medya, 20 tablo sütunu
callback_data1–64 bayt
Medya grubu2–10 öğe
Inline sorgu yanıtıEn fazla 50 sonuç
answerCallbackQuery metni0–200 karakter
setMyCommands100 komut; komut 1–32 karakter, açıklama 1–256
Deep link start parametresiEn fazla 64 karakter: A-Z a-z 0-9 _ -
Mini App sendDataEn fazla 4096 bayt

callback_data bayt olarak sayılır ve ASCII dışındaki karakterler (ğ, ş, ı gibi Türkçe harfler dahil) UTF-8'de 2–4 bayt yer kaplar; bu yüzden butonda kısa bir id saklayın, ayrıntıları veritabanında tutun. 4096 karakterden uzun metinler bölünmelidir, tercihen satır sonlarından:

def split_text(text, limit=4000):  # güvenli olsun diye 4096'nın biraz altı
    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) { // güvenli olsun diye 4096'nın biraz altı
  const parts = [];
  let current = "";
  for (let line of text.split(/(?<=\n)/)) { // satırlara böl, "\n"i koru
    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;
}

Güncelleme ve webhook limitleri

Telegram Bot API limitlerine takılmamak için

İlgili rehberler: Bot API ile mesaj gönderme biçimlendirmeyi ve mesaj başına hataları, webhook kurulumu güncellemeleri ölçekli almayı anlatır; Bot API 10'daki yenilikler ise rich mesajları ve limitlerini tanıtır.

Sık sorulan sorular

Telegram Bot API mesaj gönderme limiti nedir?

Telegram'ın Bots FAQ sayfası üç sayı verir: tek bir sohbette saniyede 1 mesajı aşmayın, bir gruba dakikada en fazla 20 mesaj gönderin, toplu bildirimlerde saniyede yaklaşık 30 mesajla sınırlı kalın. Aşılırsa 429 Too Many Requests döner.

Telegram'da 429 Too Many Requests hatası nasıl çözülür?

Hatadaki parameters.retry_after değerini okuyun, o kadar saniye bekleyin ve aynı isteği tekrarlayın. Limite takılmamak için mesajları hem sohbet başına hem genel olarak hızını ayarlayan bir kuyruktan gönderin.

Telegram bot dosya boyutu limiti nedir?

Botlar 50 MB'a kadar dosya (fotoğraflar 10 MB'a kadar) yükleyebilir ve getFile ile 20 MB'a kadar dosya indirebilir. URL ile gönderimde sınır fotoğraflar için 5 MB, diğer dosyalar için 20 MB'tır. Yerel Bot API sunucusu 2000 MB'a kadar yüklemeye ve boyut sınırı olmadan indirmeye izin verir.

Telegram bot mesajı en fazla kaç karakter olabilir?

Metin mesajı entity ayrıştırmasından sonra 1–4096 karakter, medya açıklaması (caption) 0–1024 karakter olabilir; daha uzun metinler bölünmelidir. Rich mesajlar (Bot API 10.1+) 32768 UTF-8 karaktere kadar izin verir.

Telegram botu saniyede 30'dan fazla mesajı nasıl gönderir?

@BotFather'da ücretli yayını (paid broadcast) açın ve allow_paid_broadcast: true gönderin. Bot saniyede 1000 mesaja kadar gönderebilir; ücretsiz 30 mesaj/sn'nin üzerindeki her mesaj 0,1 Telegram Stars tutar ve yalnızca başarıyla gönderilenler ücretlendirilir.

Telegram bot güncellemelerini ne kadar süre saklar?

Teslim edilmemiş güncellemeler en fazla 24 saat saklanır. getUpdates bir çağrıda en fazla 100 güncelleme döndürür; bunları son update_id + 1 değerini offset olarak göndererek onaylayın.

Telegram bot nasıl yapılır? BotFather ile adım adım bot oluşturma

Telegram bot yapma rehberi: BotFather'da /newbot ile bot oluşturun, token'ı getMe ile test edin, chat ID'yi bulun ve Python ile ilk mesajı gönderin.

Telegram botu nasıl deploy edilir: VPS, Docker ve serverless hosting

Telegram botu sunucuya kurma: polling mi webhook mu, VPS'te systemd servisi, Docker, secret_token ile Cloudflare Workers ve yayın öncesi kontrol listesi.

Telegram Bot API 10.0–10.5: bot ayarları, widget'lar, rich mesajlar, ephemeral mesajlar, misafir modu ve dahası

Telegram Bot API 10.0–10.5'teki yenilikler: setMySettings ve BotFullInfo, HTML widget'lar, rich ve ephemeral mesajlar, misafir modu; JSON örnekleriyle.

Telegram Bot API hataları: her hata ne anlama gelir ve nasıl çözülür

Telegram Bot API hataları: 400 chat not found, 403 bot was blocked by the user, 409 Conflict, 429 retry_after. Nedenleri, çözümleri ve hata yönetimi kodu.

Telegram bot komutları: setMyCommands, komut kapsamları ve /start deep link

Telegram bot komutları nasıl eklenir: @BotFather /setcommands, kapsam ve dil destekli setMyCommands, /start deep link parametresi, gruplarda /komut@bot.

Telegram bot klavyeleri: inline klavye, callback butonları ve reply klavye

Telegram bot butonu ekleme: callback_data ile inline klavye, answerCallbackQuery, basıştan sonra mesajı düzenleme, reply klavye ve ForceReply örnekleri.

n8n Telegram entegrasyonu: botu bağlama, workflow tetikleme ve mesaj gönderme

n8n'i Telegram'a bağlayın: bot token'ı Access Token olarak girin, Telegram Trigger webhook'u için HTTPS kurun, chat id ile mesaj gönderin, hataları çözün.

Telegram Bot API ile mesaj gönderme (send message): curl, Python ve JavaScript

Telegram Bot API send message rehberi: curl, Python ve JavaScript ile sendMessage, HTML ve MarkdownV2 biçimlendirme, inline butonlar ve sık hatalar.

Telegram bot token nasıl alınır, nerede bulunur ve nasıl iptal edilir?

Telegram bot token nedir, BotFather'dan nasıl alınır, mevcut botun token'ı nerede bulunur? getMe ile test, 401 hatası ve sızan token'ı iptal etme.

Telegram bot webhook kurulumu: URL, secret token, getWebhookInfo ve sorun giderme

Telegram bot webhook kurulumu: setWebhook ile HTTPS URL ve secret_token ayarlayın, getWebhookInfo ile hataları görün; 409 Conflict ve n8n localhost çözümü.

Telegram chat ID nasıl bulunur: kullanıcı, grup, kanal ve konu için adım adım

Telegram chat ID nasıl bulunur? getUpdates ile kullanıcı, grup, süper grup ve kanal ID'sini öğrenin; -100 ön eki, konu ID'si ve boş result sorunu.

Telegram inline bot: inline modu açma ve inline sorguları yanıtlama

Telegram inline bot nasıl yapılır: inline modu @BotFather veya setMySettings ile açın, inline_query güncellemelerini answerInlineQuery ile yanıtlayın.

Telegram botlarında Stars ile ödeme: fatura, ön onay, iade ve abonelikler

Telegram botunuzda Stars ile ödeme alın: XTR ile sendInvoice, pre_checkout_query, successful_payment, iade ve abonelikler; Python ve JS kodu.

Telegram test sunucusu: Telegram botunu test ortamında nasıl test edersiniz?

Telegram test sunucusu nedir? Test ortamına giriş, test botu oluşturma, Bot API'yi /test/ ile çağırma ve Bot API Tester'da TEST modu adım adım.

Web siteniz için Telegram widget'ları: Telegram ile giriş, gönderi gömme, yorumlar ve paylaş butonu

Sitenize Telegram ile giriş ekleyin: yeni Telegram Login (OIDC), eski Login Widget ve hash kontrolü, gönderi gömme, yorumlar ve paylaş butonu.

TelegramWidget JavaScript API: özellikler, olaylar, hata kodları ve sınırlar

Telegram widget API başvurusu: TelegramWidget özellikleri, request(), olaylar, hata kodları, CSS değişkenleri, widget_query, answerWidgetQuery ve sınırlar.

Telegram widget örnekleri: eksiksiz HTML ve Python bot kodu

Çalışan Telegram widget örnekleri: statik sipariş kartı, widget_query ile sayaç, paylaşılan canlı anket ve yerel önizleme; HTML ve Python bot kodu.

Telegram widget: bot mesajının içinde çalışan etkileşimli HTML

Telegram widget nedir: Bot API 10.4'teki sendWidget, chat_data ve public_data nasıl çalışır, bugün nerede kullanılabilir, Mini App'ten farkı nedir?

Telegram Mini App nasıl test edilir: tarayıcıdaki mock'tan gerçek Telegram'a

Telegram Mini App test rehberi: tarayıcıda mock mod, HTTPS tünelle localhost, test ortamı, platformlara göre DevTools ve sunucuda initData doğrulama.