الويدجت (Widget) هو مكوّن تفاعلي مضمّن مباشرة في رسالة البوت: رمز ترويجي مع زر نسخ، مؤقّت تنازلي، متتبّع حالة الطلب، اختبار، أو تقويم لاختيار التاريخ والوقت. عندما يتفاعل العميل مع الويدجت، يقوم البوت بتحديث نفس الرسالة في مكانها — دون إرسال رسائل جديدة أو عرض علامة "تم التعديل".
هناك طريقتان لإرسال الويدجت:
- قالب جاهز — سطر واحد في الحاسبة. التخطيط والوظائف منفّذة بالفعل.
- ويدجت مخصص — اكتب كود HTML الخاص بك (أو اطلب من Mavi إنشاءه) وعالج التفاعلات باستخدام كتل تدفق البوت.
أين تعمل الويدجتات
| المراسل | تيليجرام فقط |
| نوع الدردشة | المحادثات الخاصة بين العميل والبوت فقط |
| غير مدعوم | المجموعات، القنوات، تيليجرام بيزنس |
| تطبيق تيليجرام | يتطلب إصدارًا حديثًا من تيليجرام. الإصدارات الأقدم تعرض إشعار "رسالة غير مدعومة" والنص التوضيحي |
| إعادة التوجيه | لا يمكن إعادة توجيه الويدجتات أو نسخها |
لا تدعم الويدجتات حقول إدخال النص أو لوحات المفاتيح. يمكن للعملاء التفاعل فقط عن طريق النقر. إذا كنت بحاجة إلى أن يقوم العملاء بإدخال نص، استخدم سؤال بوت عادي أو تطبيق ويب.
لا يتم عرض الويدجتات في نافذة اختبار البوت في لوحة التحكم لأنها ليست تيليجرام. اختبر الويدجتات مباشرة في تيليجرام عن طريق مراسلة البوت الخاص بك.
القوالب الجاهزة
يتم إرسال جميع القوالب باستخدام دالة واحدة:
tg_send_widget(platform_id, template, params, caption)
| المعامل | الوصف |
|---|---|
platform_id |
معرف المستلم. للعميل الحالي، استخدم متغير platform_id
|
template |
اسم القالب: promo, timer, order_status, faq, quiz, calendar
|
params |
قاموس يحتوي على إعدادات القالب |
caption |
النص المعروض أسفل الويدجت. يراه العملاء أيضًا في قائمة الدردشات والإشعارات وإصدارات تيليجرام الأقدم، لذا يجب أن يكون ذا معنى بحد ذاته |
تُرجع الدالة استجابة واجهة برمجة تطبيقات تيليجرام. معرف الرسالة المرسلة متاح في response['result']['message_id']. احفظه إذا كنت تخطط لتحديث الويدجت لاحقًا.
إذا أعادت الدالة نصًا بدلاً من استجابة تيليجرام، فقد حدث خطأ: قالب غير معروف، معامل غير صالح أو مفقود، أو ويدجت يتجاوز حد الحجم. يشرح نص الخطأ ما حدث.
كيفية بناء المعاملات
أنشئ قاموسًا وخصص كل معامل في سطر منفصل:
p = {}
p["code"] = "WIDGET10"
p["title"] = "رمزك الترويجي"
p["note"] = "خصم 10% على أي طلب"
w = tg_send_widget(platform_id, "promo", p, "رمزك الترويجي WIDGET10 — خصم 10%")
أدخل الكود في حقل الحاسبة في الكتلة. تُظهر لقطة الشاشة كتلة شرط البدء التي ترسل ويدجت حالة الطلب عندما يرسل العميل عبارة "ويدجت الطلب".
في الكتلة التي ترسل الويدجت، عادةً ما تضبط حقل الاستجابة على #{none}. لا ترسل الكتلة رسالة نصية منفصلة لأن نص الويدجت يعمل كنص الرسالة.
اللغة
تتضمن القوالب نص واجهة مدمج، مثل تسميات الأزرار، وأسماء الأشهر وأيام الأسبوع، و"انتهى الوقت"، ورسائل أخرى.
اللغة الافتراضية في Mavibot هي الإنجليزية (en).
لاستخدام لغة أخرى، حدد معامل lang:
p["lang"] = "de"
اللغات المدعومة:
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, "ينتهي العرض خلال ساعتين")
عندما يصل العدّاد إلى الصفر، لا يتم إرسال أي رسالة أو رد اتصال إلى البوت. إذا كان البوت بحاجة إلى تنفيذ إجراء عند انتهاء العرض، استخدم اتصال مؤقّت عادي في تدفق البوت.
حالة الطلب — 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
يعرض قائمة بالأسئلة. يمكن للعملاء النقر على سؤال لتوسيع إجابته.
| المعامل | الوصف |
|---|---|
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 |
قاموس يحتوي على القيم الجديدة |
يمكن تحديث بيانات الأداة فقط. لا يمكنك تغيير تخطيط أداة مرسلة بالفعل. لاستخدام تخطيط مختلف، أرسل أداة جديدة.
كيف يتم تطبيق التحديثات:
-
رمز الخصم، المؤقت، حالة الطلب، الأسئلة الشائعة: البيانات الجديدة تحل محل التحديث السابق تمامًا. أي حقول مفقودة تعود إلى القيم الأصلية المقدمة عند إرسال الأداة. لذلك، قم بتضمين كل حقل يجب أن يختلف عن البيانات الأولية، مثل كل من
stepوtext. - الاختبار والتقويم: يتم تطبيق البيانات الجديدة فوق حالة الأداة الحالية.
معاملات التحديث الخاصة:
| القالب | البيانات | النتيجة |
|---|---|---|
promo |
{"used": 1} |
يحدد رمز الخصم كمستخدم |
timer |
{"seconds": 600} أو {"until": "…"}
|
يعيد تشغيل العد التنازلي |
calendar |
{"reset": 1, "error": "message"} |
يمسح التحديد، ويعيد فتح التقويم، ويعرض رسالة |
الأدوات المخصصة
عندما لا تكون القوالب الجاهزة كافية — على سبيل المثال، إذا كنت بحاجة إلى كتالوج منتجات مع سلة تسوق، أو تقييم بالنجوم، أو حاسبة أسعار — يمكنك إنشاء أداة HTML مخصصة.
كيف تعمل
- أنشئ أداة كملف HTML واحد يحتوي على أنماطه وجافا سكريبت.
- احفظ الكود كملف
.txtفي قسم الملفات بالمشروع وانسخ رابط الملف. لا يقبل نظام التخزين ملفات.html. - ترسل كتلة بوت الأداة باستخدام الرابط وتمرر بياناتها الأولية.
- عندما يتفاعل العميل مع الأداة، يستقبل البوت رد اتصال يحتوي على النص المحدد في كود الأداة.
- تحسب كتلة المعالج البيانات الجديدة وترسلها مرة أخرى إلى الأداة، التي تقوم بتحديث واجهتها الخاصة.
إرسال أداة مخصصة
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>وجافا سكريبت داخل<script>. لا يمكن تحميل البرامج النصية أو أوراق الأنماط أو الخطوط أو الصور الخارجية. يجب تضمين الصور باستخدام عناوينdata:أو SVG. - حدود الحجم: بحد أقصى 32 كيلوبايت قبل الضغط و4 كيلوبايت بعد الضغط.
-
لا حقول إدخال: تتم إزالة عناصر
inputوselectوtextareaوform. يتم دعم عناصر<button>فقط كعناصر تحكم تفاعلية. -
لا طلبات شبكة: لا تعمل
fetchوواجهات برمجة تطبيقات مماثلة. الطريقة الوحيدة للتواصل مع البوت هي عبرTelegramWidget.request("text")، بحجم طلب يتراوح بين 1-64 بايت. - لا تمرير داخلي: الحد الأقصى لارتفاع الأداة هو 600 بكسل. أي شيء يتجاوز ذلك يتم قصه. لإنشاء دائري، حرك صفًا من البطاقات بدلاً من استخدام التمرير.
-
الوصول إلى العناصر: استخدم
document.getElementById. الوصول إلى العناصر كمتغيرات عامة بناءً على معرفاتها لا يعمل. -
سمة Telegram: استخدم متغيرات سمة Telegram مثل
var(--tg-theme-text-color)بحيث تبدو الأداة صحيحة في كل من السمة الفاتحة والداكنة. -
بيانات الأداة: اقرأ البيانات من
TelegramWidget.chatDataوأعد رسم الأداة عند حدوث حدثchatDataChanged. -
الطلبات: استدعِ
requestمباشرة داخل معالج تفاعل المستخدم. يُسمح بطلب واحد فقط لكل تفاعل.
لا تعرض الأداة أخطاء الترميز. تتم إزالة العناصر غير المدعومة بصمت، وقد يؤدي خطأ جافا سكريبت إلى أداة فارغة. اختبر الأداة دائمًا في 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 والأدوات (Widgets)
يمكن لـ 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 لتمييزها في شروط تدفق البوت.
القيود
- تعمل الأدوات فقط في المحادثات الخاصة على تيليجرام بين العميل والبوت.
- يتم الاحتفاظ فقط بأحدث خمسة اختبارات وتقاويم لكل عميل. الأقدم منها يتوقف عن الاستجابة للتفاعلات.
- مسح جميع متغيرات العميل في تدفق البوت يعطل الاختبارات والتقاويم المرسلة سابقًا.
- بيانات الأداة محدودة بـ 1024 بايت.
- طلبات الأدوات المخصصة محدودة بـ 64 بايت.
- يجب الرد على طلبات الأدوات المخصصة التي تتطلب
tg_answer_widget_queryخلال 15 ثانية.
استكشاف الأخطاء وإصلاحها
| المشكلة | السبب / الحل |
|---|---|
الأداة لا تُرسل والمتغير يحتوي على Unknown parameter…
|
تلقى القالب معاملًا غير مدعوم. رسالة الخطأ تسرد المعاملات المسموح بها |
| يتوقف التقويم بعد تحديد التاريخ دون عرض الفترات الزمنية | لم يتم توفير معامل slots
|
| بعد التفاعل مع أداة، يتوقف البوت عن الاستجابة للأزرار في الخطوة الحالية | يستخدم معالج التفاعل كتلة شرط البدء. استبدلها بكتلة غير حالة مع شرط |
| تظهر الأداة المخصصة فارغة | يوجد خطأ في كود الأداة. سبب شائع هو الوصول إلى عنصر بواسطة معرفه دون استخدام document.getElementById
|
| يعرض تيليجرام "Unsupported message" | يستخدم العميل إصدارًا قديمًا من تيليجرام |
Bad Request: chat not found |
تم إرسال الأداة خارج تيليجرام، على سبيل المثال من نافذة اختبار البوت |