Telegram Bot API

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

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

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

ویژگینوعتوضیح
profileIntegerپروفایل ویجتی که اپ اعمال می‌کند: در این نسخه 1
colorSchemeStringlight یا dark، طرح رنگ چت (همچنین --tg-color-scheme)
themeParamsObjectرنگ‌های حباب به صورت رشته #rrggbb، با همان کلیدهای themeParams مینی اپ
isActiveBooleanویجت دیده می‌شود (!document.hidden)
isPreviewBooleanنتیجه inline پیش از ارسال: بدون لمس، بدون درخواست
isForwardBooleanنسخه فورواردشده
chatTypeStringprivate، group، supergroup، channel، یا null در فوروارد و پیش‌نمایش
viewerObjectid، first_name، last_name، username، is_premium کاربری که نگاه می‌کند؛ فقط جایی که ویجت اجازه درخواست دارد، وگرنه null
publicDataStringوضعیت مشترک، تا 1024 بایت، یا null. فقط‌خواندنی
chatDataStringوضعیت چت، تا 1024 بایت، یا null؛ در فوروارد همیشه null. فقط‌خواندنی
contentSafeAreaInsetObjecttop، right، bottom، left، cornerLeft، cornerRight: بخشی که زمان پیام رویش می‌افتد
walletObjectکیف پول تلگرام، یا null (کیف پولی در این اپ نیست، درخواست مجاز نیست یا پیش‌نمایش است)
HapticFeedbackObjectبازخورد لمسی، پایین‌تر توضیح داده شده

متدهای 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-schemelight یا 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 پیکسل لبه آغازین دور نگه دارید؛ در رابط راست‌به‌چپ این لبه سمت راست است.

چیزهایی که پروفایل ویجت حذف می‌کند

ویژگی‌های حذف‌شده ویجت را خراب نمی‌کنند: آن عنصر، declaration یا رویداد کنار گذاشته می‌شود و بقیه کار می‌کند. CSS.supports() و @supports بر اساس پروفایل جواب می‌دهند.

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

محدودیتمقداردر صورت عبور
HTML32768 بایت؛ 4096 بایت بعد از zlib سطح 9INPUT_MEDIA_WIDGET_TOO_LARGE
chat_data، public_dataهر کدام 1024 بایت UTF-8INPUT_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 و 3600flood wait؛ زیر 5: invalid cache time specified
CPU300 میلی‌ثانیه JavaScript در ثانیه؛ 500 میلی‌ثانیه در یک taskکند می‌شود؛ ویجت متوقف می‌شود
حافظه8 مگابایتویجت متوقف می‌شود
گره‌های DOM2000ویجت متوقف می‌شود
تایمرها64 تایمر فعالRangeError
localStorage، sessionStorage4 کیلوبایت برای هر ناحیه در هر پیامQuotaExceededError
حبابعرض 200 پیکسل تا حداکثر عرض حباب، ارتفاع 50 تا 600 پیکسلبریده می‌شود

ویجت متوقف‌شده آخرین فریمش را با نشان «Widget stopped» نگه می‌دارد و وقتی دوباره نمایش داده شود از نو ساخته می‌شود؛ بعد از دو کرش پشت سر هم تا ری‌استارت اپ متوقف می‌ماند.

پرداخت با کیف پول 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_LARGEHTML بیش از 32768 بایت یا 4096 بایت فشرده
INPUT_MEDIA_WIDGET_HTML_INVALIDUTF-8 نامعتبر یا کاراکتر NUL در html
INPUT_MEDIA_WIDGET_DATA_TOO_LARGEchat_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، محدودیت‌ها، جاهایی که فعلاً کار می‌کند و تفاوت با مینی اپ.