Telegram Bot API

محدودیت‌های Telegram Bot API: نرخ ارسال، خطای 429، حجم فایل و طول پیام

· 6 دقیقه مطالعه

محدودیت‌های Telegram Bot API روی کاغذ ساده‌اند: حدود 1 پیام در ثانیه در هر چت، 20 پیام در دقیقه در گروه و تقریباً 30 پیام در ثانیه در مجموع همه چت‌ها. اگر از این حدها بگذرید، API با 429 Too Many Requests و مقدار retry_after جواب می‌دهد. در این صفحه همه محدودیت‌های Telegram Bot API (نرخ ارسال، paid broadcast، حجم فایل، طول متن و آپدیت‌ها) یک‌جا آمده است، همراه با کدی که ربات شما را داخل این حدها نگه می‌دارد.

محدودیت ارسال پیام ربات تلگرام

Bots FAQ رسمی این محدودیت‌ها را برای ارسال معمولی و رایگان ذکر می‌کند:

محدودهمحدودیتتوضیح
یک چت≈ 1 پیام در ثانیهانفجارهای کوتاه تحمل می‌شوند، بعد خطای 429 شروع می‌شود.
یک گروه20 پیام در دقیقهبرای هر گروه جداگانه شمرده می‌شود.
ارسال انبوه (اعلان‌ها)≈ 30 پیام در ثانیهبا paid broadcast تا 1000 پیام در ثانیه.

این اعداد را راهنما بدانید، نه قرارداد. تلگرام می‌گوید محدودیت‌ها ممکن است تغییر کنند و محدودیت‌های flood در محیط تست بیشتر نمی‌شوند (حتی ممکن است سخت‌گیرانه‌تر باشند). کدی که به retry_after احترام بگذارد، از تغییراتی جان سالم به در می‌برد که عدد ثابت «30» در کد را از کار می‌اندازد.

خطای 429 Too Many Requests و retry_after

وقتی به محدودیت flood می‌خورید، پاسخ این شکلی است:

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

retry_after تعداد ثانیه‌هایی است که باید بگذرد تا بتوانید درخواست را تکرار کنید. دست‌کم همین مقدار صبر کنید و بعد همان درخواست را دوباره بفرستید؛ تکرار فوری فقط مسدودی را طولانی‌تر می‌کند. یک تابع کمکی در Python و 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("still rate limited, giving up")

call("sendMessage", chat_id=123456789, text="سلام")
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("still rate limited");
}

کنترل سرعت ارسال انبوه با صف

تکرار درخواست، مشکل درخواست‌های تکی را حل می‌کند. برای خبرنامه و اعلان‌ها باید خود سرعت ارسال را تنظیم کنید، مثلاً با نرخ کلی کمی پایین‌تر از 30 پیام در ثانیه:

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: کاربر ربات را بلاک کرده، حذفش کنید
        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: کاربر ربات را بلاک کرده، حذفش کنید
    }
    await sleep(1000 / perSecond);
  }
}

در production این کد را در یک worker پس‌زمینه اجرا کنید، برای هر چت زمان آخرین ارسال را نگه دارید تا هیچ چتی بیشتر از یک پیام در ثانیه نگیرد، و چت‌هایی را که 403 برمی‌گردانند به جای تکرار، از لیست حذف کنید. بدون paid broadcast، تلگرام توصیه می‌کند ارسال‌های بزرگ را در بازه‌های طولانی‌تر، مثلاً 8 تا 12 ساعت، پخش کنید.

اگر 30 پیام در ثانیه کافی نیست، paid broadcast را در @BotFather فعال کنید و "allow_paid_broadcast": true را به متدهای ارسال مثل sendMessage، sendPhoto یا sendMediaGroup بدهید. آن وقت ربات می‌تواند تا 1000 پیام در ثانیه ارسال کند. هر پیام بیشتر از 30 پیام رایگان در ثانیه 0.1 Telegram Stars از موجودی ربات کم می‌کند و فقط پیام‌هایی که با موفقیت ارسال شده‌اند محاسبه می‌شوند. برای فعال شدن، حداقل موجودی Stars لازم است (Bots FAQ به حداقل تعداد مخاطب هم اشاره می‌کند)؛ پس قبل از برنامه‌ریزی، اعداد فعلی را در مستندات رسمی بررسی کنید.

محدودیت حجم فایل در ربات تلگرام

عملیاتمحدودیت
آپلود فایل با multipart/form-data50 MB
آپلود عکس10 MB؛ مجموع عرض و ارتفاع ≤ 10000، نسبت ابعاد ≤ 20
ارسال عکس با HTTP URL5 MB
ارسال بقیه فایل‌ها با HTTP URL20 MB (sendDocument با URL فقط برای .PDF و .ZIP کار می‌کند)
دانلود با getFile20 MB؛ لینک دانلود دست‌کم 1 ساعت معتبر است
ارسال دوباره با file_idبدون محدودیت حجم

سرور محلی Bot API دو محدودیت بزرگ را برمی‌دارد: آپلود تا 2000 MB و دانلود بدون محدودیت حجم؛ به‌علاوه وب هوک روی HTTP ساده و هر پورتی. قبل از اینکه ربات را به سرور خودتان منتقل کنید، logOut را صدا بزنید. برای بررسی فایل قبل از دانلود، متد getFile را در Bot API Tester اجرا کنید و file_size و file_path را ببینید.

محدودیت طول پیام و سایر محدودیت‌های محتوا

موردمحدودیت
متن پیام1 تا 4096 کاراکتر بعد از پردازش entityها
کپشن مدیا0 تا 1024 کاراکتر
Rich message (sendRichMessage)32768 کاراکتر UTF-8، 500 بلوک، 50 مدیا، 20 ستون جدول
callback_data1 تا 64 بایت
Media group2 تا 10 آیتم
پاسخ inline queryحداکثر 50 نتیجه
متن answerCallbackQuery0 تا 200 کاراکتر
setMyCommands100 دستور؛ دستور 1 تا 32 کاراکتر، توضیح 1 تا 256
پارامتر start در deep linkحداکثر 64 کاراکتر: A-Z a-z 0-9 _ -
sendData در Mini Appحداکثر 4096 بایت

callback_data بر حسب بایت شمرده می‌شود و هر حرف غیر ASCII (از جمله حروف فارسی) در UTF-8 بین 2 تا 4 بایت جا می‌گیرد؛ پس در دکمه فقط یک شناسه کوتاه بگذارید و جزئیات را در دیتابیس نگه دارید. متن‌های بلندتر از 4096 کاراکتر را باید تقسیم کرد، ترجیحاً روی شکست خط:

def split_text(text, limit=4000):  # کمی کمتر از 4096 برای اطمینان
    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) { // کمی کمتر از 4096 برای اطمینان
  const parts = [];
  let current = "";
  for (let line of text.split(/(?<=\n)/)) { // تقسیم به خطوط، با حفظ "\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;
}

محدودیت‌های آپدیت و وب هوک

چطور زیر محدودیت‌های Telegram Bot API بمانیم

راهنماهای مرتبط: آموزش ارسال پیام با ربات تلگرام قالب‌بندی و خطاهای هر پیام را توضیح می‌دهد، آموزش وب هوک تلگرام دریافت آپدیت در مقیاس بالا را پوشش می‌دهد و تغییرات Bot API 10 rich messageها و محدودیت‌هایشان را معرفی می‌کند.

پرسش‌های متداول

محدودیت نرخ ارسال در Telegram Bot API چقدر است؟

در Bots FAQ تلگرام سه عدد آمده است: در یک چت بیشتر از 1 پیام در ثانیه نفرستید، در گروه حداکثر 20 پیام در دقیقه، و برای ارسال انبوه حدود 30 پیام در ثانیه. با عبور از این حدها خطای 429 Too Many Requests برمی‌گردد.

خطای 429 Too Many Requests تلگرام را چطور رفع کنم؟

مقدار parameters.retry_after را از پاسخ خطا بخوانید، همان تعداد ثانیه صبر کنید و همان درخواست را تکرار کنید. برای اینکه دیگر به محدودیت نخورید، پیام‌ها را از یک صف بفرستید که سرعت ارسال را برای هر چت و به طور کلی کنترل کند.

محدودیت حجم فایل در ربات تلگرام چقدر است؟

ربات می‌تواند فایل تا 50 مگابایت (عکس تا 10 مگابایت) آپلود کند و با getFile فایل تا 20 مگابایت دانلود کند. ارسال با URL برای عکس به 5 مگابایت و برای بقیه فایل‌ها به 20 مگابایت محدود است. با سرور محلی Bot API آپلود تا 2000 مگابایت و دانلود بدون محدودیت حجم ممکن است.

پیام ربات تلگرام حداکثر چند کاراکتر می‌تواند باشد؟

متن پیام بعد از پردازش entityها 1 تا 4096 کاراکتر و کپشن مدیا 0 تا 1024 کاراکتر است؛ پس متن‌های طولانی‌تر را باید تقسیم کنید. Rich message (از Bot API 10.1) تا 32768 کاراکتر UTF-8 را می‌پذیرد.

ربات تلگرام چطور می‌تواند بیشتر از 30 پیام در ثانیه بفرستد؟

paid broadcast را در @BotFather فعال کنید و allow_paid_broadcast: true را بفرستید. آن وقت ربات تا 1000 پیام در ثانیه می‌فرستد؛ هر پیام بیشتر از 30 پیام رایگان در ثانیه 0.1 Telegram Stars هزینه دارد و فقط پیام‌های موفق محاسبه می‌شوند.

تلگرام آپدیت‌های ربات را چه مدت نگه می‌دارد؟

آپدیت‌های تحویل‌نشده حداکثر 24 ساعت نگه داشته می‌شوند. getUpdates در هر درخواست حداکثر 100 آپدیت برمی‌گرداند؛ برای تأیید آن‌ها offset را برابر آخرین update_id + 1 بفرستید.

ساخت ربات تلگرام: آموزش قدم‌به‌قدم از BotFather تا اولین پیام با Python

ساخت ربات تلگرام قدم‌به‌قدم: ساخت ربات در BotFather، گرفتن توکن، تست با getMe، پیدا کردن chat id و ارسال اولین پیام با curl و Python.

دیپلوی ربات تلگرام: راه‌اندازی روی VPS، داکر و هاست Serverless

آموزش دیپلوی و هاست ربات تلگرام: polling یا وب هوک، سرویس systemd روی VPS، داکر، Cloudflare Workers با secret_token و چک‌لیست راه‌اندازی.

Telegram Bot API 10.0 تا 10.5: تنظیمات ربات، ویجت‌ها، پیام‌های rich و ephemeral، حالت مهمان و بیشتر

تغییرات Telegram Bot API 10.0 تا 10.5: متد setMySettings و BotFullInfo، ویجت‌های HTML، پیام‌های rich و ephemeral و حالت مهمان، همراه با مثال JSON.

خطاهای Telegram Bot API: معنی هر خطا و روش رفع آن

خطاهای ربات تلگرام به زبان ساده: 400 chat not found، 403 bot was blocked by the user، 409 Conflict و 429 retry_after؛ علت، راه حل و کد مدیریت خطا.

دستورات ربات تلگرام: setMyCommands، اسکوپ دستورات و دیپ‌لینک /start

تنظیم دستورات ربات تلگرام: /setcommands در @BotFather، متد setMyCommands با اسکوپ و زبان، پارامتر دیپ‌لینک /start و دستور /cmd@bot در گروه‌ها.

کیبورد ربات تلگرام: دکمه شیشه‌ای (inline keyboard)، دکمه‌های callback و reply keyboard

ساخت دکمه شیشه‌ای ربات تلگرام: inline keyboard با callback_data، پاسخ با answerCallbackQuery، ویرایش پیام بعد از کلیک، reply keyboard و ForceReply.

اتصال n8n به تلگرام: وصل کردن ربات، اجرای ورک‌فلو و ارسال پیام

اتصال n8n به تلگرام: توکن ربات به عنوان Access Token، وب هوک Telegram Trigger روی HTTPS عمومی، ارسال پیام با چت آیدی و رفع خطاهای رایج.

ارسال پیام با ربات تلگرام از طریق API تلگرام (sendMessage)

آموزش ارسال پیام با ربات تلگرام از طریق API تلگرام: متد sendMessage با curl، Python و JavaScript، قالب‌بندی HTML و MarkdownV2، دکمه شیشه‌ای و رفع خطاها.

توکن ربات تلگرام: چیست، چطور بگیریم، بررسی و باطل کنیم

توکن ربات تلگرام چیست و از کجا بگیریم؟ گرفتن توکن از BotFather، پیدا کردن توکن ربات قبلی، تست با getMe، باطل کردن توکن لو رفته و نگهداری امن آن.

وب هوک ربات تلگرام: راه‌اندازی setWebhook، بررسی و رفع خطا

آموزش ست وب هوک تلگرام با setWebhook: پیش‌نیازهای HTTPS و پورت‌ها، secret_token، بررسی با getWebhookInfo، حذف وب هوک و رفع خطاهای رایج مثل 409.

چت آیدی تلگرام: چیست، کجاست و چطور chat id کاربر، گروه و کانال را پیدا کنیم

چت آیدی تلگرام کجاست؟ پیدا کردن chat_id کاربر، گروه، سوپرگروه، کانال و تاپیک با getUpdates، معنی آیدی‌های منفی و رفع مشکل نتیجه خالی و خطای 409.

ربات اینلاین تلگرام: فعال کردن حالت inline و پاسخ به کوئری‌ها

ساخت ربات اینلاین تلگرام: فعال کردن حالت inline با @BotFather یا setMySettings، دریافت آپدیت inline_query و پاسخ با answerInlineQuery.

پرداخت با Telegram Stars در ربات: فاکتور، پیش‌پرداخت، بازپرداخت و اشتراک

دریافت پرداخت با استارز تلگرام در ربات: sendInvoice با ارز XTR، پاسخ به pre_checkout_query، successful_payment، بازپرداخت و اشتراک با کد پایتون و JS.

سرور تست تلگرام: چطور ربات را در محیط تست تلگرام تست کنیم

سرور تست تلگرام برای ربات‌ها: ورود به محیط تست، ساخت ربات تست در BotFather، فراخوانی Bot API با مسیر /test/ و سوییچ TEST در تستر ما.

ویجت تلگرام برای سایت: ورود با تلگرام، جاسازی پست، کامنت‌ها و دکمه اشتراک‌گذاری

ورود با تلگرام در سایت با Telegram Login (OIDC) و ویجت قدیمی همراه کد بررسی hash، جاسازی پست کانال، ویجت کامنت و دکمه اشتراک‌گذاری تلگرام.

مرجع API جاوااسکریپت TelegramWidget: رویدادها، کدهای خطا و محدودیت‌ها

مرجع API جاوااسکریپت ویجت تلگرام: ویژگی‌ها، request()، رویدادها، کدهای خطا، متغیرهای CSS، widget_query و answerWidgetQuery و همه محدودیت‌ها.

مثال ویجت تلگرام: کد کامل HTML و ربات پایتون

مثال‌های کامل ویجت تلگرام با کد: کارت سفارش ثابت، شمارنده با widget_query، نظرسنجی زنده با ویجت اشتراکی و پیش‌نمایش در مرورگر با ربات پایتون.

ویجت تلگرام چیست؟ HTML تعاملی داخل پیام‌های ربات

ویجت تلگرام در Bot API 10.4 چیست؟ ارسال با sendWidget، وضعیت chat_data و public_data، محدودیت‌ها، جاهایی که فعلاً کار می‌کند و تفاوت با مینی اپ.

تست مینی اپ تلگرام: از mock در مرورگر تا اجرای واقعی در تلگرام

تست مینی اپ تلگرام قدم به قدم: حالت mock در مرورگر، اجرای localhost با تونل HTTPS، محیط تست، DevTools در هر پلتفرم و اعتبارسنجی initData در سرور.