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

## إعداد قناة API

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

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBMGFsVHc9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--32734baff90933097fa9e1d5d2cb9c0a824de9ed/adding%20an%20inbox%20in%20chatwoot.png)

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

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBMWlsVHc9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--cf2f9535e7e9e5feb146122da5bd42ce5e5e151b/api%20channel%20inbox%20in%20chatwoot.png)

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

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBMXFsVHc9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--4d27a3aa27c07d14a098f148fdf5fb15d6ff06b6/api%20channel%20settings.png)

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

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBMDJsVHc9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--d7190cf613e5630ab61790dbaf922bf1005e7c6a/adding%20agents%20to%20a%20chatwoot%20inbox.png)

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

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

لإرسال رسائل إلى قناة API، تأكد من فهمك للنماذج و[المصطلحات](https://www.chatwoot.com/hc/user-guide/articles/1788726131-chatwoot) التالية المستخدمة في Chatwoot.

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

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

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

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

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

### كيف ترسل رسالة في قناة API؟

لإرسال رسالة في قناة API، قم بإنشاء جهة اتصال، وابدأ محادثة، ثم أرسل الرسالة.

تتطلب واجهات برمجة التطبيقات `api_access_token` في ترويسة الطلب. يمكنك الحصول على هذا الرمز من خلال زيارة إعدادات الملف الشخصي → رمز الوصول.

**1. إنشاء جهة اتصال**

**مرجع**: [توثيق API](https://www.chatwoot.com/developers/api/#operation/contactCreate)

مرر معرف صندوق بريد قناة 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](https://www.chatwoot.com/developers/api/#operation/newConversation)

استخدم الـ `source_id` الذي تم استلامه في طلب API السابق. ستحصل على معرف محادثة يمكن استخدامه لإنشاء رسالة.

```
{
  "id": 0
}
```

**3. إنشاء رسالة جديدة**

**مرجع:** [توثيق API](https://www.chatwoot.com/developers/api/#operation/create-a-new-message-in-a-conversation)

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

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"
    }
}
```

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

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBMktsVHc9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--110186260cba7057ce9b0cbb48ec5b45c12e8875/api%20inbox.png)

سيتم إعلامك عندما يتم إنشاء رسالة جديدة على الرابط الذي حددته أثناء إنشاء قناة API. يمكنك قراءة المزيد عن حمولة الرسالة [هنا](https://www.chatwoot.com/docs/product/channels/api/receive-messages).

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

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

اعثر على القائمة الكاملة للأحداث المدعومة من webhook [هنا](https://www.chatwoot.com/docs/product/others/webhook-events).

**نوع الحدث**: `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](https://www.chatwoot.com/developers/api#operation/create-a-contact) API. ستحتاج إلى تخزين هذا المعرف في جانب العميل لديك لإجراء طلبات لاحقة نيابة عن العميل. يمكن تنفيذ ذلك في ملفات الكوكيز أو التخزين المحلي وما إلى ذلك.

**APIs المتوفرة**

تم توثيق واجهات API المتوفرة للعملاء [هنا](https://www.chatwoot.com/developers/api#tag/Contacts-API). بعض المهام التي يمكنك القيام بها باستخدام هذه الواجهات:

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

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

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

### مصادقة HMAC

تدعم واجهات API للعميل أيضًا [مصادقة HMAC](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/identity-validation). يمكن الحصول على رمز 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 [هنا](https://www.chatwoot.com/docs/product/others/websocket-events).

### تحقق من Webhook

عند إنشاء قناة API، نقوم تلقائيًا بإنشاء مفتاح سري يمكنك استخدامه للتحقق من الحمولة التي تستقبلها تطبيقك. يمكنك قراءة المزيد حول التحقق من Webhook [هنا](https://www.chatwoot.com/hc/user-guide/articles/1788726371-webhooks#althqq-mn-alwybhwks).

### التنفيذ

[إليك مثال](https://github.com/chatwoot/client-api-demo) على واجهة محادثة تم بناؤها فوق واجهات برمجة التطبيقات الخاصة بالعميل.