Widget di Pesan Telegram Kini Dapat Mengirim Permintaan ke Bot — Satu per Satu Setiap Ketukan

Widget di pesan Telegram kini memiliki saluran balasan ke bot. Dalam build beta Telegram untuk macOS 13.1.0 per 26 Oktober, skrip widget kini memiliki panggilan request(): dengan satu ketukan, ia dapat mengirim hingga 64 byte ke bot dan menunggu balasan hingga 1.024 byte. Tanpa ketukan, permintaan hanya akan terkirim di obrolan pribadi dengan bot, jika bot mengizinkan permintaan tersebut, selama widget terlihat di layar dan tidak lebih sering dari sekali setiap lima detik. Di sana, widget kini juga mengetahui siapa yang membukanya — ID, nama, username, dan status Premium — serta jenis obrolan tempat widget berada. Widget itu sendiri telah terlihat di versi beta iOS, macOS, dan Android, tetapi mekanisme ini baru terlihat di build macOS; widget belum ada dalam skema API publik maupun Bot API.

The post on Telegram — @gramnews

Apa yang Berubah antara 25 dan 26 Oktober

Beta macOS didistribusikan melalui feed pembaruan, dengan setiap build berupa file zip berisi aplikasi. Untuk perbandingan, build 13.1.0.283381 dari 25 Oktober dan 13.1.0.283391 dari 26 Oktober digunakan.

Skrip widget berkomunikasi dengan klien melalui objek global TelegramWidget. Kodenya terletak di dalam paket WidgetSandbox di dalam aplikasi, dalam file sandbox-bundle.js. Pada build 283381, objek tersebut hanya memiliki sedikit kemampuan: memberikan tema, berlangganan event, membuka tautan, dan mengaktifkan getaran (haptic feedback). Pada build 283391, kemampuan berikut ditambahkan:

Selain tiga event sebelumnya — perubahan tema, aktivasi, dan deaktivasi — kini ditambahkan chatDataChanged dan publicDataChanged.

Pada saat yang sama, semua demonstrasi telah dihapus dari paket HTMLBubbles: tiga belas obrolan demo yang disebutkan dalam artikel 13 Oktober, folder ported dengan kartu yang di-porting, game multipemain voxel-clash, dan folder widget-sandbox dengan contoh-contoh. Hanya satu pustaka three.js yang tersisa di dalam paket.

Kapan Widget Dapat Menulis ke Bot

Aturan-aturan tersebut dicatat dalam sandbox yang sama, dalam teks kesalahan yang diterima skrip, dan dalam string aplikasi:

• Permintaan dikirim dari handler ketukan pada widget, satu panggilan per satu ketukan;
• Tanpa ketukan — hanya di obrolan pribadi dengan bot, hanya jika pesan diizinkan untuk permintaan latar belakang (flag background_query), hanya selama widget terlihat di layar dan tidak lebih sering dari sekali setiap lima detik;
• Selama menunggu balasan dari permintaan sebelumnya, permintaan baru tidak akan dikirim;
• Pratinjau hasil inline yang belum terkirim ke obrolan tidak akan bertanya kepada bot;
• Permintaan dinonaktifkan jika bot tidak mengizinkannya untuk pesan ini — salinan yang diteruskan memiliki izin terpisah;
• Balasan bot — hanya teks dan tidak lebih dari 1.024 byte, jika tidak skrip akan menerima kesalahan INVALID_ANSWER; jika tidak membalas tepat waktu — TIMEOUT.

Pada salinan yang diteruskan, chatData kosong, sedangkan publicData tetap ada.

Di string aplikasi di samping kode HTML bubble, muncul frasa «A tap may send data to the bot» — «ketukan dapat mengirim data ke bot». Di mana tepatnya klien menampilkannya, tidak terlihat dari build.

Apa yang Harus Dilakukan

• Widget saat ini hanya ada di versi beta, dan tidak dapat dikirim dari bot: Bot API tidak memiliki metode yang dapat mengirim widget.
• Saat mengetuk widget, perhatikan bahwa setiap ketukan dapat menjadi permintaan ke bot. Skrip melihat ID, nama, username, dan status Premium Anda, dan ID membutuhkan hingga 16 digit — cukup untuk masuk dalam permintaan 64 byte.
• Dengan sendirinya, tanpa ketukan, widget hanya menulis ke bot di obrolan pribadi dengan bot tersebut. Untuk grup dan channel, sandbox tidak menyediakan permintaan latar belakang.
• Widget tidak memiliki akses jaringan: fetch, XMLHttpRequest, WebSocket, dan worker di sandbox diganti dengan stub yang mengembalikan kesalahan. Data keluar melalui bot atau melalui tautan yang dibuka widget (openLink hanya menerima https dan tidak lebih dari 256 karakter) — ini juga berlaku di build 25 Oktober.

Bagaimana Server Mengirimkan Widget

Dalam biner 283391, muncul nama-nama tipe skema yang tidak ada di 283381. Dalam skema publik layer 232 — baik di Telegram Desktop maupun Telegram Web A — tidak ada, dan widget juga tidak ada dalam dokumentasi Bot API. Strukturnya dapat dibaca dari namanya, jadi selanjutnya adalah interpretasi, bukan deskripsi:

• botInlineMessageWidget, inputBotInlineMessageWidget, dan inputBotInlineMessageWidgetId — bot, tampaknya, mengembalikan widget sebagai hasil inline, secara keseluruhan atau berdasarkan ID;
• inputMediaWidgetId — widget sebagai lampiran pesan berdasarkan ID;
• updateBotWidgetQuery, updateInlineBotWidgetQuery, dan updateBotWidgetCopyQuery — permintaan ke bot dari widget dalam pesan biasa, dalam pesan yang dikirim melalui mode inline, dan, berdasarkan namanya, dalam salinan yang diteruskan; balasannya adalah botWidgetQueryAnswer;
• updateMessageWidgetData dan widgetPublicData — server mengirimkan data baru dari widget yang sudah terkirim, dan di sandbox ada event publicDataChanged untuk ini;
• Kesalahan server WIDGET_QUERY_NOT_ALLOWED dan WIDGET_RESPONSE_TIMEOUT terlihat seperti pasangan untuk kesalahan skrip NOT_ALLOWED dan TIMEOUT.

String klien juga menyebutkan flag izin: allow_queries untuk pesan, fwd_allow_queries untuk salinan yang diteruskan, dan background_query untuk permintaan tanpa ketukan. Apa yang sebenarnya diterima bot bersama dengan permintaan — ID pengguna yang mengetuk, seperti pada tombol di bawah pesan, atau tidak — tidak terlihat dari build.

Apa yang Diuji oleh Benchmark Labs dalam Kode Terbuka

Di repositori klien yang terbuka, mesin widget terhubung sebagai submodule twidget; tautan submodule GitHub mengembalikan 404 — repositori ditutup atau dihapus. Di sampingnya terdapat benchmark labs, dan di folder tools/perflab/TwidgetLab/widgets/attack — 28 widget yang mencoba beroperasi tanpa ketukan nyata. Enam belas di antaranya mengirim data ke bot: berdasarkan timer setiap 50 ms, dengan klik sintetis, panggilan tertunda setelah klik, melalui label bidang formulir (label), dan dengan drag-and-drop. Dua belas mencoba membuka tautan atau meninggalkan halaman tanpa ketukan — dengan tautan di atas tombol, pengiriman formulir, atau auto-refresh halaman. Folder ini muncul di repositori dengan commit pada 23 Oktober, tiga hari sebelum build dengan request().

Dalam benchmark labs ini, pengiriman masih disebut TelegramWidget.sendMessage. Di build 283391, tidak ada panggilan seperti itu — yang ada adalah request(), dan panggilan di luar ketukan diterima skrip sebagai kesalahan dengan alasan no-activation.

Apa lagi yang ada di contoh yang dihapus

Di folder widget-sandbox build 283381, terdapat dua set 20 widget — with-profile dan without-profile. Nama-nama file adalah permintaan: «show me a mortgage calculator», «make a bar chart of the top 6 programming…», «create a pomodoro timer», «create a flashcard widget for 8 Spanish…». Objek TelegramWidget disebutkan oleh 12 file dari set pertama dan tidak ada dari set kedua. Ini menyerupai widget yang dikumpulkan oleh model berdasarkan permintaan yang sama dengan deskripsi kemampuan sandbox dan tanpa itu — ini adalah kesimpulan berdasarkan konten, build itu sendiri tidak mengatakannya. Kata profile juga ada di objek TelegramWidget: properti profile sama dengan 1, dan isProfileAtLeast() memeriksa level.

Sisanya di folder tersebut adalah pemeriksaan kompatibilitas (Chart.js, D3, three.js, WebGL, formulir, drag-and-drop, localStorage), kartu untuk etalase berdasarkan tema "belanja", "pekerjaan", "kehidupan", "perjalanan", dan stress test.

Di Mana Lagi Widget Berada

Widget dalam pesan sebagai format pembaruan 13.2 berikutnya dijelaskan pada 25 Oktober. Bagaimana widget berkomunikasi dengan bot, apa yang dilihatnya tentang penonton, dan di mana batas-batas permintaan, tidak ada dalam deskripsi ini.