POST/api/public/widget/message
يرسل رسالة الزائر إلى روبوت الدردشة ويعيد ردّه – وهو نقطة النهاية المركزية لأداة الدردشة.
أرسلوا `widget_code` و`message` و`visitor_id` — وبدءًا من الرسالة الثانية — `session_id` من الرد السابق. وفي أول استدعاء لمحادثة جديدة، اتركوا `session_id` فارغة أو ضعوا لها `null`. ويحتوي الرد في الكائن `data` على `session_id` ونص الرد `response`، وعند الحاجة على أزرار (`buttons`) واقتراحات منتجات (`products`) وحالة المحادثة (`state`). يلزم إرسال رأس `X-Widget-Token` مع رمز التضمين و`widget_code`. فإذا كان الرمز مفقودًا، يردّ الخادم بـ 401 `WIDGET_TOKEN_MISSING`، وإذا كان غير صالح بـ 401 `WIDGET_TOKEN_INVALID`؛ وتحصل الاستدعاءات من نطاقات غير معتمدة على 403 `WIDGET_ORIGIN_DENIED`، وأداة معطّلة على 404 `WIDGET_DISABLED`. وإذا كانت `visitor_id` مفقودة، يردّ الخادم بـ 400 `VISITOR_ID_REQUIRED`. الاستدعاء غير idempotent: فكل إرسال ينشئ رسالة زائر جديدة وردًّا جديدًا. امنعوا الإدخال طالما أن طلبًا ما قيد التنفيذ، ولا تكرروه تلقائيًا.
نظرة عامة
الاستدعاء: POST /api/public/widget/message. تنتمي نقطة النهاية هذه إلى مجموعة «أداة الدردشة» في واجهة برمجة تطبيقات Zentor App. تتطلب رمز تضمين (embed token) صالحًا للودجت. الاستدعاء غير متساوي القوة (idempotent): كل استدعاء ناجح يُطلق الإجراء من جديد. المعاملات الإلزامية: widget_code (النص (Body)), message (النص (Body)), visitor_id (النص (Body)). المعاملات الاختيارية: session_id (النص (Body)). حالات الخطأ الموثقة: 401 WIDGET_TOKEN_MISSING, 401 WIDGET_TOKEN_INVALID, 400 VISITOR_ID_REQUIRED. يوضح مثال الاستجابة أدناه بنية الاستجابة الناجحة بتنسيق JSON.
المصادقة والأمان
رمز تضمين الودجت (ترويسة X-Widget-Token) + قائمة النطاقات المسموح بها
متطابق القوة: لا
المعلمات
widget_code(body, string، إلزامي)— رمز الأداة من رمز التضمين الخاص بكمmessage(body, string، إلزامي)— نص رسالة الزائرvisitor_id(body, string، إلزامي)— معرّف الزائر الذي تولّده الأداة وتخزّنه في المتصفحsession_id(body, string)— معرّف الجلسة من الرد السابق؛ فارغ أو `null` في أول استدعاء لمحادثة جديدةمثال طلب
{"widget_code":"...","message":"مرحبا، ما الذي يمكن أن يقدمه Zentor App؟","visitor_id":"<UUID أو معرّف يُنشأ من جهة العميل>"}مثال استجابة
{"ok":true,"data":{"session_id":"31b1096c-a366-4418-b4be-bd999ff98134","response":"...","buttons":[],"state":"idle","products":[]}}رموز الأخطاء
401 WIDGET_TOKEN_MISSING — رأس `X-Widget-Token` مفقود.401 WIDGET_TOKEN_INVALID — رمز التضمين لا يطابق رمز الأداة.400 VISITOR_ID_REQUIRED — الحقل `visitor_id` مفقود.السلوك المُتحقَّق منه
تعيد رسالة صالحة 200 مع ردّ روبوت الدردشة؛ ويعيد الرمز المفقود أو غير الصالح وكذلك `visitor_id` المفقودة رموز الخطأ الموثَّقة.
أداة الدردشة
GET /api/public/widget/healthفحص إتاحة بسيط لخدمة الأداة.GET /api/public/widget/config/:widget_codeيُرجِع التهيئة العامة لأداة (الاسم المعروض، نص الترحيب، التصميم، اللغة، وظيفة الصوت) للتهيئة في المتصفح.GET /api/public/widget/historyيحمّل سجل الرسائل السابقة لمحادثة في الأداة، مثلًا بعد إعادة تحميل الصفحة.POST /api/public/widget/pollيجلب الرسائل الواردة بعد نقطة زمنية معيّنة — مثل ردّ موظف تولّى المحادثة.POST /api/public/widget/ratingيحفظ تقييم الزائر لمحادثة (مفيد أو غير مفيد).POST /api/public/widget/trackيسجّل حدث استخدام مجهول الهوية للأداة (مثل «فُتحت الأداة») لأغراض التحليلات في لوحة التحكم.POST /api/public/widget/voice-transcribeيحوّل تسجيلًا صوتيًا للزائر إلى نص (إدخال صوتي)، إذا كانت ميزة الصوت مفعَّلة للأداة.POST /api/public/widget/voice-speakيحوّل النص إلى كلام منطوق (إخراج صوتي في الأداة)، إذا كانت ميزة الصوت مفعّلة.