مرجع REST API | توثيق Cxperium

المصادقة

تُرسل جميع الطلبات إلى https://api.cxperium.com تحت المسار /api/… عبر HTTPS. أضف ترويسة apikey التي تحمل مفتاح API إلى كل طلب.

sample-request.sh

curl https://api.cxperium.com/api/contacts?page=1&limit=10 \
  -H "apikey: $CX_API_KEY"

إنشاء المفتاح — في اللوحة انتقل إلى الإعدادات ← تكامل API وانقر على إنشاء (Generate)؛ متاح في خطتي Premium وEnterprise. الخطوات: عمليات إنشاء API والاتصال.
مجموعة Postman — يوفر زر عرض المجموعة في الشاشة نفسها مجموعة تضم كل نقاط النهاية في هذه الصفحة مع أمثلة الطلبات.
مفتاح واحد لكل حساب — يؤدي إنشاء مفتاح جديد إلى إبطال السابق فورًا. يستطيع المستخدم الفرعي أيضًا إنشاء مفتاح من شاشة تكامل API، وهذا يجدد المفتاح المشترك للحساب.
حافظ على سرية المفتاح — يمنح الوصول إلى حسابك كاملًا. لا تضمّنه في كود المتصفح أو تطبيق الجوال؛ استدعِ API من خادمك. إن اعتقدت أنه تسرّب فأعد إنشاءه من اللوحة.

يعيد المفتاح غير الصالح أو المفقود أو غير المؤهل بحسب الخطة 401:

401.json

{ "error": "Invalid API key!" }

القواعد العامة

صيغة الطلب والاستجابة واحدة في جميع نقاط النهاية. الأجسام بصيغة JSON (Content-Type: application/json)؛ والاستثناء الوحيد إنشاء تذكرة مع مرفقات (multipart/form-data).

response.json

# Successful request (200 / 201)
{ "status": 201, "success": true, "message": "OK", "data": { … } }

# Validation error (400)
{ "status": 400, "success": false, "error": "MEDIA_NOT_SUPPORTED_ON_CHANNEL", "message": "…" }

# Rate limit (429)
{ "error": "Too many requests, please slow down." }

الموضوع	القاعدة
التقسيم إلى صفحات	تأخذ نقاط القوائم معلمتي `page` (تبدأ من 1) و`limit`. الترتيب الافتراضي `createdAt` تنازليًا؛ ويمكنك تمرير JSON إلى `sort`: `sort={"createdAt":-1}`.
التصفية	معلمة `filter` هي JSON مرمّز للعنوان: `filter={"phone":"9055"}`. تطابق الحقول النصية بطريقة "يحتوي" دون تمييز حالة الأحرف؛ ويمكن تمرير `tags` كمصفوفة.
المعرّفات	جميع قيم `_id` سلاسل ست عشرية من 24 حرفًا.
أرقام الهاتف	مع رمز الدولة، دون علامة + أو مسافات: `905551112233`.
التواريخ	ISO 8601 بتوقيت UTC. تأخذ نقاط التصدير `date_type` (`TODAY`، `THIS_WEEK`، `THIS_MONTH`، `THIS_YEAR`) أو `start` / `end` (`YYYY-MM-DD`).
حد المعدل	100 طلب في الدقيقة لكل عنوان IP. بعده `429`؛ وتُقرأ الحصة المتبقية من ترويسات `RateLimit`.
حجم الجسم	حتى 10 ميغابايت في النقاط التي تحمل وسائط.
اللغة	تحدد ترويسة `language` الاختيارية (`TR`، `EN` …) لغة رسائل الاستجابة.

جهات الاتصال

جهة الاتصال فريدة: رقم الهاتف هو الهوية. طلب إنشاء ثانٍ بالرقم نفسه لا يفتح سجلًا جديدًا بل يحدّث الموجود.

نقطة النهاية	الوصف
GET`/api/contacts`	قائمة مقسمة ومصفّاة، مثل `filter={"userProfileName":"Jane"}`.
GET`/api/contacts/phone/:phone`	جهة اتصال واحدة بالهاتف.
GET`/api/contacts/:id`	جهة اتصال واحدة بالمعرّف.
POST`/api/contacts`	إنشاء جهة اتصال (أو تحديثها إن وُجدت). الجسم أدناه.
POST`/api/contacts/bulk`	إنشاء جماعي: `{ "data": [ {…}, {…} ], "uniqueData": "phone" }`. مع `uniqueData` لا تُنشأ مجددًا السجلات الموجودة بالقيمة نفسها.
PUT`/api/contacts/:id`	تحديث؛ أرسل الحقول المتغيرة فقط (`phone`، `userProfileName`، `email`، `language`، `tags`، `custom`).
PUT`/api/contacts`	إسناد وسوم جماعي: `{ "contact_ids": ["…"], "tags": ["…"] }`.
PUT`/api/contacts/delete/:id`	حذف جهة اتصال.
PUT`/api/contacts/delete-many`	حذف جماعي بشرط: `{ "condition": [ { "column": "phone", "operation": "EQUAL", "value": "9055…" } ] }`. `operation`: `EQUAL`، `NOT_EQUAL`، `CONTAINS`.
PATCH`/api/contacts/anonymize/:phone`	إخفاء هوية جهة اتصال (لطلبات "الحق في النسيان").

POST /api/contacts

{
  "phone": "905551112233",          // required
  "userProfileName": "Jane Doe",    // required
  "email": "jane@example.com",
  "language": "AR",
  "tags": ["66201122334455667788990a"],
  "custom": { "customerNo": "C-4821", "segment": "vip" }
}

المفاتيح الجديدة في custom تصبح أعمدة في جدول جهات الاتصال في اللوحة.

الوسوم

وسوم جهات الاتصال ووسوم التذاكر قائمتان منفصلتان.

نقطة النهاية	الوصف
GET`/api/tags`	قائمة مقسمة لوسوم جهات الاتصال.
POST`/api/tags`	إنشاء وسم جهة اتصال: `{ "name": "VIP", "color": "#ff0f30" }`.
GET`/api/ticket/tags`	قائمة وسوم التذاكر.
POST`/api/ticket/tag`	إنشاء وسم تذكرة.

إرسال الرسائل

قاعدة WhatsApp: إن راسلك العميل خلال آخر 24 ساعة يمكنك إرسال رسائل حرة؛ وإلا فلا يمكن الوصول إليه إلا بقالب معتمد من Meta. تنقسم نقاط النهاية وفق هاتين الحالتين.

نقطة النهاية	الوصف
POST`/api/send-message`	رسالة حرة لجهة اتصال لديها جلسة مفتوحة. `type`: `TEXT`، `IMAGE`، `DOCUMENT`، `VIDEO`. قدّم الوسائط بـ `link` (عنوان) أو `media` (Base64) مع `file_name`.
POST`/api/notification/send-single`	إشعار بقالب معتمد لجهة اتصال واحدة (دون الحاجة إلى نافذة جلسة). الجسم في قسم الإشعارات.
POST`/api/message/one-person`	دعوة استطلاع لجهة اتصال واحدة: `{ "name": "…", "survey_id": "…", "phone": "9055…", "tags": [] }`.
POST`/api/message/bulk`	ينشئ مجموعة إرسال من جهات الاتصال المطابقة لشرط (دون إرسال بعد): `{ "name", "survey_id", "condition": [ { "column", "operation", "value" } ] }`.
POST`/api/message/send/:id`	يرسل المجموعة المنشأة. جسم فارغ.
POST`/api/message/direct`	دعوة استطلاع فورية لجهة اتصال واحدة بمعلمات قالب مخصصة (`customNotification`).
POST`/api/message/basic-direct`	مثل `direct`؛ وحقول القالب (`template_name`، `template_lang`، `bodyPayload`) في جذر الجسم.
GET`/api/message`	قائمة مهام الإرسال.
GET`/api/message/task/:taskId`	حالة مهمة إرسال واحدة.

POST /api/send-message

# Text
{ "type": "TEXT", "phone": "905551112233", "text": "Your order has been shipped." }

# Image by URL
{ "type": "IMAGE", "phone": "905551112233", "link": "https://example.com/campaign.jpg", "text": "September campaign" }

# Document as Base64
{ "type": "DOCUMENT", "phone": "905551112233", "media": "JVBERi0xLjcK…", "file_name": "invoice.pdf" }

الاستجابة 201 وتعيد الجسم المرسل في data. إن كانت القناة لا تدعم الوسائط تتلقى 400 مع MEDIA_NOT_SUPPORTED_ON_CHANNEL.

الاستطلاعات

تُصمَّم الاستطلاعات في اللوحة؛ وعبر API تعرضها وتقرأ نتائجها وتنشئ روابط مخصصة مملوءة مسبقًا.

نقطة النهاية	الوصف
GET`/api/survey/form`	قائمة مقسمة للاستطلاعات.
GET`/api/survey/pure-survey`	قائمة بسيطة (المعرّف والاسم) دون تقسيم.
GET`/api/survey/form/:id`	نموذج الاستطلاع: الأسئلة والخيارات والمسار.
GET`/api/statistic/:survey_id`	نتائج الاستطلاع (الجلسات والإجابات)، مقسمة.
GET`/api/survey/pre-start/:surveyForm_id`	الروابط المملوءة مسبقًا المنشأة لهذا الاستطلاع.
POST`/api/survey/pre-start/:surveyForm_id`	ينشئ رابطًا قصيرًا مملوءًا مسبقًا. الجسم JSON حر (`{ "orderNo": "12345", "segment": "vip" }`)؛ وتتوفر الحقول في مسار الاستطلاع وتصل في webhooks باسم `preData`. يحمل `data` في الاستجابة الرابط القصير: `https://cxpe.net/pXXXXXXXX`.

الإشعارات (رسائل القوالب)

مخطط الإشعار هو مقابل قالب WhatsApp المرسل إلى Meta للموافقة داخل Cxperium. إنشاء المخططات وعرضها وحذفها متاح في خطة Professional وما فوقها.

نقطة النهاية	الوصف
POST`/api/notification/schema`	ينشئ قالبًا ويرسله إلى Meta. إلزامي: `name`، `category` (`UTILITY`، `MARKETING`، `AUTHENTICATION`)، `lang`. اختياري: `headerOptions`، `bodyOptions`، `footerText`، `buttonOptions`، `carouselOptions`.
GET`/api/notification/schema`	القوالب وحالات موافقتها.
GET`/api/notification/schema/:id`	قالب واحد.
DELETE`/api/notification/schema/:templateName`	يحذف القالب.
POST`/api/notification/send-single`	يرسل إشعار قالب لجهة اتصال واحدة. الجسم أدناه.
GET`/api/notification/form`	مهام إرسال الإشعارات؛ `/:taskId` لتفاصيل مهمة.
GET`/api/notification/export`	تصدير سجلات الإشعارات إلى Excel (`date_type` أو `start`/`end`).
GET`/api/notification/notification-message-status/:id`	حالة تسليم إشعار (أُرسل، سُلِّم، قُرئ، فشل).

POST /api/notification/send-single

{
  "contact": { "phone": "905551112233" },
  "notification": {
    "template_name": "order_shipped",
    "name": "Shipping notification",
    "data": {
      "template_lang": "ar",
      "bodyPayload": ["Jane", "TR-48291"],
      "headerPayload": { "format": "IMAGE", "link": "https://example.com/shipping.jpg" },
      "buttonPayload": [ { "type": "QUICK_REPLY", "payload": "track_shipping" } ]
    }
  }
}

املأ الجسم وفق بنية قالبك: bodyPayload مصفوفة قيم المتغيرات {{1}} و{{2}} بالترتيب (فارغة لقالب بلا متغيرات)، وheaderPayload فقط إن كان للقالب ترويسة وسائط، وbuttonPayload فقط إن كان فيه أزرار. عند انتهاء الإرسال الجماعي يصل حدث webhook NOTIFICATION_SENDING_COMPLETED.

التذاكر

حالات التذكرة NEW وOPEN وPENDING وCLOSED. يقبل إنشاء التذكرة multipart/form-data لإرفاق الملفات.

نقطة النهاية	الوصف
GET`/api/ticket`	قائمة مقسمة ومصفّاة ومرتبة: `filter={"status":"NEW"}&sort={"createdAt":-1}`.
GET`/api/ticket/:_id`	تذكرة واحدة مع تعليقاتها.
GET`/api/ticket/task/:taskId`	برقم التذكرة الظاهر في اللوحة.
GET`/api/ticket/contact/:contactNumber`	تذاكر جهة اتصال بالهاتف؛ `/api/ticket/contact-by-id/:_id` بالمعرّف.
GET`/api/ticket/assignee-count`	عدد التذاكر المفتوحة لكل موظف.
GET`/api/last-answer/:id`	آخر رد على التذكرة.
POST`/api/ticket`	إنشاء تذكرة (multipart). الحقول: `subject` و`contactId` و`message` (إلزامية)؛ `tags` (مصفوفة JSON)، `media` (ملف أو أكثر).
POST`/api/ticket/send-comment/user/:_id`	تعليق على التذكرة باسم مستخدم اللوحة: `{ "message": "…" }`.
POST`/api/ticket/send-comment/phone/:_id/:phone`	رسالة/تعليق على التذكرة يُسلَّم إلى جهة الاتصال عبر WhatsApp: `{ "message": "…" }`.
POST`/api/ticket/:_id/wa/:phone/comments`	يضيف تعليقًا أرسلته جهة الاتصال عبر WhatsApp إلى التذكرة (لتكاملات الروبوت).
PATCH`/api/assignee-change/:_id/:type/:assigneeId`	يسند التذكرة إلى مستخدم.

create-ticket.sh

curl -X POST https://api.cxperium.com/api/ticket \
  -H "apikey: $CX_API_KEY" \
  -F "subject=Delivery delay" \
  -F "contactId=6612cc33dd44ee55ff667788" \
  -F "message=My order has not arrived for 5 days." \
  -F 'tags=["66201122334455667788990a"]' \
  -F "media=@invoice.pdf"

توجد أحداث webhook للإنشاء وتغيير الحالة والمسؤول والتعليقات: أحداث التذاكر.

المحادثة المباشرة

محادثات الدعم المباشر هي السجلات التي يراها الموظفون في اللوحة. عبر API يمكنك فتح المحادثات وإرسال الرسائل وتغيير الفريق أو الحالة.

نقطة النهاية	الوصف
POST`/api/chat`	إنشاء محادثة: `{ "contactId": "…", "message": "…", "teamId": "…" }` (`contactId` وحده إلزامي). إن كانت لجهة الاتصال محادثة مفتوحة تُعاد هي.
GET`/api/chat`	قائمة المحادثات. المحادثات الجديدة غير المُسندة: `filter={"status":"NEW","assignee":{"exists":false}}`.
GET`/api/chat/active/:id`	هل لجهة الاتصال محادثة مفتوحة.
POST`/api/chat/send-message`	يرسل رسالة إلى جهة اتصال ويفتح محادثة عند الحاجة: `{ "message": "…", "contactId": "…" }`.
POST`/api/chat/send-message/:_id`	رسالة إلى محادثة موجودة (`message` و/أو `media`).
POST`/api/chat/send-message/phone/:_id`	رسالة بالهاتف: `{ "phone": "9055…", "message": { "text": "…" } }`.
PATCH`/api/chat/team-change/:_id/:teamId`	ينقل المحادثة إلى فريق آخر.
PATCH`/api/chat/status-change/:_id/:status`	يغيّر الحالة (`NEW`، `OPEN`، `PENDING`، `CLOSED`).
PUT`/api/chat/:_id/tags`	يسند وسومًا إلى المحادثة: `{ "tags": ["…"] }`.
GET`/api/chat/export`	تصدير سجلات المحادثات (`date_type` أو `start`/`end`).
PUT`/api/chat/settings/timeout`	يحدّث إعداد مهلة الجلسة.
GET`/api/business-hours`	ساعات العمل؛ `/api/business-hours/:phone` لرقم محدد.
GET`/api/teams`	قائمة الفرق.
GET`/api/subuser`	المستخدمون الفرعيون (الموظفون)؛ `/api/subuser/:id` سجل واحد، ويُحدَّث بـ `PUT` (مثل `chatAssignmentThreshold`).

لأحداث إنشاء المحادثة والرسائل والحالة والمسؤول راجع أحداث المحادثات.

إدارة Webhook

تُدار تعريفات webhook من اللوحة أو من API؛ ويرى الاثنان السجل نفسه. الإرسال حصري لخطة Enterprise.

نقطة النهاية	الوصف
POST`/api/webhook`	إنشاء أو تحديث (يُحدَّث عند تطابق العنوان): `webhook_adress`، `webhook_time` (رموز الأحداث)، `access_survey` (معرّفات الاستطلاعات أو `["*"]`)، `webhook_active`.
GET`/api/webhook`	قائمة webhooks المعرّفة.
DELETE`/api/webhook`	حذف بالعنوان: `{ "webhook_adress": "https://…" }`.

رموز الأحداث والحقول المرسلة: مرجع Webhook.

المساعد والكتالوج وPipeline وغيرها

نقاط نهاية المساعد التي تستخدمها تكاملات روبوت المحادثة، ورسائل كتالوج/منتجات WhatsApp، وإدارة Pipeline.

مساعد الذكاء الاصطناعي

نقطة النهاية	الوصف
GET`/api/assistant/configuration`	إعدادات المساعد.
GET`/api/assistant/intent`	قائمة النوايا.
GET`/api/assistant/localization`	نصوص الترجمة؛ `/:languageId` للغة واحدة. `POST` يضيف دفعة: `{ "data": [ { "languageId", "key", "value" } ] }`.
POST`/api/assistant/session`	إنشاء/تحديث جلسة جهة اتصال: `{ "phone", "language", "data": [ { "message", "isLast" } ], "isActive" }`. `GET` للقائمة، `/:phone` بالرقم.
POST`/api/assistant/report`	سجل تقرير المساعد: `{ "phone", "intentName", "message", "nlp" }`؛ `/api/assistant/bulk-report` دفعة. `GET` للتقارير و`/export` للتصدير.
POST`/api/assistant/shopping-carts`	سجل سلة: `{ "cartKey", "customerId", "productCode", "quantity", "unitPrice" }`؛ `PUT` يحدّث، `GET /:cartKey` يقرأ.
GET`/api/waba`	بيانات رقم WhatsApp للحساب.

الكتالوج ورسائل المنتجات Meta Cloud API فقط

نقطة النهاية	الوصف
GET`/api/catalog/catalogs`	قائمة الكتالوجات؛ `POST` ينشئ كتالوجًا.
GET`/api/catalog/products`	قائمة المنتجات؛ `POST` يضيف، `DELETE /:productId` يحذف.
GET`/api/catalog/commerce-settings`	ظهور السلة والكتالوج؛ يُحدَّث بـ `POST`.
POST`/api/catalog/send/single-product`	رسالة منتج واحد؛ `/multi-product` عدة منتجات، `/catalog` رسالة كتالوج.

Pipeline

نقطة النهاية	الوصف
GET`/api/funnel/stages`	قائمة المراحل؛ `POST` ينشئ، `PATCH /:id` يحدّث، `DELETE /:id` يحذف، `POST /:id/move-stage` يعيد الترتيب.
GET`/api/funnel/cards`	بطاقات العملاء المحتملين؛ `POST` ينشئ، `PATCH /:id` يحدّث، `DELETE /:id` يحذف، `POST /:id/move-card` يغيّر المرحلة.
POST`/api/funnel/cards/search-by-custom-field`	البحث عن البطاقات بحقل مخصص.
POST`/api/funnel/cards/:id/add-activity`	إضافة نشاط (`todo`، `call`، `mail`، `meeting`، `document`)؛ ومثلها `add-log` و`add-follower` و`add-attachment` مع نظائر الحذف.

لاستخدام Pipeline في اللوحة راجع ميزات CRM ← Pipeline.

مرجع REST API.