Widget ialah komponen interaktif yang disematkan terus dalam mesej bot: kod promo dengan butang salin, pemasa kira detik, penjejak status pesanan, kuiz, atau kalendar untuk memilih tarikh dan masa. Apabila pelanggan berinteraksi dengan widget, bot mengemas kini mesej yang sama di tempatnya — tanpa menghantar mesej baharu atau memaparkan label "disunting".

Kod promo

Terdapat dua cara untuk menghantar widget:

Templat siap sedia — satu baris dalam Kalkulator. Susun atur dan fungsi telah dilaksanakan.
Widget tersuai — tulis kod HTML anda sendiri (atau minta Mavi menciptanya) dan proses interaksi menggunakan blok aliran bot.


Aplikasi mesej	Telegram sahaja
Jenis chat	Sembang peribadi antara pelanggan dan bot sahaja
Tidak disokong	Kumpulan, saluran, Telegram Business
Aplikasi Telegram	Memerlukan versi Telegram terkini. Versi lama memaparkan notis "Mesej tidak disokong" dan kapsyen
Penerusan	Widget tidak boleh diteruskan atau disalin

Widget tidak menyokong medan input teks atau papan kekunci. Pelanggan hanya boleh berinteraksi dengan mengetik. Jika anda memerlukan pelanggan memasukkan teks, gunakan soalan bot biasa atau Aplikasi Web.

Widget tidak dipaparkan dalam tetingkap ujian bot dalam papan pemuka kerana ia bukan Telegram. Uji widget secara langsung dalam Telegram dengan menghantar mesej kepada bot anda.

Templat Siap Sedia

Semua templat dihantar menggunakan satu fungsi:

tg_send_widget(platform_id, template, params, caption)

Parameter	Penerangan
`platform_id`	ID penerima. Untuk pelanggan semasa, gunakan pemboleh ubah `platform_id`
`template`	Nama templat: `promo`, `timer`, `order_status`, `faq`, `quiz`, `calendar`
`params`	Kamus yang mengandungi tetapan templat
`caption`	Teks yang dipaparkan di bawah widget. Pelanggan juga melihatnya dalam senarai chat, pemberitahuan, dan versi Telegram lama, jadi ia harus bermakna dengan sendirinya

Fungsi ini mengembalikan respons API Telegram. ID mesej yang dihantar tersedia di response['result']['message_id']. Simpan jika anda bercadang untuk mengemas kini widget kemudian.

Jika fungsi mengembalikan teks dan bukan respons Telegram, ralat telah berlaku: templat tidak diketahui, parameter tidak sah atau hilang, atau widget melebihi had saiz. Teks ralat menerangkan apa yang salah.

Cara Membina Parameter

Buat kamus dan tetapkan setiap parameter pada baris berasingan:

p = {}
p["code"] = "WIDGET10"
p["title"] = "Kod promo anda"
p["note"] = "Diskaun 10% untuk sebarang pesanan"
w = tg_send_widget(platform_id, "promo", p, "Kod promo anda WIDGET10 — diskaun 10%")

Masukkan kod dalam medan Kalkulator blok. Tangkapan skrin menunjukkan blok Syarat Mula yang menghantar widget status pesanan apabila pelanggan menghantar frasa "widget pesanan".

Widget dalam pembina bot

Dalam blok yang menghantar widget, anda biasanya menetapkan medan respons kepada #{none}. Blok tidak menghantar mesej teks berasingan kerana kapsyen widget berfungsi sebagai teks mesej.

Bahasa

Templat termasuk teks antara muka terbina dalam, seperti label butang, nama bulan dan hari minggu, "Masa tamat", dan mesej lain.

Bahasa lalai dalam Mavibot ialah Inggeris (en).

Untuk menggunakan bahasa lain, nyatakan parameter lang:

p["lang"] = "ms"

Bahasa yang disokong:

ru, en, de, es, fr, pt, tr, uk, kk, ms, th, ar.

Teks yang anda sediakan sendiri — tajuk, soalan, langkah, dan kapsyen — dipaparkan tepat seperti yang dimasukkan dan tidak diterjemah secara automatik.

Kod Promo — `promo`

Memaparkan kod promo dengan butang yang menyalinnya dengan satu ketikan.

Kod promo

Parameter	Penerangan
`code`	Kod promo. Wajib
`title`	Teks yang dipaparkan di atas kod
`note`	Teks yang dipaparkan di bawah kod, seperti tarikh luput
`button`	Label butang. Lalai: "Salin kod promo"
`used_text`	Teks yang dipaparkan apabila kod ditandakan sebagai digunakan

p = {}
p["code"] = "WIDGET10"
p["title"] = "Kod promo anda"
p["note"] = "Diskaun 10% untuk sebarang pesanan"
p["button"] = "Salin kod"
w = tg_send_widget(platform_id, "promo", p, "Kod promo anda WIDGET10 — diskaun 10%")
client.promo_widget_id = w['result']['message_id']

Untuk menandakan kod sebagai digunakan, yang memangkah kod dan mengeluarkan butang:

p = {}
p["used"] = 1
t = tg_edit_widget_data(platform_id, client.promo_widget_id, p)

Pemasa Kira Detik — `timer`

Memaparkan kira detik ke tarikh dan masa yang ditentukan.

Kira detik berjalan pada peranti pelanggan. Bot tidak terlibat dalam mengemas kini pemasa.

Pemasa kira detik

Parameter	Penerangan
`until`	Tarikh dan masa sasaran dalam format `"DD.MM.YYYY HH:MM"`, menggunakan zon waktu projek
`seconds`	Sebagai alternatif, bilangan saat dari saat widget dihantar
`title`	Tajuk pemasa. Lalai: "Tawaran tamat dalam"
`done`	Teks yang dipaparkan apabila kira detik tamat
`text`	Teks yang dipaparkan di bawah kira detik
`button`, `url`	Label butang dan URL destinasi (`https://` sahaja)
`hide_button`	Tetapkan kepada `1` untuk menyembunyikan butang apabila kira detik tamat

Anda mesti menyediakan sama ada until atau seconds.

p = {}
p["seconds"] = 7200
p["title"] = "Tawaran tamat dalam"
p["button"] = "Lawati laman web"
p["url"] = "https://salebot.pro"
w = tg_send_widget(platform_id, "timer", p, "Tawaran tamat dalam 2 jam")

Apabila kira detik mencapai sifar, tiada mesej atau panggilan balik dihantar ke bot. Jika bot perlu melakukan tindakan apabila tawaran tamat, gunakan sambungan pemasa biasa dalam aliran bot.

Status Pesanan — `order_status`

Memaparkan senarai peringkat pesanan dengan peringkat semasa diserlahkan.

Bot boleh mengemas kini peringkat di tempatnya, jadi pelanggan sentiasa melihat mesej yang sama.

Status pesanan: peringkat pertama

Parameter	Penerangan
`title`	Tajuk widget
`steps`	Senarai peringkat, dari 1 hingga 12. Lalai: diterima, disediakan, diserahkan kepada kurier, dalam perjalanan, dihantar
`step`	Nombor peringkat semasa, bermula dari 1
`text`	Teks yang dipaparkan di bawah peringkat

Menghantar widget:

p = {}
p["title"] = "Status pesanan"
p["steps"] = ["Diterima", "Disediakan", "Dihantar"]
p["step"] = 1
p["text"] = "Pesanan anda telah diterima dan sedang disediakan"
w = tg_send_widget(platform_id, "order_status", p, "Pesanan anda")
client.order_widget_id = w['result']['message_id']

Bergerak ke peringkat seterusnya dari mana-mana blok lain, seperti apabila peringkat deal berubah, pengurus menghantar arahan, atau pemasa dicetuskan:

p = {}
p["step"] = 2
p["text"] = "Pesanan anda sedang disediakan dan akan diserahkan kepada kurier tidak lama lagi"
t = tg_edit_widget_data(platform_id, client.order_widget_id, p)

Status pesanan: peringkat kedua

Kapsyen di bawah widget tidak berubah apabila peringkat dikemas kini. Gunakan kapsyen neutral seperti "Pesanan anda" dan bukan "Status: Diterima".

Soalan Lazim — `faq`

Memaparkan senarai soalan. Pelanggan boleh mengetik soalan untuk mengembangkan jawapannya.

Widget FAQ

Parameter	Penerangan
`title`	Tajuk widget
`items`	Senarai pasangan soalan dan jawapan. Wajib

p = {}
p["title"] = "Soalan Lazim"
p["items"] = [["Bagaimana saya boleh membayar?", "Anda boleh membayar dengan kad. Pautan pembayaran akan dihantar ke chat ini."], ["Berapa lama penghantaran?", "Penghantaran biasanya mengambil masa 1–2 hari di kawasan tempatan dan 3–7 hari di seluruh negara."], ["Bolehkah saya memulangkan item?", "Ya, dalam tempoh 14 hari."]]
w = tg_send_widget(platform_id, "faq", p, "Jawapan kepada soalan lazim")

Teks dipaparkan sebagai teks biasa. Tag HTML dan markup lain tidak diproses.

Kuiz dan Tinjauan — `quiz`

Memaparkan soalan dengan jawapan pelbagai pilihan, satu soalan pada satu masa.

Jika jawapan betul ditentukan, widget bertindak sebagai kuiz dan mengira skor. Tanpa jawapan betul, ia berfungsi sebagai tinjauan.

Soalan kuiz

Parameter	Penerangan
`title`	Tajuk yang dipaparkan di atas soalan
`questions`	Senarai soalan. Wajib
`retry`	Tetapkan kepada `1` untuk memaparkan butang "Cuba lagi" di akhir
`callback`	Teks panggilan balik tersuai dan bukannya `widget_quiz_finished`

Setiap soalan ialah kamus yang mengandungi:

q — teks soalan
options — pilihan jawapan
correct — jawapan betul, ditentukan oleh indeks bermula 1 atau teks tepat

p = {}
p["title"] = "Kuiz: Uji Pengetahuan Anda"
p["retry"] = 1
p["questions"] = [{"q": "Berapakah 2 + 2?", "options": ["3", "4", "5"], "correct": 2}, {"q": "Apakah ibu negara Perancis?", "options": ["London", "Paris", "Berlin"], "correct": "Paris"}]
w = tg_send_widget(platform_id, "quiz", p, "Cuba kuiz dua soalan ini!")

Untuk mencipta tinjauan tanpa pemarkahan, tinggalkan correct daripada setiap soalan.

Jawapan betul disemak oleh platform dan tidak dihantar ke peranti pelanggan.

Apa yang Diterima oleh Aliran Bot

Jawapan soalan individu tidak dihantar ke perbualan.

Apabila pelanggan menjawab soalan terakhir, bot menerima panggilan balik widget_quiz_finished dan pemboleh ubah berikut diisi:

Pemboleh ubah	Nilai
`widget_quiz_score`	Bilangan jawapan betul; kosong untuk tinjauan
`widget_quiz_total`	Jumlah bilangan soalan
`widget_quiz_answers`	Indeks pilihan yang dipilih, seperti `[2,2]`

Untuk memproses hasil, buat sambungan dari blok yang menghantar kuiz atau gunakan blok Syarat Mula dengan syarat widget_quiz_finished.

Contoh respons:

Keputusan anda: #{widget_quiz_score} daripada #{widget_quiz_total} jawapan betul

Keputusan kuiz dan respons bot

Kalendar — `calendar`

Memaparkan kalendar bulanan di mana pelanggan boleh memilih tarikh dan kemudian slot masa.

Ia menggantikan berbilang halaman butang tarikh dan masa, termasuk navigasi "Kembali" dan "Seterusnya".

Kalendar: memilih tarikh dan masa

Kalendar menyokong tiga mod.

Tarikh dan Masa Tersuai

Masa yang tersedia sentiasa dihantar melalui parameter slots.

Slot masa yang sama setiap hari — sediakan senarai masa dan julat tarikh:

p = {}
p["title"] = "Pilih tarikh dan masa"
p["name"] = "Konsultasi"
p["days"] = 10
p["slots"] = ["10:00", "12:00", "15:00"]
w = tg_send_widget(platform_id, "calendar", p, "Pilih tarikh dan masa")

Slot masa berbeza untuk tarikh tertentu — sediakan kamus yang memetakan tarikh kepada senarai masa. Tarikh yang tersedia diambil daripada kunci kamus:

p = {}
p["slots"] = {"20.11.2026": ["10:00", "12:00"], "21.11.2026": ["15:00"]}
w = tg_send_widget(platform_id, "calendar", p, "Pilih tarikh dan masa")

Parameter	Penerangan
`slots`	Masa yang tersedia, sebagai senarai atau kamus yang dikumpulkan mengikut tarikh
`days`	Bilangan hari yang tersedia bermula dari hari ini
`date_from`, `date_to`	Sebagai alternatif, sempadan julat tarikh dalam format `"DD.MM.YYYY"`
`dates`	Sebagai alternatif, senarai tarikh tertentu
`weekdays_off`	Hari minggu yang tidak tersedia: 1 = Isnin hingga 7 = Ahad
`title`	Petunjuk yang dipaparkan di bawah grid kalendar
`name`	Nama item atau perkhidmatan yang ditempah; dipaparkan selepas pemilihan
`change`	Tetapkan kepada `1` untuk memaparkan butang "Pilih masa lain" selepas pemilihan
`callback`	Teks panggilan balik tersuai dan bukannya `widget_calendar_selected`

Tarikh Sahaja

Jangan hantar slots jika pelanggan hanya perlu memilih tarikh.

p = {}
p["days"] = 45
p["weekdays_off"] = [7]
w = tg_send_widget(platform_id, "calendar", p, "Pilih tarikh")

Tempahan Dalam Talian

Sediakan cawangan dan perkhidmatan, dan kalendar akan mendapatkan tarikh dan slot masa yang tersedia secara automatik daripada modul Perkhidmatan.

cal = {}
cal["company_id"] = comp_id
cal["service_ids"] = serv_id
cal["days_limit"] = 30
cal["name"] = serv_title
w = tg_send_widget(platform_id, "calendar", cal, serv_title)

Parameter	Penerangan
`company_id`	Pengecam cawangan
`service_ids`	Perkhidmatan atau senarai perkhidmatan
`employee_id`	Pengecam pekerja; jika diabaikan, mana-mana pekerja yang tersedia digunakan
`days_limit`	Bilangan hari ke hadapan untuk mencari ketersediaan. Lalai: 14
`people_count`	Bilangan tempat yang diperlukan untuk perkhidmatan berkumpulan
`auto_booking`	Tetapkan kepada `1` untuk membolehkan platform membuat tempahan secara automatik

Parameter ini adalah sama seperti yang digunakan oleh get_dates_for_booking dan get_slots_for_booking.

Apa yang Diterima oleh Aliran Bot

Pemilihan tarikh individu tidak dihantar ke perbualan.

Apabila pelanggan memilih slot masa, atau tarikh jika kalendar tidak mempunyai slot masa, bot menerima panggilan balik widget_calendar_selected dan pemboleh ubah berikut diisi:

Pemboleh Ubah	Nilai
`widget_date`	Tarikh yang dipilih dalam format `DD.MM.YYYY`
`widget_time`	Masa yang dipilih dalam format `HH:MM`; kosong untuk kalendar tarikh sahaja
`widget_message_id`	ID mesej yang mengandungi widget

Kalendar: pemilihan selesai

Format tarikh dan masa adalah sama seperti yang diterima oleh create_booking dan modify_booking_time.

Tempahan Dalam Talian dengan Kalendar: Contoh Lengkap

Widget mengendalikan pemilihan tarikh, slot masa, dan navigasi, mengurangkan bilangan blok bot yang diperlukan.

Blok 1. Pemilihan Perkhidmatan

Gunakan blok Keadaan Mula dengan syarat "tempah janji temu".

Respons: "Pilih perkhidmatan:"

Tetapkan medan butang kepada #{srv_buttons}.

comp_id = 8
srv_data = get_services_for_booking(comp_id)
srv_kb = tools_make_button_str_checker(srv_data, 'title', 1)
srv_buttons = srv_kb['buttons']
srv_checker = srv_kb['checker']

Blok 2. Kalendar

Respons: #{none}.

Sambungkan Blok 1 ke Blok 2 menggunakan syarat #{srv_checker}.

serv_id = tools_check_user_input(srv_data, question, 'title', 'id')
serv_title = tools_check_user_input(srv_data, question, 'title', 'title')
cal = {}
cal["company_id"] = comp_id
cal["service_ids"] = serv_id
cal["days_limit"] = 30
cal["name"] = serv_title
cal_sent = tg_send_widget(platform_id, "calendar", cal, serv_title)

Blok 3. Buat Tempahan

Respons: #{none}.

Sambungkan Blok 2 ke Blok 3 menggunakan syarat widget_calendar_selected dengan Padanan Tepat.

booking_date = widget_date
booking_time = widget_time
booking_result = create_booking(comp_id, serv_id, booking_date, booking_time, '')
booking_ok = booking_result['status']

Blok 4. Tempahan Disahkan

Sambungkan Blok 3 ke Blok 4 menggunakan syarat pemboleh ubah booking_ok == True dengan kelewatan satu saat.

Respons:

Janji temu anda disahkan: #{serv_title}, #{booking_date} pada #{booking_time}. Jumpa lagi!

Blok 5. Slot Masa Tidak Lagi Tersedia

Respons: #{none}.

Sambungkan Blok 3 ke Blok 5 menggunakan syarat pemboleh ubah booking_ok != True dengan kelewatan satu saat.

Blok ini menetapkan semula kalendar sedia ada, membolehkan pelanggan memilih masa lain dan memaparkan mesej ralat.

fix = {}
fix["reset"] = 1
fix["error"] = "Slot masa ini baru sahaja ditempah. Sila pilih yang lain."
t = tg_edit_widget_data(platform_id, widget_message_id, fix)

Tambah satu lagi sambungan dari Blok 5 ke Blok 3 dengan syarat widget_calendar_selected.

Pelanggan kini boleh memilih masa lain dalam kalendar yang sama.

Pilihan Lebih Mudah: Tempahan Automatik

Tambahkan parameter berikut pada tetapan kalendar:

cal["auto_booking"] = 1

Platform akan membuat tempahan serta-merta apabila pelanggan memilih masa.

Jika slot masa yang dipilih menjadi tidak tersedia, widget memaparkan ralat secara langsung.

Panggilan balik widget_calendar_selected dihantar hanya selepas tempahan berjaya, bersama dengan pemboleh ubah widget_booking_id.

Dengan pendekatan ini, Blok 3 dan 5 tidak diperlukan.

Gunakan tempahan melalui aliran bot (pendekatan pertama) jika anda memerlukan prapembayaran atau semakan tersuai sebelum mengesahkan janji temu.

Mengemas Kini Widget yang Dihantar

Gunakan fungsi berikut untuk mengemas kini data widget:

tg_edit_widget_data(platform_id, message_id, data)

Parameter	Penerangan
`message_id`	ID mesej widget, disimpan semasa menghantarnya atau diperoleh daripada `widget_message_id` selepas interaksi
`data`	Kamus yang mengandungi nilai baharu

Hanya data widget yang boleh dikemas kini. Anda tidak boleh menukar susun atur widget yang telah dihantar. Untuk menggunakan susun atur yang berbeza, hantar widget baharu.

Cara kemas kini digunakan:

Kod promo, pemasa, status pesanan, FAQ: data baharu menggantikan sepenuhnya kemas kini sebelumnya. Sebarang medan yang hilang akan kembali kepada nilai asal yang diberikan semasa widget dihantar. Oleh itu, sertakan setiap medan yang sepatutnya berbeza daripada data awal, seperti kedua-dua step dan text.
Kuiz dan kalendar: data baharu digunakan di atas keadaan widget semasa.

Parameter kemas kini khas:

Templat	Data	Hasil
`promo`	`{"used": 1}`	Menandakan kod promo sebagai digunakan
`timer`	`{"seconds": 600}` atau `{"until": "…"}`	Memulakan semula kiraan detik
`calendar`	`{"reset": 1, "error": "mesej"}`	Membersihkan pemilihan, membuka semula kalendar, dan memaparkan mesej

Widget Tersuai

Apabila templat sedia ada tidak mencukupi — contohnya, jika anda memerlukan katalog produk dengan troli beli-belah, penilaian bintang, atau kalkulator harga — anda boleh mencipta widget HTML tersuai.

Widget tersuai: penilaian bintang

Cara Ia Berfungsi

Cipta widget sebagai satu fail HTML yang mengandungi gaya dan JavaScriptnya.
Simpan kod sebagai fail .txt dalam bahagian Fail projek dan salin URL fail. Sistem storan tidak menerima fail .html.
Blok bot menghantar widget menggunakan URL dan menghantar data awalnya.
Apabila pelanggan berinteraksi dengan widget, bot menerima panggilan balik yang mengandungi teks yang ditakrifkan dalam kod widget.
Blok pengendali mengira data baharu dan menghantarnya kembali ke widget, yang mengemas kini antara mukanya sendiri.

tg_send_widget_file(platform_id, url, data, caption)

Contoh:

st = {}
st["rating"] = 0
w = tg_send_widget_file(platform_id, "https://files.mavibot.ai/…/rating.txt", st, "Nilaikan pesanan anda — ketik bintang")

Parameter data ialah kamus yang mengandungi keadaan awal yang digunakan untuk memaparkan widget.

Mengendalikan Interaksi

Apabila pelanggan berinteraksi dengan widget tersuai, bot menerima panggilan balik.

Pemboleh ubah berikut juga diisi:

Pemboleh Ubah	Nilai
`widget_data`	Teks permintaan yang dihantar oleh widget, seperti `rate:4`
`widget_message_id`	ID mesej di mana interaksi berlaku
`widget_query_id`	Pengecam permintaan

Cipta pengendali menggunakan blok Pencetus dan dayakan tetapan Pencetus Hanya pada Panggilan Balik.

Syarat harus sepadan dengan teks permintaan widget.

Jenis blok ini berfungsi tanpa mengira kedudukan semasa pelanggan dalam aliran bot dan tidak mengalihkan mereka dari langkah semasa.

Penting: Jangan gunakan blok Keadaan Mula untuk mengendalikan interaksi widget tersuai. Widget kekal dalam sembang, dan pelanggan boleh berinteraksi dengannya pada bila-bila masa — walaupun semasa melengkapkan soal selidik, menempah janji temu, atau membuat pembayaran. Blok Keadaan Mula akan mengalihkan pelanggan ke pengendali dan mengganggu langkah semasa mereka.

Contoh pengendali penilaian:

Syarat (ungkapan biasa):

^rate:[1-5]$

Kalkulator:

local a = splitter(widget_data, ":")
client.widget_rating = a[1]
st = {}
st["rating"] = client.widget_rating
t = tg_edit_widget_data(platform_id, widget_message_id, st)

Data widget tersuai diganti sepenuhnya semasa kemas kini. Sentiasa hantar keadaan lengkap dan bukannya hanya medan yang berubah.

Had saiz data ialah 1024 bait.

Simpan set data statik yang besar (seperti katalog produk) di dalam kod widget, dan hantar hanya nilai yang berubah melalui data widget.

Secara lalai, widget serta-merta menerima respons kosong, dan data yang dikemas kini tiba melalui kemas kini widget yang berasingan.

Jika widget perlu menerima data secara langsung sebagai respons kepada permintaannya, teks permintaan mesti bermula dengan ?, contohnya:

?price

Dalam kes ini, blok pengendali mesti memanggil fungsi berikut dalam 15 saat:

tg_answer_widget_query(data)

Jika tidak, widget memaparkan ralat tamat masa.

Had saiz respons ialah 1024 bait.

Keperluan Kod

Fail tunggal: sertakan gaya dalam <style> dan JavaScript dalam <script>. Skrip luaran, helaian gaya, fon, dan imej tidak boleh dimuatkan. Imej mesti dibenamkan menggunakan URL data: atau SVG.
Had saiz: maksimum 32 KB sebelum pemampatan dan 4 KB selepas pemampatan.
Tiada medan input: elemen input, select, textarea, dan form dialih keluar. Hanya elemen <button> disokong sebagai kawalan interaktif.
Tiada permintaan rangkaian: fetch dan API serupa tidak berfungsi. Satu-satunya cara untuk berkomunikasi dengan bot ialah melalui TelegramWidget.request("teks"), dengan saiz permintaan 1–64 bait.
Tiada tatal dalaman: ketinggian widget maksimum ialah 600 piksel. Apa-apa yang melebihi itu dipotong. Untuk mencipta karusel, gerakkan baris kad dan bukannya menggunakan tatal.
Akses elemen: gunakan document.getElementById. Mengakses elemen sebagai pemboleh ubah global berdasarkan ID mereka tidak berfungsi.
Tema Telegram: gunakan pemboleh ubah tema Telegram seperti var(--tg-theme-text-color) supaya widget kelihatan betul dalam kedua-dua tema terang dan gelap.
Data widget: baca data daripada TelegramWidget.chatData dan lukis semula widget apabila peristiwa chatDataChanged berlaku.
Permintaan: panggil request secara langsung dalam pengendali interaksi pengguna. Hanya satu permintaan dibenarkan setiap interaksi.

Widget tidak memaparkan ralat pengekodan. Elemen yang tidak disokong dialih keluar secara senyap, dan ralat JavaScript boleh mengakibatkan widget kosong. Sentiasa uji widget dalam Telegram selepas membuat perubahan.

Contoh di bawah memaparkan produk, butang yang menghantar permintaan ke bot, dan kaunter troli berdasarkan data widget.

<style>
body{margin:0;padding:14px}
.h{color:var(--tg-theme-hint-color);font-size:.85em}
button{width:100%;margin-top:8px}
</style>

<b>Margherita · $10</b>
<div class="h" id="c"></div>
<button id="add">Tambah ke troli</button>
<div class="h" id="e"></div>

<script>
var W=window.TelegramWidget,$=function(i){return document.getElementById(i)},busy=0;

function draw(){
  var s={};
  try{s=JSON.parse(W.chatData)||{}}catch(e){}
  $('c').textContent='Dalam troli: '+(s.count||0)
}

$('add').onclick=function(){
  if(busy)return;
  busy=1;
  $('e').textContent='';
  W.request('cart_add').then(
    function(){busy=0},
    function(x){
      busy=0;
      $('e').textContent='Ralat: '+x.code
    }
  )
};

W.onEvent('chatDataChanged',draw);
draw();
</script>

Mavi dan Widget

Mavi boleh mencipta aliran bot yang lengkap dengan widget secara automatik.

Hanya terangkan apa yang anda perlukan dalam bahasa biasa.

Contohnya:

"Apabila pelanggan menghantar 'order', paparkan widget status pesanan dengan tiga peringkat. Apabila mereka menghantar 'ready', gerakkan pesanan ke peringkat kedua."
"Cipta aliran tempahan perkhidmatan: pelanggan memilih perkhidmatan menggunakan butang, kemudian pilih tarikh dan masa menggunakan widget kalendar."
"Cipta widget penilaian bintang untuk pesanan dan simpan penilaian yang dipilih ke pemboleh ubah klien."

Mavi secara automatik mengkonfigurasi templat siap sedia.

Untuk widget tersuai, Mavi menulis dan menyemak kod, menyimpan fail widget ke projek, dan mencipta blok yang diperlukan untuk menghantar widget dan mengendalikan interaksi pelanggan.

Rujukan

Fungsi

Fungsi	Penerangan
`tg_send_widget(platform_id, template, params, caption)`	Menghantar templat widget siap sedia
`tg_send_widget_file(platform_id, url, data, caption)`	Menghantar widget tersuai daripada fail
`tg_edit_widget_data(platform_id, message_id, data)`	Mengemas kini data dalam widget sedia ada
`tg_answer_widget_query(data)`	Membalas permintaan widget tersuai yang bermula dengan `?`

Panggilan Balik dan Pemboleh Ubah

Peristiwa	Panggilan Balik	Pemboleh Ubah
Kuiz selesai	`widget_quiz_finished`	`widget_quiz_score`, `widget_quiz_total`, `widget_quiz_answers`
Tarikh dan masa dipilih dalam kalendar	`widget_calendar_selected`	`widget_date`, `widget_time`; juga `widget_booking_id` apabila `auto_booking` diaktifkan
Interaksi widget tersuai	Teks permintaan yang ditakrifkan dalam kod widget	`widget_data`, `widget_message_id`, `widget_query_id`

Jika bot anda mengandungi pelbagai kuiz atau kalendar, tetapkan panggilan balik unik kepada setiap widget menggunakan parameter callback supaya anda boleh membezakannya dalam syarat aliran bot anda.

Had

Widget hanya berfungsi dalam sembang Telegram peribadi antara pelanggan dan bot.
Hanya lima kuiz dan kalendar terbaru dikekalkan untuk setiap pelanggan. Yang lebih lama berhenti bertindak balas kepada interaksi.
Membersihkan semua pemboleh ubah klien dalam aliran bot melumpuhkan kuiz dan kalendar yang dihantar sebelum ini.
Data widget dihadkan kepada 1024 bait.
Permintaan daripada widget tersuai dihadkan kepada 64 bait.
Permintaan widget tersuai yang memerlukan tg_answer_widget_query mesti dijawab dalam masa 15 saat.

Penyelesaian Masalah

Masalah	Punca / Penyelesaian
Widget tidak dihantar dan pemboleh ubah mengandungi `Unknown parameter…`	Templat menerima parameter yang tidak disokong. Mesej ralat menyenaraikan parameter yang dibenarkan
Kalendar berhenti selepas pemilihan tarikh tanpa menunjukkan slot masa	Parameter `slots` tidak disediakan
Selepas berinteraksi dengan widget, bot berhenti bertindak balas kepada butang dalam langkah semasa	Pengendali interaksi menggunakan blok Syarat Mula. Gantikannya dengan Blok Bukan Keadaan dengan Syarat
Widget tersuai kelihatan kosong	Terdapat ralat dalam kod widget. Punca biasa ialah mengakses elemen dengan IDnya tanpa menggunakan `document.getElementById`
Telegram memaparkan "Unsupported message"	Pelanggan menggunakan versi Telegram yang lapuk
`Bad Request: chat not found`	Widget dihantar di luar Telegram, contohnya dari tetingkap ujian bot

Widget Telegram

Tempat Widget Berfungsi

Templat Siap Sedia

Cara Membina Parameter

Bahasa

Pemasa Kira Detik — `timer`

Status Pesanan — `order_status`

Soalan Lazim — `faq`

Kuiz dan Tinjauan — `quiz`

Apa yang Diterima oleh Aliran Bot

Kalendar — `calendar`

Tarikh dan Masa Tersuai

Tarikh Sahaja

Tempahan Dalam Talian

Apa yang Diterima oleh Aliran Bot

Tempahan Dalam Talian dengan Kalendar: Contoh Lengkap

Pilihan Lebih Mudah: Tempahan Automatik

Mengemas Kini Widget yang Dihantar

Widget Tersuai

Cara Ia Berfungsi

Menghantar Widget Tersuai

Mengendalikan Interaksi

Membalas Permintaan Widget

Keperluan Kod

Contoh Widget Tersuai Minimum

Mavi dan Widget

Rujukan

Fungsi

Panggilan Balik dan Pemboleh Ubah

Had

Penyelesaian Masalah

Widget Telegram

Tempat Widget Berfungsi

Templat Siap Sedia

Cara Membina Parameter

Bahasa

Kod Promo — promo

Pemasa Kira Detik — timer

Status Pesanan — order_status

Soalan Lazim — faq

Kuiz dan Tinjauan — quiz

Apa yang Diterima oleh Aliran Bot

Kalendar — calendar

Tarikh dan Masa Tersuai

Tarikh Sahaja

Tempahan Dalam Talian

Apa yang Diterima oleh Aliran Bot

Tempahan Dalam Talian dengan Kalendar: Contoh Lengkap

Pilihan Lebih Mudah: Tempahan Automatik

Mengemas Kini Widget yang Dihantar

Widget Tersuai

Cara Ia Berfungsi

Menghantar Widget Tersuai

Mengendalikan Interaksi

Membalas Permintaan Widget

Keperluan Kod

Contoh Widget Tersuai Minimum

Mavi dan Widget

Rujukan

Fungsi

Panggilan Balik dan Pemboleh Ubah

Had

Penyelesaian Masalah

Kod Promo — `promo`

Pemasa Kira Detik — `timer`

Status Pesanan — `order_status`

Soalan Lazim — `faq`

Kuiz dan Tinjauan — `quiz`

Kalendar — `calendar`