POST/api/public/widget/voice-speak

يحوّل النص إلى كلام منطوق (إخراج صوتي في الأداة)، إذا كانت ميزة الصوت مفعّلة.

أرسلوا `widget_code` والنص المطلوب قراءته في `text`. ويحتوي الرد على بيانات صوتية للتشغيل في المتصفح. وللتشغيل المباشر عبر عنصر `<audio>`، يتوفر المسار نفسه إضافيًا عبر GET. إذا كانت `widget_code` مفقودة، يردّ الخادم بـ 400 `WIDGET_CODE_REQUIRED`؛ وإن لم تكن ميزة الصوت مفعّلة أو غير متاحة حاليًا، بـ 503 `VOICE_UNAVAILABLE`. ابدؤوا تشغيلًا جديدًا فقط بعد انتهاء التشغيل السابق.

نظرة عامة

الاستدعاء: POST /api/public/widget/voice-speak. تنتمي نقطة النهاية هذه إلى مجموعة «أداة الدردشة» في واجهة برمجة تطبيقات Zentor App. تتطلب رمز تضمين (embed token) صالحًا للودجت. الاستدعاء متساوي القوة (idempotent): الاستدعاءات المتكررة بالبيانات نفسها تُرجع النتيجة نفسها. المعاملات الإلزامية: widget_code (النص (Body)), text (النص (Body)). حالات الخطأ الموثقة: 400 WIDGET_CODE_REQUIRED, 503 VOICE_UNAVAILABLE. يوضح مثال الاستجابة أدناه بنية الاستجابة الناجحة بتنسيق JSON.

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

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

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

المعلمات

widget_code(body, string، إلزامي)— رمز الأداة من رمز التضمين الخاص بكم
text(body, string، إلزامي)— النص المطلوب قراءته

مثال استجابة

{"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-transcribeيحوّل تسجيلًا صوتيًا للزائر إلى نص (إدخال صوتي)، إذا كانت ميزة الصوت مفعَّلة للأداة.

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

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