POST/api/public/widget/voice-transcribe
يحوّل تسجيلًا صوتيًا للزائر إلى نص (إدخال صوتي)، إذا كانت ميزة الصوت مفعَّلة للأداة.
أرسلوا `widget_code` وبيانات الصوت في الحقل `audio` بصيغة `multipart/form-data`. ويحتوي الرد على النص المكتشف، الذي ترسلونه بعدها عبر `POST /api/public/widget/message`. ويُظهِر `voice_enabled` في تهيئة الأداة ما إذا كانت ميزة الصوت مفعّلة. إذا كانت `widget_code` مفقودة، يردّ الخادم بـ 400 `WIDGET_CODE_REQUIRED`؛ وإن لم تكن ميزة الصوت مفعّلة أو غير متاحة حاليًا، بـ 503 `VOICE_UNAVAILABLE`. وتتولى Zentor إعداد ميزة الصوت لأداتكم.
نظرة عامة
الاستدعاء: POST /api/public/widget/voice-transcribe. تنتمي نقطة النهاية هذه إلى مجموعة «أداة الدردشة» في واجهة برمجة تطبيقات Zentor App. تتطلب رمز تضمين (embed token) صالحًا للودجت. الاستدعاء غير متساوي القوة (idempotent): كل استدعاء ناجح يُطلق الإجراء من جديد. المعاملات الإلزامية: widget_code (النص (Body)), audio (النص (Body)). حالات الخطأ الموثقة: 400 WIDGET_CODE_REQUIRED, 503 VOICE_UNAVAILABLE. يوضح مثال الاستجابة أدناه بنية الاستجابة الناجحة بتنسيق JSON.
المصادقة والأمان
رمز تضمين الودجت (ترويسة X-Widget-Token) + قائمة النطاقات المسموح بها
متطابق القوة: لا
المعلمات
widget_code(body, string، إلزامي)— رمز الأداة من رمز التضمين الخاص بكمaudio(body, binary، إلزامي)— تسجيل صوتي كملف (`multipart/form-data`)مثال استجابة
{"ok":false,"error":{"code":"VOICE_UNAVAILABLE","message":"Sprachfunktion aktuell nicht verfügbar."}}رموز الأخطاء
400 WIDGET_CODE_REQUIRED — الحقل `widget_code` مفقود.503 VOICE_UNAVAILABLE — ميزة الصوت غير مفعّلة لهذه الأداة أو غير متاحة حاليًا.السلوك المُتحقَّق منه
`widget_code` المفقودة تعيد 400 `WIDGET_CODE_REQUIRED`، وأداة دون ميزة صوت تعيد 503 `VOICE_UNAVAILABLE`. ويتطلب حالة النجاح أداة بميزة صوت مفعّلة.
أداة الدردشة
GET /api/public/widget/healthفحص إتاحة بسيط لخدمة الأداة.GET /api/public/widget/config/:widget_codeيُرجِع التهيئة العامة لأداة (الاسم المعروض، نص الترحيب، التصميم، اللغة، وظيفة الصوت) للتهيئة في المتصفح.POST /api/public/widget/messageيرسل رسالة الزائر إلى روبوت الدردشة ويعيد ردّه – وهو نقطة النهاية المركزية لأداة الدردشة.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-speakيحوّل النص إلى كلام منطوق (إخراج صوتي في الأداة)، إذا كانت ميزة الصوت مفعّلة.