مرجع Webhook.

آلية العمل

عند وقوع حدث ما، ترسل Cxperium طلب HTTP واحدًا إلى العنوان المسجل في اللوحة. الإرسال أحادي الاتجاه؛ ولا يُقرأ جسم ردك. تتوفر webhooks في خطة Enterprise.

التعريف من اللوحة: في شاشة Webhook أدخل العنوان، واختر الأحداث التي تُفعِّله والاستطلاعات التي يشملها، ثم فعّله. للاطلاع على الخطوات راجع تكامل Webhook. لكي تُرسل أحداث المحادثات والتذاكر يجب أن يكون وصول webhook إلى الاستطلاعات "الكل".

التعريف عبر API: يمكن إنشاء السجل نفسه وتحديثه عبر POST /api/webhook (يُحدَّث عند تطابق العنوان). حقول الجسم هي نفسها حقول اللوحة:

curl -X POST https://api.cxperium.com/api/webhook \
  -H "apikey: $CX_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "webhook_adress": "https://example.com/cxperium-hook",
    "webhook_time": ["COMPLETED", "ANSWER_GRANTED", "TICKET_CREATED"],
    "access_survey": ["*"],
    "webhook_active": true
  }'

webhook_time قائمة رموز الأحداث (العناوين أدناه). access_survey قائمة معرّفات الاستطلاعات؛ و"*" تعني جميع الاستطلاعات. اعرض التعريفات بـ GET /api/webhook واحذف أحدها بـ DELETE /api/webhook (مع webhook_adress في الجسم).

الحقول الموجودة في كل طلب

ميّز الأحداث بحقل event_status. بقية الحقول خاصة بكل حدث.

جميع حقول المعرّفات سلاسل ست عشرية من 24 حرفًا، وجميع التواريخ بصيغة ISO 8601 بتوقيت UTC. تُحذف الحقول التي لا قيمة لها من JSON؛ تحقق من وجودها عند المعالجة. "webhook_adress": [ … ] في الأمثلة اختصار.

أحداث الاستطلاعات

تتشارك أحداث مسار الاستطلاع بنية واحدة: survey الاستطلاع، وcontact المجيب، وquestions الأسئلة والإجابات حتى تلك اللحظة.

START — عند بدء الاستطلاع

عندما ينقر الشخص على رابط الاستطلاع ويرسل أول رسالة عبر WhatsApp، قبل إرسال السؤال الأول مباشرة. لا توجد أي إجابة في هذه المرحلة.

{
  "survey": { "id": "6650aabbccddeeff00112233", "name": "Customer Satisfaction Survey", "preData": { "orderId": "SP-99123" } },
  "contact": { "contactId": "6612cc33dd44ee55ff667788", "name": "J*** D**", "phone": "905321112233" },
  "questions": [
    { "id": "6650bbccddeeff0011223345", "name": { "EN": "How would you rate our service from 1 to 5?" } },
    { "id": "6650bbccddeeff0011223346", "name": { "EN": "Anything you would like to add?" } }
  ],
  "event_status": "START",
  "start_time": "2026-09-07T09:45:12.512Z",
  "complated_time": "2026-09-07T09:45:12.740Z",
  "webhook_adress": [ … ]
}

ANSWER_GRANTED — عند الإجابة عن كل سؤال

عندما تجتاز إجابة الشخص التحقق وتُحفظ. إضافة إلى البنية المشتركة، يحتوي هذا الحدث وحده على كتلة instantReply التي تعطي السؤال المُجاب للتو منفردًا: questionId وquestionText (حسب اللغة) وanswer (النص الخام) وpreData.

{
  "survey": { "id": "6650aabbccddeeff00112233", "name": "Customer Satisfaction Survey", "preData": { "orderId": "SP-99123" } },
  "contact": { "contactId": "6612cc33dd44ee55ff667788", "name": "J*** D**", "phone": "905321112233" },
  "instantReply": {
    "questionId": "6650bbccddeeff0011223345",
    "questionText": { "EN": "How would you rate our service from 1 to 5?" },
    "answer": "5",
    "preData": { "orderId": "SP-99123" }
  },
  "questions": [
    { "id": "6650bbccddeeff0011223345", "name": { "EN": "How would you rate our service from 1 to 5?" }, "answer": { "button_reply": "5" } },
    { "id": "6650bbccddeeff0011223346", "name": { "EN": "Anything you would like to add?" } }
  ],
  "event_status": "ANSWER_GRANTED",
  "start_time": "2026-09-07T09:46:02.101Z",
  "complated_time": "2026-09-07T09:46:02.330Z",
  "webhook_adress": [ … ]
}

COMPLETED — عند انتهاء الاستطلاع

عند الإجابة عن السؤال الأخير وإرسال رسالة الختام. البنية مثل START؛ والفرق أن حقل answer ممتلئ لجميع الأسئلة في questions.

LEAVE — عند مغادرة الشخص للاستطلاع

عندما يكتب الشخص أمر الخروج أو ينقر زر "مغادرة" أثناء استطلاع جارٍ. البنية مثل START؛ وتوجد الإجابات المقدمة حتى تلك اللحظة في questions. يُرسل هذا الحدث فقط إلى webhooks التي وصولها إلى الاستطلاعات "الكل".

TIMEOUT — عند انتهاء مدة الاستطلاع تلقائي

عندما يرسل شخص رسالة إلى استطلاع انقضى تاريخ انتهائه. لا يُختار في اللوحة بشكل منفصل؛ ويُرسل إلى جميع webhooks النشطة. له شكلان: إن كان الشخص قد بدأ الاستطلاع سابقًا فالبنية مثل START وquestions ممتلئة. وإن نقر على رابط منتهٍ لأول مرة فلا يوجد حقل questions ولا contact.contactId:

{
  "survey": { "id": "6650aabbccddeeff00112233", "name": "Customer Satisfaction Survey" },
  "contact": { "name": "Jane Doe", "phone": "905321112233" },
  "event_status": "TIMEOUT",
  "start_time": "2026-09-07T09:52:00.000Z",
  "complated_time": "2026-09-07T09:52:00.180Z",
  "webhook_adress": [ … ]
}

REPEATED — عند إعادة فتح استطلاع أحادي الاستخدام تلقائي

عندما ينقر شخص أكمل سابقًا استطلاعًا موسومًا "أحادي الاستخدام" على الرابط نفسه مجددًا. لا يُختار في اللوحة بشكل منفصل؛ ويُرسل إلى جميع webhooks النشطة. البنية مثل TIMEOUT للرابط المنتهي؛ وتختلف فقط قيمة event_status وهي REPEATED.

SURVEY_FORM_CREATE_OR_UPDATE — عند إنشاء نموذج استطلاع أو تغييره

عند إنشاء استطلاع في اللوحة، أو حفظ إعداداته، أو تعديل سؤال، أو إضافة خيار زر/قائمة أو حذفه. في كل الحالات يُرسل التعريف الكامل الحالي للاستطلاع؛ ولا يُحدَّد الجزء الذي تغيّر.

أحداث التذاكر

في أحداث التذاكر، userId هو مستخدم اللوحة الذي نفّذ الإجراء، وuserType يبيّن هل هو الحساب الرئيسي (NORMAL) أم مستخدم فرعي (SUB).

TICKET_CREATED — عند إنشاء تذكرة

عند فتح تذكرة جديدة من اللوحة أو من API. يأتي السجل الكامل للتذكرة تحت createOneResult: _id (يطابق ticket_id في أحداث التذاكر الأخرى)، وtaskId (رقم التذكرة الظاهر في اللوحة، يبدأ من 1001)، وstatus (NEW، OPEN، PENDING، CLOSED)، وsubject وmessage، وpriorty (الأولوية، يُكتب الاسم هكذا)، وcontactId، وassigneeId (غير موجود إن لم تُسنَد)، وdueDate، وtags، وmediaName، وcreatedAt.

{
  "createOneResult": {
    "_id": "665f1a2b3c4d5e6f70819200",
    "taskId": "1042",
    "status": "NEW",
    "subject": "Delivery delay",
    "message": "My order has not arrived for 5 days.",
    "priorty": "NORMAL",
    "contactId": "6612cc33dd44ee55ff667788",
    "tags": [ "66201122334455667788990a" ],
    "mediaName": [ "invoice.pdf" ],
    "comments": [],
    "createdAt": "2026-09-07T09:12:44.123Z",
    "updatedAt": "2026-09-07T09:12:44.123Z"
  },
  "userId": "6600aa11bb22cc33dd44ee55",
  "userType": "NORMAL",
  "event_status": "TICKET_CREATED",
  "complated_time": "2026-09-07T09:12:44.400Z",
  "webhook_adress": [ … ]
}

TICKET_STATUS_CHANGE — عند تغيّر حالة التذكرة

عند ضبط حالة تذكرة على NEW أو OPEN أو PENDING أو CLOSED. الحقول: status (الحالة الجديدة)، ticket_id، tagsId (معرّفات وسوم التذكرة)، userId / userType.

TICKET_ASSIGNEE_CHANGE — عند تغيّر المسؤول عن التذكرة

عند إسناد تذكرة إلى مستخدم. الحقول: assigneeId (المستخدم الذي أُسندت إليه)، ticket_id، tagsId، userId / userType (من قام بالإسناد).

TICKET_SEND_COMMENT_PANEL — عند كتابة تعليق على تذكرة

عند إضافة تعليق موجّه إلى جهة الاتصال على تذكرة من اللوحة أو من API. التعليقات الموسومة "ملاحظة داخلية" لا تُفعّل هذا الحدث، والملفات المرفقة بالتعليق ليست في الحمولة. الحقول: message (نص التعليق)، ticket_id، taskId (رغم اسمه ليس رقم التذكرة بل معرّفات وسومها)، userId / userType.

{
  "message": "Spoke with the courier, it will be delivered tomorrow.",
  "ticket_id": "665f1a2b3c4d5e6f70819200",
  "taskId": [ "66201122334455667788990a" ],
  "userId": "6633445566778899aabbccdd",
  "userType": "SUB",
  "event_status": "TICKET_SEND_COMMENT_PANEL",
  "complated_time": "2026-09-07T10:08:30.000Z",
  "webhook_adress": [ … ]
}

أحداث المحادثات

أحداث محادثات الدعم المباشر. chat_id معرّف المحادثة؛ وcontactId جهة الاتصال، وuserId وuserType الموظف الذي نفّذ الإجراء.

CHAT_CREATED — عند إنشاء محادثة

عند بدء محادثة مع جهة اتصال من اللوحة أو من API. إن كانت لجهة الاتصال محادثة مفتوحة فلا يُنشأ سجل جديد وتُعاد المحادثة الحالية. الحقول تحت createOneResult: _id، status، contactId، teamId، assigneeId (غير موجود إن لم تُسنَد)، messages، tags، sessionTime.startTime.

{
  "createOneResult": {
    "_id": "667700112233445566778899",
    "status": "NEW",
    "contactId": "6612cc33dd44ee55ff667788",
    "teamId": "6644556677889900aabbccdd",
    "messages": [],
    "tags": [],
    "sessionTime": { "startTime": "2026-09-07T09:30:00.000Z" }
  },
  "userId": "6600aa11bb22cc33dd44ee55",
  "userType": "NORMAL",
  "event_status": "CHAT_CREATED",
  "complated_time": "2026-09-07T09:30:00.250Z",
  "webhook_adress": [ … ]
}

CHAT_NORMAL_MESSAGE — عند إرسال الموظف رسالة

يُفعَّل عندما يرسل موظف رسالة نصية إلى جهة الاتصال من اللوحة (وليس عند رسائل العميل). تُحوَّل فواصل الأسطر إلى مسافات، والوسائط المرفقة ليست في الحمولة. الحقول: message، chat_id، contactId، userId / userType.

CHAT_TEMPLATE_MESSAGE — عند إرسال رسالة قالب

عندما يرسل موظف رسالة قالب WhatsApp من المحادثة. محتوى القالب ليس في الحمولة؛ ويأتي معرّف المحادثة في هذا الحدث باسم conversationId.

CHAT_STATUS_CHANGE — عند تغيّر حالة المحادثة

عند تغيير حالة المحادثة يدويًا، أو عندما يكتب موظف أول رسالة في محادثة NEW (OPEN)، أو عند إغلاق المحادثة بسبب حذف جهة الاتصال (CLOSED)، أو عند إغلاقها بانتهاء مهلة الجلسة (CLOSED). الحقول: status، chat_id، contactId، userId / userType. قد لا يوجد userType في الإغلاق التلقائي.

CHAT_ASSIGNEE_CHANGE — عند تغيّر المسؤول عن المحادثة

عند إسناد المحادثة إلى موظف آخر، أو عندما يتولاها أول موظف يكتب في محادثة غير مُسندة. الحقول: assigneeId، chat_id، contactId، userId / userType.

أحداث الإرسال

عند اكتمال إرسال جماعي يصل حدث ملخص واحد. success وfailed مصفوفتان من أرقام الهواتف؛ استخدم طول المصفوفة للعدد.

SURVEY_SENDING_COMPLETED — عند اكتمال إرسال استطلاع

عند انتهاء محاولة التسليم لكل الأرقام في جلسة إرسال استطلاع. الحقول: surveyName، success، failed، startingDate، endDate، preData (بيانات مخصصة مرفقة بالإرسال؛ غير موجود إن لم توجد).

{
  "surveyName": "Customer Satisfaction Survey",
  "success": [ "905321112233", "905334445566" ],
  "failed": [ "905559998877" ],
  "startingDate": "2026-09-07T08:00:00.000Z",
  "endDate": "2026-09-07T08:04:12.000Z",
  "event_status": "SURVEY_SENDING_COMPLETED",
  "complated_time": "2026-09-07T08:04:12.300Z",
  "webhook_adress": [ … ]
}

NOTIFICATION_SENDING_COMPLETED — عند اكتمال إرسال إشعار

عند انتهاء محاولة التسليم لكل الأرقام في جلسة إرسال إشعار (رسالة قالب). البنية نفسها، مع templateName بدلًا من اسم الاستطلاع.

أحداث المساعد

أحداث تخص مساعد الذكاء الاصطناعي ونواياه ونصوص الترجمة وملفات قاعدة المعرفة.

ASSISTANT_SESSION_TIMEOUT — عند انتهاء مهلة جلسة المساعد

عند إغلاق جلسة المساعد لجهة اتصال لعدم وصول رسائل خلال المدة المحددة. إن كانت لجهة الاتصال محادثة مفتوحة يُرسل أيضًا CHAT_STATUS_CHANGE بحالة CLOSED. حقل واحد: contactId.

ASSISTANT_INTENT_CHANGE — عند تغيّر نية المساعد

عند إنشاء نية (intent) أو تحديثها أو حذفها في اللوحة. يبيّن حقل place ما حدث (CREATE، UPDATED، DELETED). قواعد regex للنية ليست في الحمولة؛ ويُستخدم هذا الحدث عادة لتحديث ذاكرة مؤقتة. الحقول: place، name، languageId، userId.

ASSISTANT_LOCATION_CHANGE — عند تغيّر ترجمة المساعد

عند إضافة نصوص المساعد (مفاتيح الترجمة) أو تحديثها أو حذفها. تختلف الحقول بحسب قيمة place:

FILE_UPLOAD_AGENT — عند تغيّر ملفات معرفة المساعد تلقائي

عند رفع ملف إلى مساعد الذكاء الاصطناعي كمصدر معرفة، أو حذف ملف، أو حذف قاعدة معرفة (stage). لا يُختار في اللوحة بشكل منفصل؛ ويُرسل إلى webhooks النشطة. يضيّق خيار "قواعد المعرفة التي يتلقاها هذا الروبوت" في تعريف webhook القواعد التي تصلك أحداثها. يبيّن حقل status ما حدث:

{
  "status": "FILE_ADDED",
  "stageId": "66f1c2a9b4e5d6f7a8b9c0d1",
  "files": [
    {
      "originalName": "product-catalogue-2026.pdf",
      "storageLink": "https://storage.cxperium.com/…/product-catalogue-2026.pdf",
      "mimeType": "application/pdf",
      "size": 481920
    }
  ],
  "userId": "6512b0f4a1c2d3e4f5a6b7c8",
  "event_status": "FILE_UPLOAD_AGENT",
  "complated_time": "2026-09-07T11:45:02.117Z",
  "webhook_adress": [ … ]
}