GET/api/public/widget/history

يحمّل سجل الرسائل السابقة لمحادثة في الأداة، مثلًا بعد إعادة تحميل الصفحة.

مرّروا `widget_code` و`session_id` و`visitor_id` كمعاملات استعلام. ويحتوي الرد في الكائن `data` على قائمة `messages` التي تضم `role` (`user` أو `assistant`) و`text` و`created_at` بترتيب المحادثة. والاستدعاء قرائي بالكامل وidempotent. يلزم إرسال رأس `X-Widget-Token` مع رمز التضمين و`widget_code`. فإذا كان الرمز مفقودًا، يردّ الخادم بـ 401 `WIDGET_TOKEN_MISSING`، وإذا كان غير صالح بـ 401 `WIDGET_TOKEN_INVALID`؛ وتحصل الاستدعاءات من نطاقات غير معتمدة على 403 `WIDGET_ORIGIN_DENIED`، وأداة معطّلة على 404 `WIDGET_DISABLED`. وإذا كانت `session_id` أو `visitor_id` مفقودة، يردّ الخادم بـ 400 `PARAMS_REQUIRED`. وإذا لم تكن الجلسة معروفة بعد الآن، ابدؤوا محادثة جديدة.

نظرة عامة

الاستدعاء: GET /api/public/widget/history. تنتمي نقطة النهاية هذه إلى مجموعة «أداة الدردشة» في واجهة برمجة تطبيقات Zentor App. تتطلب رمز تضمين (embed token) صالحًا للودجت. الاستدعاء متساوي القوة (idempotent): الاستدعاءات المتكررة بالبيانات نفسها تُرجع النتيجة نفسها. المعاملات الإلزامية: widget_code (الاستعلام (Query)), session_id (الاستعلام (Query)), visitor_id (الاستعلام (Query)). حالات الخطأ الموثقة: 400 PARAMS_REQUIRED. يوضح مثال الاستجابة أدناه بنية الاستجابة الناجحة بتنسيق JSON.

المصادقة والأمان

رمز تضمين الودجت (ترويسة X-Widget-Token) + قائمة النطاقات المسموح بها

متطابق القوة: نعم

المعلمات

widget_code(query, string، إلزامي)— رمز الأداة من رمز التضمين الخاص بكم
session_id(query, string، إلزامي)— معرّف جلسة المحادثة من رد `message`
visitor_id(query, string، إلزامي)— معرّف الزائر الذي تولّده الأداة وتخزّنه في المتصفح

مثال استجابة

{"ok":true,"data":{"messages":[{"role":"user","text":"مرحبا...","created_at":"..."},{"role":"assistant","text":"...","created_at":"..."}]}}

رموز الأخطاء

400 PARAMS_REQUIRED — `session_id` أو `visitor_id` مفقودة.

السلوك المُتحقَّق منه

تعيد جلسة موجودة 200 مع سجل الرسائل؛ وتعيد المعاملات المفقودة 400 `PARAMS_REQUIRED`.

أداة الدردشة

GET /api/public/widget/healthفحص إتاحة بسيط لخدمة الأداة.GET /api/public/widget/config/:widget_codeيُرجِع التهيئة العامة لأداة (الاسم المعروض، نص الترحيب، التصميم، اللغة، وظيفة الصوت) للتهيئة في المتصفح.POST /api/public/widget/messageيرسل رسالة الزائر إلى روبوت الدردشة ويعيد ردّه – وهو نقطة النهاية المركزية لأداة الدردشة.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يحوّل النص إلى كلام منطوق (إخراج صوتي في الأداة)، إذا كانت ميزة الصوت مفعّلة.

مقالات ذات صلة

← أداة الدردشة