Telegram Bot API limitleri: mesaj gönderme hızı, 429 hatası, dosya boyutu ve mesaj uzunluğu
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:
| Kapsam | Limit | Not |
|---|---|---|
| Tek sohbet | ≈ saniyede 1 mesaj | Kısa patlamalar tolere edilir, sonra 429 hataları başlar. |
| Tek grup | Dakikada 20 mesaj | Her 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.
Ücretli yayın: saniyede 1000 mesaja kadar
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
| İşlem | Limit |
|---|---|
multipart/form-data ile dosya yükleme | 50 MB |
| Fotoğraf yükleme | 10 MB; genişlik + yükseklik ≤ 10000, en-boy oranı ≤ 20 |
| HTTP URL ile fotoğraf gönderme | 5 MB |
| HTTP URL ile diğer dosyaları gönderme | 20 MB (URL ile sendDocument yalnızca .PDF ve .ZIP için çalışır) |
getFile ile indirme | 20 MB; indirme linki en az 1 saat geçerlidir |
file_id ile yeniden gönderme | Boyut 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
| Öğe | Limit |
|---|---|
| Mesaj metni | Entity 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_data | 1–64 bayt |
| Medya grubu | 2–10 öğe |
| Inline sorgu yanıtı | En fazla 50 sonuç |
answerCallbackQuery metni | 0–200 karakter |
setMyCommands | 100 komut; komut 1–32 karakter, açıklama 1–256 |
Deep link start parametresi | En fazla 64 karakter: A-Z a-z 0-9 _ - |
Mini App sendData | En 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 partsfunction 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
- Gelen güncellemeler botunuz alana kadar Telegram sunucularında en fazla 24 saat saklanır.
getUpdatesbir çağrıda 1–100 güncelleme döndürür (limit, varsayılan 100). Long polling içintimeoutkullanın ve güncellemelerioffset= sonupdate_id+ 1 ile onaylayın.- Webhook kuruluyken
getUpdatesçalışmaz (409 Conflict); öncedeleteWebhookçağırmanız gerekir. setWebhook,max_connectionsiçin 1–100 (varsayılan 40) kabul eder ve yalnızca 443, 80, 88 ve 8443 portlarını destekler. Yerel Bot API sunucusu 100000 bağlantıya kadar ve her porta izin verir.
Telegram Bot API limitlerine takılmamak için
- Her şeyi genel hızı saniyede 30'un altında, sohbet başına en fazla saniyede bir mesaj olan tek bir kuyruktan gönderin.
- İlerlemeyi göstermek için çok sayıda yeni mesaj yerine tek bir mesajı
editMessageTextile düzenleyin. - Medyayı yeniden yüklemek yerine
file_idile tekrar gönderin. retry_after'a uyun ve 403 hatalarını asla tekrar denemeyin.- Yalnızca gerçekten işlediğiniz güncelleme türlerini almak için
allowed_updatesgönderin.
İ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.
İlgili rehberler
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.