لإنشاء وتكوين صندوق وارد لقناة API في تثبيتات Voxys Connect، اتبع الخطوات الموضحة أدناه.
إعداد قناة API
الخطوة 1. اذهب إلى الإعدادات → صناديق الوارد → "إضافة صندوق وارد".
الخطوة 2. انقر على أيقونة "API".
الخطوة 3. قدم اسمًا للقناة وعنوان URL للرد. إليك مثال:
الخطوة 4. "أضف وكلاء" إلى صندوق وارد API الخاص بك.
تم الانتهاء من إعداد صندوق الوارد.
إرسال الرسائل إلى قناة API
لإرسال الرسائل إلى قناة API، تأكد من فهم النماذج التالية والتسمية المستخدمة في Voxys Connect.
- القناة: القناة تحدد نوع مصدر المحادثات. مثلًا، فيسبوك، تويتر، API، إلخ.
- صندوق الوارد: يمكنك إنشاء مصادر متعددة للمحادثات من نفس نوع القناة. مثلًا، يمكنك ربط أكثر من صفحة فيسبوك بحساب Voxys Connect. كل صفحة تسمى صندوق الوارد في Voxys Connect.
- المحادثة: المحادثة هي مجموعة من الرسائل.
- جهة الاتصال: كل محادثة مرتبطة بشخص حقيقي يسمى جهة اتصال.
- صناديق وارد جهة الاتصال: هذه هي الجلسة لكل جهة اتصال في صندوق وارد. يمكن لجهة الاتصال أن يكون لها جلسات متعددة ومحادثات متعددة في نفس صندوق الوارد.
كيف ترسل رسالة في قناة API؟
لإرسال رسالة في قناة API، أنشئ جهة اتصال، ابدأ محادثة، وأخيرًا أرسل الرسالة.
تتطلب واجهات برمجة التطبيقات api_access_token في رأس الطلب. يمكنك الحصول على هذا الرمز بزيارة إعدادات ملفك الشخصي → رمز الوصول.
1. إنشاء جهة اتصال
مرجع: توثيق API
مرر معرف صندوق الوارد لقناة API مع المعلمات الأخرى المحددة. سيؤدي هذا إلى إنشاء جلسة تلقائيًا. رد العينة سيكون كما يلي.
{
"email": "string",
"name": "string",
"phone_number": "string",
"thumbnail": "string",
"additional_attributes": {},
"contact_inboxes": [
{
"source_id": "string",
"inbox": {
"id": 0,
"name": "string",
"website_url": "string",
"channel_type": "string",
"avatar_url": "string",
"widget_color": "string",
"website_token": "string",
"enable_auto_assignment": true,
"web_widget_script": "string",
"welcome_title": "string",
"welcome_tagline": "string",
"greeting_enabled": true,
"greeting_message": "string"
}
}
],
"id": 0,
"availability_status": "string"
}
كما ترى في الحمولة، ستتمكن من رؤية contact_inboxes وكل contact_inbox سيكون له source_id. يمكن اعتبار معرف المصدر كمُعرف للجلسة. ستستخدم هذا source_id لإنشاء محادثة جديدة كما هو موضح أدناه.
2. إنشاء محادثة
مرجع: توثيق API
استخدم source_id الذي تلقيته في نداء API السابق. ستتلقى معرف المحادثة الذي يمكن استخدامه لإنشاء رسالة.
{
"id": 0
}
3. إنشاء رسالة جديدة
مرجع: توثيق API
هناك نوعان من الرسائل.
- واردة: الرسائل التي يرسلها المستخدم النهائي تصنف كرسائل واردة.
- صادرة: الرسائل التي يرسلها الوكيل تصنف كرسائل صادرة.
إذا استدعيت API بالمحتوى الصحيح، ستتلقى حمولة مماثلة لهذه:
{
"id": 0,
"content": "هذه رسالة واردة من قناة API",
"inbox_id": 0,
"conversation_id": 0,
"message_type": 0,
"content_type": null,
"content_attributes": {},
"created_at": 0,
"private": false,
"sender": {
"id": 0,
"name": "Pranav",
"type": "contact"
}
}
إذا تم كل شيء بنجاح، سترى المحادثة على لوحة التحكم كما يلي.
سيتم إعلامك عندما يتم إنشاء رسالة جديدة على عنوان URL المحدد أثناء إنشاء قناة API. يمكنك قراءة المزيد عن حمولة الرسالة هنا.
استقبال الرسائل باستخدام عنوان URL للرد
عندما يتم إنشاء رسالة جديدة في قناة API، ستحصل على طلب POST إلى عنوان URL للرد المحدد أثناء إنشاء قناة API. ستكون الحمولة كما يلي.
اعثر على القائمة الكاملة للأحداث المدعومة بواسطة الويب هوك هنا.
نوع الحدث: message_created
{
"id": 0,
"content": "هذه رسالة واردة من قناة API",
"created_at": "2020-08-30T15:43:04.000Z",
"message_type": "incoming",
"content_type": null,
"content_attributes": {},
"source_id": null,
"sender": {
"id": 0,
"name": "contact-name",
"avatar": "",
"type": "contact"
},
"inbox": {
"id": 0,
"name": "API Channel"
},
"conversation": {
"additional_attributes": null,
"channel": "Channel::Api",
"id": 0,
"inbox_id": 0,
"status": "open",
"agent_last_seen_at": 0,
"contact_last_seen_at": 0,
"timestamp": 0
},
"account": {
"id": 1,
"name": "API testing"
},
"event": "message_created"
}
إنشاء واجهات باستخدام APIs العميل
تساعد APIs العميل المتاحة لقناة API في بناء واجهات موجهة للعملاء لـ Voxys Connect.
هذه APIs مفيدة في حالات مثل التالية.
- استخدام واجهة دردشة مخصصة بدلاً من أداة الدردشة الخاصة بـ Voxys Connect.
- بناء واجهات محادثة في تطبيقات الهاتف المحمول الخاصة بك.
- إضافة Voxys Connect إلى منصات أخرى لا تتوفر لها SDK رسمية من Voxys Connect.
إنشاء كائنات العملاء
يمكنك إنشاء واسترجاع كائنات بيانات العملاء باستخدام inbox_identifier و customer_identifier.
معرف صندوق الوارد
يمكنك الحصول على inbox_identifier من قناة API الخاصة بك -> الإعدادات -> التكوين.
معرف العميل
يمكن الحصول على customer_identifier أو source_id عند إنشاء العميل باستخدام API إنشاء. ستحتاج إلى تخزين هذا المعرف على جانب العميل لإجراء طلبات لاحقة نيابة عن العميل. يمكن تخزينه في الكوكيز، التخزين المحلي، إلخ.
APIs المتاحة
تم توثيق APIs العميل المتاحة هنا. بعض الأشياء التي يمكنك القيام بها باستخدام APIs هي:
- إنشاء، عرض وتحديث جهة الاتصال
- إنشاء وقائمة المحادثات
- إنشاء، قائمة وتحديث الرسائل
مصادقة HMAC
تدعم APIs العميل أيضًا مصادقة HMAC. يمكن الحصول على رمز HMAC للقناة عن طريق تشغيل الأمر التالي في وحدة تحكم Rails الخاصة بك.
# استبدل api_inbox_id بمعرف صندوق الوارد الخاص بك
Inbox.find(api_inbox_id).channel.hmac_token
الاتصال بـ WebSockets في Voxys Connect
للحصول على تحديثات في الوقت الحقيقي من لوحة تحكم الوكيل، اتصل بـ WebSockets في Voxys Connect باستخدام عنوان URL التالي.
<your installation url>/cable
مصادقة اتصال WebSocket الخاص بك
بعد الاشتراك باستخدام pubsub_token الخاص بالعميل، ستتلقى الأحداث الموجهة نحو كائن العميل الخاص بك. يتم توفير pubsub_token أثناء نداء API لإنشاء العميل.
مثال
const connection = new WebSocket('ws://localhost:3000/cable');
connection.send(JSON.stringify({ command:"subscribe", identifier: "{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\""+ customer_pubsub_token+"\\"}" }));
اعثر على القائمة الكاملة للأحداث المدعومة بواسطة WebSockets هنا.
التحقق من Webhook
بمجرد إنشاء قناة API، نقوم تلقائيًا بإنشاء سر يمكنك استخدامه للتحقق من الحمولة التي يتلقاها تطبيقك. يمكنك قراءة المزيد عن التحقق من Webhook هنا.
التنفيذ
هنا مثال على واجهة دردشة مبنية باستخدام APIs العميل.