ویجت تلگرام چیست؟ HTML تعاملی داخل پیامهای ربات
ویجت تلگرام یک بلوک HTML تعاملی کوچک است که ربات با متد sendWidget داخل پیام میفرستد؛ این قابلیت در Bot API 10.4 (9 نوامبر 2026) اضافه شد. ویجت یک سند HTML تا 32 کیلوبایت است که اپ تلگرام روی دستگاه کاربر و بدون هیچ دسترسی به شبکه اجرا میکند و با ظاهر خود چت رسم میشود: کارت سفارشی که وضعیتش بهروز میشود، یک شمارنده، نظرسنجیای که نوارهایش با رأیها جابهجا میشوند یا کد تخفیفی که با یک لمس کپی میشود.
ویجتها فعلاً کجا کار میکنند: در محیط production ربات فقط در چت خصوصی با کاربر میتواند ویجت بفرستد و این پیامها با محتوای محافظتشده (protected content) ارسال میشوند، یعنی قابل فوروارد نیستند. ویجت در گروهها، حالت inline و فوروارد فعلاً فقط روی سرور تست کار میکند.
ویجت تلگرام دقیقاً چیست
- یک سند HTML.
<style>و<script>درونخطی، تصویر فقط به صورتdata:URL یا SVG درونخطی. حداکثر 32768 بایت UTF-8 و حداکثر 4096 بایت بعد از فشردهسازی zlib سطح 9. یک تکه HTML بدون<html>و<body>هم قابل قبول است. - داخل sandbox. جاوااسکریپت ویجت در QuickJS (یک موتور JavaScript کوچک) اجرا میشود، نه WebView. اپ هر تغییر را با پروفایل ویجت (widget profile) میسنجد و فقط موارد مجاز را رسم میکند، پس ویجت در iOS، اندروید، macOS، Desktop و وب یکسان است.
- آفلاین.
fetch،XMLHttpRequest،WebSocketو بقیه APIهای شبکه خطایNetworkDisabledErrorمیدهند. اسکریپت، استایل، فونت و تصویر خارجی هرگز بارگذاری نمیشود و هیچ کتابخانهای هم همراه ویجت نیست. - ظاهر بومی. رنگهای چت به صورت متغیرهای CSS با پیشوند
--tg-theme-*در دسترس است و یک<button>بدون استایل، شبیه دکمه خود اپ رسم میشود. - بدون کیبورد. input، select و textarea حذف میشوند. ویجت به لمس، رویدادهای pointer، کشیدن افقی و نگهداشتن واکنش نشان میدهد.
کد و وضعیت: chat_data و public_data
ویجت یعنی کد ثابت بهعلاوه وضعیت قابل تغییر. HTML هنگام ارسال تعیین میشود و دیگر هیچ متدی آن را عوض نمیکند. چیزی که تغییر میکند وضعیت (state) است و فقط ربات آن را مینویسد. ویجت وضعیت را از TelegramWidget.chatData و TelegramWidget.publicData میخواند و با رویدادهای chatDataChanged و publicDataChanged دوباره رسم میکند.
| ویژگی | وضعیت چت (chat_data) | وضعیت مشترک (public_data) |
|---|---|---|
| وابسته به | یک پیام اصلی | پیام یک ویجت ثابت، یا ویجت اشتراکی در همه جاهایی که نمایش داده میشود |
| چه کسی میبیند | فقط همان چت (در گروه، یکی برای همه اعضا) | هر جا ویجت نمایش داده شود |
| در فوروارد | هرگز | یک کپی (ویجت ثابت) یا وضعیت زنده (ویجت اشتراکی) |
| اندازه | حداکثر 1024 بایت متن | حداکثر 1024 بایت متن |
| تغییر با | editMessageWidgetData | editMessageWidgetData یا 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
- ربات بسازید و توکنش را کپی کنید (آموزش ساخت ربات تلگرام، توکن ربات تلگرام را از کجا بگیریم).
- به ربات
/startبفرستید تا بتواند به شما پیام بدهد و چت آیدی خود را ازgetUpdatesبردارید. - متد 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 داخل ویجت کار میکند:
- ربات ویجت را با
allow_queries: trueمیفرستد. - با لمس کاربر، ویجت
TelegramWidget.request("like")را با 1 تا 64 بایت داده صدا میزند. - ربات آپدیت
widget_queryبا فیلدهایid،from،chat،message_idوdataمیگیرد (از فوروارد یک ویجت اشتراکی:shared_widget_query). اگرallowed_updatesمیفرستید، هر دو نوع را در آن بگذارید. - ربات ظرف 15 ثانیه answerWidgetQuery را صدا میزند و میتواند
dataتا 1024 بایت برگرداند که فقط به ویجتِ درخواستدهنده میرسد. - برای تغییر چیزی که همه میبینند، ربات editMessageWidgetData (یا
editSharedWidgetData) را صدا میزند و ویجت رویدادchatDataChanged/publicDataChangedرا دریافت میکند.
خود پاسخ هرگز وضعیت را تغییر نمیدهد. سقف درخواستها 5 درخواست در 5 ثانیه برای هر کاربر و ربات است و درخواستی که جواب نگیرد، در ویجت با TIMEOUT تمام میشود. کد کامل و قابل اجرا در مثالهای ویجت تلگرام آمده است.
ویجت ثابت و ویجت اشتراکی
بدون is_shared ویجت ثابت (static) است: کد و وضعیت داخل پیام میمانند و فوروارد یک کپی منجمد دریافت میکند. با is_shared، اولین ارسال یک ویجت اشتراکی میسازد: یک شیء با شناسه (widget.id در پیام برگشتی) که هر تعداد پیام میتواند نمایشش دهد. آن را با sendSharedWidget دوباره بفرستید و وضعیت مشترکش را برای همه پیامها یکجا با editSharedWidgetData عوض کنید، حداکثر یک بار در ثانیه. ویجتی که روی صفحه است فقط وقتی وضعیت مشترک جدید را میگیرد که TelegramWidget.watchPublicData() را صدا زده باشد؛ در این حالت اپ با دوره بهروزرسانی ویجت (پیشفرض 30 ثانیه، 5 تا 3600 ثانیه با cache_time) وضعیت را میپرسد.
خلاصه محدودیتهای ویجت تلگرام
| مورد | محدودیت |
|---|---|
| HTML | 32768 بایت؛ 4096 بایت بعد از zlib سطح 9 |
chat_data، public_data | هر کدام 1024 بایت |
| داده درخواست / داده پاسخ | 1 تا 64 بایت / حداکثر 1024 بایت |
| مهلت پاسخ به کوئری | 15 ثانیه |
| درخواستها | 5 در 5 ثانیه برای هر کاربر و ربات |
| اندازه حباب | عرض 200 پیکسل تا حداکثر عرض حباب، ارتفاع 50 تا 600 پیکسل؛ بقیه بریده میشود |
| ویرایش ویجت اشتراکی | 1 بار در ثانیه |
| حافظه / گرههای DOM | 8 مگابایت / 2000 گره |
جدول کامل، با سهمیه CPU، تایمرها و حافظه محلی، در مرجع API ویجت TelegramWidget آمده است.
نکات طراحی
- همیشه کپشن بفرستید. لیست چتها، اعلانها، جستوجو و اپهای بدون پشتیبانی ویجت همین کپشن را نشان میدهند.
- از تم استفاده کنید. رنگها را روی متغیرهای
--tg-theme-*بسازید و ویجت را در تم روشن و تیره تست کنید؛prefers-color-schemeاز تم چت پیروی میکند، نه از سیستم. - اولین وضعیت را فوراً رسم کنید از روی
chatData/publicData؛ چیزی برای بارگذاری وجود ندارد. - کوچک نگهش دارید. حجم فشرده را همانطور که سرور حساب میکند بشمارید:
python3 -c 'import sys,zlib; print(len(zlib.compress(sys.stdin.buffer.read(), 9)))' < widget.html. - هیچ رازی در ویجت نگذارید. کد و وضعیت مشترک را عمومی فرض کنید؛ در گروه همه اعضا وضعیت چت را میبینند.
- چیدمان را بر اساس عرض بسازید با
%، flex یا grid. واحدvhپشتیبانی نمیشود و هیچ چیزی داخل ویجت اسکرول نمیخورد. - همه نتایج یک درخواست را نشان دهید: «در حال ارسال…»، پاسخ ربات و هر کد خطا.
با ویجتهای وبسایت اشتباه نگیرید
«ویجت تلگرام» به ویجتهای قدیمی وبسایت هم گفته میشود (Telegram Login Widget، جاسازی پست، دکمه اشتراکگذاری) که اسکریپتهایی برای سایت خودتان هستند. ویجتهای Bot API 10.4 اما HTMLی هستند که ربات داخل چت میفرستد. راهاندازی آن ویجتها، از جمله ورود با تلگرام در سایت، در راهنمای ویجتهای تلگرام برای سایت آمده است. مستندات رسمی این ویجتها در core.telegram.org/bots/widgets است.
قدمهای بعدی
- مثالهای ویجت تلگرام: کارت سفارش، شمارنده با درخواست و نظرسنجی زنده اشتراکی، همراه با کد ربات پایتون.
- API جاوااسکریپت TelegramWidget: ویژگیها، متدها، رویدادها، کدهای خطا، متغیرهای CSS و محدودیتها.
- مرجع متدهای Bot API: پارامترهای همه متدهای ویجت در نسخه 10.4.
پرسشهای متداول
ویجت تلگرام چیست؟
بلوک تعاملی کوچکی که داخل پیام ربات رسم میشود و در 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، نظرسنجی زنده با ویجت اشتراکی و پیشنمایش در مرورگر با ربات پایتون.