Telegram Bot API

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

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

ویجت تلگرام یک بلوک HTML تعاملی کوچک است که ربات با متد sendWidget داخل پیام می‌فرستد؛ این قابلیت در Bot API 10.4 (9 نوامبر 2026) اضافه شد. ویجت یک سند HTML تا 32 کیلوبایت است که اپ تلگرام روی دستگاه کاربر و بدون هیچ دسترسی به شبکه اجرا می‌کند و با ظاهر خود چت رسم می‌شود: کارت سفارشی که وضعیتش به‌روز می‌شود، یک شمارنده، نظرسنجی‌ای که نوارهایش با رأی‌ها جابه‌جا می‌شوند یا کد تخفیفی که با یک لمس کپی می‌شود.

ویجت‌ها فعلاً کجا کار می‌کنند: در محیط production ربات فقط در چت خصوصی با کاربر می‌تواند ویجت بفرستد و این پیام‌ها با محتوای محافظت‌شده (protected content) ارسال می‌شوند، یعنی قابل فوروارد نیستند. ویجت در گروه‌ها، حالت inline و فوروارد فعلاً فقط روی سرور تست کار می‌کند.

ویجت تلگرام دقیقاً چیست

کد و وضعیت: chat_data و public_data

ویجت یعنی کد ثابت به‌علاوه وضعیت قابل تغییر. HTML هنگام ارسال تعیین می‌شود و دیگر هیچ متدی آن را عوض نمی‌کند. چیزی که تغییر می‌کند وضعیت (state) است و فقط ربات آن را می‌نویسد. ویجت وضعیت را از TelegramWidget.chatData و TelegramWidget.publicData می‌خواند و با رویدادهای chatDataChanged و publicDataChanged دوباره رسم می‌کند.

ویژگیوضعیت چت (chat_data)وضعیت مشترک (public_data)
وابسته بهیک پیام اصلیپیام یک ویجت ثابت، یا ویجت اشتراکی در همه جاهایی که نمایش داده می‌شود
چه کسی می‌بیندفقط همان چت (در گروه، یکی برای همه اعضا)هر جا ویجت نمایش داده شود
در فورواردهرگزیک کپی (ویجت ثابت) یا وضعیت زنده (ویجت اشتراکی)
اندازهحداکثر 1024 بایت متنحداکثر 1024 بایت متن
تغییر باeditMessageWidgetDataeditMessageWidgetData یا editSharedWidgetData
مثالبازی در جریان، وضعیت سفارشنتایج نظرسنجی، قیمت

هر دو متن ساده‌اند که سرور تفسیرشان نمی‌کند و معمولاً JSON هستند. وضعیتی که وجود ندارد یا پاک شده، در ویجت null است.

ویجت‌ها کجا کار می‌کنند: production در برابر سرور تست

مکاننحوه رسیدندرخواست‌ها (با allow_queries)Production
چت خصوصی با رباتsendWidget، sendSharedWidgetبا لمس و در پس‌زمینهبله
گروه معمولی یا سوپرگروهsendWidgetفقط با لمسفقط سرور تست
هر چتی به جز کانال، از طریق رباتحالت inline (InputWidgetMessageContent، InputSharedWidgetMessageContent)فقط با لمسفقط سرور تست
فوروارد، از جمله در کانالفوروارد توسط کاربرانبا لمس، فقط ویجت اشتراکیفقط سرور تست

ربات نمی‌تواند ویجت را در کانال پست کند و اپ‌های قدیمی پیام را به شکل رسانه پشتیبانی‌نشده با کپشن نشان می‌دهند. پیام ویجت با copyMessage یا copyMessages کپی نمی‌شود و در گروه‌ها، مجوز can_send_other_messages ویجت‌ها را هم شامل می‌شود.

تفاوت ویجت تلگرام و مینی اپ

ویژگیمینی اپویجت
محل نمایشWebView که از دکمه، منو یا لینک باز می‌شودداخل حباب پیام، همیشه در چت دیده می‌شود
کدصفحه وب روی سرور شماحداکثر 32 کیلوبایت HTML داخل پیام، ثابت پس از ارسال
موتورWebView سیستم‌عاملsandbox مبتنی بر QuickJS، رسم توسط اپ تلگرام
شبکهکل وبندارد
ارتباط با رباتبک‌اند خودتان با initData امضاشدهTelegramWidget.request() ← آپدیت widget_query
ورودیهمه چیز، از جمله کیبوردلمس و رویدادهای pointer، بدون کیبورد

جایی که دو API هم‌پوشانی دارند، TelegramWidget همان نام‌های Telegram.WebApp را دارد (themeParams، colorScheme، onEvent، openLink، HapticFeedback، ready). برای کارهای بزرگ‌تر، مینی اپ را با openTelegramLink باز کنید و آن را در Mini App Tester تست کنید.

ارسال اولین ویجت ربات تلگرام با sendWidget

  1. ربات بسازید و توکنش را کپی کنید (آموزش ساخت ربات تلگرام، توکن ربات تلگرام را از کجا بگیریم).
  2. به ربات /start بفرستید تا بتواند به شما پیام بدهد و چت آیدی خود را از getUpdates بردارید.
  3. متد sendWidget را صدا بزنید. پارامتر html یک رشته است، پس درخواست را به صورت JSON بفرستید:
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendWidget" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "html": "<h3>کد تخفیف شما</h3><p>برای کپی، دکمه را لمس کنید.</p><button onclick=\"TelegramWidget.copyText(this.textContent)\">PROMO10</button>",
    "caption": "کد تخفیف شما: PROMO10"
  }'

همین درخواست در پایتون با requests یا در JavaScript با fetch:

import requests

API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours"
html = """<h3>کد تخفیف شما</h3>
<p>برای کپی، دکمه را لمس کنید.</p>
<button onclick="TelegramWidget.copyText(this.textContent)">PROMO10</button>"""

r = requests.post(f"{API}/sendWidget", json={
    "chat_id": 123456789,
    "html": html,
    "caption": "کد تخفیف شما: PROMO10",
}, timeout=10)
print(r.json())  # result: پیام ارسال‌شده همراه با فیلد "widget"
const API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours";
const html = `<h3>کد تخفیف شما</h3>
<p>برای کپی، دکمه را لمس کنید.</p>
<button onclick="TelegramWidget.copyText(this.textContent)">PROMO10</button>`;

const r = await fetch(`${API}/sendWidget`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    chat_id: 123456789,
    html,
    caption: "کد تخفیف شما: PROMO10",
  }),
  signal: AbortSignal.timeout(10_000),
});
console.log(await r.json()); // result: پیام ارسال‌شده همراه با فیلد "widget"

این ویجت CSS ندارد و باز هم مثل پیام معمولی با دکمه بومی دیده می‌شود؛ copyText هم کار می‌کند چون داخل handler لمس صدا زده شده است. می‌توانید همین HTML را در فرم sendWidget در Bot API Tester بچسبانید و با توکن خودتان ارسال کنید.

پارامترهای دیگر sendWidget: width و height (لنگرهای اندازه به پیکسل منطقی)، chat_data و public_data (وضعیت اولیه)، allow_queries، is_shared و پارامترهای آشنای کپشن، reply_markup، reply_parameters، message_thread_id و protect_content.

ویجت چطور با ربات حرف می‌زند

درخواست (request) مثل یک دکمه callback داخل ویجت کار می‌کند:

  1. ربات ویجت را با allow_queries: true می‌فرستد.
  2. با لمس کاربر، ویجت TelegramWidget.request("like") را با 1 تا 64 بایت داده صدا می‌زند.
  3. ربات آپدیت widget_query با فیلدهای id، from، chat، message_id و data می‌گیرد (از فوروارد یک ویجت اشتراکی: shared_widget_query). اگر allowed_updates می‌فرستید، هر دو نوع را در آن بگذارید.
  4. ربات ظرف 15 ثانیه answerWidgetQuery را صدا می‌زند و می‌تواند data تا 1024 بایت برگرداند که فقط به ویجتِ درخواست‌دهنده می‌رسد.
  5. برای تغییر چیزی که همه می‌بینند، ربات editMessageWidgetData (یا editSharedWidgetData) را صدا می‌زند و ویجت رویداد chatDataChanged / publicDataChanged را دریافت می‌کند.

خود پاسخ هرگز وضعیت را تغییر نمی‌دهد. سقف درخواست‌ها 5 درخواست در 5 ثانیه برای هر کاربر و ربات است و درخواستی که جواب نگیرد، در ویجت با TIMEOUT تمام می‌شود. کد کامل و قابل اجرا در مثال‌های ویجت تلگرام آمده است.

ویجت ثابت و ویجت اشتراکی

بدون is_shared ویجت ثابت (static) است: کد و وضعیت داخل پیام می‌مانند و فوروارد یک کپی منجمد دریافت می‌کند. با is_shared، اولین ارسال یک ویجت اشتراکی می‌سازد: یک شیء با شناسه (widget.id در پیام برگشتی) که هر تعداد پیام می‌تواند نمایشش دهد. آن را با sendSharedWidget دوباره بفرستید و وضعیت مشترکش را برای همه پیام‌ها یک‌جا با editSharedWidgetData عوض کنید، حداکثر یک بار در ثانیه. ویجتی که روی صفحه است فقط وقتی وضعیت مشترک جدید را می‌گیرد که TelegramWidget.watchPublicData() را صدا زده باشد؛ در این حالت اپ با دوره به‌روزرسانی ویجت (پیش‌فرض 30 ثانیه، 5 تا 3600 ثانیه با cache_time) وضعیت را می‌پرسد.

خلاصه محدودیت‌های ویجت تلگرام

موردمحدودیت
HTML32768 بایت؛ 4096 بایت بعد از zlib سطح 9
chat_data، public_dataهر کدام 1024 بایت
داده درخواست / داده پاسخ1 تا 64 بایت / حداکثر 1024 بایت
مهلت پاسخ به کوئری15 ثانیه
درخواست‌ها5 در 5 ثانیه برای هر کاربر و ربات
اندازه حبابعرض 200 پیکسل تا حداکثر عرض حباب، ارتفاع 50 تا 600 پیکسل؛ بقیه بریده می‌شود
ویرایش ویجت اشتراکی1 بار در ثانیه
حافظه / گره‌های DOM8 مگابایت / 2000 گره

جدول کامل، با سهمیه CPU، تایمرها و حافظه محلی، در مرجع API ویجت TelegramWidget آمده است.

نکات طراحی

با ویجت‌های وب‌سایت اشتباه نگیرید

«ویجت تلگرام» به ویجت‌های قدیمی وب‌سایت هم گفته می‌شود (Telegram Login Widget، جاسازی پست، دکمه اشتراک‌گذاری) که اسکریپت‌هایی برای سایت خودتان هستند. ویجت‌های Bot API 10.4 اما HTMLی هستند که ربات داخل چت می‌فرستد. راه‌اندازی آن ویجت‌ها، از جمله ورود با تلگرام در سایت، در راهنمای ویجت‌های تلگرام برای سایت آمده است. مستندات رسمی این ویجت‌ها در core.telegram.org/bots/widgets است.

قدم‌های بعدی

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

ویجت تلگرام چیست؟

بلوک تعاملی کوچکی که داخل پیام ربات رسم می‌شود و در Bot API 10.4 (9 نوامبر 2026) اضافه شد. ویجت یک سند HTML مستقل با CSS و JavaScript درون‌خطی است که اپ تلگرام آن را روی دستگاه کاربر، داخل sandbox و بدون دسترسی به شبکه اجرا می‌کند.

آیا ویجت‌های تلگرام در گروه کار می‌کنند؟

فعلاً در محیط production نه. در حال حاضر ربات فقط در چت خصوصی با کاربر می‌تواند ویجت بفرستد و این پیام‌ها قابل فوروارد نیستند. گروه‌ها، حالت inline و فوروارد فقط روی سرور تست کار می‌کنند.

چطور با ربات ویجت بفرستم؟

متد sendWidget را با chat_id و html (رشته‌ای 1 تا 32768 بایتی که بعد از فشرده‌سازی zlib سطح 9 حداکثر 4096 بایت باشد) صدا بزنید؛ caption، chat_data، public_data و allow_queries اختیاری‌اند. خروجی، پیام ارسال‌شده با فیلد widget است.

آیا ویجت می‌تواند درخواست HTTP بفرستد؟

خیر. fetch، XMLHttpRequest، WebSocket و بقیه APIهای شبکه خطای NetworkDisabledError می‌دهند. تنها راه ارتباط، TelegramWidget.request() است که 1 تا 64 بایت داده را به شکل آپدیت widget_query به ربات می‌رساند.

فرق ویجت با مینی اپ چیست؟

مینی اپ صفحه وبی است که خودتان میزبانی می‌کنید و در WebView با دسترسی کامل به شبکه باز می‌شود. ویجت داخل حباب پیام زندگی می‌کند، حداکثر 32 کیلوبایت HTML ثابت دارد، به شبکه دسترسی ندارد و فقط از طریق درخواست با ربات خودش حرف می‌زند.

آیا می‌شود HTML ویجت را بعد از ارسال عوض کرد؟

خیر. کد بعد از ارسال ثابت است و فقط وضعیت تغییر می‌کند: chat_data یا public_data را با editMessageWidgetData یا editSharedWidgetData عوض کنید، یا برای طراحی جدید ویجت تازه بفرستید. کپشن با editMessageCaption قابل ویرایش است.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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