كيف يمكن إنشاء صندوق وارد لقناة واجهة برمجة التطبيقات (API)؟

لإنشاء وتكوين صندوق بريد قناة API في تثبيتات Chatwoot، اتبع الخطوات الموضحة أدناه.

إعداد قناة API

الخطوة 1. انتقل إلى الإعدادات → صناديق البريد → "إضافة صندوق بريد".

الخطوة 2. انقر على أيقونة "API".

الخطوة 3. أدخل اسماً للقناة و رابط Callback. فيما يلي مثال:

الخطوة 4. "أضف الوكلاء" إلى صندوق بريد API الخاص بك.

تم الانتهاء من إعداد صندوق البريد.

إرسال الرسائل إلى قناة API

لإرسال رسائل إلى قناة API، تأكد من فهمك للنماذج والمصطلحات التالية المستخدمة في Chatwoot.

1. القناة: القناة تحدد نوع مصدر المحادثات. مثل: فيسبوك، تويتر، API، إلخ.

2. صندوق البريد: يمكنك إنشاء مصادر متعددة للمحادثات من نفس نوع القناة. على سبيل المثال: يمكنك ربط أكثر من صفحة فيسبوك بحساب Chatwoot واحد. كل صفحة تعتبر صندوق بريد في Chatwoot.

3. المحادثة: المحادثة هي مجموعة من الرسائل.

4. جهة الاتصال: كل محادثة مرتبطة بشخص حقيقي يسمى جهة اتصال.

5. صناديق جهات الاتصال: هذه هي الجلسة لكل جهة اتصال في صندوق بريد معين. يمكن لجهة الاتصال أن يكون لديها عدة جلسات وعدة محادثات في نفس صندوق البريد.

كيف ترسل رسالة في قناة 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

هناك نوعان من الرسائل:

1. واردة: الرسائل المرسلة من قبل المستخدم النهائي تصنف كرسالة واردة.

2. صادرة: الرسائل المرسلة من قبل الوكيل تصنف كرسالة صادرة.

إذا قمت باستدعاء API بالمحتوى الصحيح، سوف تستلم حمولة مماثلة لما يلي:

{
    "id": 0,
    "content": "This is a incoming message from API Channel",
    "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"
    }
}

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

سيتم إعلامك عندما يتم إنشاء رسالة جديدة على الرابط الذي حددته أثناء إنشاء قناة API. يمكنك قراءة المزيد عن حمولة الرسالة هنا.

استلام الرسائل باستخدام رابط Callback

عند إنشاء رسالة جديدة في قناة API، ستتلقى طلب POST إلى رابط Callback المحدد أثناء إنشاء قناة API. ستكون الحمولة كالتالي.

اعثر على القائمة الكاملة للأحداث المدعومة من webhook هنا.

نوع الحدث: message_created

{
  "id": 0,
  "content": "This is a incoming message from API Channel",
  "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"
}

إنشاء واجهات باستخدام API العميل

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

هذه الـ APIs مفيدة للحالات كالتالي:

1. استخدام واجهة دردشة مخصصة بدلاً من عنصر دردشة Chatwoot.

2. بناء واجهات محادثة ضمن تطبيقات الموبايل الخاصة بك.

3. إضافة Chatwoot إلى منصات أخرى لا يتوفر لها SDK رسمي من Chatwoot.

إنشاء كائنات العملاء

يمكنك إنشاء واسترجاع بيانات العملاء باستخدام inbox_identifier و customer_identifier.

معرف صندوق البريد

يمكنك الحصول على inbox_identifier من قناة API الخاصة بك -> الإعدادات -> التكوين.

معرف العميل

يمكن الحصول على customer_identifier أو source_id عند إنشاء العميل باستخدام  create API. ستحتاج إلى تخزين هذا المعرف في جانب العميل لديك لإجراء طلبات لاحقة نيابة عن العميل. يمكن تنفيذ ذلك في ملفات الكوكيز أو التخزين المحلي وما إلى ذلك.

APIs المتوفرة

تم توثيق واجهات API المتوفرة للعملاء هنا. بعض المهام التي يمكنك القيام بها باستخدام هذه الواجهات:

• إنشاء، عرض وتحديث جهة اتصال

• إنشاء وعرض المحادثات

• إنشاء، عرض وتحديث الرسائل

مصادقة HMAC

تدعم واجهات API للعميل أيضًا مصادقة HMAC. يمكن الحصول على رمز HMAC للقناة عبر تنفيذ الأمر التالي في سطر أوامر Rails الخاص بك.

# استبدل api_inbox_id بمعرف صندوق بريدك
Inbox.find(api_inbox_id).channel.hmac_token

الاتصال بـ WebSockets الخاصة بـ Chatwoot

للحصول على التحديثات الفورية من لوحة تحكم الوكيل، اتصل بـ WebSockets الخاصة بـ Chatwoot باستخدام الرابط التالي.

<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 هنا.

التنفيذ

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