كيفية إعداد اتصال WebSocket؟

تُنشئ WebSockets اتصالاً مستمراً بين العميل والخادم، مما يتيح الاتصال ثنائي الاتجاه. يستخدم Chatwoot هذا الاتصال لتوفير التحديثات الفورية حول أحداث المنصة. للاتصال بـ Chatwoot WebSocket، ما عليك سوى تقديم رمز مميز واتباع تعليمات الإعداد الموضحة في هذا الدليل.

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

لماذا يجب أن أستخدم اتصال WebSocket؟

يسمح اتصال WebSocket بتحديثات البيانات في الوقت الفعلي، مما يجعله مثالياً للعملاء مثل حزمة SDK لعملاء Android أو iOS لـ Chatwoot. يساعد ذلك في تحديث لوحة المعلومات دون الحاجة إلى إعادة تحميل الصفحة. وبالتالي، يمكنه تعزيز تجربة المستخدم وتحسين إنتاجية الوكيل.

كيف يمكنني إعداد اتصال WebSocket مع Chatwoot؟

لإعداد اتصال WebSocket مع Chatwoot، تحتاج إلى بدء اتصال باستخدام رمز PubSub الخاص بالمصادقة المقدم من Chatwoot. عنوان URL للاتصال هو wss://<your-installation-url>/cable. إذا كنت تستخدم Chatwoot Cloud، يمكنك استخدام wss://app.chatwoot.com/cable كعنوان URL.

رمز PubSub هو رمز يُستخدم لمصادقة العميل عند الاتصال بخدمة PubSub (النشر/الاشتراك). يجب على العميل تقديم هذا الرمز للخدمة من أجل إنشاء الاتصال وبدء النشر أو الاشتراك في الرسائل.

هناك نوعان من رموز PubSub المتاحة في Chatwoot كما هو موضح أدناه.

1. رمز PubSub للمستخدم: يمتلك هذا الرمز امتيازات الوكيل/المسؤول وسيتلقى جميع الأحداث المدرجة لاحقاً في الصفحة. يمكنك الحصول على رمز PubSub من خلال الاتصال بـ واجهة تعريف الملف الشخصي.

2. رمز PubSub لجهة الاتصال: ينشئ Chatwoot رمز PubSub فريد لكل جلسة لجهة الاتصال. يمكن استخدام هذا الرمز للاتصال بـ WebSocket وتلقي التحديثات الفورية لنفس الجلسة. عند إنشاء جهة اتصال من خلال الواجهات العامة، يتم تضمين pubsub_token في حمولة الاستجابة. يمنح هذا الرمز الوصول فقط للأحداث المتعلقة بالجلسة الحالية مثل conversation.created، conversation.status_changed، message.created، message.updated، conversation_typing_on، conversation_typing_off و presence.update.

يرجى الرجوع إلى واجهات برمجة التطبيقات للعميل لبناء تكاملات تفاعلية مع العملاء باستخدام Chatwoot.

ملاحظة: قد يتم تحديث هذا الرمز بشكل منتظم حسب نوع التثبيت لديك. يرجى التأكد من أنك تستخدم أحدث رمز.

كيف يمكنني الاتصال بـ Chatwoot WebSocket؟

للاتصال بـ Chatwoot WebSocket، استخدم الأمر subscribe وضمن طلب الاتصال أضف pubSubToken، و accountId، و userId (إذا كنت تستخدم رمز المستخدم). فيما يلي مثال على كيفية الاتصال بـ Chatwoot.

 // أضف دالة مساعدة لتحويل JSON إلى سلسلة نصية
const stringify = (payload = {}) => JSON.stringify(payload);

const pubSubToken = "<contact/user-pub-sub-token>";
const accountId = "<your-account-id-in-integer>";
const userId = "<user-id-in-integer-if-using-user-token>";
const connection = new WebSocket(
  "wss://app.chatwoot.com/cable"
);

connection.send(
  stringify({
    command: "subscribe",
    identifier: stringify({
      channel: "RoomChannel",
      pubsub_token: pubSubToken,
      account_id: accountId,
      user_id: userId,
    }),
  })
);

// السلسلة المتوقعة في connection.send هي بالتنسيق التالي:
// {"command":"subscribe","identifier":"{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\"your-pubsub-token\\",\\"account_id\\": account_id_integer,\\"user_id\\":user_id_integer }"}

نشر الحضور إلى خادم WebSocket

للحفاظ على حالة المستخدمين نشطة في Chatwoot، يمكنك إرسال حدث لتحديث الحضور إلى Chatwoot كل 30 ثانية. هذا الإجراء سيبقي حالة الوكيل/جهة الاتصال على الإنترنت.

كيف يتم تحديث حالة الحضور لوكيل/مسؤول؟

لتحديث حالة الحضور لوكيل أو مسؤول، أرسل الحمولة التالية إلى الخادم:

const userPayload = stringify({
  command: "message",
  identifier: stringify({
    channel: "RoomChannel",
    pubsub_token: "<user-pubsub-token>",
    account_id: accountId,
    user_id: userId,
  }),
  data: stringify({ action: "update_presence" }),
});

connection.send(userPayload);
// السلسلة المتوقعة في connection.send هي بالتنسيق التالي:
// {"command":"message","identifier":"{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\"your-pubsub-token\\",\\"account_id\\": account_id_integer,\\"user_id\\":user_id_integer ","data":"{\\"action\\":\\"update_presence\\"}"}

كيف يتم تحديث حالة الحضور لجهة الاتصال؟

لتحديث حالة الحضور لجهة اتصال، أرسل الحمولة التالية إلى الخادم:

const agentPayload = stringify({
  command: "message",
  identifier: stringify({
    channel: "RoomChannel",
    pubsub_token: "<user-pubsub-token>",
  }),
  data: stringify({ action: "update_presence" }),
});

connection.send(agentPayload);
// السلسلة المتوقعة في connection.send هي بالتنسيق التالي:
// {"command":"message","identifier":"{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\"your-pubsub-token\\","data":"{\\"action\\":\\"update_presence\\"}"}

حمولة WebSocket

الكائنات

يمكن أن يحتوي الحدث على أي من الكائنات التالية كحمولة. أنواع الكائنات المدعومة في Chatwoot هي كما يلي.

المحادثة

سيتم إرجاع الحمولة التالية لمحادثة.

{
  "additional_attributes": {
    "browser": {
      "device_name": "string",
      "browser_name": "string",
      "platform_name": "string",
      "browser_version": "string",
      "platform_version": "string"
    },
    "referer": "string",
    "initiated_at": {
      "timestamp": "iso-datetime"
    }
  },
  "can_reply": "boolean",
  "channel": "string",
  "id": "integer",
  "inbox_id": "integer",
  "contact_inbox": {
    "id": "integer",
    "contact_id": "integer",
    "inbox_id": "integer",
    "source_id": "string",
    "created_at": "datetime",
    "updated_at": "datetime",
    "hmac_verified": "boolean"
  },
  "messages": ["Array of message objects"],
  "meta": {
    "sender": {
      // كائن جهة الاتصال
    },
    "assignee": {
      // كائن المستخدم
    }
  },
  "status": "string",
  "unread_count": "integer",
  "agent_last_seen_at": "unix-timestamp",
  "contact_last_seen_at": "unix-timestamp",
  "timestamp": "unix-timestamp",
  "account_id": "integer"
}

جهة الاتصال

سيتم إرجاع الحمولة التالية لجهة الاتصال.

{
  "additional_attributes": "object",
  "custom_attributes": "object",
  "email": "string",
  "id": "integer",
  "identifier": "string or null",
  "name": "string",
  "phone_number": "string or null",
  "thumbnail": "string"
}

المستخدم

سيتم إرجاع الحمولة التالية للوكيل/المسؤول.

{
  "id": "integer",
  "name": "string",
  "available_name": "string",
  "avatar_url": "string",
  "availability_status": "string",
  "thumbnail": "string"
}

الرسالة

سيتم إرجاع الحمولة التالية لرسالة.

{
  "id": "integer",
  "content": "string",
  "account_id": "integer",
  "inbox_id": "integer",
  "message_type": "integer",
  "created_at": "unix-timestamp",
  "updated_at": "datetime",
  "private": "boolean",
  "status": "string",
  "source_id": "string / null",
  "content_type": "string",
  "content_attributes": "object",
  "sender_type": "string",
  "sender_id": "integer",
  "external_source_ids": "object",
  "sender": {
    "type": "string - contact/user"
    // كائن المستخدم أو جهة الاتصال
  }
}

الإشعار

سيتم إرجاع الحمولة التالية لإشعار.

{
  "id": "integer",
  "notification_type": "string",
  "primary_actor_type": "string",
  "primary_actor_id": "integer",
  "primary_actor": {
    "can_reply": "boolean",
    "channel": "string",
    "id": "integer",
    "inbox_id": "integer",
    "meta": {
      "assignee": {
        "id": "integer",
        "name": "string",
        "available_name": "string",
        "avatar_url": "string",
        "type": "user",
        "availability_status": "string",
        "thumbnail": "string"
      },
      "hmac_verified": "boolean"
    },
    "agent_last_seen_at": "unix-timestamp",
    "contact_last_seen_at": "unix-timestamp",
    "timestamp": "unix-timestamp",
  },
  "read_at": "unix-timestamp",
  "secondary_actor": "object/null",
  "created_at":"unix-timestamp",
  "account_id": "integer",
  "push_message_title": "string"
}

المعرف

سيكون لدى كل حدث سمة identifier بالتنسيق التالي.

{
  "identifier": "{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\"token\\",\\"account_id\\":id,\\"user_id\\":user_id}"
}

الرسالة

سيحتوي كل حدث على سمة message والتي نُرجِع من خلالها اسم الحدث بالإضافة إلى البيانات المرتبطة به. للاطلاع على قائمة الأحداث، يرجى مراجعة الوثائق أدناه.

أنواع الأحداث

conversation.created

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

متاح لـ: وكيل/مسؤول، جهة اتصال

{
  "message": {
    "event": "conversation.created",
    "data": {
      // كائن المحادثة سيكون متاحاً هنا
    }
  }
}

conversation.read

يتم إطلاق هذا الحدث وإرساله إلى الوكلاء/المسؤولين الذين لديهم حق الوصول إلى البريد الوارد، عندما تقوم جهة الاتصال بقراءة رسالة.

متاح لـ: وكيل/مسؤول

{
  "message": {
    "event": "conversation.read",
    "data": {
      // كائن المحادثة سيكون متاحاً هنا
    }
  }
}

message.created

يتم إطلاق هذا الحدث وإرساله إلى الوكلاء، المسؤولين، وجهات الاتصال عندما يتم إنشاء رسالة جديدة في محادثة لديهم حق الوصول إليها.

متاح لـ: وكيل/مسؤول، جهة اتصال

{
  "message": {
    "event": "message.created",
    "data": {
      // كائن الرسالة سيكون متاحاً هنا
    }
  }
}

message.updated

يتم إطلاق هذا الحدث وإرساله إلى الوكلاء، المسؤولين، وجهات الاتصال عند تحديث رسالة في محادثة لديهم حق الوصول إليها.

متاح لـ: وكيل/مسؤول، جهة اتصال

{
  "message": {
    "event": "message.updated",
    "data": {
      // كائن الرسالة سيكون متاحاً هنا
    }
  }
}

conversation.status_changed

يتم إرسال هذا الحدث إلى الوكلاء، المسؤولين، وجهات الاتصال عند تحديث حالة محادثة.

متاح لـ: وكيل/مسؤول، جهة اتصال

{
  "message": {
    "event": "conversation.status_changed",
    "data": {
      // كائن المحادثة سيكون متاحاً هنا
    }
  }
}

conversation.typing_on

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

متاح لـ: وكيل/مسؤول، جهة اتصال

{
  "message": {
    "event": "conversation.typing_on",
    "data": {
      "conversation": {
        // كائن المحادثة سيكون متاحاً هنا
      },
      "user": {
        // كائن المستخدم – جهة اتصال/وكيل/مسؤول سيكون متاحاً هنا.
      },
      "is_private": "boolean", // يُظهر ما إذا كان الوكيل يكتب ملاحظة خاصة أم لا.
      "account_id": "integer"
    }
  }
}

conversation.typing_off

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

متاح لـ: وكيل/مسؤول، جهة اتصال

{
  "message": {
    "event": "conversation.typing_off",
    "data": {
      "conversation": {
        // كائن المحادثة سيكون متاحاً هنا
      },
      "user": {
        // كائن جهة الاتصال / المستخدم سيكون متاحاً هنا.
      },
      "account_id": "integer"
    }
  }
}

assignee.changed

يتم إرسال هذا الحدث إلى الوكلاء/المسؤولين الذين لديهم حق الوصول إلى البريد الوارد عند تغيير الوكيل المخصص.

متاح لـ: وكيل/مسؤول

{
  "message": {
    "event": "assignee.changed",
    "data": {
      // كائن المحادثة سيكون متاحاً هنا
    }
  }
}

team.changed

يتم إرسال هذا الحدث إلى الوكلاء/المسؤولين الذين لديهم حق الوصول إلى البريد الوارد عند تغيير الفريق المخصص.

متاح لـ: وكيل/مسؤول

{
  "message": {
    "event": "team.changed",
    "data": {
      // كائن المحادثة سيكون متاحاً هنا
    }
  }
}

conversation.contact_changed

يتم إرسال هذا الحدث إلى الوكلاء/المسؤولين عندما يتم دمج جهتي اتصال وجمع جميع محادثاتهم تحت جهة اتصال واحدة.

متاح لـ: وكيل/مسؤول

{
  "message": {
    "event": "conversation.contact_changed",
    "data": {
      // كائن المحادثة سيكون متاحاً هنا
    }
  }
}

contact.created

يتم إرسال هذا الحدث إلى الوكلاء/المسؤولين عند إنشاء جهة اتصال.

متاح لـ: وكيل/مسؤول

{
  "message": {
    "event": "contact.created",
    "data": {
      // كائن جهة الاتصال سيكون متاحاً هنا
    }
  }
}

contact.updated

يتم إرسال هذا الحدث إلى الوكلاء/المسؤولين عند تحديث جهة اتصال.

متاح لـ: وكيل/مسؤول

{
  "message": {
    "event": "contact.updated",
    "data": {
      // كائن جهة الاتصال سيكون متاحاً هنا
    }
  }
}

presence.update

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

متاح لـ: وكيل/مسؤول

{
  "message": {
    "event": "presence.update",
    "data": {
      "account_id": "integer",
      "users": {
        "user-id": "string"
      },
      "contacts": {
        "contact-id": "string"
      }
    }
  }
}

notification_created

يتم إرسال هذا الحدث إلى الوكلاء/المسؤولين عند إنشاء إشعار.

متاح لـ: وكيل/مسؤول