واجهة محادثة الموقع البرمجية

بعد أن تضع كود محادثة الموقع في صفحتك (راجع إضافة محادثة الموقع)، يستطيع JavaScript موقعك أن يتحكّم فيها. كل شيء تحت ثلاثة أسماء: window.hadirSettings وwindow.hadirSDK وwindow.$hadir.

تشغيل المحادثة

الكود يحمّل https://app.hadir.chat/packs/js/sdk.js ثم يستدعي:

window.hadirSDK.run({ websiteToken: '…', baseUrl: 'https://app.hadir.chat' });

أبقِ الكود كما تعطيك إياه لوحة التحكم؛ قيمة websiteToken خاصة بقناتك.

إعدادات قبل التحميل

اضبط window.hadirSettings في سكربت يعمل قبل كود المحادثة:

<script>
  window.hadirSettings = {
    locale: 'ar',            // لغة المحادثة
    position: 'auto',        // 'left' أو 'right' أو 'auto' (يتبع اتجاه الصفحة)
    darkMode: 'auto',        // 'light' أو 'dark' أو 'auto'
    hideMessageBubble: false // true يخفي زر المحادثة، وتفتحها بـ toggle()
  };
</script>

ومتاح أيضاً: useBrowserLanguage: true لتظهر المحادثة بلغة متصفح الزائر بدل locale.

الأوامر

استدعها فقط بعد أن تجهز المحادثة (راجع hadir:ready بالأسفل).

• $hadir.toggle('open') أو toggle('close'): يفتح نافذة المحادثة أو يغلقها، وبدون قيمة يبدّل بينهما.
• $hadir.toggleBubbleVisibility('hide') أو ('show'): يخفي زر المحادثة أو يظهره.
• $hadir.popoutChatWindow(): يفتح المحادثة في نافذة متصفح مستقلة.
• $hadir.setUser(identifier, user): يعرّف المحادثة بالعميل المسجّل دخوله (بالأسفل).
• $hadir.setCustomAttributes({ plan: 'gold' }) وdeleteCustomAttribute('plan'): السمات المخصّصة لجهة الاتصال.
• $hadir.setConversationCustomAttributes({ order_id: '1001' }) وdeleteConversationCustomAttribute('order_id'): سمات المحادثة الحالية.
• $hadir.setLabel('vip') وremoveLabel('vip'): وسم على المحادثة الحالية، ويجب أن يكون الوسم موجوداً في مساحة عملك.
• $hadir.setLocale('en'): يغيّر لغة المحادثة.
• $hadir.setColorScheme('dark'): 'light' أو 'dark' أو 'auto'.
• $hadir.reset(): يمسح الزائر ومحادثته من هذا المتصفح. استدعه عند تسجيل خروج العميل.

مفاتيح السمات يجب أن تطابق سمات مخصّصة أنشأتها؛ راجع السمات المخصّصة.

مرّر العميل المسجّل دخوله

window.addEventListener('hadir:ready', function () {
  window.$hadir.setUser('cust-1001', {
    name: 'سارة',
    email: '[email protected]',
    phone_number: '+966500000000',
    identifier_hash: 'تحسبه على خادمك'
  });
});

• القيمة الأولى هي معرّف العميل في نظامك، نصاً أو رقماً.
• الكائن يحتاج واحداً على الأقل من name أو email أو avatar_url، وإلا يظهر خطأ.
• identifier_hash هو HMAC SHA256 للمعرّف نفسه، بالمفتاح السري لقناتك. احسبه على خادمك فقط. طريقة الحصول على المفتاح والحساب في التحقق من هوية الزوار.

الأحداث

تطلق المحادثة هذه الأحداث على window، وإن كان معها بيانات فهي في event.detail.

• hadir:ready: حُمّلت المحادثة وصار بالإمكان استدعاء الأوامر.
• hadir:opened وhadir:closed: فتح الزائر النافذة أو أغلقها.
• hadir:on-message: وصلت رسالة في المحادثة.
• hadir:on-start-conversation: بدأ الزائر محادثة جديدة.
• hadir:postback: ضغط الزائر زراً في رسالة.
• hadir:error: فشل شيء، مثل استدعاء setUser بقيمة identifier_hash خاطئة.

window.addEventListener('hadir:on-message', function (e) {
  console.log('رسالة جديدة', e.detail);
});

ملاحظة: الأسماء التي تبدأ بـ hadir أعلاه فقط هي التي تعمل. إن نسخت كوداً لأداة محادثة أخرى فغيّر أسماء أوامرها؛ لا توجد أسماء بديلة.