محدودیتهای Telegram Bot API: نرخ ارسال، خطای 429، حجم فایل و طول پیام
محدودیتهای 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 ساعت، پخش کنید.
Paid broadcast: تا 1000 پیام در ثانیه
اگر 30 پیام در ثانیه کافی نیست، paid broadcast را در @BotFather فعال کنید و "allow_paid_broadcast": true را به متدهای ارسال مثل sendMessage، sendPhoto یا sendMediaGroup بدهید. آن وقت ربات میتواند تا 1000 پیام در ثانیه ارسال کند. هر پیام بیشتر از 30 پیام رایگان در ثانیه 0.1 Telegram Stars از موجودی ربات کم میکند و فقط پیامهایی که با موفقیت ارسال شدهاند محاسبه میشوند. برای فعال شدن، حداقل موجودی Stars لازم است (Bots FAQ به حداقل تعداد مخاطب هم اشاره میکند)؛ پس قبل از برنامهریزی، اعداد فعلی را در مستندات رسمی بررسی کنید.
محدودیت حجم فایل در ربات تلگرام
| عملیات | محدودیت |
|---|---|
آپلود فایل با multipart/form-data | 50 MB |
| آپلود عکس | 10 MB؛ مجموع عرض و ارتفاع ≤ 10000، نسبت ابعاد ≤ 20 |
| ارسال عکس با HTTP URL | 5 MB |
| ارسال بقیه فایلها با HTTP URL | 20 MB (sendDocument با URL فقط برای .PDF و .ZIP کار میکند) |
دانلود با getFile | 20 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_data | 1 تا 64 بایت |
| Media group | 2 تا 10 آیتم |
| پاسخ inline query | حداکثر 50 نتیجه |
متن answerCallbackQuery | 0 تا 200 کاراکتر |
setMyCommands | 100 دستور؛ دستور 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 partsfunction 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;
}محدودیتهای آپدیت و وب هوک
- آپدیتهای ورودی تا وقتی ربات آنها را دریافت کند، حداکثر 24 ساعت روی سرورهای تلگرام نگه داشته میشوند.
getUpdatesدر هر درخواست 1 تا 100 آپدیت برمیگرداند (limit، پیشفرض 100). برای long polling ازtimeoutاستفاده کنید و آپدیتها را باoffset= آخرینupdate_id+ 1 تأیید کنید.- تا وقتی وب هوک تنظیم شده،
getUpdatesکار نمیکند (409 Conflict) مگر اینکهdeleteWebhookرا صدا بزنید. setWebhookمقدارmax_connectionsرا از 1 تا 100 (پیشفرض 40) میپذیرد و فقط پورتهای 443، 80، 88 و 8443 را. سرور محلی Bot API تا 100000 اتصال و هر پورتی را مجاز میکند.
چطور زیر محدودیتهای Telegram Bot API بمانیم
- همه پیامها را از یک صف با نرخ کلی کمتر از 30 در ثانیه و حداکثر یک پیام در ثانیه برای هر چت بفرستید.
- برای نمایش پیشرفت کار، یک پیام را با
editMessageTextویرایش کنید، نه اینکه پشت سر هم پیام جدید بفرستید. - مدیا را به جای آپلود دوباره، با
file_idارسال کنید. - به
retry_afterاحترام بگذارید و هرگز خطای 403 را تکرار نکنید. allowed_updatesرا بفرستید تا فقط نوع آپدیتهایی را بگیرید که واقعاً پردازش میکنید.
راهنماهای مرتبط: آموزش ارسال پیام با ربات تلگرام قالببندی و خطاهای هر پیام را توضیح میدهد، آموزش وب هوک تلگرام دریافت آپدیت در مقیاس بالا را پوشش میدهد و تغییرات 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 در سرور.