الرئيسية الدردشة المباشرة على الموقع الإلكتروني كيفية إرسال معلومات إضافية عن المستخدم إلى Voxys Connect باستخدام SDK؟

كيفية إرسال معلومات إضافية عن المستخدم إلى Voxys Connect باستخدام SDK؟

آخر تحديث في May 28, 2026

تمكّنك مجموعة تطوير البرمجيات (SDK) لموقع Voxys Connect من إرسال معلومات إضافية عن المستخدم إلى Voxys Connect.

إذا قمت بتثبيت الكود الخاص بنا على موقعك، فإن الـ SDK ستعرض كائن window.$chatwoot. للتأكد من أن الـ SDK قد تم تحميله بالكامل، يرجى التأكد من الاستماع إلى حدث chatwoot:ready كما يلي:

window.addEventListener("chatwoot:ready", function () {
  // استخدم window.$chatwoot هنا
  // ...
});

إذا كنت ترغب في الاستماع إلى الرسائل في الودجت، يمكنك استخدام الحدث التالي.

window.addEventListener('chatwoot:on-message', function(e) {
  console.log('chatwoot:on-message', e.detail)
})

إعدادات SDK​

لإخفاء الفقاعة، يمكنك استخدام الإعداد المذكور أدناه.

ملاحظة: إذا استخدمت هذا، يجب عليك أيضًا تفعيل الودجت.

window.chatwootSettings = {
  hideMessageBubble: false,
  showUnreadMessagesDialog: false, // تعطيل مربع الرسائل غير المقروءة
  position: "left", // يمكن أن تكون left أو right
  locale: "en", // تعيين اللغة
  useBrowserLanguage: false, // تعيين لغة الودجت من متصفح المستخدم
  type: "standard", // [standard, expanded_bubble]
  darkMode: "auto", // [light, auto]
  // baseDomain: "yourdomain.com" // قم بالتكوين إذا كنت تريد تتبع المستخدمين عبر النطاقات الفرعية
};

استخدام لغة المتصفح تلقائيًا في ودجت الدردشة الحية

لعرض ودجت الدردشة الحية بلغة متصفح المستخدم، قم بتعيين useBrowserLanguage إلى true في window.chatwootSettings المذكورة أعلاه.

ملاحظة: إذا تم تعيين useBrowserLanguage إلى true، سيتم تجاهل locale المذكورة. إذا لم تكن لغة المتصفح مدعومة من قبل Voxys Connect، سيتم استخدام اللغة المذكورة تحت locale. وإذا لم تكن موجودة أيضًا، فسيتراجع الودجت إلى locale لوحة تحكم الوكيل.

الوضع الداكن​

يدعم ودجت الدردشة الحية في Voxys Connect الوضع الداكن بدءًا من الإصدار 2.4.0. لتمكين الوضع الداكن، اتبع الخطوات المذكورة هنا.

تصاميم الودجت​

يدعم Voxys Connect تصميمين للودجت.

  1. القياسي (الافتراضي)

2. الفقاعة الموسعة

إذا كنت تستخدم الفقاعة الموسعة، يمكنك تخصيص النص المستخدم في الفقاعة عن طريق تعيين معامل launcherTitle في إعدادات voxys connect كما هو موضح أدناه.

window.chatwootSettings = {
  type: "expanded_bubble",
  launcherTitle: "الدردشة معنا",
};

تمكين نافذة منبثقة​

لتمكين النافذة المنبثقة، أضف التكوين التالي إلى chatwootSettings. هذا الخيار معطل بشكل افتراضي.

window.chatwootSettings = {
  // ...تكوينات أخرى
  showPopoutButton: true,
}

يمكنك أيضًا فتح نافذة الدردشة المنبثقة برمجيًا باستخدام الدالة `popoutChatWindow()`.

الرسائل المخصصة​

خصص رسائل الترحيب والتوفر المعروضة في رأس الودجت ومؤشرات حالة الفريق.

window.chatwootSettings = {
  // ...تكوينات أخرى

  welcomeTitle: "هل تحتاج مساعدة؟", // رأس الودجت المخصص
  welcomeDescription: "نحن هنا لدعمك.", // العنوان الفرعي للرأس
  availableMessage: "نحن متصلون وجاهزون للدردشة!", // عندما يكون الفريق متصلًا
  unavailableMessage: "نحن غير متصلين حاليًا." // عندما يكون الفريق غير متوفر
};

تبديل الميزات

تمكين أو تعطيل ميزات واجهة المستخدم الاختيارية داخل الودجت:

window.chatwootSettings = {
  // ...تكوينات أخرى

  enableFileUpload: true, // عرض زر إرفاق الملفات
  enableEmojiPicker: true, // تمكين اختيار الرموز التعبيرية في إدخال الدردشة
  enableEndConversation: true // السماح للمستخدمين بإنهاء المحادثة
};

فتح النافذة المنبثقة برمجيًا​

يمكنك فتح النافذة المنبثقة برمجيًا باستخدام الدالة popoutChatWindow().

لبدء ذلك، استدعِ الدالة كما يلي.

window.$chatwoot.popoutChatWindow();

تبديل ظهور فقاعة الودجت​

إذا كنت تريد إخفاء/عرض فقاعة ودجت Voxys Connect، يمكنك فعل ذلك باستخدام toggleBubbleVisibility('show/hide')

مثال

window.$chatwoot.toggleBubbleVisibility("show"); // لعرض الفقاعة
window.$chatwoot.toggleBubbleVisibility("hide"); // لإخفاء الفقاعة

تفعيل الودجت برمجيًا

إذا كنت تريد فتح نافذة الدردشة بالنقر على رابط في الموقع، اتبع الطريقة أدناه. في الإجراء الخاص بك، استدعِ SDK الخاص بـ Voxys Connect كما هو موضح أدناه.

window.$chatwoot.toggle();

// تبديل الودجت بتمرير الحالة
window.$chatwoot.toggle("open"); // لفتح الودجت
window.$chatwoot.toggle("close"); // لإغلاق الودجت

تعيين المستخدم في الودجت​

window.$chatwoot.setUser("<مفتاح-معرف-فريد-للمستخدم>", {
  email: "<[email protected]>",
  name: "<اسم-المستخدم>",
  avatar_url: "<رابط-الصورة-الشخصية-للمستخدم>",
  phone_number: "<رقم-هاتف-المستخدم>",
});

تقبل دالة setUser معرفًا يمكن أن يكون user_id في قاعدة بياناتك أو أي معلمة فريدة تمثل المستخدم. يمكنك تمرير البريد الإلكتروني، الاسم، رابط الصورة الشخصية، ورقم الهاتف كمعاملات. دعم المعلمات الإضافية قيد التنفيذ.

تأكد من إعادة تعيين الجلسة عند تسجيل خروج المستخدم من تطبيقك.

التحقق من الهوية باستخدام HMAC​

لمنع الانتحال وللحفاظ على خصوصية المحادثة مع عملائك، نوصي بإعداد التحقق من الهوية في Voxys Connect. يتم تفعيل التحقق من الهوية عن طريق إنشاء HMAC (رمز مصادقة الرسائل المعتمد على التجزئة) بناءً على خاصية identifier، باستخدام SHA256. بالإضافة إلى identifier يمكنك تمرير identifier_hash كما هو موضح أدناه للتأكد من أن المستخدم هو الصحيح.

window.$chatwoot.setUser(`<مفتاح-معرف-فريد-للمستخدم>`, {
  name: "", // اسم المستخدم
  avatar_url: "", // رابط الصورة الشخصية
  email: "", // البريد الإلكتروني للمستخدم
  identifier_hash: "", // تجزئة المعرف المولدة بناءً على webwidget hmac_token
  phone_number: "", // رقم هاتف المستخدم
  description: "", // وصف عن المستخدم
  country_code: "", // رمز الدولة المكون من حرفين
  city: "", // مدينة المستخدم
  company_name: "", // اسم الشركة
  social_profiles: {
    twitter: "", // اسم مستخدم تويتر
    linkedin: "", // اسم مستخدم لينكدإن
    facebook: "", // اسم مستخدم فيسبوك
    github: "", // اسم مستخدم جيتهاب
  },
});

لإنشاء HMAC، اقرأ التحقق من الهوية. لاحظ أن تنفيذ مصادقة HMAC سيسمح بالاحتفاظ بسجل الدردشة عبر الجلسات.

تعيين سمات مخصصة​

لتعيين معلومات إضافية عن العميل، يمكنك استخدام حقل السمات المخصصة للعميل. اقرأ المزيد عن السمات المخصصة هنا.

لتعيين سمة مخصصة، استدعِ setCustomAttributes كما يلي

window.$chatwoot.setCustomAttributes({
  accountId: 1,
  pricingPlan: "paid",

  // هنا المفتاح الذي تم تعريفه مسبقًا في السمة المخصصة
  // يجب أن تكون القيمة بناءً على النوع (يدعم حاليًا Number, Date, String و Number)
});

يمكنك عرض هذه المعلومات في اللوحة الجانبية للمحادثة.

لحذف سمة مخصصة، استخدم deleteCustomAttribute كما يلي

window.$chatwoot.deleteCustomAttribute("attribute-key");

تعيين اللغة يدويًا​

window.$chatwoot.setLocale("en");

لتعيين اللغة يدويًا، استخدم دالة setLocale.

تعيين العلامات على المحادثة​

يرجى ملاحظة أن العلامات سيتم تعيينها على المحادثة إذا لم يبدأ المستخدم محادثة. في هذه الحالة، لن يكون للعناصر التالية أي تأثير:

window.$chatwoot.setLabel("support-ticket");

window.$chatwoot.removeLabel("support-ticket");

تحديث الجلسة (استخدم هذا عند تسجيل خروج المستخدم من تطبيقك)​

window.$chatwoot.reset();

أخطاء الودجت​

لمشاهدة أي أخطاء في الودجت، يرجى التأكد من الاستماع إلى حدث chatwoot:event كما يلي:

window.addEventListener("chatwoot:error", function () {
  // ...
});

ملاحظة: هذه الميزة متاحة في الإصدار 2.3.0 وما بعده.

تخصيص رأس الترحيب والوصف

يمكنك تغيير:

  • عنوان الترحيب والوصف
  • الرسائل المعروضة عندما يكون فريقك متصلًا أو غير متصل
  • تمكين ميزات واجهة المستخدم بشكل انتقائي مثل رفع الملفات، اختيار الرموز التعبيرية، وزر إنهاء المحادثة
window.chatwootSettings = {
  welcomeTitle: 'هل تحتاج مساعدة؟',
  welcomeDescription: 'نحن هنا لدعمك.',
  availableMessage: 'نحن متصلون وجاهزون للدردشة!',
  unavailableMessage: 'نحن غير متصلين حاليًا.',

  enableFileUpload: true,
  enableEmojiPicker: true,
  enableEndConversation: true
 };