المطورون / الوكلاء
إنشاء تذكرة لويدجت موقع خاص
https://api.echonova.ai/v1/widgets/{publicId}/ticketsاستدعِ هذه النقطة من خادمك لزائر مسجّل الدخول. تعيد تذكرة تُستخدم مرة واحدة، تمرّرها إلى متصفح الزائر، فيبدأ بها جلسة واحدة في الويدجت. يجب أن يكون الويدجت خاصًا ومفعّلًا. إنشاء التذكرة مجاني.
Headers
كلمة Bearer ثم مسافة ثم مفتاح API الذي يبدأ بـ ek_. أنشئ المفاتيح في البوابة من المطورون، ثم مفاتيح واجهة برمجة التطبيقات.
معاملات المسار
معرّف الويدجت من إعدادات الويدجت، ويبدأ بـ `wdg_`.
متن الطلب
application/json
الزائر المسجّل الدخول الذي أُنشئت له هذه التذكرة.
يقصر التذكرة على قناة واحدة. احذفه للسماح بالقناتين.
عدد الثواني التي تبقى فيها التذكرة صالحة، من 60 إلى 900. تعمل مرة واحدة فقط.
الاستجابة
200 application/json كل استجابة تستخدم هذا الغلاف.
النتيجة.
التذكرة التي تُستخدم مرة واحدة. سلّمها إلى متصفح الزائر؛ فتبدأ جلسة واحدة.
وقت توقف التذكرة عن العمل، بصيغة ISO 8601 للتاريخ والوقت.
قيمته true عند نجاح الطلب.
يكرر رمز حالة HTTP.
قيمته null عند النجاح.
الأخطاء
الغلاف نفسه، مع success بقيمة false و data بقيمة null. كل الأخطاء
متى يحدث. قيمة `ttlSeconds` خارج النطاق من 60 إلى 900، أو ليست عددًا صحيحًا؛ تذكر الرسالة الحد المخالف.
الحل. أرسل عدد ثوانٍ صحيحًا من 60 إلى 900، أو احذف الحقل لتكون القيمة 300.
متى يحدث. قيمة `channel` ليست `voice` ولا `chat`.
الحل. أرسل `voice` أو `chat`، أو احذف الحقل.
متى يحدث. قيمة `user.id` أطول من 128 حرفًا.
الحل. أرسل `user.id` من 128 حرفًا أو أقل.
متى يحدث. قيمة `user.id` نص فارغ.
الحل. أرسل `user.id` غير فارغ، أو احذف الحقل.
متى يحدث. تحتوي `user.id` على حرف تحكّم، مثل السطر الجديد أو الجدولة (tab).
الحل. أزل أحرف التحكم من `user.id`.
متى يحدث. قيمة `user.name` أطول من 80 حرفًا.
الحل. أرسل `user.name` من 80 حرفًا أو أقل.
متى يحدث. يحمل الجسم أو الاستعلام حقلًا لا تعرّفه نقطة النهاية.
الحل. احذف الحقل.
متى يحدث. header `Authorization` مفقود، أو قيمته لا تبدأ بـ `Bearer ek_...`، أو أن الرمز لا يطابق أي مفتاح، أو أن المفتاح محذوف أو معطّل أو منتهي الصلاحية، أو أن حسابه مغلق.
الحل. أرسل `Authorization: Bearer ek_...` بمفتاح مفعّل من هذه البيئة.
متى يحدث. مساحة العمل المالكة للمفتاح ليس لها اشتراك.
الحل. راجع خطة مساحة العمل في البوابة.
متى يحدث. حالة الاشتراك ليست نشطة أو تجريبية.
الحل. جدّد الاشتراك.
متى يحدث. المفتاح مقيّد: صلاحية تذاكر الويدجت مضبوطة على No access.
الحل. عدّل المفتاح واضبط تذاكر الويدجت على Access، أو استخدم مفتاحًا آخر.
متى يحدث. لا يوجد ويدجت بهذا `publicId`، أو أن الويدجت يتبع مساحة عمل أخرى.
الحل. انسخ `publicId` من إعدادات الويدجت لوكيل في مساحة العمل هذه.
متى يحدث. الويدجت في الوضع العام، ولا يحتاج إلى تذكرة.
الحل. بدّل الويدجت إلى الوضع الخاص من إعداداته.
متى يحدث. الويدجت متوقف، فلا تستطيع أي تذكرة أن تبدأ جلسة.
الحل. فعّل الويدجت من إعداداته.
متى يحدث. متن JSON أكبر من 100 كيلوبايت؛ يُرفض الطلب قبل فحص مفتاح API، فلا يحصل على صف في النشاط.
الحل. أرسل جسمًا أصغر؛ النص الطويل مكانه عدة طلبات.
متى يحدث. للطلب جسم وقيمة `Content-Type` فيه ليست `application/json`.
الحل. أرسل `Content-Type: application/json`.
متى يحدث. أرسل المفتاح أكثر من 100 طلب إلى نقطة نهاية واحدة خلال 60 ثانية، أو أرسل عنوان IP واحد أكثر من 100 طلب إلى نقطة نهاية واحدة خلال 60 ثانية (يُحسب حد عنوان IP قبل فحص المفتاح، لذلك قد يردّ بلا مفتاح أصلًا)؛ وترويسة `Retry-After` تحمل عدد الثواني للانتظار.
الحل. انتظر عدد ثواني `Retry-After`، ثم أعد المحاولة.
متى يحدث. خطأ لم تصنّفه الواجهة.
الحل. راجع الطلب، ثم أعد المحاولة بعد انتظار قصير، وتواصل مع الدعم إن استمر الخطأ.
متى يحدث. انقطاع مؤقت داخل الواجهة.
الحل. أعد المحاولة بعد انتظار قصير.
متى يحدث. انتهاء مهلة مؤقت داخل الواجهة.
الحل. أعد المحاولة بعد انتظار قصير.
curl -X POST "https://api.echonova.ai/v1/widgets/wdg_a1B2c3D4e5F6g7H8i9J0/tickets" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'{
"data": {
"ticket": "wtk_IlrI02c2RnE7iqidinRQanxpcTovunoAK7Bu5R6Zc5w",
"expiresAt": "2026-10-19T09:30:00.000Z"
},
"success": true,
"statusCode": 200,
"errorMessage": null
}