Telegram Bot API

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

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

Telegram Bot API 10.5 که 22 نوامبر 2026 منتشر شد، نسخه فعلی Bot API با 194 متد است. سری 10.x که با Bot API 10.0 در 8 مه 2026 شروع شد، این‌ها را آورد: حالت مهمان، live photo، پیام‌های rich با پیش‌نویس استریمی، پیام‌های ephemeral، communityها، کوئری درخواست عضویت، ویجت‌های تعاملی HTML داخل پیام (10.4) و در 10.5 متد setMySettings و آبجکت جدید BotFullInfo که getMe برمی‌گرداند. در ادامه تغییرات هر نسخه را با مثال‌های کوتاه JSON و تغییراتی که ممکن است ربات فعلی شما را خراب کنند می‌بینید.

نگاه کلی به Telegram Bot API 10

نسخهتاریخمهم‌ترین تغییرات
10.08 مه 2026حالت مهمان، live photo، مدیا در نظرسنجی، حذف ری‌اکشن
10.111 ژوئن 2026پیام‌های rich و پیش‌نویس rich، کوئری درخواست عضویت
10.214 جولای 2026پیام‌های ephemeral، communityها، آپدیت subscription، محافظت origin در Mini App
10.324 اوت 2026EphemeralMessageParameters، پیش‌نویس قابل توقف، DisabledButton، دکمه در پیام‌های rich
10.49 نوامبر 2026ویجت‌های HTML، پاسخ ephemeral به callback query در هر چت، نقل‌قول از پیام rich، کارت کیف پول TON، تم اشتراک‌گذاری چت
10.522 نوامبر 2026setMySettings، BotFullInfo در getMe، callback_query_mode، لینک دعوت ربات، بلوک در نقل‌قول‌های بازشونده

Bot API 10.0: حالت مهمان، live photo و نظرسنجی‌ها

حالت مهمان (guest mode). بعد از فعال کردن Guest Mode در Mini App ربات @BotFather، کاربران می‌توانند ربات شما را در چت‌هایی که عضوشان نیست منشن کنند. ربات آپدیت guest_message را می‌گیرد و می‌تواند یک پاسخ با answerGuestQuery بفرستد؛ با guest_query_id از همان پیام و یک InlineQueryResult:

{
  "guest_query_id": "<message.guest_query_id>",
  "result": {
    "type": "article",
    "id": "1",
    "title": "ترجمه",
    "input_message_content": {"message_text": "Bonjour tout le monde"}
  }
}

ربات مهمان به تاریخچه چت یا لیست اعضا دسترسی ندارد و پیام‌های بعدی را نمی‌بیند، مگر اینکه دوباره منشن شود یا کسی به پیامش ریپلای کند.

Bot API 10.1: پیام‌های rich تلگرام و کوئری درخواست عضویت

پیام‌های rich برای خروجی ساختاریافته‌اند؛ مثل گزارش، مستندات و پاسخ‌های هوش مصنوعی. sendRichMessage یک آبجکت rich_message می‌گیرد که محتوا در html یا markdown آن است (10.2 فیلد صریح blocks و لیست media را اضافه کرد). پشتیبانی می‌شود: تیتر، لیست و لیست کارها، جدول، نقل‌قول، بخش بازشونده (details)، پانویس، فرمول LaTeX، نقشه، کلاژ، اسلایدشو و بلوک مدیا. محدودیت‌ها: 32768 کاراکتر UTF-8، 500 بلوک، 16 سطح تودرتو، 50 مدیا و 20 ستون جدول.

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendRichMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "rich_message": {
      "markdown": "# گزارش هفتگی\n\n| شاخص | مقدار |\n|:-------|------:|\n| کاربران | **1204** |\n| خطاها | 3 |\n\n- [x] انتشار v2.1\n- [ ] به‌روزرسانی مستندات\n\n$$E = mc^2$$"
    }
  }'

sendRichMessageDraft یک پیام rich ناقص را در حین تولید، به صورت استریم در چت خصوصی نشان می‌دهد. پیش‌نویس یک پیش‌نمایش موقت 30 ثانیه‌ای است، پس در پایان sendRichMessage را صدا بزنید. editMessageText هم حالا rich_message را می‌پذیرد.

کوئری درخواست عضویت. وقتی ربات شما به عنوان guard bot یک چت تنظیم شده باشد، آپدیت chat_join_request یک query_id دارد. می‌توانید فوراً با answerChatJoinRequestQuery تصمیم بگیرید (approve، decline یا queue برای واگذاری تصمیم به ادمین‌های دیگر)، یا اول با sendChatJoinRequestWebApp یک Mini App نشان دهید؛ Mini App مقدار chat_join_request_query_id را در init data دریافت می‌کند.

{"chat_join_request_query_id": "<chat_join_request.query_id>", "result": "approve"}

در 10.1 نظرسنجی‌ها مدیای لینک (link) هم گرفتند.

Bot API 10.2: پیام‌های ephemeral، communityها و امنیت Mini App

پیام‌های ephemeral پیام‌هایی در گروه هستند که فقط یک کاربر و ربات می‌بینند؛ به این ترتیب راهنماها، پیام خوشامد و نتایج شخصی در تایم‌لاین مشترک گروه نمی‌آیند. کاربران هم می‌توانند دستورهای ephemeral (BotCommand.is_ephemeral) بفرستند که هیچ‌کس دیگری نمی‌بیند. قواعد تحویل:

پیام‌های ephemeral متدهای مخصوص خودشان را دارند: editEphemeralMessageText، editEphemeralMessageMedia، editEphemeralMessageCaption، editEphemeralMessageReplyMarkup و deleteEphemeralMessage:

{"chat_id": -1001234567890, "receiver_user_id": 123456789, "ephemeral_message_id": 15}

Bot API 10.3: EphemeralMessageParameters، پیش‌نویس قابل توقف و DisabledButton

تغییر ناسازگار برای پیام‌های ephemeral. پارامترهای receiver_user_id و callback_query_id نسخه 10.2 در 13 متد ارسال (sendMessage، sendPhoto، sendVideo، sendAnimation، sendAudio، sendDocument، sendLivePhoto، sendSticker، sendVideoNote، sendVoice، sendContact، sendLocation، sendVenue) با یک آبجکت واحد، ephemeral_message_parameters، جایگزین شدند. sendRichMessage هم آن را می‌پذیرد و فیلد جدید replace_callback_query_message پیام ephemeral را به جای پیامی که دکمه‌اش زده شده نشان می‌دهد:

{
  "chat_id": -1001234567890,
  "text": "فقط شما این پیام را می‌بینید.",
  "ephemeral_message_parameters": {
    "receiver_user_id": 123456789,
    "callback_query_id": "<callback_query.id>",
    "replace_callback_query_message": true
  }
}

پیش‌نویس قابل توقف. با ارسال can_stop به sendMessageDraft یا sendRichMessageDraft دکمه Stop نمایش داده می‌شود. وقتی کاربر آن را بزند، ربات آپدیت stopped_message_generation را با chat و draft_id می‌گیرد تا بتوانید تولید مدل را متوقف کنید. keep_on_stop پیش‌نویس ناقص را مدتی نگه می‌دارد؛ اگر باید بماند، آن را به صورت پیام معمولی بفرستید.

import time
import requests

API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours"
text, last = "", 0.0
for chunk in generate_reply():          # استریم توکن‌های مدل زبانی شما
    text += chunk
    if time.monotonic() - last > 0.5:   # برای هر توکن پیش‌نویس نفرستید
        requests.post(f"{API}/sendMessageDraft", json={"chat_id": 123456789,
                      "draft_id": 1, "text": text, "can_stop": True}, timeout=10)
        last = time.monotonic()
requests.post(f"{API}/sendMessage", json={"chat_id": 123456789, "text": text}, timeout=10)
const API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours";
const post = (method, body) => fetch(`${API}/${method}`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(10_000),
});

let text = "", last = 0;
for await (const chunk of generateReply()) {  // استریم توکن‌های مدل زبانی شما
  text += chunk;
  if (Date.now() - last > 500) {               // برای هر توکن پیش‌نویس نفرستید
    await post("sendMessageDraft", { chat_id: 123456789,
      draft_id: 1, text, can_stop: true });
    last = Date.now();
  }
}
await post("sendMessage", { chat_id: 123456789, text });

Bot API 10.4: ویجت‌های تلگرام، پاسخ ephemeral در هر چت و کیف پول TON

ویجت‌ها. ربات‌ها حالا می‌توانند بلوک‌های کوچک و تعاملی HTML داخل پیام بفرستند. ویجت یک سند HTML است (تا 32768 بایت و 4096 بایت بعد از فشرده‌سازی zlib) که اپ آن را در sandbox و بدون دسترسی به شبکه اجرا می‌کند، به‌علاوه یک state که فقط ربات تغییرش می‌دهد: chat_data برای یک پیام و public_data که هر جا ویجت نمایش داده شود مشترک است. متدهای جدید: sendWidget، sendSharedWidget، answerWidgetQuery، editMessageWidgetData و editSharedWidgetData؛ آپدیت‌های جدید: widget_query و shared_widget_query؛ حالت inline هم InputWidgetMessageContent و InputSharedWidgetMessageContent را گرفت (فعلاً فقط روی سرور تست).

{
  "chat_id": 123456789,
  "html": "<h3>سفارش #1042</h3><p>2 × مارگاریتا، 1 × لیموناد</p><p><strong>جمع: $23.50</strong></p>",
  "caption": "سفارش #1042: $23.50"
}

در production ویجت‌ها فعلاً فقط در چت خصوصی کار می‌کنند و با محتوای محافظت‌شده ارسال می‌شوند، پس قابل فوروارد نیستند؛ گروه‌ها، حالت inline و فوروارد روی سرور تست کار می‌کنند. پیام ویجت را نمی‌شود با copyMessage / copyMessages کپی کرد و دسترسی can_send_other_messages حالا ویجت‌ها را هم شامل می‌شود. جزئیات: راهنمای ویجت‌های تلگرام.

پاسخ ephemeral به callback query در هر چت (به جز چت‌های پیام مستقیم کانال). در ephemeral_message_parameters فقط callback_query_id را بدون receiver_user_id بفرستید؛ پیام فقط به کاربری که دکمه را زده نشان داده می‌شود. receiver_user_id و پارامتر chat_id در متدهای ارسال حالا اختیاری‌اند. همچنان باید answerCallbackQuery را صدا بزنید.

{
  "text": "این پاسخ را فقط شما می‌بینید.",
  "ephemeral_message_parameters": {"callback_query_id": "<callback_query.id>"}
}

Bot API 10.5: setMySettings، BotFullInfo و لینک دعوت ربات

تنظیمات ربات از داخل کد. متد جدید setMySettings تنظیماتی را تغییر می‌دهد که قبلاً فقط در @BotFather بودند. همه پارامترها اختیاری‌اند، پس فقط موارد مورد نظر را بفرستید؛ خروجی متد True است:

{
  "supports_inline_queries": true,
  "inline_query_placeholder": "جستجوی دستور پخت...",
  "can_join_groups": false,
  "has_topics_enabled": true,
  "callback_query_mode": "auto"
}

این را به https://api.telegram.org/bot<token>/setMySettings بفرستید یا با توکن خودتان در Bot API Tester امتحان کنید، بعد با getMe نتیجه را بررسی کنید.

BotFullInfo (تغییر ناسازگار). getMe حالا به جای User آبجکت جدید BotFullInfo را برمی‌گرداند و فیلدهایی که فقط getMe برمی‌گرداند از User حذف شدند. BotFullInfo فیلدهای active_usernames، inline_query_placeholder، needs_inline_query_location و has_topic_sidebar را هم اضافه می‌کند. کدی که فیلدهایی مثل can_join_groups، can_read_all_group_messages یا supports_inline_queries را از خروجی getMe می‌خواند همچنان کار می‌کند، چون این فیلدها در BotFullInfo هستند. چیزی که خراب می‌شود، کدی است که این فیلدها را روی بقیه آبجکت‌های User انتظار دارد، یا کد تایپ‌شده‌ای که خروجی getMe را User تعریف کرده است.

چطور ربات را به Bot API 10.5 به‌روز کنیم

  1. کتابخانه خود (python-telegram-bot، aiogram، grammY، Telegraf و بقیه) را به نسخه‌ای به‌روز کنید که در changelog آن پشتیبانی از Bot API 10.5 آمده باشد.
  2. receiver_user_id و callback_query_id به سبک 10.2 را به داخل ephemeral_message_parameters منتقل کنید.
  3. اگر لیست صریح allowed_updates می‌فرستید، نوع‌های جدیدی را که پردازش می‌کنید اضافه کنید: guest_message، subscription، stopped_message_generation، widget_query، shared_widget_query.
  4. اعتبارسنجی نظرسنجی را آسان‌تر کنید: حالا یک گزینه هم مجاز است.
  5. در Mini Appها مطمئن شوید همه فراخوانی‌های Telegram.WebApp روی دامنه ثبت‌شده اجرا می‌شوند.
  6. اگر در کد با نام نوع کار می‌کنید، StoryAreaPosition را به AreaPosition تغییر دهید.
  7. خروجی getMe را BotFullInfo در نظر بگیرید و فیلدهای مخصوص getMe مثل can_join_groups را دیگر از بقیه آبجکت‌های User نخوانید.
  8. در پیام‌های rich، نقل‌قول بازشونده را با blocks بسازید، نه text.
  9. اگر callback_query_mode را روی "auto" یا "inline" می‌گذارید، handler دکمه‌ها را طوری بنویسید که وقتی message نیست، inline_message_id را بپذیرد.
  10. متدهای جدید را با توکن خودتان در Bot API Tester امتحان کنید: setMySettings، sendWidget، sendRichMessage، deleteEphemeralMessage و answerChatJoinRequestQuery.

پیام‌های ephemeral و معمولی مبانی یکسانی دارند، پس آموزش ارسال پیام با ربات تلگرام مرور خوبی است، و محدودیت‌های Telegram Bot API محدودیت‌های پیام rich را کنار محدودیت‌های کلاسیک آورده است. تاریخچه کامل در Bot API changelog رسمی آمده است.

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

آخرین نسخه Telegram Bot API کدام است؟

Bot API 10.5 که 22 نوامبر 2026 با 194 متد منتشر شد. این ششمین نسخه از سری 10.x است که با Bot API 10.0 در 8 مه 2026 شروع شد. این نسخه متد setMySettings را اضافه کرد که ربات با آن تنظیمات خودش را تغییر می‌دهد، و getMe حالا BotFullInfo برمی‌گرداند. نسخه قبلی، 10.4 (9 نوامبر 2026)، ویجت‌های HTML را به پیام‌ها آورد.

پیام rich در تلگرام چیست؟

پیام‌های rich (از Bot API 10.1) پیام‌های ساختاریافته‌ای هستند که با sendRichMessage ارسال می‌شوند: تیتر، لیست، جدول، فرمول LaTeX، بلوک مدیا، نقشه و از 10.3 دکمه. محتوا را به صورت HTML، Markdown یا بلوک در rich_message می‌فرستید، تا 32768 کاراکتر UTF-8.

پیام ephemeral در ربات تلگرام چیست؟

پیام‌های ephemeral (از Bot API 10.2) پیام‌هایی در گروه یا سوپرگروه هستند که فقط یک کاربر و ربات آن‌ها را می‌بینند. از 10.3 آن‌ها را با ephemeral_message_parameters در sendMessage و بقیه متدهای ارسال می‌فرستید؛ از 10.4 ربات می‌تواند به callback query در هر چتی (به جز چت‌های پیام مستقیم کانال) پاسخ ephemeral بدهد. تحویل تضمینی نیست، مخصوصاً وقتی کاربر آفلاین است.

چطور پاسخ هوش مصنوعی را در ربات تلگرام به صورت استریم نشان دهم؟

در چت خصوصی، sendMessageDraft یا sendRichMessageDraft را چند بار با همان draft_id صدا بزنید و در پایان متن نهایی را با sendMessage یا sendRichMessage بفرستید، چون پیش‌نویس فقط یک پیش‌نمایش موقت 30 ثانیه‌ای است. با can_stop کاربر دکمه Stop می‌بیند و ربات آپدیت stopped_message_generation را می‌گیرد.

setMySettings در Telegram Bot API 10.5 چیست؟

setMySettings به ربات اجازه می‌دهد بدون @BotFather تنظیمات خودش را تغییر دهد: حالت inline، حالت privacy، عضویت در گروه‌ها، اتصال business، کوئری‌های مهمان و درخواست عضویت، تاپیک در چت خصوصی، ارتباط ربات با ربات و callback_query_mode. فقط فیلدهایی را بفرستید که می‌خواهید تغییر کنند؛ خروجی True است. مقادیر فعلی را getMe برمی‌گرداند که حالا خروجی‌اش BotFullInfo است.

حالت مهمان (guest mode) در Telegram Bot API 10.0 چیست؟

در حالت مهمان، ربات وقتی در چتی منشن شود که عضوش نیست، می‌تواند پاسخ بدهد. ربات آپدیت guest_message را می‌گیرد و یک بار با answerGuestQuery جواب می‌دهد، بدون دسترسی به تاریخچه چت. این حالت را در Mini App ربات @BotFather فعال می‌کنید.

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

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

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

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

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

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

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

محدودیت‌های Telegram Bot API به زبان ساده: 30 پیام در ثانیه، 1 پیام در ثانیه در هر چت، 20 در دقیقه در گروه، مدیریت خطای 429 و محدودیت حجم فایل.

دستورات ربات تلگرام: 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 در سرور.