التوثيق.

البدء السريع

ثلاث خطوات تكفي للبدء باستخدام Cxperium. نتولى إدارة طلب WhatsApp Business API نيابة عنك.

1. أنشئ حسابك

   بعد طلب العرض التوضيحي، يفتح فريقنا حسابك ويرسل طلب WhatsApp Business API الخاص بك إلى Meta. تكتمل الموافقة عادة في اليوم نفسه.

2. تحقق من رقمك وملفك التعريفي

   عند اعتماد رقم عملك، يمكنك تعديل الملف التعريفي لعلامتك التجارية (الشعار، الوصف، ساعات العمل) من لوحة التحكم. ويُقدَّم طلب شارة التحقق الخضراء من هنا أيضًا.

3. أرسل رسالتك الأولى

   أنشئ قالبًا وأرسله للموافقة وأطلق حملتك الأولى — أو اختر من مكتبة القوالب الجاهزة. يمكنك إنجاز كل ذلك من اللوحة دون كتابة أي كود.

وحدات المنصة

أدلة استخدام مفصّلة لجميع الوحدات في لوحة التحكم، إضافة إلى مراجع المطورين. تتوفر أيضًا شروحات خطوة بخطوة لكل وحدة في مركز المساعدة داخل اللوحة.

قنوات الويب والجوال

الروبوت نفسه وصندوق الوارد نفسه: إلى جانب WhatsApp، أضف فقاعة محادثة إلى موقعك أو اربط تطبيق الجوال الخاص بك. عند إنشاء قناة من القنوات ← إضافة في لوحة التحكم تحصل على مفتاح القناة والسر (secret).

بالنسبة إلى قناة الويب، كل ما عليك هو لصق كود التثبيت الذي توفره اللوحة قبل وسم </body> في موقعك مباشرة. تُغيَّر الألوان والموضع والنصوص من مصمم الأداة في اللوحة، ثم تنسخ الكود مجددًا.

<!-- Cxperium chat -->
<script>
  window.cxperiumSettings = {
    channelKey: "ch_xxxxxxxxxxxxxxxx",
    secret: "…",
    brand: "Acme Support",
    color: "#7c3aed"
  };
  (function (d) {
    var s = d.createElement("script");
    s.src = "https://cdn.cxperium.com/widget/v1/cxperium-widget.js";
    s.async = true;
    d.head.appendChild(s);
  })(document);
</script>

أما تطبيقات الجوال (iOS وAndroid وReact Native وFlutter) فتعمل عبر القناة المخصصة باستخدام REST وWebSocket: يسجّل التطبيق مرة واحدة ليحصل على هوية ورمز (token)، ثم يرسل الرسائل عبر WebSocket ويتلقى الردود فورًا. لا حاجة إلى خادم؛ ويمكنك إن شئت الاتصال عبر خادمك الخاص بطلبات موقّعة.

خطوات الإعداد وجميع إعدادات الأداة وأنواع الرسائل ورموز الأخطاء في دليل القنوات.

واجهة API للمطورين

اربط إدارة جهات الاتصال وإرسال الرسائل والإشعارات والاستطلاعات والتذاكر والمحادثة المباشرة بأنظمتك الخاصة عبر Cxperium REST API. تُرسل جميع الطلبات إلى https://api.cxperium.com عبر HTTPS وتُصادَق بترويسة apikey. تنشئ مفتاح API من الإعدادات ← تكامل API في لوحة التحكم (متاح في خطتي Premium وEnterprise).

# إنشاء جهة اتصال (تُحدَّث الموجودة إذا كان رقم الهاتف مسجلًا)
curl -X POST https://api.cxperium.com/api/contacts \
  -H "apikey: $CX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "905551112233",
    "userProfileName": "Jane Doe",
    "email": "jane@example.com",
    "language": "AR",
    "tags": []
  }'

# رسالة نصية حرة إلى جهة اتصال لديها جلسة مفتوحة (راسلتك خلال 24 ساعة)
curl -X POST https://api.cxperium.com/api/send-message \
  -H "apikey: $CX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "TEXT", "phone": "905551112233", "text": "Your order has been shipped." }'

# 201 Created
{ "status": 201, "success": true, "message": "OK", "data": { … } }

تحمل كل استجابة الحقول status وsuccess وmessage وdata عند الحاجة. يعيد المفتاح غير الصالح أو المفقود 401 مع { "error": "Invalid API key!" }. للوصول إلى جهات اتصال انتهت نافذة جلستها، أرسل إشعارًا بقالب معتمد عبر POST /api/notification/send-single. الحد الأقصى 100 طلب في الدقيقة لكل عنوان IP، وبعده تتلقى 429.

جميع نقاط النهاية وقواعد التقسيم إلى صفحات والتصفية وأمثلة الطلبات: مرجع REST API. يمكن تنزيل مجموعة Postman من زر عرض المجموعة في شاشة تكامل API.

Webhooks

عند وقوع إجابات الاستطلاعات أو أحداث التذاكر والمحادثات أو ملخصات الإرسال الجماعي أو أحداث المساعد، ترسل Cxperium طلب POST بجسم JSON إلى عنوان HTTPS الذي تحدده في اللوحة. تتوفر webhooks في خطة Enterprise، وتختار في تعريف webhook الأحداث التي تُرسل والاستطلاعات المشمولة.

# COMPLETED — عندما يُكمل شخص استطلاعًا
{
  "event_status": "COMPLETED",
  "survey": { "id": "6650aabbccddeeff00112233", "name": "Customer Satisfaction Survey" },
  "contact": { "contactId": "6612cc33dd44ee55ff667788", "name": "J*** D**", "phone": "905321112233" },
  "questions": [
    { "id": "6650bbccddeeff0011223345", "name": { "EN": "How would you rate our service from 1 to 5?" }, "answer": { "button_reply": "5" } }
  ],
  "start_time": "2026-09-07T09:47:40.000Z",
  "complated_time": "2026-09-07T09:47:40.212Z"
}

يحتوي كل طلب على رمز الحدث event_status ووقت الإرسال complated_time، وبقية الحقول خاصة بكل حدث. يكفي أن ترد بحالة 2xx؛ ولا يُقرأ جسم الرد. يُعاد الطلب مرة واحدة فقط عند خطأ في الشبكة، ولا تُعاد استجابات 4xx/5xx. تُحذف الحقول التي لا قيمة لها من JSON.

جميع الأحداث ووصف الحقول: مرجع Webhook. خطوات التعريف من اللوحة: تكامل Webhook.