Виджет — бұл бот хабарламасына тікелей ендірілген интерактивті компонент: көшіру түймесі бар промокод, кері санақ таймері, тапсырыс мәртебесін бақылаушы, викторина немесе күн мен уақытты таңдауға арналған күнтізбе. Тұтынушы виджетпен әрекеттескенде, бот сол хабарламаны орнында жаңартады — жаңа хабарламалар жібермейді немесе «өңделген» белгісін көрсетпейді.

Промокод

Виджетті жіберудің екі жолы бар:

  • Дайын шаблон — Калькулятордағы бір жол. Орналасуы мен функционалдығы әлдеқашан іске асырылған.
  • Теңшелетін виджет — өз HTML кодыңызды жазыңыз (немесе Mavi-ден жасатуды сұраңыз) және бот ағыны блоктары арқылы әрекеттесуді өңдеңіз.

Виджеттер қайда жұмыс істейді
Мессенджер Тек Telegram
Чат түрі Тек тұтынушы мен бот арасындағы жеке чаттар
Қолдау көрсетілмейді Топтар, арналар, Telegram Business
Telegram қолданбасы Telegram-ның жаңартылған нұсқасы қажет. Ескі нұсқалар «Қолдау көрсетілмейтін хабарлама» ескертуін және жазуын көрсетеді
Алға жіберу Виджеттерді алға жіберуге немесе көшіруге болмайды

Виджеттер мәтіндік енгізу өрістерін немесе пернетақталарды қолдамайды. Тұтынушылар тек түрту арқылы әрекеттесе алады. Тұтынушылардың мәтін енгізуі қажет болса, кәдімгі бот сұрағын немесе Web App қолданыңыз.

Виджеттер басқару панеліндегі ботты тексеру терезесінде көрсетілмейді, себебі ол Telegram емес. Виджеттерді тікелей Telegram-да ботыңызға хабарлама жіберу арқылы тексеріңіз.

Дайын шаблондар

Барлық шаблондар бір функция арқылы жіберіледі:

tg_send_widget(platform_id, template, params, caption)
Параметр Сипаттама
platform_id Алушының ID-і. Ағымдағы тұтынушы үшін platform_id айнымалысын пайдаланыңыз
template Шаблон атауы: promo, timer, order_status, faq, quiz, calendar
params Шаблон параметрлерін қамтитын сөздік
caption Виджеттің астында көрсетілетін мәтін. Тұтынушылар оны чат тізімінде, хабарландыруларда және Telegram-ның ескі нұсқаларында да көреді, сондықтан ол өздігінен мағыналы болуы керек

Функция Telegram API жауабын қайтарады. Жіберілген хабарламаның ID-і response['result']['message_id'] мекенжайында қолжетімді. Кейінірек виджетті жаңартуды жоспарласаңыз, оны сақтаңыз.

Егер функция Telegram жауабының орнына мәтінді қайтарса, қате орын алды: белгісіз шаблон, жарамсыз немесе жоқ параметр немесе виджет өлшем шегінен асып кетті. Қате мәтіні не дұрыс емес екенін түсіндіреді.

Параметрлерді қалай құру керек

Сөздік жасаңыз және әр параметрді бөлек жолға тағайындаңыз:

p = {}
p["code"] = "WIDGET10"
p["title"] = "Сіздің промокодыңыз"
p["note"] = "Кез келген тапсырысқа 10% жеңілдік"
w = tg_send_widget(platform_id, "promo", p, "Сіздің промокодыңыз WIDGET10 — 10% жеңілдік")

Кодты блоктың Калькулятор өрісіне енгізіңіз. Скриншотта тұтынушы «order widget» деген сөз тіркесін жібергенде тапсырыс мәртебесі виджетін жіберетін Бастапқы шарт блогы көрсетілген.

Бот құрастырушысындағы виджет

Виджетті жіберетін блокта әдетте жауап өрісін #{none} мәніне орнатасыз. Блок бөлек мәтіндік хабарлама жібермейді, себебі виджеттің жазуы хабарлама мәтіні ретінде қызмет етеді.

Тіл

Шаблондарға кірістірілген интерфейс мәтіні кіреді, мысалы, түйме белгілері, ай және апта күндерінің атаулары, «Уақыт бітті» және басқа хабарламалар.

Mavibot-та әдепкі тіл — ағылшын (en).

Басқа тілді пайдалану үшін lang параметрін көрсетіңіз:

p["lang"] = "kk"

Қолдау көрсетілетін тілдер:

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

Өзіңіз беретін мәтіндер — тақырыптар, сұрақтар, қадамдар және жазулар — дәл енгізілгендей көрсетіледі және автоматты түрде аударылмайды.

Промокод — promo

Бір түртумен көшіретін түймесі бар промокодты көрсетеді.

Промокод

Параметр Сипаттама
code Промокод. Міндетті
title Кодтың үстінде көрсетілетін мәтін
note Кодтың астында көрсетілетін мәтін, мысалы, жарамдылық мерзімі
button Түйме белгісі. Әдепкі: «Промокодты көшіру»
used_text Код пайдаланылған деп белгіленгенде көрсетілетін мәтін 
p = {}
p["code"] = "WIDGET10"
p["title"] = "Сіздің промокодыңыз"
p["note"] = "Кез келген тапсырысқа 10% жеңілдік"
p["button"] = "Кодты көшіру"
w = tg_send_widget(platform_id, "promo", p, "Сіздің промокодыңыз WIDGET10 — 10% жеңілдік")
client.promo_widget_id = w['result']['message_id']

Кодты пайдаланылған деп белгілеу үшін, бұл кодты сызып тастайды және түймені алып тастайды:

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

Кері санақ таймері — timer

Белгіленген күн мен уақытқа дейінгі кері санақты көрсетеді.

Кері санақ тұтынушының құрылғысында жүреді. Бот таймерді жаңартуға қатыспайды.

Кері санақ таймері

Параметр Сипаттама
until Мақсатты күн мен уақыт "DD.MM.YYYY HH:MM" форматында, жобаның уақыт белдеуінде
seconds Немесе виджет жіберілген сәттен бастап секунд саны
title Таймер тақырыбы. Әдепкі: «Ұсыныс аяқталуға»
done Кері санақ аяқталғанда көрсетілетін мәтін
text Кері санақтың астында көрсетілетін мәтін
button, url Түйме белгісі және межелі URL (https:// ғана)
hide_button Кері санақ аяқталғанда түймені жасыру үшін 1 мәніне орнатыңыз

until немесе seconds параметрлерінің бірін беру керек.

p = {}
p["seconds"] = 7200
p["title"] = "Ұсыныс аяқталуға"
p["button"] = "Веб-сайтқа кіру"
p["url"] = "https://salebot.pro"
w = tg_send_widget(platform_id, "timer", p, "Ұсыныс 2 сағаттан кейін аяқталады")

Кері санақ нөлге жеткенде, ботқа ешқандай хабарлама немесе кері шақыру жіберілмейді. Егер бот ұсыныс мерзімі аяқталғанда әрекет жасауы қажет болса, бот ағынында кәдімгі таймер қосылымын пайдаланыңыз.

Тапсырыс мәртебесі — order_status

Ағымдағы кезең бөлектелген тапсырыс кезеңдерінің тізімін көрсетеді.

Бот кезеңді орнында жаңарта алады, сондықтан тұтынушы әрқашан бірдей хабарламаны көреді.

Тапсырыс мәртебесі: бірінші кезең

Параметр Сипаттама
title Виджет тақырыбы
steps Кезеңдер тізімі, 1-ден 12-ге дейін. Әдепкі: қабылданды, дайындалуда, курьерге берілді, жолда, жеткізілді
step Ағымдағы кезең нөмірі, 1-ден бастап
text Кезеңдердің астында көрсетілетін мәтін

Виджетті жіберу:

p = {}
p["title"] = "Тапсырыс мәртебесі"
p["steps"] = ["Қабылданды", "Дайындалуда", "Жеткізілді"]
p["step"] = 1
p["text"] = "Тапсырысыңыз қабылданды және дайындалуда"
w = tg_send_widget(platform_id, "order_status", p, "Сіздің тапсырысыңыз")
client.order_widget_id = w['result']['message_id']

Келесі кезеңге кез келген басқа блоктан өтіңіз, мысалы, мәміле кезеңі өзгергенде, менеджер команда жібергенде немесе таймер іске қосылғанда:

p = {}
p["step"] = 2
p["text"] = "Тапсырысыңыз дайындалуда және жақын арада курьерге беріледі"
t = tg_edit_widget_data(platform_id, client.order_widget_id, p)

Тапсырыс мәртебесі: екінші кезең

Виджеттің астындағы жазу кезең жаңартылғанда өзгермейді. «Мәртебе: Қабылданды» сияқты емес, «Сіздің тапсырысыңыз» сияқты бейтарап жазу қолданыңыз.

Жиі қойылатын сұрақтар — faq

Сұрақтар тізімін көрсетеді. Тұтынушылар жауапты ашу үшін сұрақты түрте алады.

FAQ виджеті

Параметр Сипаттама
title Виджет тақырыбы
items Сұрақ-жауап жұптарының тізімі. Міндетті 
p = {}
p["title"] = "Жиі қойылатын сұрақтар"
p["items"] = [["Қалай төлеуге болады?", "Картамен төлей аласыз. Төлем сілтемесі осы чатқа жіберіледі."], ["Жеткізу қанша уақыт алады?", "Жеткізу әдетте жергілікті жерде 1–2 күн, ал бүкіл ел бойынша 3–7 күн алады."], ["Тауарды қайтаруға бола ма?", "Иә, 14 күн ішінде."]]
w = tg_send_widget(platform_id, "faq", p, "Жиі қойылатын сұрақтарға жауаптар")

Мәтін қарапайым мәтін ретінде көрсетіледі. HTML тегтері және басқа белгілеу өңделмейді.

Викторина және сауалнама — quiz

Бір уақытта бір сұрақты көрсететін, бірнеше жауап нұсқалары бар сұрақтарды көрсетеді.

Егер дұрыс жауаптар көрсетілсе, виджет викторина ретінде жұмыс істейді және ұпай есептейді. Дұрыс жауаптарсыз ол сауалнама ретінде жұмыс істейді.

Викторина сұрағы

Параметр Сипаттама
title Сұрақтардың үстінде көрсетілетін тақырып
questions Сұрақтар тізімі. Міндетті
retry Соңында «Қайталау» түймесін көрсету үшін 1 мәніне орнатыңыз
callback widget_quiz_finished орнына теңшелетін кері шақыру мәтіні

Әр сұрақ келесілерді қамтитын сөздік болып табылады:

  • q — сұрақ мәтіні
  • options — жауап нұсқалары
  • correct — дұрыс жауап, 1-негізделген индексі немесе нақты мәтіні арқылы көрсетіледі
p = {}
p["title"] = "Викторина: Біліміңізді тексеріңіз"
p["retry"] = 1
p["questions"] = [{"q": "2 + 2 нешеге тең?", "options": ["3", "4", "5"], "correct": 2}, {"q": "Францияның астанасы қай қала?", "options": ["Лондон", "Париж", "Берлин"], "correct": "Париж"}]
w = tg_send_widget(platform_id, "quiz", p, "Осы екі сұрақтан тұратын викторинаға қатысыңыз!")

Ұпайсыз сауалнама жасау үшін әр сұрақтан correct параметрін алып тастаңыз.

Дұрыс жауаптар платформа арқылы тексеріледі және тұтынушының құрылғысына жіберілмейді.

Бот ағыны не қабылдайды

Жеке сұрақтарға жауаптар сөйлесуге жіберілмейді.

Тұтынушы соңғы сұраққа жауап бергенде, бот widget_quiz_finished кері шақыруын алады және келесі айнымалылар толтырылады:

Айнымалы Мән
widget_quiz_score Дұрыс жауаптар саны; сауалнамалар үшін бос
widget_quiz_total Сұрақтардың жалпы саны
widget_quiz_answers Таңдалған нұсқалардың индекстері, мысалы, [2,2]

Нәтижені өңдеу үшін викторинаны жіберген блоктан қосылым жасаңыз немесе widget_quiz_finished шарты бар Бастапқы шарт блогын пайдаланыңыз.

Мысал жауап:

Сіздің нәтижеңіз: #{widget_quiz_score} / #{widget_quiz_total} дұрыс жауап

Викторина нәтижесі және бот жауабы

Күнтізбе — calendar

Тұтынушылар күнді, содан кейін уақыт аралығын таңдай алатын айлық күнтізбені көрсетеді.

Ол «Артқа» және «Келесі» навигациясын қоса алғанда, күн мен уақыт түймелерінің бірнеше бетін алмастырады.

Күнтізбе: күн мен уақытты таңдау

Күнтізбе үш режимді қолдайды.

Теңшелетін күндер мен уақыттар

Қолжетімді уақыттар әрқашан slots параметрі арқылы беріледі.

Әр күні бірдей уақыт аралықтары — уақыттар тізімін және күн ауқымын беріңіз:

p = {}
p["title"] = "Күн мен уақытты таңдаңыз"
p["name"] = "Кеңес"
p["days"] = 10
p["slots"] = ["10:00", "12:00", "15:00"]
w = tg_send_widget(platform_id, "calendar", p, "Күн мен уақытты таңдаңыз")

Нақты күндер үшін әртүрлі уақыт аралықтары — күндерді уақыт тізімдеріне салыстыратын сөздік беріңіз. Қолжетімді күндер сөздік кілттерінен алынады:

p = {}
p["slots"] = {"20.11.2026": ["10:00", "12:00"], "21.11.2026": ["15:00"]}
w = tg_send_widget(platform_id, "calendar", p, "Күн мен уақытты таңдаңыз")
Параметр Сипаттама
slots Қолжетімді уақыттар, тізім немесе күн бойынша топталған сөздік ретінде
days Бүгіннен бастап қолжетімді күндер саны
date_from, date_to Немесе `"DD.MM.YYYY"" форматындағы күн ауқымының шекаралары
dates Немесе нақты күндер тізімі
weekdays_off Қолжетімсіз апта күндері: 1 = дүйсенбі, 7 = жексенбі
title Күнтізбе торының астында көрсетілетін кеңес
name Таңдалатын нысанның немесе қызметтің атауы; таңдаудан кейін көрсетіледі
change Таңдаудан кейін «Басқа уақытты таңдау» түймесін көрсету үшін 1 мәніне орнатыңыз
callback widget_calendar_selected орнына теңшелетін кері шақыру мәтіні

Тек қана күн

Егер тұтынушыға тек күнді таңдау қажет болса, slots параметрін бермеңіз.

p = {}
p["days"] = 45
p["weekdays_off"] = [7]
w = tg_send_widget(platform_id, "calendar", p, "Күнді таңдаңыз")

Онлайн брондау

Филиал мен қызметті көрсетіңіз, сонда күнтізбе Қызметтер модулінен қолжетімді күндер мен уақыт ұяшықтарын автоматты түрде алады.

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)
Параметр Сипаттама
company_id Филиал идентификаторы
service_ids Қызмет немесе қызметтер тізімі
employee_id Қызметкер идентификаторы; егер көрсетілмесе, кез келген қолжетімді қызметкер пайдаланылады
days_limit Қолжетімділікті іздеу үшін алдағы күндер саны. Әдепкі: 14
people_count Топтық қызмет үшін қажетті орындар саны
auto_booking Платформа брондауды автоматты түрде жасауы үшін 1 мәнін орнатыңыз

Бұл параметрлер get_dates_for_booking және get_slots_for_booking функцияларында қолданылатындармен бірдей.

Бот ағыны не қабылдайды

Жеке күн таңдаулары сөйлесуге жіберілмейді.

Тұтынушы уақыт ұяшығын немесе күнтізбеде уақыт ұяшықтары болмаса, күнді таңдағанда, бот widget_calendar_selected кері шақыруын алады және келесі айнымалылар толтырылады:

Айнымалы Мән
widget_date DD.MM.YYYY форматындағы таңдалған күн
widget_time HH:MM форматындағы таңдалған уақыт; тек күн ғана бар күнтізбелер үшін бос
widget_message_id Виджеті бар хабарламаның идентификаторы

Күнтізбе: таңдау аяқталды

Күн мен уақыт форматтары create_booking және modify_booking_time функциялары қабылдайтындармен бірдей.

Күнтізбе арқылы онлайн брондау: толық мысал

Виджет күн таңдауды, уақыт ұяшықтарын және навигацияны өңдейді, бұл қажетті бот блоктарының санын азайтады.

1-блок. Қызметті таңдау

"Қызметке жазылу" шартымен Бастапқы шарт блогын пайдаланыңыз.

Жауап: "Қызметті таңдаңыз:"

Түймелер өрісін #{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']

2-блок. Күнтізбе

Жауап: #{none}.

1-блокты 2-блокқа #{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)

3-блок. Брондауды жасау

Жауап: #{none}.

2-блокты 3-блокқа widget_calendar_selected шартымен Дәл сәйкестік режимінде қосыңыз.

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']

4-блок. Брондау расталды

3-блокты 4-блокқа booking_ok == True айнымалы шартымен бір секундтық кідіріспен қосыңыз.

Жауап:

Сіздің жазылуыңыз расталды: #{serv_title}, #{booking_date} сағат #{booking_time}. Кездескенше!

5-блок. Уақыт ұяшығы енді қолжетімсіз

Жауап: #{none}.

3-блокты 5-блокқа booking_ok != True айнымалы шартымен бір секундтық кідіріспен қосыңыз.

Бұл блок бар күнтізбені қалпына келтіреді, бұл тұтынушыға басқа уақытты таңдауға мүмкіндік береді және қате туралы хабарламаны көрсетеді.

fix = {}
fix["reset"] = 1
fix["error"] = "Бұл уақыт ұяшығы жаңа ғана брондалды. Басқасын таңдаңыз."
t = tg_edit_widget_data(platform_id, widget_message_id, fix)

5-блоктан 3-блокқа widget_calendar_selected шартымен тағы бір қосылым қосыңыз.

Тұтынушы енді сол күнтізбеде басқа уақытты таңдай алады.

Қарапайым нұсқа: автоматты брондау

Күнтізбе параметрлеріне келесі параметрді қосыңыз:

cal["auto_booking"] = 1

Платформа тұтынушы уақытты таңдаған кезде брондауды бірден жасайды.

Егер таңдалған уақыт ұяшығы қолжетімсіз болса, виджет қатені тікелей көрсетеді.

widget_calendar_selected кері шақыруы тек сәтті брондаудан кейін, widget_booking_id айнымалысымен бірге жіберіледі.

Бұл тәсілде 3 және 5 блоктар қажет емес.

Егер алдын ала төлем немесе кездесуді растау алдында арнайы тексерулер қажет болса, бот ағыны арқылы брондауды (бірінші тәсіл) пайдаланыңыз.

Жіберілген виджетті жаңарту

Виджет деректерін жаңарту үшін келесі функцияны пайдаланыңыз:

tg_edit_widget_data(platform_id, message_id, data)
Параметр Сипаттама
message_id Виджет хабарламасының идентификаторы, оны жіберу кезінде сақталған немесе өзара әрекеттесуден кейін widget_message_id мәнінен алынған
data Жаңа мәндерді қамтитын сөздік

Тек виджет деректерін жаңартуға болады. Жіберілген виджеттің орналасуын өзгерту мүмкін емес. Басқа орналасуды пайдалану үшін жаңа виджет жіберіңіз.

Жаңартулар қалай қолданылады:

  • Промокод, таймер, тапсырыс мәртебесі, FAQ: жаңа деректер алдыңғы жаңартуды толығымен ауыстырады. Жетіспейтін өрістер виджет жіберілген кезде берілген бастапқы мәндерге оралады. Сондықтан бастапқы деректерден ерекшеленетін әрбір өрісті қосыңыз, мысалы, step және text екеуін де.
  • Викторина және күнтізбе: жаңа деректер виджеттің ағымдағы күйіне қолданылады.

Арнайы жаңарту параметрлері:

Үлгі Деректер Нәтиже
promo {"used": 1} Промокодты пайдаланылған деп белгілейді
timer {"seconds": 600} немесе {"until": "…"} Кері санақты қайта бастайды
calendar {"reset": 1, "error": "message"} Таңдауды тазартады, күнтізбені қайта ашады және хабарламаны көрсетеді

Арнайы виджеттер

Дайын үлгілер жеткіліксіз болғанда — мысалы, сатып алу себеті бар өнім каталогы, жұлдызды бағалау немесе баға калькуляторы қажет болса — арнайы HTML виджетін жасауға болады.

Арнайы виджет: жұлдызды бағалау

Ол қалай жұмыс істейді

  1. Виджетті стильдері мен JavaScript кодын қамтитын бір HTML файлы ретінде жасаңыз.
  2. Кодты жобаның Файлдар бөлімінде .txt файлы ретінде сақтаңыз және файл URL мекенжайын көшіріңіз. Сақтау жүйесі .html файлдарын қабылдамайды.
  3. Бот блогы URL мекенжайын пайдаланып виджетті жібереді және оның бастапқы деректерін береді.
  4. Тұтынушы виджетпен өзара әрекеттескенде, бот виджет кодында анықталған мәтінді қамтитын кері шақыруды алады.
  5. Өңдеуші блок жаңа деректерді есептейді және оны виджетке қайта жібереді, ол өз интерфейсін жаңартады.

Арнайы виджетті жіберу

tg_send_widget_file(platform_id, url, data, caption)

Мысал:

st = {}
st["rating"] = 0
w = tg_send_widget_file(platform_id, "https://files.mavibot.ai/…/rating.txt", st, "Тапсырысыңызды бағалаңыз — жұлдызды түртіңіз")

data параметрі виджетті көрсету үшін пайдаланылатын бастапқы күйді қамтитын сөздік болып табылады.

Өзара әрекеттесулерді өңдеу

Тұтынушы арнайы виджетпен өзара әрекеттескенде, бот кері шақыруды алады.

Келесі айнымалылар да толтырылады:

Айнымалы Мән
widget_data Виджет жіберген сұрау мәтіні, мысалы, rate:4
widget_message_id Өзара әрекеттесу болған хабарламаның идентификаторы
widget_query_id Сұрау идентификаторы

Триггер блогын пайдаланып өңдеушіні жасаңыз және Тек кері шақыруда триггер параметрін қосыңыз.

Шарт виджет сұрау мәтініне сәйкес келуі керек.

Бұл блок түрі тұтынушының бот ағынындағы ағымдағы орнына қарамастан жұмыс істейді және оларды ағымдағы қадамнан алып кетпейді.

Маңызды: Арнайы виджет өзара әрекеттесулерін өңдеу үшін Бастапқы шарт блогын пайдаланбаңыз. Виджет чатта қалады және тұтынушы онымен кез келген уақытта өзара әрекеттесе алады — тіпті сауалнаманы толтыру, кездесуге жазылу немесе төлем жасау кезінде де. Бастапқы шарт блогы тұтынушыны өңдеушіге қайта бағыттайды және олардың ағымдағы қадамын үзеді.

Бағалау өңдеушісінің мысалы:

Шарт (тұрақты өрнек):

^rate:[1-5]$

Калькулятор:

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)

Арнайы виджет деректері жаңарту кезінде толығымен ауыстырылады. Тек өзгерген өрісті емес, әрқашан толық күйді жіберіңіз.

Деректер көлемінің шегі 1024 байт.

Үлкен, статикалық деректер жиынтығын (мысалы, өнім каталогтарын) виджет кодының ішінде сақтаңыз және виджет деректері арқылы тек өзгеретін мәндерді жіберіңіз.

Виджет сұрауына жауап беру

Әдепкі бойынша, виджет бірден бос жауап алады, ал жаңартылған деректер бөлек виджет жаңартуы арқылы келеді.

Егер виджет өз сұрауына тікелей жауап алуы қажет болса, сұрау мәтіні ? белгісінен басталуы керек, мысалы:

?price

Бұл жағдайда өңдеуші блок 15 секунд ішінде келесі функцияны шақыруы керек:

tg_answer_widget_query(data)

Әйтпесе, виджет уақыт аяқталды қатесін көрсетеді.

Жауап көлемінің шегі 1024 байт.

Кодқа қойылатын талаптар

  • Бір файл: стильдерді <style> ішіне, ал JavaScript-ті <script> ішіне қосыңыз. Сыртқы скрипттер, стильдер, қаріптер және суреттер жүктеле алмайды. Суреттер data: URL немесе SVG көмегімен ендірілуі керек.
  • Көлем шектеулері: қысу алдында максимум 32 КБ және қысудан кейін 4 КБ.
  • Енгізу өрістері жоқ: input, select, textarea және form элементтері жойылады. Интерактивті басқару элементтері ретінде тек <button> элементтері қолдау көрсетіледі.
  • Желі сұраулары жоқ: fetch және осыған ұқсас API жұмыс істемейді. Ботпен байланысудың жалғыз жолы — TelegramWidget.request("text"), сұрау көлемі 1–64 байт.
  • Ішкі айналдыру жоқ: виджеттің максималды биіктігі 600 пиксель. Одан жоғары кез келген нәрсе қиылады. Карусель жасау үшін айналдыруды қолданудың орнына карталар қатарын жылжытыңыз.
  • Элементтерге қол жеткізу: document.getElementById пайдаланыңыз. Элементтерге олардың ID негізінде жаһандық айнымалылар ретінде қол жеткізу жұмыс істемейді.
  • Telegram тақырыбы: виджет ашық және қараңғы тақырыптарда дұрыс көрінуі үшін var(--tg-theme-text-color) сияқты Telegram тақырып айнымалыларын пайдаланыңыз.
  • Виджет деректері: деректерді TelegramWidget.chatData мәнінен оқыңыз және chatDataChanged оқиғасы болғанда виджетті қайта сызыңыз.
  • Сұраулар: request функциясын тікелей пайдаланушы өзара әрекеттесу өңдеушісінің ішінде шақырыңыз. Бір өзара әрекеттесуге тек бір сұрауға рұқсат етіледі.

Виджет кодтау қателерін көрсетпейді. Қолдау көрсетілмейтін элементтер үнсіз жойылады, ал JavaScript қатесі бос виджетке әкелуі мүмкін. Өзгерістер енгізгеннен кейін виджетті әрқашан Telegram-да сынап көріңіз.

Ең қарапайым арнайы виджет мысалы

Төмендегі мысал өнімді, ботқа сұрау жіберетін түймені және виджет деректеріне негізделген себет санауышын көрсетеді.

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

<b>Маргарита · $10</b>
<div class="h" id="c"></div>
<button id="add">Себетке қосу</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='Себетте: '+(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='Қате: '+x.code
    }
  )
};

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

Mavi және Виджеттер

Mavi виджеттермен толық бот ағындарын автоматты түрде жасай алады.

Қажет нәрсені қарапайым тілмен сипаттаңыз.

Мысалы:

  • «Тұтынушы 'order' жібергенде, үш кезеңнен тұратын тапсырыс күйі виджетін көрсетіңіз. Олар 'ready' жібергенде, тапсырысты екінші кезеңге жылжытыңыз.»
  • «Қызметті брондау ағынын жасаңыз: тұтынушылар түймелер арқылы қызметті таңдайды, содан кейін күнтізбе виджеті арқылы күн мен уақытты таңдайды.»
  • «Тапсырыстар үшін жұлдызды бағалау виджетін жасаңыз және таңдалған бағаны клиент айнымалысына сақтаңыз.»

Mavi дайын шаблондарды автоматты түрде конфигурациялайды.

Арнайы виджеттер үшін Mavi кодты жазады және тексереді, виджет файлын жобаға сақтайды және виджетті жіберу мен тұтынушы әрекеттерін өңдеу үшін қажетті блоктарды жасайды.

Анықтама

Функциялар

Функция Сипаттама
tg_send_widget(platform_id, template, params, caption) Дайын виджет шаблонын жібереді
tg_send_widget_file(platform_id, url, data, caption) Файлдан арнайы виджет жібереді
tg_edit_widget_data(platform_id, message_id, data) Бар виджеттегі деректерді жаңартады
tg_answer_widget_query(data) ? белгісімен басталатын арнайы виджет сұрауына жауап береді

Қоңыраулар мен Айнымалылар

Оқиға Қоңырау Айнымалылар
Викторина аяқталды widget_quiz_finished widget_quiz_score, widget_quiz_total, widget_quiz_answers
Күнтізбеде күн мен уақыт таңдалды widget_calendar_selected widget_date, widget_time; сонымен қатар auto_booking қосылғанда widget_booking_id
Арнайы виджетпен әрекеттесу Виджет кодында анықталған сұрау мәтіні widget_data, widget_message_id, widget_query_id

Егер ботыңызда бірнеше викторина немесе күнтізбе болса, оларды бот ағынының шарттарында ажырату үшін әр виджетке callback параметрі арқылы бірегей қоңырау тағайындаңыз.

Шектеулер

  • Виджеттер тек тұтынушы мен бот арасындағы жеке Telegram чаттарында жұмыс істейді.
  • Әр тұтынушы үшін тек соңғы бес викторина мен күнтізбе сақталады. Ескілері әрекеттесуді тоқтатады.
  • Бот ағынындағы барлық клиент айнымалыларын тазалау бұрын жіберілген викториналар мен күнтізбелерді өшіреді.
  • Виджет деректері 1024 байтпен шектелген.
  • Арнайы виджеттерден келетін сұраулар 64 байтпен шектелген.
  • tg_answer_widget_query қажет ететін арнайы виджет сұрауларына 15 секунд ішінде жауап беру керек.

Ақаулықтарды жою

Мәселе Себеп / Шешім
Виджет жіберілмеді және айнымалыда Unknown parameter… бар Шаблон қолдау көрсетілмейтін параметр алды. Қате хабары рұқсат етілген параметрлерді тізімдейді
Күнтізбе күн таңдаудан кейін уақыт ұяшықтарын көрсетпей тоқтайды slots параметрі берілмеді
Виджетпен әрекеттесуден кейін бот ағымдағы қадамдағы түймелерге жауап беруді тоқтатады Әрекеттесу өңдеушісі Start Condition блогын пайдаланады. Оны Condition бар Non-State Block-пен ауыстырыңыз
Арнайы виджет бос көрінеді Виджет кодында қате бар. Жиі кездесетін себеп — document.getElementById қолданбай элементке ID арқылы қатынау
Telegram «Unsupported message» көрсетеді Тұтынушы Telegram-ның ескірген нұсқасын пайдаланып жатыр
Bad Request: chat not found Виджет Telegram-нан тыс жерден, мысалы, ботты тексеру терезесінен жіберілді