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

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

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

لماذا يجب عليّ استخدام اتصال WebSocket؟

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

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

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

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

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

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

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

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

كيفية الاتصال بـ Voxys Connect WebSocket؟

للاتصال بـ Voxys Connect WebSocket، استخدم الأمر subscribe وأدرج pubSubToken وaccountId وuserId (في حالة استخدام رمز مستخدم) في طلب الاتصال. فيما يلي مثال على كيفية الاتصال بـ Voxys Connect.

// أضف طريقة مساعدة لتحويل 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

للحفاظ على حالة المستخدمين متصلة بالإنترنت في Voxys Connect، يمكنك إرسال حدث تحديث حالة التواجد إلى Voxys Connect كل 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

الكائنات

يمكن أن يحتوي الحدث على أي من الكائنات التالية كحمولة. فيما يلي أنواع الكائنات المختلفة المدعومة في Voxys Connect.

المحادثة

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

{
  "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": "تاريخ ووقت"،
    "updated_at": "تاريخ ووقت"،
    "hmac_verified": "منطقي"
  },
  "messages": ["مصفوفة من كائنات الرسائل"],
  "meta": {
    "sender": {
 // كائن جهة الاتصال
    },
    "assignee": {
 // كائن المستخدم
    }
  },
  "status": "سلسلة"،
  "unread_count": "عدد صحيح"،
  "agent_last_seen_at": "طابع زمني unix"،
  "contact_last_seen_at": "unix-timestamp",
  "timestamp": "unix-timestamp",
  "account_id": "integer"
}

جهة الاتصال

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

{
  "additional_attributes": "كائن"،
  "custom_attributes": "كائن"،
  "email": "سلسلة"،
  "id": "عدد صحيح"،
  "identifier": "سلسلة أو فارغ"،
  "name": "سلسلة"،
  "phone_number": "string or null",
  "thumbnail": "string"
}

المستخدم

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

{
  "id": "integer",
  "name": "string",
  "available_name": "string",
  "avatar_url": "سلسلة"،
  "availability_status": "سلسلة"،
  "thumbnail": "سلسلة"
}

الرسالة

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

{
  "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

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

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