WebChat

توفر قناة WebChat أداة دردشة مدمجة وقابلة للتضمين تتصل بوكيل Triggerfish عبر WebSocket. صُممت للتفاعلات مع العملاء وأدوات الدعم، أو أي سيناريو تريد فيه تقديم تجربة دردشة عبر الويب.

التصنيف الافتراضي

يتم تصنيف WebChat افتراضياً كـ PUBLIC. هذا افتراضي ثابت لسبب وجيه: زوار الويب لا يُعاملون أبداً كمالك. كل رسالة من جلسة WebChat تحمل تلوث PUBLIC بغض النظر عن التكوين.

الزوار ليسوا مالكين أبداً بخلاف القنوات الأخرى حيث يتم التحقق من هوية المالك

بمعرّف المستخدم أو رقم الهاتف، يعيّن WebChat isOwner: false لجميع الاتصالات. هذا يعني أن الوكيل لن ينفذ أبداً أوامر على مستوى المالك من جلسة WebChat. هذا قرار أمني متعمد -- لا يمكنك التحقق من هوية زائر ويب مجهول. :::

الإعداد

الخطوة 1: تكوين Triggerfish

أضف قناة WebChat إلى triggerfish.yaml:

channels:
  webchat:
    port: 8765
    allowedOrigins:
      - "https://your-site.com"

الخيار	النوع	مطلوب	الوصف
port	number	لا	منفذ خادم WebSocket (الافتراضي: 8765)
classification	string	لا	مستوى التصنيف (الافتراضي: PUBLIC)
allowedOrigins	string[]	لا	أصول CORS المسموح بها (الافتراضي: ["*"])

الخطوة 2: تشغيل Triggerfish

triggerfish stop && triggerfish start

يبدأ خادم WebSocket بالاستماع على المنفذ المُعدّ.

الخطوة 3: توصيل أداة الدردشة

اتصل بنقطة نهاية WebSocket من تطبيق الويب الخاص بك:

const ws = new WebSocket("ws://localhost:8765");

ws.onopen = () => {
  console.log("Connected to Triggerfish");
};

ws.onmessage = (event) => {
  const frame = JSON.parse(event.data);

  if (frame.type === "session") {
    // الخادم عيّن معرّف جلسة
    console.log("Session:", frame.sessionId);
  }

  if (frame.type === "message") {
    // رد الوكيل
    console.log("Agent:", frame.content);
  }
};

// إرسال رسالة
function sendMessage(text) {
  ws.send(JSON.stringify({
    type: "message",
    content: text,
  }));
}

كيف يعمل

تدفق الاتصال

1. يفتح عميل المتصفح اتصال WebSocket إلى المنفذ المُعدّ
2. يُرقّي Triggerfish طلب HTTP إلى WebSocket
3. يُولّد معرّف جلسة فريد (webchat-<uuid>)
4. يرسل الخادم معرّف الجلسة للعميل في إطار session
5. يرسل ويستقبل العميل إطارات message بصيغة JSON

تنسيق إطار الرسالة

جميع الرسائل هي كائنات JSON بهذا الهيكل:

{
  "type": "message",
  "content": "Hello, how can I help?",
  "sessionId": "webchat-a1b2c3d4-..."
}

أنواع الإطارات:

النوع	الاتجاه	الوصف
session	من الخادم إلى العميل	يُرسل عند الاتصال مع معرّف الجلسة المُعيّن
message	كلا الاتجاهين	رسالة دردشة بمحتوى نصي
ping	كلا الاتجاهين	نبض للحفاظ على الاتصال
pong	كلا الاتجاهين	استجابة نبض الحفاظ على الاتصال

إدارة الجلسات

كل اتصال WebSocket يحصل على جلسته الخاصة. عند إغلاق الاتصال، تُزال الجلسة من خريطة الاتصالات النشطة. لا يوجد استئناف للجلسة -- إذا انقطع الاتصال، يُعيّن معرّف جلسة جديد عند إعادة الاتصال.

فحص الصحة

يستجيب خادم WebSocket أيضاً لطلبات HTTP العادية بفحص صحة:

curl http://localhost:8765
# الاستجابة: "WebChat OK"

هذا مفيد لفحوصات صحة موازن الحمل والمراقبة.

مؤشرات الكتابة

يرسل ويستقبل Triggerfish مؤشرات كتابة عبر WebChat. عندما يعالج الوكيل طلباً، يُرسل إطار مؤشر كتابة إلى العميل. يمكن للأداة عرضه لإظهار أن الوكيل يفكر.

اعتبارات أمنية

• جميع الزوار خارجيون -- isOwner دائماً false. لن ينفذ الوكيل أوامر المالك من WebChat.
• تلوث PUBLIC -- كل رسالة ملوثة بـ PUBLIC على مستوى الجلسة. لا يمكن للوكيل الوصول إلى أو إعادة بيانات فوق تصنيف PUBLIC في جلسة WebChat.
• CORS -- كوّن allowedOrigins لتقييد النطاقات التي يمكنها الاتصال. الافتراضي ["*"] يسمح بأي أصل، وهو مناسب للتطوير لكن يجب تقييده في الإنتاج.

قيّد الأصول في الإنتاج لنشر الإنتاج، حدد دائماً

الأصول المسموح بها صراحة:

channels:
  webchat:
    port: 8765
    allowedOrigins:
      - "https://your-domain.com"
      - "https://app.your-domain.com"

تغيير التصنيف

بينما يتم تصنيف WebChat افتراضياً كـ PUBLIC، يمكنك تقنياً تعيينه لمستوى مختلف. ومع ذلك، بما أن isOwner دائماً false، يظل التصنيف الفعّال لجميع الرسائل PUBLIC بسبب قاعدة التصنيف الفعّال (min(channel, recipient)).

channels:
  webchat:
    port: 8765
    classification: INTERNAL # مسموح، لكن isOwner لا يزال false

المستويات الصالحة: PUBLIC، INTERNAL، CONFIDENTIAL، RESTRICTED.