أداة الدردشة للموقع

أداة الدردشة هي المحادثة التي يراها زوار موقعكم. تُحمّل البوت الذي نشرتموه وتُدير المحادثة كاملة في المتصفح. بلا نموذج لغوي، وبلا طلبات إلى أطراف خارجية، وبحجم يقارب 22KB بعد الضغط. تُحمّل الدردشة مع موظف الدعم من ملف منفصل، عند تفعيلها فقط.

التثبيت

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

HTML

<script src="https://cdn.kavchat.com/v1/kavchat.js" data-key="pk_live_..." async></script>

يمكن وضع المفتاح العام (pk_live_...) في الصفحة. أما المفتاح السري (sk_live_...) فلا تضعوه في الصفحة أبدًا.

السمات

السمة	القيمة الافتراضية	الوصف
`data-key`	مطلوب	مفتاحكم العام.
`data-api`	`https://api.kavchat.com`	عنوان API.
`data-locale`	لغة المتصفح	لغة واجهة أداة الدردشة (الأزرار، النموذج، الإشعارات): `he`, `en`, `ar`, `ru`, `es`, `fr`, `de`, `pt`, `it`, `tr`. إذا لم تتوفر ترجمة للغة، تُستخدم لغة البوت. يظهر محتوى السيناريو دائمًا كما كتبتموه. تُعرض `he` و`ar` من اليمين إلى اليسار.
`data-user-token`	لا يوجد	رمز هوية لمستخدم سجّل دخوله. راجعوا التعرّف على المستخدمين.
`data-user-name`	لا يوجد	يظهر في رسالة الترحيب (`{name}`) ويُملأ مسبقًا في نموذج التذكرة.
`data-open`	`false`	عند ضبطها على `"true"`، تُفتح الدردشة فور تحميلها.

HTML

<script
  src="https://cdn.kavchat.com/v1/kavchat.js"
  data-key="pk_live_..."
  data-locale="he"
  data-user-token="<identity JWT>"
  data-user-name="Dana"
  data-open="false"
  async></script>

واجهة JavaScript

يُثبّت السكربت window.Kavchat:

JavaScript

Kavchat.init({
  publicKey: 'pk_live_...',
  apiBase: 'https://api.kavchat.com', // optional
  locale: 'he',                       // optional
  userToken: '<identity JWT>',        // optional
  userName: 'Dana',                   // optional
  open: false,                        // optional
  onScreen(screen, targetId) {},      // optional: "screen" buttons in your scripts
  onEvent(event) {},                  // optional: ready, unavailable, open, close, effect, ticket
});
Kavchat.open();
Kavchat.close();
Kavchat.toggle();
Kavchat.setUser({ token: '<identity JWT>', name: 'Dana' }); // on login; setUser(null) on logout
Kavchat.offset({ bottom: 80 });       // lift the launcher, e.g. above a cookie banner; offset(null) resets
Kavchat.destroy();

لا حاجة إلى init عندما يحتوي وسم السكربت على data-key. استدعاء init مرة أخرى يستبدل أداة الدردشة الحالية.

استدعاء الواجهة قبل تحميل السكربت

يحمل وسم السكربت السمة async، لذا قد تعمل شيفرتكم قبله. أنشئوا قائمة انتظار وأضيفوا إليها الاستدعاءات، وستنفّذها أداة الدردشة بالترتيب عند تحميلها. يُنفّذ init أولًا دائمًا، وتكون لإعداداته الأولوية على سمات الوسم.

HTML

<script>
  window.Kavchat = window.Kavchat || { q: [] };
  Kavchat.q.push(['init', { publicKey: 'pk_live_...', onScreen: function (s, id) { location.href = '/' + s + '/' + id; } }]);
  Kavchat.q.push(['setUser', { token: '<identity JWT>', name: 'Dana' }]);
</script>
<script src="https://cdn.kavchat.com/v1/kavchat.js" async></script>

كل عنصر في قائمة الانتظار هو [methodName, ...args]. حتى بعد تحميل السكربت، يظل Kavchat.q.push(...) يعمل وينفّذ الاستدعاء فورًا، لذا تصلح الشيفرة نفسها للحالتين.

مساحة لشريط ملفات تعريف الارتباط

إذا كان في الموقع عنصر ثابت أسفل الشاشة، مثل شريط ملفات تعريف الارتباط، يمكن إزاحة الزر والنافذة والفقاعات إلى أعلى هذا العنصر. هناك طريقتان: متغير CSS باسم --kavchat-bottom أو الأمر Kavchat.offset، الذي يقبل رقمًا بالبكسل أو قيمة طول مثل 5rem. تُضاف الإزاحة إلى الارتفاع المحدد في شاشة الإدارة. عند إغلاق الشريط، أزِل المتغير أو استدعِ offset(null). تعمل الطريقتان أيضًا في المواقع التي تطبّق سياسة CSP صارمة. على الهاتف، تُفتح النافذة بملء الشاشة ولا تتأثر بالإزاحة.

CSS

/* while your cookie banner is shown */
body.cookie-banner-open { --kavchat-bottom: 80px; }

JavaScript

// works before or after the widget script loads
window.Kavchat = window.Kavchat || { q: [] };
Kavchat.q.push(['offset', { bottom: banner.offsetHeight + 12 }]);

// after the visitor makes a choice
Kavchat.q.push(['offset', null]);

الأحداث

تستقبل الدالة onEvent أحد الأحداث التالية:

`type`	الحقول	متى يحدث
`ready`	`version`, `offline`	تم تحميل البوت من الشبكة، أو من النسخة المحفوظة عند انقطاع الاتصال.
`unavailable`	`reason?` (`'quota'`)	البوت متوقف، أو متاح لمستخدمي الاختبار فقط، أو نفدت الحصة. لا يظهر أي شيء.
`open`, `close`		فُتحت النافذة أو أُغلقت.
`effect`	`effect`	طلب زر فتح نموذج التذكرة أو رابط أو شاشة.
`ticket`	`id`, `number`	تم فتح تذكرة.
`live`	`state`, `id`	تغيّرت حالة المحادثة مع موظف الدعم: `queued`, `active`, `closed` أو `ticket`.

JavaScript

Kavchat.init({
  publicKey: 'pk_live_...',
  onEvent(event) {
    if (event.type === 'ready') console.log('Bot version', event.version, event.offline ? '(offline copy)' : '');
    if (event.type === 'ticket') console.log('Request opened', event.number);
  },
});

الإجراءات في السيناريو

تذكرة: يفتح نموذج التذكرة داخل الدردشة. يُرفق نص المحادثة بالتذكرة.
رابط: يفتح روابط https: وtel: في علامة تبويب جديدة (rel="noopener noreferrer"). لا تُفتح أنواع الروابط الأخرى.
شاشة: يستدعي دالتكم onScreen(screen, targetId). من دونها، لا يفعل الزر شيئًا على الموقع.

قائمة الشاشات في المحرّر

عرّفوا الشاشات التي يستطيع تطبيقكم فتحها مرة واحدة في الخيار screens ضمن Kavchat.init. تُرسل حزمة التطوير القائمة إلى Kavchat تلقائيًا، ويعرض محرّر السيناريوهات هذه الشاشات بأسمائها في قائمة منسدلة بدلًا من حقل نص حر. يطلب المحرّر أيضًا معرّف عنصر عندما تحتاج إليه الشاشة، وينبّه إلى أي زر يؤدي إلى شاشة لم تُعرّف. لا أحد يُدخل قائمة الشاشات يدويًا في لوحة التحكم.

JavaScript

Kavchat.init({
  publicKey: 'pk_live_...',
  screens: [
    { id: 'orders', label: 'My orders' },
    { id: 'product', label: 'Product page', needsTarget: true }, // the button also carries a product id
  ],
  onScreen(screen, targetId) {
    location.href = targetId ? `/${screen}/${targetId}` : `/${screen}`;
  },
});

id هو القيمة التي تصل إلى onScreen: أحرف لاتينية، وأرقام، و_، و.، و-، بحد أقصى 40 محرفًا. label هو الاسم الذي يراه المسؤول، بحد أقصى 60 محرفًا. الحد الأقصى 100 شاشة. تُستبعد السجلات غير الصالحة والمعرّفات المكررة.
needsTarget: يحمل الزر أيضًا معرّف عنصر (مثل معرّف منتج)، ويصل إلى onScreen بوصفه targetId.
تُرسل القائمة في الخلفية بعد تحميل الإصدار، فقط عند تغيّرها أو مرة في الأسبوع. لا يظهر أي إشعار عند فشل الإرسال، وتُعاد المحاولة عند التشغيل التالي. لا يرى المستخدم أي شيء.
تظهر الشاشات المسجّلة في لوحة التحكم ضمن البوت، الإعدادات، "شاشات التطبيق"، مع المنصات التي أبلغت عن كل شاشة. يمكنكم من هناك حذف شاشة أزلتموها من التطبيق.

التعرّف على مستخدميكم

لربط المحادثات والتذاكر بمعرّف المستخدم لديكم، أو لعرض البوت لمستخدمي الاختبار فقط، وقّعوا JWT على الخادم ومرّروه عبر data-user-token أو userToken. عند تسجيل المستخدم دخوله أو خروجه، استدعوا Kavchat.setUser(...). تُرسل أداة الدردشة الرمز في الترويسة Authorization: Bearer <token> مع كل استدعاء، ويمكن للمستخدم الذي سجّل دخوله فتح تذكرة دون ترك بريد إلكتروني أو رقم هاتف. لمعرفة كيفية إنشاء الرمز: التعرّف على المستخدمين.

سياسة CSP

تعمل الأداة على موقع يطبّق CSP صارمة، دون 'unsafe-inline' ودون 'unsafe-eval'. يكفي السماح بالمصدرين الخاصين بنا:

CSP

script-src https://cdn.kavchat.com;
connect-src https://api.kavchat.com;

تُحمَّل الأنماط بصيغة constructable stylesheets داخل Shadow DOM، لذا لا حاجة إلى تعديل style-src. إذا كانت للبوت صورة خاصة به أو كانت السيناريوهات تتضمن صورًا، فأضيفوا إلى img-src الخادم الذي تُحمَّل منه هذه الصور. لا تُحمِّل الأداة أي شيء من مصدر آخر، ولا تفتح iframe.

الدردشة مع موظف الدعم

لا حاجة إلى إعداد أي شيء على الموقع. عند تفعيل الدردشة مع موظفي الدعم في شاشة الإدارة، تُحمّل أداة الدردشة ملفًا إضافيًا، kavchat-live.js، من المجلد نفسه وبالإصدار نفسه لملف kavchat.js. المواقع التي لا تستخدم الدردشة مع موظفي الدعم لا تُنزّل هذا الملف إطلاقًا.

الخيار: يظهر خيار "محادثة مع موظف الدعم" بجانب "التواصل مع الفريق"، فقط بعد تأكيد الخادم وجود موظف متاح. خارج ساعات العمل، أو عندما يكون جميع الموظفين مشغولين، يظهر نموذج تذكرة فقط. وبجانبه توضيح قصير، وموعد عودة الفريق إن كان معروفًا. عند نفاد الحصة الشهرية، يظهر النموذج دون توضيح.
الطلب: يترك الزوار بريدًا إلكترونيًا أو رقم هاتف، تحسبًا لعدم تفرّغ أي موظف في الوقت المحدد. ويمكنهم أيضًا إضافة اسم ورسالة أولى. عندما يكون أكثر من قسم واحد مفتوحًا، يختارون قسمًا. لا يحتاج المستخدمون الذين تم التعرّف عليهم (userToken) إلى إدخال بيانات الاتصال. إذا لم يتمكّن أي موظف من قبول المحادثة، يُفتح نموذج تذكرة بالبيانات التي أُدخلت بالفعل.
الانتظار: تظهر عبارة "بانتظار موظف الدعم" مع عدّ تنازلي حتى نهاية مدة الانتظار التي حدّدتموها، وزرّي "ترك رسالة بدلًا من الانتظار" و"إنهاء المحادثة". يمكن الكتابة أثناء الانتظار. عند انتهاء الوقت، تتحوّل المحادثة تلقائيًا إلى تذكرة. يظهر للزائر رقم التذكرة وتوضيح بأن أيًا من الموظفين لم يتفرّغ في الوقت المحدد.
المحادثة: اسم الموظف، والرسائل، ومؤشر الكتابة، والتحويل إلى موظف آخر، وإنهاء المحادثة. يُعرض كل ما يصل من الخادم كنص عادي، بلا HTML وبلا روابط. تقرأ قارئات الشاشة الرسائل الجديدة، وعندما تكون النافذة مغلقة تظهر نقطة على الزر العائم.
التحديث الفوري: يتم الاتصال باستخدام Server-Sent Events. إذا انقطع الاتصال، تحاول أداة الدردشة إعادة الاتصال بفواصل زمنية تتزايد تدريجيًا، وتستكمل كل ما فاتها. وهكذا لا تضيع أي رسالة ولا تظهر مرتين. في الشبكات التي تحجب هذا الاتصال، تنتقل الأداة إلى الاستعلام المتكرر (long-poll). لكل رسالة معرّف، لذا لا تؤدي إعادة المحاولة إلى تكرارها. تُميّز الرسالة التي لم تُرسل، ويمكن إعادة إرسالها بنقرة.
إعادة التحميل: تُحفظ بيانات اعتماد الوصول إلى المحادثة في localStorage حسب المفتاح العام والمحادثة، ولا تُحفظ في العنوان أبدًا. تبقى صالحة لمدة تصل إلى 12 ساعة أو حتى انتهاء المحادثة. وهكذا تُستعاد المحادثة كاملة بعد إعادة التحميل أو الانتقال إلى صفحة أخرى: الجزء مع البوت، ثم الجزء مع موظف الدعم.
بلا طلب preflight: تُرسل الاستدعاءات دون ترويسات خاصة، ويكون جسم الطلب JSON يُرسل بنوع text/plain.

إجابات الذكاء الاصطناعي (Premium)

لا حاجة إلى إعداد أي شيء على الموقع. عند تفعيل إجابات الذكاء الاصطناعي في شاشة الإدارة (باستخدام مفتاحكم الخاص لدى مزوّد ذكاء اصطناعي)، يُرسل إلى Kavchat أي سؤال لا يجيب عنه أي سيناريو. وأثناء الانتظار، لمدة تصل إلى 20 ثانية، تُظهر الدردشة أن البوت يكتب. تظهر الإجابة كنص عادي مع وسم صغير "إجابة الذكاء الاصطناعي" بلغة الواجهة، وتحتها زر لموضوع ذي صلة، إن وُجد، وزر "التواصل مع الفريق".

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

كيف تعمل أداة الدردشة

العزل: يُعرض كل شيء داخل Shadow DOM. لا تؤثر تنسيقات CSS لديكم على أداة الدردشة، ولا تؤثر تنسيقات CSS الخاصة بالأداة على الصفحة.
التخزين المؤقت: يُحفظ البوت المنشور في localStorage حسب المفتاح العام، مع قيمة ETag الخاصة به. تُرسل الترويسة If-None-Match عند كل تحميل، ويرد الخادم بالرمز 304 عندما لا يتغيّر شيء. عند انقطاع الشبكة، تستخدم أداة الدردشة النسخة المحفوظة وتعرض إشعارًا بذلك.
المحادثات: يُحفظ معرّف عشوائي للمحادثة في sessionStorage، بحيث تستمر المحادثة نفسها عند التنقّل بين الصفحات.
الدردشة مع موظف الدعم: تُحفظ المحادثة المفتوحة في localStorage وتُستعاد في الصفحة التالية.
البيانات: تُرسل بيانات سير المحادثة بعد نحو 2 ثانية من كل إجراء، وكذلك عندما تصبح الصفحة مخفية.
شارة Kavchat: تظهر في جميع الباقات. في Premium، يمكنكم إخفاؤها من إعدادات البوت.
إمكانية الوصول: النافذة عبارة عن مربع حوار مُسمّى، ينتقل التركيز إليه ثم يعود منه، ويُغلقه مفتاح Esc. الأزرار عناصر أزرار فعلية، وتُقرأ رسائل البوت الجديدة، وتُقلَّل الرسوم المتحركة عندما يطلب الزائر ذلك.

التثبيت من npm

في تطبيق أحادي الصفحة، يمكنكم تضمين أداة الدردشة في حزمة شيفرتكم بدلًا من تحميل وسم السكربت:

Terminal

yarn add @kavchat/widget
# or: npm install @kavchat/widget

JavaScript

import { createWidget } from '@kavchat/widget';

const widget = createWidget({ publicKey: 'pk_live_...' });
await widget.ready;
widget.open();