วิดเจ็ต Telegram

12-11-2026

ในหน้านี้

วิดเจ็ตคือคอมโพเนนต์แบบอินเทอร์แอกทีฟที่ฝังอยู่ในข้อความของบอทโดยตรง: โค้ดโปรโมชันพร้อมปุ่มคัดลอก ตัวจับเวลาถอยหลัง ตัวติดตามสถานะคำสั่งซื้อ แบบทดสอบ หรือปฏิทินสำหรับเลือกวันที่และเวลา เมื่อลูกค้าโต้ตอบกับวิดเจ็ต บอทจะอัปเดตข้อความเดียวกันนั้นในตำแหน่งเดิม โดยไม่ส่งข้อความใหม่หรือแสดงป้าย "แก้ไขแล้ว"

Promo code

มีสองวิธีในการส่งวิดเจ็ต:

เทมเพลตสำเร็จรูป — หนึ่งบรรทัดในเครื่องคิดเลข เค้าโครงและฟังก์ชันการทำงานถูกนำไปใช้แล้ว
วิดเจ็ตแบบกำหนดเอง — เขียนโค้ด HTML ของคุณเอง (หรือขอให้ Mavi สร้างให้) และจัดการการโต้ตอบโดยใช้บล็อกโฟลว์ของบอท

สถานที่ที่วิดเจ็ตทำงาน


เมสเซนเจอร์	Telegram เท่านั้น
ประเภทแชท	แชทส่วนตัวระหว่างลูกค้าและบอทเท่านั้น
ไม่รองรับ	กลุ่ม, ช่อง, Telegram Business
แอป Telegram	ต้องใช้ Telegram เวอร์ชันล่าสุด เวอร์ชันเก่าจะแสดงข้อความ "Unsupported message" และคำบรรยาย
การส่งต่อ	ไม่สามารถส่งต่อหรือคัดลอกวิดเจ็ตได้

วิดเจ็ตไม่รองรับช่องป้อนข้อความหรือคีย์บอร์ด ลูกค้าสามารถโต้ตอบได้โดยการแตะเท่านั้น หากคุณต้องการให้ลูกค้าป้อนข้อความ ให้ใช้คำถามปกติของบอทหรือ 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"] = "Your promo code"
p["note"] = "10% off any order"
w = tg_send_widget(platform_id, "promo", p, "Your promo code WIDGET10 — 10% discount")

ป้อนโค้ดในช่อง Calculator ของบล็อก ภาพหน้าจอแสดงบล็อก Start Condition ที่ส่งวิดเจ็ตสถานะคำสั่งซื้อเมื่อลูกค้าส่งวลี "order widget"

Widget in the bot builder

ในบล็อกที่ส่งวิดเจ็ต คุณมักจะตั้งค่าฟิลด์การตอบสนองเป็น #{none} บล็อกจะไม่ส่งข้อความแยกต่างหาก เนื่องจากคำบรรยายของวิดเจ็ตทำหน้าที่เป็นข้อความของข้อความ

ภาษา

เทมเพลตมีข้อความอินเทอร์เฟซในตัว เช่น ป้ายกำกับปุ่ม ชื่อเดือนและวันในสัปดาห์ "หมดเวลา" และข้อความอื่นๆ

ภาษาที่ใช้โดยค่าเริ่มต้นใน Mavibot คือภาษาอังกฤษ (en)

หากต้องการใช้ภาษาอื่น ให้ระบุพารามิเตอร์ lang:

p["lang"] = "de"

ภาษาที่รองรับ:

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

ข้อความที่คุณระบุเอง — ชื่อเรื่อง คำถาม ขั้นตอน และคำบรรยาย — จะแสดงตามที่ป้อนทุกประการและไม่ได้รับการแปลโดยอัตโนมัติ

โค้ดโปรโมชัน — `promo`

แสดงโค้ดโปรโมชันพร้อมปุ่มที่คัดลอกด้วยการแตะครั้งเดียว

Promo code

พารามิเตอร์	คำอธิบาย
`code`	โค้ดโปรโมชัน จำเป็น
`title`	ข้อความที่แสดงเหนือโค้ด
`note`	ข้อความที่แสดงใต้โค้ด เช่น วันหมดอายุ
`button`	ป้ายกำกับปุ่ม ค่าเริ่มต้น: "Copy promo code"
`used_text`	ข้อความที่แสดงเมื่อโค้ดถูกทำเครื่องหมายว่าใช้แล้ว

p = {}
p["code"] = "WIDGET10"
p["title"] = "Your promo code"
p["note"] = "10% off any order"
p["button"] = "Copy code"
w = tg_send_widget(platform_id, "promo", p, "Your promo code WIDGET10 — 10% discount")
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`

แสดงการนับถอยหลังจนถึงวันที่และเวลาที่ระบุ

การนับถอยหลังทำงานบนอุปกรณ์ของลูกค้า บอทไม่เกี่ยวข้องกับการอัปเดตตัวจับเวลา

Countdown timer

พารามิเตอร์	คำอธิบาย
`until`	วันที่และเวลาเป้าหมายในรูปแบบ `"DD.MM.YYYY HH:MM"` โดยใช้เขตเวลาของโปรเจกต์
`seconds`	อีกทางเลือกหนึ่ง คือจำนวนวินาทีจากช่วงเวลาที่ส่งวิดเจ็ต
`title`	หัวข้อตัวจับเวลา ค่าเริ่มต้น: "Offer ends in"
`done`	ข้อความที่แสดงเมื่อการนับถอยหลังสิ้นสุด
`text`	ข้อความที่แสดงใต้การนับถอยหลัง
`button`, `url`	ป้ายกำกับปุ่มและ URL ปลายทาง (`https://` เท่านั้น)
`hide_button`	ตั้งเป็น `1` เพื่อซ่อนปุ่มเมื่อการนับถอยหลังสิ้นสุด

คุณต้องระบุ until หรือ seconds อย่างใดอย่างหนึ่ง

p = {}
p["seconds"] = 7200
p["title"] = "Offer ends in"
p["button"] = "Visit website"
p["url"] = "https://salebot.pro"
w = tg_send_widget(platform_id, "timer", p, "The offer ends in 2 hours")

เมื่อการนับถอยหลังถึงศูนย์ จะไม่มีการส่งข้อความหรือการเรียกกลับไปยังบอท หากบอทต้องดำเนินการเมื่อข้อเสนอหมดอายุ ให้ใช้การเชื่อมต่อตัวจับเวลาปกติในโฟลว์ของบอท

สถานะคำสั่งซื้อ — `order_status`

แสดงรายการขั้นตอนของคำสั่งซื้อโดยไฮไลต์ขั้นตอนปัจจุบัน

บอทสามารถอัปเดตขั้นตอนในตำแหน่งเดิมได้ ดังนั้นลูกค้าจะเห็นข้อความเดียวกันเสมอ

Order status: first stage

พารามิเตอร์	คำอธิบาย
`title`	ชื่อวิดเจ็ต
`steps`	รายการขั้นตอน ตั้งแต่ 1 ถึง 12 ค่าเริ่มต้น: accepted, preparing, handed to courier, on the way, delivered
`step`	หมายเลขขั้นตอนปัจจุบัน เริ่มจาก 1
`text`	ข้อความที่แสดงใต้ขั้นตอน

การส่งวิดเจ็ต:

p = {}
p["title"] = "Order status"
p["steps"] = ["Accepted", "Preparing", "Delivered"]
p["step"] = 1
p["text"] = "Your order has been accepted and is being prepared"
w = tg_send_widget(platform_id, "order_status", p, "Your order")
client.order_widget_id = w['result']['message_id']

ย้ายไปยังขั้นตอนถัดไปจากบล็อกอื่น เช่น เมื่อขั้นตอนดีลเปลี่ยนแปลง ผู้จัดการส่งคำสั่ง หรือตัวจับเวลาทำงาน:

p = {}
p["step"] = 2
p["text"] = "Your order is being prepared and will be handed to the courier soon"
t = tg_edit_widget_data(platform_id, client.order_widget_id, p)

Order status: second stage

คำบรรยายใต้วิดเจ็ตจะไม่เปลี่ยนแปลงเมื่ออัปเดตขั้นตอน ใช้คำบรรยายที่เป็นกลาง เช่น "Your order" แทน "Status: Accepted"

คำถามที่พบบ่อย — `faq`

แสดงรายการคำถาม ลูกค้าสามารถแตะคำถามเพื่อขยายคำตอบ

FAQ widget

พารามิเตอร์	คำอธิบาย
`title`	ชื่อวิดเจ็ต
`items`	รายการคู่คำถามและคำตอบ จำเป็น

p = {}
p["title"] = "Frequently Asked Questions"
p["items"] = [["How can I pay?", "You can pay by card. A payment link will be sent to this chat."], ["How long does delivery take?", "Delivery usually takes 1–2 days locally and 3–7 days nationwide."], ["Can I return an item?", "Yes, within 14 days."]]
w = tg_send_widget(platform_id, "faq", p, "Answers to frequently asked questions")

ข้อความจะแสดงเป็นข้อความธรรมดา แท็ก HTML และมาร์กอัปอื่นๆ จะไม่ถูกประมวลผล

แบบทดสอบและแบบสำรวจ — `quiz`

แสดงคำถามพร้อมตัวเลือกคำตอบหลายตัวเลือก ทีละคำถาม

หากระบุคำตอบที่ถูกต้อง วิดเจ็ตจะทำหน้าที่เป็นแบบทดสอบและคำนวณคะแนน หากไม่มีคำตอบที่ถูกต้อง วิดเจ็ตจะทำงานเป็นแบบสำรวจ

Quiz question

พารามิเตอร์	คำอธิบาย
`title`	หัวข้อที่แสดงเหนือคำถาม
`questions`	รายการคำถาม จำเป็น
`retry`	ตั้งเป็น `1` เพื่อแสดงปุ่ม "Try again" ที่ส่วนท้าย
`callback`	ข้อความเรียกกลับแบบกำหนดเองแทน `widget_quiz_finished`

แต่ละคำถามเป็นพจนานุกรมที่ประกอบด้วย:

q — ข้อความคำถาม
options — ตัวเลือกคำตอบ
correct — คำตอบที่ถูกต้อง ระบุโดยดัชนีที่เริ่มจาก 1 หรือข้อความที่แน่นอน

p = {}
p["title"] = "Quiz: Test Your Knowledge"
p["retry"] = 1
p["questions"] = [{"q": "What is 2 + 2?", "options": ["3", "4", "5"], "correct": 2}, {"q": "What is the capital of France?", "options": ["London", "Paris", "Berlin"], "correct": "Paris"}]
w = tg_send_widget(platform_id, "quiz", p, "Take this two-question quiz!")

หากต้องการสร้างแบบสำรวจโดยไม่มีการให้คะแนน ให้ละเว้น correct ในทุกคำถาม

คำตอบที่ถูกต้องจะถูกตรวจสอบโดยแพลตฟอร์มและจะไม่ถูกส่งไปยังอุปกรณ์ของลูกค้า

สิ่งที่โฟลว์ของบอทได้รับ

คำตอบของแต่ละคำถามจะไม่ถูกส่งไปยังการสนทนา

เมื่อลูกค้าตอบคำถามสุดท้าย บอทจะได้รับการเรียกกลับ widget_quiz_finished และตัวแปรต่อไปนี้จะถูกเติม:

ตัวแปร	ค่า
`widget_quiz_score`	จำนวนคำตอบที่ถูกต้อง; ว่างเปล่าสำหรับแบบสำรวจ
`widget_quiz_total`	จำนวนคำถามทั้งหมด
`widget_quiz_answers`	ดัชนีของตัวเลือกที่เลือก เช่น `[2,2]`

ในการประมวลผลผลลัพธ์ ให้สร้างการเชื่อมต่อจากบล็อกที่ส่งแบบทดสอบหรือใช้บล็อก Start Condition ที่มีเงื่อนไข widget_quiz_finished

ตัวอย่างการตอบสนอง:

Your result: #{widget_quiz_score} out of #{widget_quiz_total} correct answers

Quiz result and bot response

ปฏิทิน — `calendar`

แสดงปฏิทินรายเดือนที่ลูกค้าสามารถเลือกวันที่แล้วเลือกช่วงเวลา

แทนที่หลายหน้าของปุ่มวันที่และเวลา รวมถึงการนำทาง "Back" และ "Next"

Calendar: selecting date and time

ปฏิทินรองรับสามโหมด

วันที่และเวลาที่กำหนดเอง

เวลาที่ว่างจะถูกส่งผ่านพารามิเตอร์ slots เสมอ

ช่วงเวลาเดียวกันทุกวัน — ระบุรายการเวลาและช่วงวันที่:

p = {}
p["title"] = "Select a date and time"
p["name"] = "Consultation"
p["days"] = 10
p["slots"] = ["10:00", "12:00", "15:00"]
w = tg_send_widget(platform_id, "calendar", p, "Choose a date and time")

ช่วงเวลาที่แตกต่างกันสำหรับวันที่เฉพาะ — ระบุพจนานุกรมที่แมปวันที่กับรายการเวลา วันที่ว่างจะถูกนำมาจากคีย์ของพจนานุกรม:

p = {}
p["slots"] = {"20.11.2026": ["10:00", "12:00"], "21.11.2026": ["15:00"]}
w = tg_send_widget(platform_id, "calendar", p, "Choose a date and time")

พารามิเตอร์	คำอธิบาย
`slots`	เวลาที่ว่าง เป็นรายการหรือพจนานุกรมที่จัดกลุ่มตามวันที่
`days`	จำนวนวันที่ว่างเริ่มจากวันนี้
`date_from`, `date_to`	อีกทางเลือกหนึ่ง คือขอบเขตช่วงวันที่ในรูปแบบ `"DD.MM.YYYY"`
`dates`	อีกทางเลือกหนึ่ง คือรายการวันที่เฉพาะ
`weekdays_off`	วันในสัปดาห์ที่ไม่ว่าง: 1 = วันจันทร์ ถึง 7 = วันอาทิตย์
`title`	คำแนะนำที่แสดงใต้ตารางปฏิทิน
`name`	ชื่อของรายการหรือบริการที่จอง; แสดงหลังการเลือก
`change`	ตั้งเป็น `1` เพื่อแสดงปุ่ม "Choose another time" หลังการเลือก
`callback`	ข้อความเรียกกลับแบบกำหนดเองแทน `widget_calendar_selected`

เลือกเฉพาะวันที่

ไม่ต้องส่ง slots หากลูกค้าต้องการเลือกเพียงวันที่เท่านั้น

p = {}
p["days"] = 45
p["weekdays_off"] = [7]
w = tg_send_widget(platform_id, "calendar", p, "Choose a date")

การจองออนไลน์

ระบุสาขาและบริการ ปฏิทินจะดึงวันที่และช่วงเวลาที่ว่างจากโมดูล Services โดยอัตโนมัติ

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

สิ่งที่ Bot Flow ได้รับ

การเลือกวันที่แต่ละครั้งจะไม่ถูกส่งไปยังบทสนทนา

เมื่อลูกค้าเลือกช่วงเวลา หรือเลือกวันที่หากปฏิทินไม่มีช่วงเวลา บอทจะได้รับ callback widget_calendar_selected และตัวแปรต่อไปนี้จะถูกเติมค่า:

ตัวแปร	ค่า
`widget_date`	วันที่เลือกในรูปแบบ `DD.MM.YYYY`
`widget_time`	เวลาที่เลือกในรูปแบบ `HH:MM`; ว่างเปล่าสำหรับปฏิทินที่เลือกเฉพาะวันที่
`widget_message_id`	ID ของข้อความที่มีวิดเจ็ต

ปฏิทิน: การเลือกเสร็จสมบูรณ์

รูปแบบวันที่และเวลาเหมือนกับที่ create_booking และ modify_booking_time ยอมรับ

การจองออนไลน์ด้วยปฏิทิน: ตัวอย่างที่สมบูรณ์

วิดเจ็ตจัดการการเลือกวันที่ ช่วงเวลา และการนำทาง ซึ่งช่วยลดจำนวนบล็อกที่ต้องใช้ในบอท

บล็อก 1. การเลือกบริการ

ใช้บล็อก Start Condition โดยมีเงื่อนไขว่า "จองนัดหมาย"

การตอบกลับ: "เลือกบริการ:"

ตั้งค่าฟิลด์ปุ่มเป็น #{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 ด้วย Exact match

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 โดยหน่วงเวลา 1 วินาที

การตอบกลับ:

Your appointment is confirmed: #{serv_title}, #{booking_date} at #{booking_time}. See you soon!

บล็อก 5. ช่วงเวลาไม่ว่างแล้ว

การตอบกลับ: #{none}

เชื่อมต่อบล็อก 3 กับบล็อก 5 โดยใช้เงื่อนไขตัวแปร booking_ok != True โดยหน่วงเวลา 1 วินาที

บล็อกนี้จะรีเซ็ตปฏิทินที่มีอยู่ เพื่อให้ลูกค้าสามารถเลือกเวลาอื่นและแสดงข้อความแสดงข้อผิดพลาด

fix = {}
fix["reset"] = 1
fix["error"] = "This time slot has just been booked. Please choose another one."
t = tg_edit_widget_data(platform_id, widget_message_id, fix)

เพิ่มการเชื่อมต่ออีกครั้งจากบล็อก 5 ไปยังบล็อก 3 ด้วยเงื่อนไข widget_calendar_selected

ตอนนี้ลูกค้าสามารถเลือกเวลาอื่นในปฏิทินเดียวกันได้

ตัวเลือกที่ง่ายกว่า: การจองอัตโนมัติ

เพิ่มพารามิเตอร์ต่อไปนี้ในการตั้งค่าปฏิทิน:

cal["auto_booking"] = 1

แพลตฟอร์มจะสร้างการจองทันทีเมื่อลูกค้าเลือกเวลา

หากช่วงเวลาที่เลือกไม่ว่าง วิดเจ็ตจะแสดงข้อผิดพลาดโดยตรง

callback widget_calendar_selected จะถูกส่งหลังจากจองสำเร็จเท่านั้น พร้อมกับตัวแปร widget_booking_id

ด้วยวิธีนี้ ไม่จำเป็นต้องใช้บล็อก 3 และ 5

ใช้การจองผ่าน bot flow (วิธีแรก) หากคุณต้องการชำระเงินล่วงหน้าหรือตรวจสอบแบบกำหนดเองก่อนยืนยันการนัดหมาย

การอัปเดตวิดเจ็ตที่ส่งไปแล้ว

ใช้ฟังก์ชันต่อไปนี้เพื่ออัปเดตข้อมูลวิดเจ็ต:

tg_edit_widget_data(platform_id, message_id, data)

พารามิเตอร์	คำอธิบาย
`message_id`	ID ของข้อความวิดเจ็ต ซึ่งบันทึกไว้เมื่อส่งหรือได้รับจาก `widget_message_id` หลังจากการโต้ตอบ
`data`	พจนานุกรมที่มีค่าใหม่

สามารถอัปเดตได้เฉพาะข้อมูลวิดเจ็ตเท่านั้น คุณไม่สามารถเปลี่ยนเลย์เอาต์ของวิดเจ็ตที่ส่งไปแล้วได้ หากต้องการใช้เลย์เอาต์อื่น ให้ส่งวิดเจ็ตใหม่

วิธีการใช้การอัปเดต:

รหัสโปรโมชัน ตัวจับเวลา สถานะคำสั่งซื้อ คำถามที่พบบ่อย: ข้อมูลใหม่จะแทนที่การอัปเดตก่อนหน้าทั้งหมด ฟิลด์ที่ขาดหายไปจะกลับไปใช้ค่าเดิมที่ระบุเมื่อส่งวิดเจ็ต ดังนั้น ให้รวมทุกฟิลด์ที่ควรแตกต่างจากข้อมูลเริ่มต้น เช่น ทั้ง step และ text
แบบทดสอบและปฏิทิน: ข้อมูลใหม่จะถูกนำไปใช้กับสถานะปัจจุบันของวิดเจ็ต

พารามิเตอร์การอัปเดตพิเศษ:

เทมเพลต	ข้อมูล	ผลลัพธ์
`promo`	`{"used": 1}`	ทำเครื่องหมายรหัสโปรโมชันว่าใช้แล้ว
`timer`	`{"seconds": 600}` หรือ `{"until": "…"}`	รีสตาร์ทการนับถอยหลัง
`calendar`	`{"reset": 1, "error": "message"}`	ล้างการเลือก เปิดปฏิทินใหม่ และแสดงข้อความ

วิดเจ็ตแบบกำหนดเอง

เมื่อเทมเพลตสำเร็จรูปไม่เพียงพอ เช่น หากคุณต้องการแคตตาล็อกสินค้าพร้อมตะกร้าสินค้า การให้คะแนนแบบดาว หรือเครื่องคำนวณราคา คุณสามารถสร้างวิดเจ็ต HTML แบบกำหนดเองได้

วิดเจ็ตแบบกำหนดเอง: การให้คะแนนแบบดาว

วิธีการทำงาน

สร้างวิดเจ็ตเป็นไฟล์ HTML ไฟล์เดียวที่มีสไตล์และ JavaScript
บันทึกโค้ดเป็นไฟล์ .txt ในส่วน Files ของโปรเจกต์และคัดลอก URL ของไฟล์ ระบบจัดเก็บข้อมูลไม่ยอมรับไฟล์ .html
บล็อกบอทส่งวิดเจ็ตโดยใช้ URL และส่งข้อมูลเริ่มต้น
เมื่อลูกค้าโต้ตอบกับวิดเจ็ต บอทจะได้รับ callback ที่มีข้อความที่กำหนดในโค้ดวิดเจ็ต
บล็อกตัวจัดการคำนวณข้อมูลใหม่และส่งกลับไปยังวิดเจ็ต ซึ่งจะอัปเดตอินเทอร์เฟซของตัวเอง

การส่งวิดเจ็ตแบบกำหนดเอง

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, "Rate your order — tap a star")

พารามิเตอร์ data เป็นพจนานุกรมที่มีสถานะเริ่มต้นที่ใช้ในการเรนเดอร์วิดเจ็ต

การจัดการการโต้ตอบ

เมื่อลูกค้าโต้ตอบกับวิดเจ็ตแบบกำหนดเอง บอทจะได้รับ callback

ตัวแปรต่อไปนี้จะถูกเติมค่า:

ตัวแปร	ค่า
`widget_data`	ข้อความคำขอที่ส่งโดยวิดเจ็ต เช่น `rate:4`
`widget_message_id`	ID ของข้อความที่เกิดการโต้ตอบ
`widget_query_id`	ตัวระบุคำขอ

สร้างตัวจัดการโดยใช้บล็อก Trigger และเปิดใช้งานการตั้งค่า Trigger only on Callback

เงื่อนไขควรตรงกับข้อความคำขอของวิดเจ็ต

บล็อกประเภทนี้ทำงานโดยไม่คำนึงถึงตำแหน่งปัจจุบันของลูกค้าใน bot flow และไม่ทำให้พวกเขาออกจากขั้นตอนปัจจุบัน

สำคัญ: อย่าใช้บล็อก Start Condition เพื่อจัดการการโต้ตอบของวิดเจ็ตแบบกำหนดเอง วิดเจ็ตยังคงอยู่ในแชท และลูกค้าสามารถโต้ตอบได้ตลอดเวลา แม้ในขณะที่กรอกแบบสอบถาม จองนัดหมาย หรือชำระเงิน บล็อก Start Condition จะเปลี่ยนเส้นทางลูกค้าไปยังตัวจัดการและขัดจังหวะขั้นตอนปัจจุบันของพวกเขา

ตัวอย่างตัวจัดการการให้คะแนน:

เงื่อนไข (นิพจน์ทั่วไป):

^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> ไม่สามารถโหลดสคริปต์ภายนอก สไตล์ชีต ฟอนต์ และรูปภาพได้ รูปภาพต้องฝังโดยใช้ URL data: หรือ SVG
ขีดจำกัดขนาด: สูงสุด 32 KB ก่อนบีบอัดและ 4 KB หลังบีบอัด
ไม่มีฟิลด์อินพุต: องค์ประกอบ input, select, textarea และ form จะถูกลบออก รองรับเฉพาะองค์ประกอบ <button> เป็นตัวควบคุมแบบโต้ตอบ
ไม่มีคำขอเครือข่าย: fetch และ API ที่คล้ายกันไม่ทำงาน วิธีเดียวในการสื่อสารกับบอทคือผ่าน TelegramWidget.request("text") โดยมีขนาดคำขอ 1–64 ไบต์
ไม่มีการเลื่อนภายใน: ความสูงสูงสุดของวิดเจ็ตคือ 600 พิกเซล สิ่งที่เกินกว่านั้นจะถูกตัดออก หากต้องการสร้างแถบเลื่อน ให้เลื่อนแถวของการ์ดแทนการใช้การเลื่อน
การเข้าถึงองค์ประกอบ: ใช้ document.getElementById การเข้าถึงองค์ประกอบเป็นตัวแปรทั่วโลกตาม ID ไม่ทำงาน
ธีม Telegram: ใช้ตัวแปรธีม Telegram เช่น var(--tg-theme-text-color) เพื่อให้วิดเจ็ตดูถูกต้องทั้งในธีมสว่างและธีมมืด
ข้อมูลวิดเจ็ต: อ่านข้อมูลจาก 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>Margherita · $10</b>
<div class="h" id="c"></div>
<button id="add">Add to cart</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='In cart: '+(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='Error: '+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`; รวมถึง `widget_booking_id` เมื่อเปิดใช้งาน `auto_booking`
การโต้ตอบกับวิดเจ็ตที่กำหนดเอง	ข้อความคำขอที่กำหนดในโค้ดวิดเจ็ต	`widget_data`, `widget_message_id`, `widget_query_id`

หากบอทของคุณมีแบบทดสอบหรือปฏิทินหลายรายการ ให้กำหนดคอลแบ็กที่ไม่ซ้ำกันให้กับแต่ละวิดเจ็ตโดยใช้พารามิเตอร์ callback เพื่อให้คุณสามารถแยกแยะได้ในเงื่อนไขโฟลว์บอทของคุณ

ข้อจำกัด

วิดเจ็ตทำงานเฉพาะในแชท Telegram ส่วนตัวระหว่างลูกค้าและบอทเท่านั้น
ระบบจะเก็บเฉพาะแบบทดสอบและปฏิทินห้ารายการล่าสุดสำหรับลูกค้าแต่ละรายเท่านั้น รายการที่เก่ากว่าจะหยุดตอบสนองต่อการโต้ตอบ
การล้างตัวแปรลูกค้าทั้งหมดในโฟลว์บอทจะปิดใช้งานแบบทดสอบและปฏิทินที่ส่งไปก่อนหน้านี้
ข้อมูลวิดเจ็ตจำกัดที่ 1024 ไบต์
คำขอจากวิดเจ็ตที่กำหนดเองจำกัดที่ 64 ไบต์
คำขอวิดเจ็ตที่กำหนดเองที่ต้องใช้ tg_answer_widget_query ต้องตอบภายใน 15 วินาที

การแก้ไขปัญหา

ปัญหา	สาเหตุ / วิธีแก้ไข
ไม่ส่งวิดเจ็ตและตัวแปรมีข้อความ `Unknown parameter…`	เทมเพลตได้รับพารามิเตอร์ที่ไม่รองรับ ข้อความแสดงข้อผิดพลาดจะแสดงรายการพารามิเตอร์ที่อนุญาต
ปฏิทินหยุดหลังจากการเลือกวันที่โดยไม่แสดงช่วงเวลา	ไม่ได้ระบุพารามิเตอร์ `slots`
หลังจากการโต้ตอบกับวิดเจ็ต บอทหยุดตอบสนองต่อปุ่มในขั้นตอนปัจจุบัน	ตัวจัดการการโต้ตอบใช้บล็อก Start Condition แทนที่ด้วยบล็อก Non-State Block ที่มี Condition
วิดเจ็ตที่กำหนดเองปรากฏว่างเปล่า	มีข้อผิดพลาดในโค้ดวิดเจ็ต สาเหตุทั่วไปคือการเข้าถึงองค์ประกอบด้วย ID โดยไม่ใช้ `document.getElementById`
Telegram แสดง "Unsupported message"	ลูกค้ากำลังใช้ Telegram เวอร์ชันเก่า
`Bad Request: chat not found`	ส่งวิดเจ็ตนอก Telegram เช่น จากหน้าต่างทดสอบบอท

วิดเจ็ต Telegram

สถานที่ที่วิดเจ็ตทำงาน

เทมเพลตสำเร็จรูป

วิธีสร้างพารามิเตอร์

ภาษา

โค้ดโปรโมชัน — promo

ตัวจับเวลาถอยหลัง — timer

สถานะคำสั่งซื้อ — order_status

คำถามที่พบบ่อย — faq

แบบทดสอบและแบบสำรวจ — quiz

สิ่งที่โฟลว์ของบอทได้รับ

ปฏิทิน — calendar

วันที่และเวลาที่กำหนดเอง

เลือกเฉพาะวันที่

การจองออนไลน์

สิ่งที่ Bot Flow ได้รับ

การจองออนไลน์ด้วยปฏิทิน: ตัวอย่างที่สมบูรณ์

ตัวเลือกที่ง่ายกว่า: การจองอัตโนมัติ

การอัปเดตวิดเจ็ตที่ส่งไปแล้ว

วิดเจ็ตแบบกำหนดเอง

วิธีการทำงาน

การส่งวิดเจ็ตแบบกำหนดเอง

การจัดการการโต้ตอบ

การตอบสนองต่อคำขอของวิดเจ็ต

ข้อกำหนดของโค้ด

ตัวอย่างวิดเจ็ตแบบกำหนดเองขั้นต่ำ

Mavi และวิดเจ็ต

เอกสารอ้างอิง

ฟังก์ชัน

คอลแบ็กและตัวแปร

ข้อจำกัด

การแก้ไขปัญหา

โค้ดโปรโมชัน — `promo`

ตัวจับเวลาถอยหลัง — `timer`

สถานะคำสั่งซื้อ — `order_status`

คำถามที่พบบ่อย — `faq`

แบบทดสอบและแบบสำรวจ — `quiz`

ปฏิทิน — `calendar`