POST/api/public/widget/poll

يستعلم عن الرسائل الجديدة منذ آخر استعلام — مهم مثلاً عندما يتولى موظف المحادثة عبر التسليم (handover) ويجب أن يرى العميل الرد في Widget.

تتناول صفحة «POST /api/public/widget/poll — مرجع واجهة برمجة التطبيقات» مجال الوظيفة المحدد في هذا الرابط. ويُستكمل الملخص الحالي بسير العمل الفعلي والمتطلبات والقيود المعروفة. تدير Zentor النطاقات المسموح بها عند إنشاء الـ Widget، ولا توجد واجهة إعداد لهذا الأمر في لوحة المستأجر. قد يؤدي مصدر غير مسموح إلى الخطأ WIDGET_ORIGIN_DENIED. يقتصر إنشاء الـ Widget على Master Admin، بينما يحصل المستأجر على كود التضمين الجاهز. يمثل المسار `POST /api/public/widget/poll` العملية المحددة في هذه مادة المساعدة. من الضروري أن على العميل الالتزام بطريقة HTTP والمسار ونوع المصادقة والحقول الإلزامية وحالات الخطأ الموثقة. لا توفر Zentor نظام مفتاح API عام للمطورين؛ فالمسار إما عام أو محمي برمز تضمين Widget والتحقق من المصدر. عند استدعاء `/api/public/widget/poll` يلزم تقييم حالة HTTP مع محتوى JSON معًا. أخطاء المراجعة أو المورد غير الموجود أو المصدر المرفوض أو القيمة المنتهية أو خطأ الخادم حالات مختلفة. نجاح الطلب يثبت معالجة هذه الخطوة فقط، ولا يثبت تلقائيًا وصول بريد أو اكتمال دفع أو انتهاء تسجيل SSO. يجب اختبار `POST /api/public/widget/poll` بقيم مجهولة الهوية. لا تُنشر بيانات عميل حقيقية أو UUID شبيهة بالإنتاج أو JWT أو رموز Widget أو طوابع زمنية حقيقية. الحد المعروف للمنصة هو 2000 طلب خلال 15 دقيقة، ولم يُنفذ حد منفصل مثبت لهذا المسار. لا ينبغي تكرار طلب POST غير المتطابق القوة تلقائيًا بمجرد انقطاع شبكة غير واضح، لأن الطلب الأول ربما أحدث أثرًا. يمكن تسجيل الحالة ورمز خطأ آمن، لكن لا تُسجل كلمات المرور أو رموز التحقق أو رموز إعادة التعيين. وتنطبق هذه النقطة مباشرة على «POST /api/public/widget/poll». بالنسبة إلى «POST /api/public/widget/poll — مرجع واجهة برمجة التطبيقات»، مصدر الحقيقة هو سجل API والمسار الخلفي والاختبارات. الاختبار السلبي أو التشابه مع مسار آخر لا يمثل تحققًا حيًا كاملًا. يلزم الفصل بين المعلومات المستخرجة من المخطط والاختبار الآلي والملاحظة الحية الآمنة. ينبغي تنفيذ الاستعلام الدوري بفاصل زمني مناسب ومنع تشغيل طلب جديد قبل انتهاء الطلب السابق. عند عدم وجود رسائل جديدة، لا يمثل الرد الفارغ خطأ. أما أخطاء الرمز أو النطاق المسموح به فيجب معالجتها كأخطاء إعداد، لا بإعادة المحاولة المستمرة دون تغيير.

{"widget_code":"...","session_id":"...","visitor_id":"..."}

{"ok":true,"data":{"messages":[]}}