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

أنواع القنوات وإنشاؤها

يمكن أن يضم حساب Cxperium أكثر من قناة. ترتبط جميع القنوات بالروبوت نفسه وقائمة جهات الاتصال نفسها وصندوق الوارد نفسه؛ ويرى الموظفون المحادثة على شاشة واحدة أيًا كان مصدرها.

لإنشاء قناة جديدة:

1. افتح صفحة القنوات

   ادخل إلى القنوات (Channels) من القائمة الجانبية وانقر على إضافة (Add) أعلى اليمين.

2. اختر النوع

   اختر بطاقة Web للمحادثة في موقعك، أو Mobile لتطبيق الجوال أو عميلك الخاص.

3. حدد اسمًا وعنوان الروبوت

   اكتب اسمًا للقناة وعنوان الروبوت الذي تُحوَّل إليه الرسائل الواردة على هذه القناة. اللغة الافتراضية اختيارية. انقر على إضافة قناة (Add Channel).

4. احصل على بيانات الاتصال

   تعرض الخطوة الأخيرة مفتاح القناة والسر و(لنوع Web) كود تثبيت جاهزًا. يمكنك الوصول إليها لاحقًا من نافذة التفاصيل (Detail) في قائمة القنوات.

قناة الويب: تثبيت الأداة

تضيف قناة الويب فقاعة محادثة إلى زاوية موقعك. ينقر الزائر على الفقاعة، ويكتب اسمه إن شئت، ويبدأ الحديث مع الروبوت أو مع موظفك. التثبيت مقطع كود واحد فقط.

<!-- Cxperium chat -->
<script>
  window.cxperiumSettings = {
    channelKey: "ch_c727ccd3ef5112a1",
    secret: "f57b4e…",
    brand: "Acme Support",
    color: "#7c3aed",
    launcherText: "راسلنا",
    texts: { greetingMessage: "مرحبًا! كيف يمكننا مساعدتك؟" }
  };
  // Optional: introduce the signed-in user — the welcome form is skipped:
  // window.cxperiumSettings.user = { name: "Jane Doe", username: "jane.d" };
  (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>

1. انسخ الكود

   انقر على نسخ في الخطوة الأخيرة من إنشاء القناة أو في نافذة التفاصيل في قائمة القنوات. إذا خصّصت المظهر فانسخ الكود من مصمم الأداة؛ فذلك الكود يتضمن تصميمك.

2. الصقه في موقعك

   الصقه قبل وسم </body> مباشرة في كل صفحة تريد ظهور المحادثة فيها. يجب أن يكون في الصفحة مقطع Cxperium واحد فقط؛ احذف أي مقطع قديم.

3. أعد تحميل الصفحة

   يجب أن تظهر الفقاعة في الزاوية المختارة. إن لم تظهر فأعد التحميل دون ذاكرة التخزين المؤقت (Ctrl + F5).

تحفظ الأداة هوية الزائر ورمزه في المتصفح؛ وعندما يعود الزائر يمكنه متابعة محادثته السابقة أو فتح محادثة جديدة. إذا عرّفت مستخدمًا مسجّل الدخول عبر إعداد user فلن يظهر نموذج الترحيب إطلاقًا.

الأداة نفسها في تطبيق الجوال: يمكنك أيضًا استخدام قناة الجوال داخل WebView. تضبط شاشة WebView Customizer لقناة الجوال في قائمة القنوات مظهر الصفحة التي تضمّنها في تطبيقك، فتضيف المحادثة دون كتابة تكامل SDK الموضح أدناه.

مظهر الأداة (مصمم الأداة)

تغيّر لون الفقاعة وموضعها ونصوصها وعلامتها التجارية من لوحة التحكم. لا يُفتح المصمم إلا لقنوات نوع Web.

تصل إلى المصمم من مكانين: زر تخصيص المظهر في الخطوة الأخيرة عند إنشاء القناة، أو لاحقًا من نافذة التفاصيل للقناة في قائمة القنوات. تتكون الشاشة من ثلاثة أجزاء: الإعدادات على اليسار، ومعاينة حية على اليمين (عرضا المحادثة ونموذج الترحيب)، وكود التثبيت أسفل المعاينة. لا يوجد زر حفظ؛ ينعكس كل تغيير على المعاينة والكود خلال نصف ثانية تقريبًا.

العلامة التجارية

الألوان والخط

التخطيط والحجم

النصوص والسلوك

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

تطبيق الجوال (القناة المخصصة)

تربط قناة الجوال (القناة المخصصة) تطبيقك على iOS أو Android أو React Native أو Flutter مباشرة بـ Cxperium. يكتب المستخدم رسالة في التطبيق، ويرد الروبوت أو الموظف، ويصل الرد إلى التطبيق فورًا. لا حاجة إلى خادم.

مساران للإعداد

القرار يتوقف على سؤال واحد: هل سيقف خادمك الخاص بين تطبيقك وCxperium؟

إن لم يكن لديك خادم فاتبع المسار أ. تصف الخطوات أدناه المسار أ؛ وفي المسار ب تتغير ترويسة المصادقة فقط (انظر "إن كان لديك خادم: التوقيع").

الخطوة 1: التسجيل (مرة واحدة عند أول تشغيل)

const res = await fetch("https://provider.cxperium.com/custom/ch_xxxxxxxx/register", {
  method: "POST",
  headers: { "apiKey": SECRET, "Content-Type": "application/json" },
  body: JSON.stringify({ user: { name: "Jane" } }),
}).then((r) => r.json());

// res = { status: 200, channelKey: "ch_xxxxxxxx",
//         contact: { id: "c_5d5cdeb1-…" }, token: "8abfc196…" }
save("contactId", res.contact.id);   // Keychain / EncryptedSharedPreferences
save("token", res.token);             // never expires, obtained once

إذا أُعيد تثبيت التطبيق وما زال contactId المحفوظ لديك، فضمّنه في جسم التسجيل باسم user.id؛ فيُعاد الرمز نفسه وتستمر المحادثة من حيث توقفت. لا يمكن أن تحتوي هوية المستخدم على الحرف &.

الخطوة 2: الاتصال وجلب السجل (عند كل تشغيل)

import { io } from "socket.io-client";

const socket = io("https://ws.cxperium.com/custom", {
  transports: ["websocket"],
  auth: { channelKey: "ch_xxxxxxxx", user: contactId, token },
});

socket.on("connect", async () => {
  // ORDER MATTERS: connect first, THEN fetch history.
  let after = stored("lastSeq") || 0;
  for (;;) {
    const h = await fetch(
      `https://provider.cxperium.com/custom/ch_xxxxxxxx/messages?user=${contactId}&after=${after}&limit=50`,
      { headers: { Authorization: `Bearer ${token}` } },
    ).then((r) => r.json());
    for (const m of h.messages) render(m);
    if (!h.hasMore) break;
    after = h.cursor;   // advance from the page's cursor
  }
});

يعيد السجل الاتجاهين معًا: direction: "in" رسالة المستخدم نفسه (ارسمها يمينًا في واجهة LTR)، و"out" رد الروبوت أو الموظف. seq رقم تسلسلي متزايد لكل مستخدم. إن كنت تحفظ الرسائل محليًا فابدأ من آخر seq رأيته، وإلا فابدأ من 0.

الخطوة 3: الإرسال والاستقبال وتأكيد التسليم

// Send — id is the replay guard: on a network error resend with the SAME id
socket.emit("message.send",
  { user: { name: "Jane" }, message: { id: uniqueId(), type: "text", text: "hello" } },
  (ack) => { /* ack = { status: 202, messageId: "…" } */ });

// Receive — m = { id, seq, ts, type, text, choices, media, link, form }
socket.on("message.created", (m) => {
  if (seen.has(m.id)) return;
  seen.add(m.id);
  render(m);
  save("lastSeq", m.seq);
  socket.emit("message.ack", { seq: m.seq }, () => {});
});

إذا انقطع WebSocket يمكن إرسال الأجسام نفسها عبر REST: POST /custom/<KEY>/messages وPOST /custom/<KEY>/ack مع ترويسة Authorization: Bearer <token>. يعيد socket.io الاتصال تلقائيًا؛ وعند حدث connect شغّل جلب السجل من الخطوة 2 مجددًا لتصل الرسائل الفائتة.

• احفظ contactId والرمز بشكل دائم — يجب أن يبقيا بعد إغلاق التطبيق.
• WebSocket أولًا ثم السجل — الترتيب المعاكس يفوّت الرسائل التي تصل في الأثناء.
• أزل تكرار الرسائل بحسب id — يضمن النظام التسليم مرة واحدة على الأقل، لا مرة واحدة بالضبط.
• عند التقسيم إلى صفحات تقدّم بـ after من cursor الاستجابة — لا من عداد تحتفظ به أنت.
• لا داعي للقلق عند الانقطاع — اجلب السجل بعد إعادة الاتصال؛ لا تضيع أي رسالة.

إن كان لديك خادم: التوقيع (المسار ب)

يتحدث التطبيق مع خادمك، ويتحدث خادمك مع Cxperium. لا يصل السر إلى التطبيق أبدًا. يحمل كل طلب ترويسة X-Cxperium-Signature: t=<unix seconds>,v1=<hex> حيث v1 = HMAC-SHA256(secret, "<t>.<content>"). المحتوى هو نص JSON الخام لطلبات POST، والسلسلة "<channelKey>:<userId>" لاتصال WebSocket واستعلام السجل. التوقيع صالح لمدة 300 ثانية؛ أنشئ توقيعًا جديدًا لكل طلب.

const crypto = require("crypto");
function sign(content) {
  const t = Math.floor(Date.now() / 1000);
  const v1 = crypto.createHmac("sha256", CHANNEL_SECRET).update(`${t}.${content}`).digest("hex");
  return `t=${t},v1=${v1}`;
}

// For WebSocket, auth must be a FUNCTION — the signature is refreshed on reconnect
const socket = io("https://ws.cxperium.com/custom", {
  transports: ["websocket"],
  auth: (cb) => cb({ channelKey: CHANNEL_KEY, user: userId, signature: sign(`${CHANNEL_KEY}:${userId}`) }),
});

أنواع الرسائل والنماذج

جسم الرسالة نفسه يُستخدم في حدث WebSocket message.created وفي استعلام السجل وفي webhook التسليم. إذا وصل type لا تعرفه فاعرض حقل text؛ تُضاف أنواع جديدة مع الوقت وtext ممتلئ دائمًا.

ما يمكن إرساله من المستخدم إلى الروبوت

نوع الموقع (location) غير مدعوم بعد؛ إن أرسلته تتلقى 202 لكنه لا يُعالَج.

ما قد يصل من الروبوت

النماذج (Flow)

يستطيع الروبوت إرسال نماذج إلى قناة الجوال بالكود نفسه الذي يستخدمه لـ WhatsApp Flows. يصل تعريف النموذج داخل الرسالة في form.screens، والشاشات بصيغة Meta Flow JSON (TextInput وDropdown وRadioButtonsGroup وCheckboxGroup وDatePicker وFooter). ابدأ بـ form.screen؛ وform.data هي بيانات الشاشة الأولى. إن لم تستطع عرض النماذج فاعرض حقل text على الأقل.

• الإجابة: إذا كان إجراء Footer في الشاشة الأخيرة complete فأرسل الحقول المعبأة كرسالة عادية من نوع form؛ وtoken إلزامي.
• طلب شاشة من الخادم: إذا كان إجراء Footer هو data_exchange فاستدعِ POST /custom/<KEY>/flows/exchange؛ تكون الاستجابة { "version": "3.0", "screen": "…", "data": { … } }. إذا كانت screen تساوي SUCCESS فأغلق النموذج وأرسل الكائن data.extension_message_response.params كإجابة.
• تطبيق جاهز: تنفّذ أداة الويب هذا القسم بالكامل؛ ولا يحتاج تكامل WebView إلى عمل إضافي.

حل المشكلات

أكثر الحالات شيوعًا وحلولها.

أداة الويب

قناة الجوال