مرجع API جاوااسکریپت TelegramWidget: رویدادها، کدهای خطا و محدودیتها
API ویجت تلگرام همان شیء window.TelegramWidget است که هر ویجت Bot API 10.4 از اپ تلگرام میگیرد، بهعلاوه سمت Bot API: آپدیتهای widget_query و متد answerWidgetQuery. این مرجع همه ویژگیها، متدها، رویدادها و کدهای خطای TelegramWidget، متغیرهای CSS، قواعد ژستها و محدودیتها را بر اساس مستندات رسمی ویجتهای تلگرام فهرست میکند.
دسترسپذیری: در محیط production ویجتها فعلاً فقط در چت خصوصی با ربات کار میکنند و قابل فوروارد نیستند (با محتوای محافظتشده ارسال میشوند). گروهها، حالت inline و فوروارد فقط روی سرور تست کار میکنند، پس ویژگیهایی مثلisForwardیاchatType: "group"فعلاً آنجا اهمیت دارند.
تازه با ویجتها آشنا شدهاید؟ از ویجت تلگرام چیست و مثالهای ویجت شروع کنید.
شیء TelegramWidget چطور در دسترس قرار میگیرد
ویجت به هیچ تگ script نیاز ندارد. داخل تلگرام، window.TelegramWidget پیش از اجرای اولین اسکریپت ویجت وجود دارد و در مرورگر معمولی undefined است. متدهایی که در طول یک پروفایل اضافه شدهاند با typeof تشخیص داده میشوند:
const W = window.TelegramWidget; // در مرورگر معمولی undefined
if (W && typeof W.setResizeAnchor === 'function') W.setResizeAnchor('bottom');
function render() {
let state = null;
try { state = JSON.parse(W.chatData); } catch (e) {}
// از روی state رسم کن؛ null یعنی «هنوز وضعیتی نیست»
}
if (W) W.onEvent('chatDataChanged', render);
render();
ویژگیهای TelegramWidget
| ویژگی | نوع | توضیح |
|---|---|---|
profile | Integer | پروفایل ویجتی که اپ اعمال میکند: در این نسخه 1 |
colorScheme | String | light یا dark، طرح رنگ چت (همچنین --tg-color-scheme) |
themeParams | Object | رنگهای حباب به صورت رشته #rrggbb، با همان کلیدهای themeParams مینی اپ |
isActive | Boolean | ویجت دیده میشود (!document.hidden) |
isPreview | Boolean | نتیجه inline پیش از ارسال: بدون لمس، بدون درخواست |
isForward | Boolean | نسخه فورواردشده |
chatType | String | private، group، supergroup، channel، یا null در فوروارد و پیشنمایش |
viewer | Object | id، first_name، last_name، username، is_premium کاربری که نگاه میکند؛ فقط جایی که ویجت اجازه درخواست دارد، وگرنه null |
publicData | String | وضعیت مشترک، تا 1024 بایت، یا null. فقطخواندنی |
chatData | String | وضعیت چت، تا 1024 بایت، یا null؛ در فوروارد همیشه null. فقطخواندنی |
contentSafeAreaInset | Object | top، right، bottom، left، cornerLeft، cornerRight: بخشی که زمان پیام رویش میافتد |
wallet | Object | کیف پول تلگرام، یا null (کیف پولی در این اپ نیست، درخواست مجاز نیست یا پیشنمایش است) |
HapticFeedback | Object | بازخورد لمسی، پایینتر توضیح داده شده |
متدهای TelegramWidget
| متد | کارکرد |
|---|---|
request(data[, options]) | 1 تا 64 بایت به ربات میفرستد. Promiseی برمیگرداند که با { result } (پاسخ ربات یا null) resolve یا با WidgetRequestError رد میشود. فقط در handler لمس یا در پسزمینه، جایی که مجاز است. options میتواند { wallet: true } باشد |
watchPublicData() / unwatchPublicData() | شروع / توقف polling زنده وضعیت مشترک ویجت اشتراکی تا وقتی روی صفحه است. روی ویجت ثابت یا پیشنمایش اثری ندارد |
copyText(text) | با لمس، 1 تا 256 کاراکتر کپی میکند؛ اپ یک toast با همان متن نشان میدهد |
openLink(url) | یک URL با https: (حداکثر 256 کاراکتر، نه دامنه t.me) را پس از تأیید کاربر باز میکند |
openTelegramLink(url) | لینک https://t.me/… را داخل تلگرام باز میکند، مثل لمس لینک در پیام |
setResizeAnchor(edge) | top (پیشفرض) یا bottom: کدام لبه حباب هنگام تغییر ارتفاع ثابت بماند |
ready() | اختیاری: به اپ میگوید اولین وضعیت رسم شده است |
onEvent(type, handler) / offEvent(type, handler) | افزودن / حذف handler رویداد (حداکثر 16 برای هر نوع رویداد) |
isProfileAtLeast(n) | profile >= n را برمیگرداند |
همه متدها به جز isProfileAtLeast، request و متدهای کیف پول همزمان (synchronous) هستند. HapticFeedback متدهای impactOccurred(style) (light، medium، heavy، rigid، soft)، notificationOccurred(type) (error، success، warning) و selectionChanged() را دارد. متد sendMessage وجود ندارد و ویجت widget_id خودش را نمیداند.
رویدادها
| رویداد | چه زمانی |
|---|---|
themeChanged | تم چت عوض شد؛ colorScheme، themeParams و متغیرهای CSS از قبل بهروز شدهاند |
activated / deactivated | ویجت دیده شد / پنهان شد (پس از visibilitychange) |
chatDataChanged | ربات وضعیت چت را تغییر داد؛ chatData از قبل جدید است. هرگز در فوروارد |
publicDataChanged | ربات وضعیت مشترک را تغییر داد؛ برای ویجت اشتراکی روی صفحه فقط در حالت watch. اگر هر دو تغییر کنند، بعد از chatDataChanged میآید |
contentSafeAreaChanged | ناحیهای که زمان پیام میپوشاند تغییر کرد (کپشن اضافه، حذف یا جابهجا شد، برچسب «ویرایششده») |
handlerها بدون آرگومان و با this برابر TelegramWidget صدا زده میشوند، پس مقدار جدید را از خود شیء بخوانید.
کدهای خطای WidgetRequestError
button.addEventListener('click', () => {
status.textContent = 'در حال ارسال…';
TelegramWidget.request('vote:2').then(
(answer) => { status.textContent = answer.result ?? 'انجام شد'; },
(error) => { status.textContent = 'خطا: ' + error.code; }, // error.name === 'WidgetRequestError'
);
});
| code | معنی |
|---|---|
NOT_ALLOWED | بدون allow_queries، فوروارد ویجت ثابت، بدون لمس جایی که درخواست پسزمینه مجاز نیست، پیشنمایش، یا اپی که درخواست را تحویل نمیدهد |
BUSY | درخواست یا فراخوانی کیف پول دیگری از این ویجت در جریان است |
RATE_LIMITED | درخواست پسزمینه کمتر از 5 ثانیه بعد از قبلی، یا بیش از 5 درخواست در 5 ثانیه برای هر کاربر و ربات |
TIMEOUT | ربات ظرف 15 ثانیه جواب نداد (خاموش، کند یا بدون دریافت widget_query / shared_widget_query) |
FAILED | هر چیز دیگر: ربات بلاک یا حذف شده، پیام وجود ندارد، شبکه قطع شده |
INVALID_ANSWER | پاسخ ربات از محدودیتها فراتر رفت |
REJECTED، BAD_REQUEST | فقط برای کیف پول: کاربر رد کرد، یا کیف پول تراکنش یا payload را نپذیرفت |
داده خالی یا بیش از 64 بایت قبل از هر ارسالی TypeError میدهد.
سمت ربات: widget_query و answerWidgetQuery
درخواست از پیام اصلی به صورت widget_query در Update میرسد و از ویجت اشتراکی فورواردشده به صورت shared_widget_query. اگر به getUpdates یا setWebhook پارامتر allowed_updates میدهید (راهنمای وب هوک تلگرام)، هر دو را بگذارید.
{
"update_id": 100000001,
"widget_query": {
"id": "8123456789012345678",
"from": {"id": 123456789, "is_bot": false, "first_name": "Alice"},
"chat": {"id": 123456789, "type": "private", "first_name": "Alice"},
"message_id": 4242,
"chat_instance": "901234567890123456",
"type": {"type": "data"},
"data": "refresh"
}
}
widget_query از پیامی که از طریق ربات ارسال شده، به جای chat و message_id فیلدهای inline_message_id و chat_type دارد؛ widget_id برای ویجتهای اشتراکی میآید. shared_widget_query فقط id، from، type، data و widget_id دارد. به هر کوئری با answerWidgetQuery (widget_query_id و data اختیاری تا 1024 بایت) جواب دهید و وضعیت را جداگانه با editMessageWidgetData یا editSharedWidgetData عوض کنید. from و widget_id را تلگرام تعیین میکند و جعلشدنی نیستند، اما data را ورودی غیرقابل اعتماد بدانید.
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/answerWidgetQuery" \
-H "Content-Type: application/json" \
-d '{"widget_query_id": "8123456789012345678", "data": "{\"n\":5,\"r\":3}"}'
متغیرهای CSS
| متغیر | معنی |
|---|---|
--tg-theme-bg-color، --tg-theme-text-color، --tg-theme-hint-color، --tg-theme-link-color | پسزمینه حباب، متن، متن ثانویه، لینکها |
--tg-theme-button-color، --tg-theme-button-text-color | دکمه اصلی اپ |
--tg-theme-secondary-bg-color، --tg-theme-accent-text-color، --tg-theme-subtitle-text-color، --tg-theme-destructive-text-color، --tg-theme-section-separator-color | سطح دوم، رنگ تأکید، زیرعنوانها، اقدامات مخرب، جداکنندهها |
--tg-color-scheme | light یا dark |
--tg-text-font-size، --tg-text-line-height، --tg-text-padding | اندازه متن پیام (حدود 15px)، ارتفاع خط (حدود 1.35)، فاصله متن از لبه حباب (حدود 8px 12px) |
--tg-button-bg، --tg-button-text، --tg-button-radius، --tg-button-font، --tg-button-padding، --tg-button-height، --tg-button-pressed-opacity، --tg-button-disabled-opacity | استایل دکمه اپ که <button> پیشفرض از آن استفاده میکند |
--tg-content-safe-area-inset-*، --tg-content-safe-area-corner-left / -right | نواری که زمان پیام در آن رسم میشود (همان env(safe-area-inset-*)) |
اپ این متغیرها را روی عنصر ریشه با !important تنظیم میکند؛ فقط روی عناصر خودتان میتوانید بازتعریفشان کنید. prefers-color-scheme، light-dark() و color-scheme از تم چت پیروی میکنند، نه سیستم.
ژستها و touch-action
لمس و دابلتپ همیشه مال ویجت است؛ کشیدن عمودی همیشه چت را اسکرول میکند (ویجت pointercancel میگیرد). نگهداشتن و کشیدن افقی برای هر عنصر با CSS touch-action تعیین میشود: auto آنها را به چت میدهد (منوی پیام، کشیدن برای ریپلای)، pan-y کشیدن افقی را به ویجت میدهد و none نگهداشتن (contextmenu) و کشیدن افقی را. قاعده سرانگشتی: touch-action: none روی دکمه نگهداشتنی، کنترل بازی یا canvas، pan-y روی اسلایدر افقی یا carousel و auto برای بقیه. از رویدادهای pointer استفاده کنید؛ رویدادهای touch تحویل داده نمیشوند. کنترلها را از 20 پیکسل لبه آغازین دور نگه دارید؛ در رابط راستبهچپ این لبه سمت راست است.
چیزهایی که پروفایل ویجت حذف میکند
- کنترلهای فرم (
input،select،textarea)؛<button>تنها کنترل است. رویداد کیبورد و focus وجود ندارد. - همه APIهای شبکه (
fetch،XMLHttpRequest،WebSocketو بقیهNetworkDisabledErrorمیدهند)، اسکریپت، استایل، فونت و تصویر خارجی،locationوhistory. vhو دیگر واحدهای وابسته به ارتفاع،overflow: auto / scroll(بهhiddenتبدیل میشود)،position: sticky،@font-face،:has()و CSS nesting.alert،confirm،prompt،navigator.clipboard(به جایشcopyText)،iframe،video،audioو WebGL.
ویژگیهای حذفشده ویجت را خراب نمیکنند: آن عنصر، declaration یا رویداد کنار گذاشته میشود و بقیه کار میکند. CSS.supports() و @supports بر اساس پروفایل جواب میدهند.
محدودیتهای ویجت تلگرام
| محدودیت | مقدار | در صورت عبور |
|---|---|---|
| HTML | 32768 بایت؛ 4096 بایت بعد از zlib سطح 9 | INPUT_MEDIA_WIDGET_TOO_LARGE |
chat_data، public_data | هر کدام 1024 بایت UTF-8 | INPUT_MEDIA_WIDGET_DATA_TOO_LARGE |
| داده درخواست | 1 تا 64 بایت | TypeError در ویجت |
| داده پاسخ | 1024 بایت | WIDGET_RESULT_TOO_LARGE |
| مهلت پاسخ | 15 ثانیه | TIMEOUT؛ پاسخ دیرهنگام: query is too old |
| درخواستها | 5 در 5 ثانیه برای هر کاربر و ربات | RATE_LIMITED |
| ویرایش ویجت اشتراکی | 1 در ثانیه؛ دوره بهروزرسانی پیشفرض 30 ثانیه، cache_time بین 5 و 3600 | flood wait؛ زیر 5: invalid cache time specified |
| CPU | 300 میلیثانیه JavaScript در ثانیه؛ 500 میلیثانیه در یک task | کند میشود؛ ویجت متوقف میشود |
| حافظه | 8 مگابایت | ویجت متوقف میشود |
| گرههای DOM | 2000 | ویجت متوقف میشود |
| تایمرها | 64 تایمر فعال | RangeError |
localStorage، sessionStorage | 4 کیلوبایت برای هر ناحیه در هر پیام | QuotaExceededError |
| حباب | عرض 200 پیکسل تا حداکثر عرض حباب، ارتفاع 50 تا 600 پیکسل | بریده میشود |
ویجت متوقفشده آخرین فریمش را با نشان «Widget stopped» نگه میدارد و وقتی دوباره نمایش داده شود از نو ساخته میشود؛ بعد از دو کرش پشت سر هم تا ریاستارت اپ متوقف میماند.
حافظه محلی، لینکها، بازخورد لمسی و copyText
- Web Storage متعلق به همین پیام روی همین دستگاه است. بعد از ریاستارت اپ باقی میماند، هرگز برای ربات ارسال نمیشود و بین دستگاهها همگام نمیشود.
setItemرا داخلtry/catchبگذارید. - لینکها:
openLink،openTelegramLink،copyTextوrequestلمس واقعی میخواهند: آنها را همزمان داخل handlerclickصدا بزنید، نه بعد ازawaitیا تایمر. هر لمس یک فراخوانی را مجاز میکند. URL نامعتبرTypeErrorمیدهد؛ لمس یک<a href="https://…">هم کار میکند. - بازخورد لمسی فقط وقتی ویجت دیده میشود پخش میشود، حداکثر 5 تا پشت سر هم و 10 در ثانیه؛ هنگام لمس و تا 5 ثانیه بعد آزاد است. اپهای دسکتاپ و وب چیزی پخش نمیکنند.
- copyText 1 تا 256 کاراکتر کپی میکند و همیشه toast با متن کپیشده نشان میدهد.
پرداخت با کیف پول TON به طور خلاصه
ویجت میتواند از کاربر بخواهد با کیف پول داخلی تلگرام و فرمتهای TON Connect پرداخت کند. دکمه پرداخت را فقط وقتی TelegramWidget.wallet برابر null نیست رسم کنید. با لمس، ویجت request(data, { wallet: true }) را میفرستد؛ کوئری ربات type برابر {"type": "data", "wallet_card": …} دارد و ربات با یک تراکنش تازه جواب میدهد. ویجت در handler پاسخ wallet.sendTransaction() را صدا میزند که ظرف 10 ثانیه به لمس دوم نیاز ندارد:
TelegramWidget.request('pay:42', { wallet: true })
.then((a) => TelegramWidget.wallet.sendTransaction(JSON.parse(a.result), 'paid:42'))
.then((a) => show(a.result), (e) => showError(e.code));
سپس ربات کوئری از نوع sent_transaction با هش پیام میگیرد و باید تراکنش را روی زنجیره بررسی کند. بعد از TIMEOUT ممکن است پرداخت انجام شده باشد، پس به جای پرداخت دوباره، وضعیت سفارش را از ربات بپرسید.
خطاهای Bot API برای ویجتها
| خطا | علت |
|---|---|
INPUT_MEDIA_WIDGET_TOO_LARGE | HTML بیش از 32768 بایت یا 4096 بایت فشرده |
INPUT_MEDIA_WIDGET_HTML_INVALID | UTF-8 نامعتبر یا کاراکتر NUL در html |
INPUT_MEDIA_WIDGET_DATA_TOO_LARGE | chat_data یا public_data بیش از 1024 بایت |
INPUT_MEDIA_WIDGET_DATA_INVALID / WIDGET_DATA_INVALID | متن وضعیت نامعتبر هنگام ارسال / هنگام ویرایش |
message is not modified | ویرایشی که چیزی را تغییر نمیدهد؛ موفقیت حساب کنید |
این متدها را با توکن خودتان در Bot API Tester امتحان کنید و پارامترهای sendWidget را ببینید. اگر هنوز ربات ندارید، از آموزش ساخت ربات تلگرام شروع کنید.
پرسشهای متداول
برای استفاده از TelegramWidget باید اسکریپتی اضافه کنم؟
خیر. داخل تلگرام، window.TelegramWidget پیش از اجرای اولین اسکریپت ویجت با وضعیت، تم و زمینه آماده است. بیرون از تلگرام undefined است، پس وقتی ویجت را در مرورگر باز میکنید وجودش را چک کنید.
خطای NOT_ALLOWED در WidgetRequestError یعنی چه؟
این پیام اجازه درخواست ندارد: ویجت بدون allow_queries ارسال شده، فوروارد یک ویجت ثابت یا پیشنمایش است، یا request() بیرون از لمس و در جایی صدا زده شده که درخواست پسزمینه مجاز نیست.
ربات چقدر وقت دارد به widget_query جواب دهد؟
15 ثانیه، با answerWidgetQuery. بعد از آن promise ویجت با TIMEOUT رد میشود و پاسخ دیرهنگام با query is too old پذیرفته نمیشود. به همه کوئریها جواب دهید، حتی وقتی کاری شکست خورده است.
آیا ویجت میتواند chatData یا publicData خودش را تغییر دهد؟
خیر. هر دو در ویجت فقطخواندنیاند. فقط ربات وضعیت را با sendWidget، editMessageWidgetData یا editSharedWidgetData مینویسد و ویجت فقط میتواند با TelegramWidget.request() از ربات درخواست کند.
آیا متد TelegramWidget.sendMessage وجود دارد؟
خیر. sendMessage در ویجتها وجود ندارد و هیچ چیزی از طرف کاربر در چت ارسال نمیشود. ویجت فقط میتواند به ربات خودش درخواست بفرستد، متن کپی کند، لینک باز کند و بازخورد لمسی پخش کند.
آموزشهای مرتبط
ساخت ربات تلگرام: آموزش قدمبهقدم از 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، جاسازی پست کانال، ویجت کامنت و دکمه اشتراکگذاری تلگرام.
مثال ویجت تلگرام: کد کامل HTML و ربات پایتون
مثالهای کامل ویجت تلگرام با کد: کارت سفارش ثابت، شمارنده با widget_query، نظرسنجی زنده با ویجت اشتراکی و پیشنمایش در مرورگر با ربات پایتون.
ویجت تلگرام چیست؟ HTML تعاملی داخل پیامهای ربات
ویجت تلگرام در Bot API 10.4 چیست؟ ارسال با sendWidget، وضعیت chat_data و public_data، محدودیتها، جاهایی که فعلاً کار میکند و تفاوت با مینی اپ.