# واجهة برمجة التطبيقات لبرنامج التحرير

* [كيفية استلام الرسائل على عنوان Webhook URL المحدد في إعدادات المشروع](#how-to-get-messages-on-webhook-url-that-is-specified-in-the-projects-settings) 
* [كيفية استخدام webhook عام](#how-to-use-a-universal-webhook) 
* [كيفية تشغيل البوت](#how-to-launch-the-bot) 
* [كيفية العمل مع الرسائل](#how-to-work-with-messages) 
* [كيفية توزيع العملاء](#how-to-distribute-the-clients) 
* [كيفية العمل مع المتغيرات](#how-to-work-with-variables) 
* [كيفية الحصول على client\_id](#how-to-get-client_id) 
* [ما الإمكانيات الأخرى المتاحة](#what-other-possibilities-there-are)

يتم تنفيذ الطلبات باستخدام الطريقة **POST** على عنوان URL أيّ **<https://chatter.mavibot.ai/api/{api\\_key}/{action}>**

أين يقع: **api\_key** هو المفتاح للوصول إلى واجهة API والذي يتم الحصول عليه في إعدادات المشروع:

![](https://lh4.googleusercontent.com/NMHfsMXf9aqYBwcLqud8V-NoFMxqqxkcSdhxjckgEtowma_UmtxTmDqHFIsQwrpjc7kR8afwlpnC5FGMjLxYHtNwhnkR6xF0iwlUPjXTlkqRlYtoHfWrhp_dce8r5I5R-pPgDMzV)

{% hint style="success" %}
**يمكنك الحصول على مفتاح الوصول باستخدام المتغير #{api\_key}.** يحتوي على المفتاح المُولَّد المناسب. لا تنسَ توليد واحد قبل استخدامه.
{% endhint %}

{% hint style="danger" %}
عند نسخ عنوان URL الخاص بالاستعلام من هذه الصفحة تُضاف مسافة يجب حذفها عند الاستدعاء&#x20;

مثال على نسخ الرابط بطريقة خاطئة: <https://chatter.mavibot.ai/api/callback&#x20>;

من السهل عدم ملاحظة المسافة بعد .pro، لكن إذا تُركت فلن يعمل الاستعلام
{% endhint %}

{% hint style="warning" %}
**عند إرسال الطلب باستخدام طريقة GET، لا تستخدم الكلمات المحظورة.** اطّلع على الصياغة الصحيحة لطلبات GET
{% endhint %}

## كيفية استلام الرسائل على عنوان Webhook URL المحدد في إعدادات المشروع

![إعدادات المشروع](https://lh5.googleusercontent.com/042KfsD4dxlKvcCDd-bReA7zTmfMHDr2LoX5jD1maPuo5OIwkyQ4qEXwFpwX41YA1Sx7SHES2TwLQD6Trs_TmwO57Pso2ogV4w8lJdmwhtIi7JdSwJvoePaXSYxO8NKLVm6kooPc)

كل رسالة واردة أو صادرة تأتي مع طلبات JSON POST التالية:

```
{
    'id': معرّف الرسالة في النظام،
    'client': {
        'id': معرّف العميل في النظام،
        'recepient': معرّف العميل في المراسلة،
        'client_type': نوع المراسلة،
        'name': اسم العميل،
        'avatar': صورة العميل الرمزية،
        'created_at': تاريخ إنشاء العميل،
        'tag': مفتاح الاشتراك،
        'group': البوت الذي يرتبط به العميل،
    },
    'message': نص الرسالة،
    'attachments': مصفوفة الروابط إلى الملفات،
    'message_id': معرّف الكتلة التي أُرسلت منها الرسالة،
    'project_id': معرّف المشروع،
    'is_input': 1 إذا كانت الرسالة من العميل، 0 إذا كانت من البوت،
    'delivered': 1 إذا تم إرسال الرسالة بنجاح، 0 إذا حدث خطأ،،
    'error_message': الرسالة التي تشرح الخطأ
}
```

إذا عاد الطلب بخطأ فلن يُعاد إرساله. وإذا عاد الخادم بخطأ فستصل الإشعارات رغم ذلك.

## كيفية استخدام webhook عام

يمكن الآن تشغيل هذه الطرق باستخدام كلٍّ من طلب POST وطلب GET.

* [callback ](#the-bots-launch)
* [whatsapp\_callback](#launching-the-bot-through-the-number-on-whatsapp)&#x20;
* [message ](#sending-the-message-to-the-client)
* [whatsapp\_message](#sending-messages-in-whatsapp)

سابقًا، كانت المعلمات (التي تُشغَّل بها طرق العملاء، أيّ **client\_id**) مكتوبة بشكل صارم جدًا في طرقنا، وكان ذلك يفرض بعض القيود عند استخدامها مع الخدمات الخارجية.

يمكنك الآن تحديد في أيّ معلمة من الطلب سيبحث Mavibot عن معرّف المستخدم: ولهذا تُستخدم معلمة بالبادئة **value\_** مثل **value\_user\_id** و **value\_group\_id**.

كذلك يمكن تشغيل طريقة إرسال callback **callback** عن طريق تمرير بريد إلكتروني (**client\_email**) ورقم هاتف العميل (**client\_phone**).

{% hint style="success" %}
الأساليب **callback** و **whatsapp\_callback** غير مرتبطين بأسماء المعلمات. يمكنك تحديد أيّ معلمة ستحتوي على رقم هاتف العميل والبريد الإلكتروني والمعرّف.
{% endhint %}

وذلك مفيد عند إعداد استقبال webhook عبر موقع آخر.

**لتحديد أيّ متغير يحتوي على client\_id** تحتاج إلى تمرير **value\_client\_id** وذكر اسم المعلمة التي تحتوي على هذه القيمة

**لتحديد أيّ متغير يحتوي على phone** تحتاج إلى تمرير **value\_phone** وذكر اسم المعلمة التي تحتوي على هذه القيمة

**لتحديد أيّ متغير يحتوي على email** تحتاج إلى تمرير **value\_email** وذكر اسم المعلمة التي تحتوي على هذه القيمة

**لتحديد أيّ متغير يحتوي على user\_id** تحتاج إلى تمرير **value\_user\_id** وذكر اسم المعلمة التي تحتوي على هذه القيمة

**لتحديد أيّ متغير يحتوي على group\_id** تحتاج إلى تمرير **value\_group\_id** وذكر اسم المعلمة التي تحتوي على هذه القيمة

مثال:

اكتب في القيمة address value\_client\_id = my\_client

`https://chatter.mavibot.ai/api/d3f31dabef80ddeb73d43938b4ef8bb0/callback?value_client_id=my_client`\
`{"my_client":49177759, "message":"Hello world"}`

سيكون الاستعلام مطابقًا للاستعلام أدناه:

`https://chatter.mavibot.ai/api/d3f31dabef80ddeb73d43938b4ef8bb0/callback`\
`{"client_id":49177759, "message":"Hello world"}`

{% hint style="info" %}
كما ترى، فإن اسم المعلمة التي تحتوي على الاسم يتم تمييزه بواسطة البادئة **value\_**
{% endhint %}

## كيفية تشغيل البوت

## تشغيل البوت

<mark style="color:green;">`POST`</mark> `https://chatter.mavibot.ai/api/<api_key>/callback`

يمكن استخدام هذه الطريقة لتشغيل سير العمل للعميل أو للموافقة على الإجراء في خدمة خارجية. هذه الرسالة لن تكون مرئية للعميل. \
**تُحفظ المعلمات المنقولة إضافيًا في المتغيرات.** \
يمكن الآن تفعيل طريقة إرسال callback عبر مشاركة بريد إلكتروني (client\_email) أو رقم هاتف العميل (client\_phone)

#### معلمات المسار

| Name     | النوع | الوصف      |
| -------- | ----- | ---------- |
| api\_key | لـ    | رمز الوصول |

#### جسم الطلب

| Name          | النوع | الوصف                                            |
| ------------- | ----- | ------------------------------------------------ |
| client\_phone | لـ    | رقم الهاتف الذي يُعثر على العميل من خلاله        |
| client\_email | لـ    | البريد الإلكتروني الذي يُعثر على العميل من خلاله |
| client\_id    | لـ    | معرّف العميل في المحرر                           |
| message       | لـ    | نص الرسالة                                       |

{% tabs %}
{% tab title="200: OK " %}

```javascript
import requests
import json
 
params = {"message": "some_text", "client_id": "25554"}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/callback'
requests.post(url, json=params)
```

{% endtab %}
{% endtabs %}

## تشغيل البوت عبر الرقم على واتساب

<mark style="color:green;">`POST`</mark> `https://chatter.mavibot.ai/api/<api_key>/whatsapp_callback`

تشغّل هذه الطريقة البوت في واتساب بعد أن يسجل العميل عبر الموقع أو بعد أن يترك طلبًا مع رقم هاتفه \
**تُحفظ المعلمات المنقولة إضافيًا في المتغيرات**

#### معلمات المسار

| Name     | النوع | الوصف      |
| -------- | ----- | ---------- |
| api\_key | لـ    | رمز الوصول |

#### جسم الطلب

| Name    | النوع | الوصف           |
| ------- | ----- | --------------- |
| name    | لـ    | اسم العميل      |
| message | لـ    | نص الرسالة      |
| phone   | لـ    | رقم هاتف العميل |
| bot\_id | لـ    | معرّف البوت     |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    // الاستجابة
}
```

{% endtab %}
{% endtabs %}

## تشغيل البوت عبر معرف Telegram

<mark style="color:green;">`POST`</mark> `https://chatter.mavibot.ai/api/<api_key>/tg_callback`

يمكن استخدام الطريقة لتشغيل سير العمل أو تأكيد الإجراءات على موقع خارجي. لن تكون هذه الرسالة مرئية للعميل.&#x20;

**تُحفظ المعلمات المنقولة إضافيًا في المتغيرات**

#### معلمات المسار

| Name     | النوع | الوصف      |
| -------- | ----- | ---------- |
| api\_key | لـ    | رمز الوصول |

#### جسم الطلب

| Name      | النوع | الوصف                               |
| --------- | ----- | ----------------------------------- |
| message   | لـ    | نص الرسالة                          |
| user\_id  | لـ    | معرّف المستخدم في Telegram          |
| group\_id | لـ    | اسم البوت (يجب أن ينتهي بـ **bot**) |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    // الاستجابة
}
```

{% endtab %}
{% endtabs %}

## كيفية العمل مع الرسائل

**معلمات إرسال الرسائل**

**attachment\_type** يمكن أن تأخذ هذه القيم: **صورة، فيديو، رابط، ملف، صوت** \
عند إرسال المرفقات فإن المعلمة **message** ليست إلزامية

**buttons** تحدد الأزرار التي ستُرفق بالرسالة. صيغة الأزرار مماثلة للإعدادات المتقدمة للزر. هناك متغيران ممكنان لإرسال الأزرار: أحدهما مع التلميح في المراسلات التي لا تحتوي على أزرار، والآخر بدونه

إليك مثال على معلمة الأزرار:

```
"buttons": {"hint": "سيظهر هذا النص في واتساب",
 "buttons": [
    {"type": "reply", 
     "text": "ما الخدمات التي يمكننا تقديمها", 
     "line": 0, "index_in_line": 0}, 
       
    {"type": "reply", 
     "text": "معلومات الدفع", 
     "line": 0, 
     "index_in_line": 1}, 
        
    {"type": "reply", 
     "text": "معلومات الاتصال الخاصة بنا", 
     "line": 1, "index_in_line": 0}, 
        
    {"type": "reply", 
     "text": "ترك طلب", 
     "line": 1, "index_in_line": 1}
   ] 
}
```

## إرسال الرسالة إلى العميل

<mark style="color:green;">`POST`</mark> `https://chatter.mavibot.ai/api/<api_key>/message`

يمكن استخدام هذه الطريقة لإرسال رسائل مع إشعارات. المعلمة **message** إلزامية إذا كنت لا ترسل ملفًا. وإذا كنت ترسل ملفًا، فالنص غير مطلوب

#### معلمات المسار

| Name     | النوع | الوصف        |
| -------- | ----- | ------------ |
| api\_key | لـ    | مفتاح الوصول |

#### جسم الطلب

| Name             | النوع | الوصف                  |
| ---------------- | ----- | ---------------------- |
| message\_id      | لـ    | رقم كتلة الإرسال       |
| message          | لـ    | نص الرسالة             |
| client\_id       | لـ    | معرّف العميل في المحرر |
| attachment\_type | لـ    | نوع عرض الملف          |
| attachment\_url  | لـ    | رابط الملف             |
| buttons          | كائن  | buttons                |

{% tabs %}
{% tab title="200: OK " %}

```javascript
import requests
import json

params = {"message": "some_text", "client_id": "25554"}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/message'
requests.post(url, json=params)
```

{% endtab %}
{% endtabs %}

## إرسال الرسائل في واتساب

<mark style="color:green;">`POST`</mark> `https://chatter.mavibot.ai/api/<api_key>/whatsapp_message`

يسمح بإرسال رسالة باسم البوت المتصل إلى الرقم المذكور **whatsapp\_bot\_id** يجب أخذه من قسم “Messengers and chats”. كل صفحة واتساب متصلة تحصل على تعريف فريد

#### معلمات المسار

| Name     | النوع | الوصف        |
| -------- | ----- | ------------ |
| api\_key | لـ    | مفتاح الوصول |

#### جسم الطلب

| Name              | النوع | الوصف                        |
| ----------------- | ----- | ---------------------------- |
| message\_id       | لـ    | رقم كتلة الإرسال             |
| whatsapp\_bot\_id | الرقم | بوت واتساب الذي يرسل الرسالة |
| attachment\_url   | لـ    | رابط الملف                   |
| attachment\_type  | لـ    | نوع عرض الملف                |
| message           | لـ    | نص الرسالة                   |
| phone             | لـ    | رقم هاتف المستلم             |

{% tabs %}
{% tab title="200: OK " %}

```javascript
import requests
import json

params = {"message": "some_text", "phone": "79875146788"}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/whatsapp_message'
requests.post(url, json=params)
```

{% endtab %}
{% endtabs %}

## إرسال الرسائل بشكل جماعي

<mark style="color:green;">`POST`</mark> `https://chatter.mavibot.ai/api/<api_key>/broadcast`

تتيح الطريقة توزيع الرسائل. إذا لم تُذكر المعلمة **clients** فسيُرسل البث إلى جميع المستخدمين. من الضروري إرسال ملف أو نص

#### معلمات المسار

| Name     | النوع | الوصف        |
| -------- | ----- | ------------ |
| api\_key | لـ    | مفتاح الوصول |

#### جسم الطلب

| Name             | النوع  | الوصف                                  |
| ---------------- | ------ | -------------------------------------- |
| message\_id      | لـ     | رقم كتلة الإرسال                       |
| list             | لـ     | قائمة أرقام المستلمين                  |
| shift            | لـ     | عدد الثواني بين الرسائل. الافتراضي 0.2 |
| message          | لـ     | نص الرسالة                             |
| clients          | مصفوفة | معرّفات المستلمين                      |
| attachment\_type | لـ     | نوع عرض الملف                          |
| attachment\_url  | لـ     | رابط الملف                             |
| buttons          | لـ     | buttons                                |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{import requests
import json

params = {"message": "some_text", "clients": ["5", "58", "110"]}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/broadcast'
requests.post(url, json=params)
```

{% endtab %}
{% endtabs %}

## الحصول على سجل الرسائل

<mark style="color:blue;">`GET`</mark> `https://chatter.mavibot.ai/api/<api_key>/get_history?client_id=`

الحصول على سجل الرسائل. يمكنك الحصول على **client\_id** المعلمة [هنا](#how-to-get-client_id)

#### معلمات المسار

| Name     | النوع | الوصف        |
| -------- | ----- | ------------ |
| api\_key | لـ    | مفتاح الوصول |

#### معلمات الاستعلام

| Name       | النوع | الوصف        |
| ---------- | ----- | ------------ |
| client\_id | لـ    | معرّف العميل |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
  "status": "success",
  "result": [
    {
      "id": 104500,
      "answered": true,
      "client_replica": false,
      "message_id": 390,
      "message_from_outside": 0,
      "created_at": 1587895014,
      "text": "CouCou",
      "attachments": {
        
      },
      "delivered": true,
      "error_message": "true"
    },
  ]
}
```

{% endtab %}
{% endtabs %}

## مسح سجل الرسائل

<mark style="color:blue;">`GET`</mark> `https://chatter.mavibot.ai/api/<api_key>/clear_history?client_id=`

#### معلمات المسار

| Name     | النوع | الوصف        |
| -------- | ----- | ------------ |
| api\_key | لـ    | مفتاح الوصول |

#### معلمات الاستعلام

| Name       | النوع | الوصف        |
| ---------- | ----- | ------------ |
| client\_id | لـ    | معرّف العميل |

{% tabs %}
{% tab title="200: OK " %}

```javascript
import requests
import json


token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/clear_history?client_id=85856'
requests.get(url)
```

{% endtab %}
{% endtabs %}

## كيفية توزيع العملاء

## إسناد عميل إلى موظف

<mark style="color:blue;">`GET`</mark> `https://chatter.mavibot.ai/api/<api_key>/assign_to_user`

تتيح الطريقة إسناد عميل إلى موظف. معلمة البريد الإلكتروني اختيارية. إذا لم يُقدَّم البريد الإلكتروني، فسيتم توزيعه عبر خوارزمية النظام

#### معلمات المسار

| Name     | النوع | الوصف        |
| -------- | ----- | ------------ |
| api\_key | لـ    | مفتاح الوصول |

#### معلمات الاستعلام

| Name              | النوع      | الوصف                          |
| ----------------- | ---------- | ------------------------------ |
| client\_id        | سلسلة نصية | معرّف العميل                   |
| البريد الإلكتروني | سلسلة نصية | بريد إلكتروني للعامل (اختياري) |

{% tabs %}
{% tab title="200: OK " %}

```javascript
import requests
import json

params = {"message": "some_text", "clients": ["5", "58", "110"]}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/broadcast'
requests.post(url, json=params)
```

{% endtab %}
{% endtabs %}

## تحميل العملاء إلى النظام

<mark style="color:blue;">`GET`</mark> `https://chatter.mavibot.ai/api/<api_key>/load_clients`

تتيح الطريقة تحميل العملاء إلى النظام. عند رفع عملاء واتساب يمكنك تمرير الرقم بحرية مع @s.whatsapp.net في النهاية أو بدونه.&#x20;

يمكنك الحصول على معرّف المجموعة (**group\_id**) [هنا ](#what-other-possibilities-there-are)عبر /api/\<api\_key>/connected\_channels&#x20;

(إذا كان client\_type=13 (الاتصالات الهاتفية) فإن group\_id=””)&#x20;

يمكنك رؤية نوع المراسلة التي جاء منها العميل (**client\_type**)&#x20;

مثال: \[{"platform\_id":"79875555555","group\_id":34810,"client\_type":6}]

#### معلمات المسار

| Name     | النوع | الوصف        |
| -------- | ----- | ------------ |
| api\_key | لـ    | مفتاح الوصول |

#### جسم الطلب

| Name         | النوع      | الوصف                             |
| ------------ | ---------- | --------------------------------- |
| platform\_id | سلسلة نصية | رقم الهاتف                        |
| group\_id    | سلسلة نصية | معرّف المجموعة                    |
| client\_type | سلسلة نصية | نوع المراسلة التي جاء منها العميل |

{% tabs %}
{% tab title="200: OK " %}

```javascript
import requests
import json


token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/load_clients'

params = [{ "platform_id": 274827917, "group_id": 169166236, "client_type":0},
{"platform_id":"79538550785@s.whatsapp.net", "group_id": "1hwF7lwEjv4SKYIGFhQnBw==", "client_type": 6}]
requests.post(url, json=params)
# في حالة النجاح تُعيد الدالة لكل عنصر معرّفه وحالة إضافية
# مثال على الإجابة
# {"status":"success","items":[{"platform_id":"700000000@s.whatsapp.net","group_id":"5kqchxwyvdvFZOsp80q2qw==","client_type":6,"status":"success","id":1469409}]}
```

{% endtab %}
{% endtabs %}

## إضافة عملاء إلى القائمة

<mark style="color:green;">`POST`</mark> `https://chatter.mavibot.ai/api/<api_key>/add_to_list`

#### معلمات المسار

| Name     | النوع | الوصف        |
| -------- | ----- | ------------ |
| api\_key | لـ    | مفتاح الوصول |

#### جسم الطلب

| Name     | النوع    | الوصف                |
| -------- | -------- | -------------------- |
| list\_id | عدد صحيح | رقم القائمة          |
| clients  | مصفوفة   | مصفوفة أرقام العملاء |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    // الاستجابة
}
```

{% endtab %}
{% endtabs %}

## إزالة العملاء من القائمة

<mark style="color:green;">`POST`</mark> `https://chatter.mavibot.ai/api/<api_key>/remove_from_list`

#### معلمات المسار

| Name     | النوع | الوصف        |
| -------- | ----- | ------------ |
| api\_key | لـ    | مفتاح الوصول |

#### جسم الطلب

| Name     | النوع    | الوصف                |
| -------- | -------- | -------------------- |
| list\_id | عدد صحيح | رقم القائمة          |
| clients  | مصفوفة   | مصفوفة أرقام العملاء |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    // الاستجابة
}
```

{% endtab %}
{% endtabs %}

## الحصول على قائمة العملاء

<mark style="color:green;">`POST`</mark> `https://chatter.mavibot.ai/api/<api_key>/get_clients`

#### معلمات المسار

| Name     | النوع | الوصف        |
| -------- | ----- | ------------ |
| api\_key | لـ    | مفتاح الوصول |

#### معلمات الاستعلام

| Name   | النوع    | الوصف                                                   |
| ------ | -------- | ------------------------------------------------------- |
| offset | لـ       | إزاحة من أول عنصر                                       |
| limit  | عدد صحيح | عدد العناصر في الإجابة. الافتراضي 500، والحد الأقصى 500 |
| list   | لـ       | رقم القائمة                                             |

{% tabs %}
{% tab title="200: OK تُعيد حالة العناصر ومصفوفتها" %}

```javascript
{
"status":"success",
"clients":[{
    "id":44483,
    "platform_id":"146467928",
    "client_type":0,
    "name":null,
    "avatar":null,
    "message_id":null,
    "project_id":1,
    "created_at":1588248599,
    "updated_at":1588248599,
    "custom_answer":null,
    "tag":null,
    "group":"143414131",
    "operator_start_dialog":null
    }
]
}
```

{% endtab %}
{% endtabs %}

## الحصول على قائمة المشتركين في أيّ مراسلة

<mark style="color:green;">`POST`</mark> `https://chatter.mavibot.ai/api/<api_key>/subscribers`

الحصول على معلومات العملاء في المراسلة المختارة

#### معلمات المسار

| Name     | النوع | الوصف        |
| -------- | ----- | ------------ |
| api\_key | لـ    | مفتاح الوصول |

#### معلمات الاستعلام

| Name         | النوع    | الوصف                                                                                            |
| ------------ | -------- | ------------------------------------------------------------------------------------------------ |
| page         | عدد صحيح |                                                                                                  |
| tag          | لـ       | الوسم الذي ذُكر في صفحة الاشتراك                                                                 |
| group        | عدد صحيح | معرّف المجموعة التي يرتبط بها المشترك                                                            |
| date\_from   | عدد صحيح | طابع زمني للتاريخ بعد اشتراكهم                                                                   |
| date\_to     | عدد صحيح | طابع زمني للتاريخ الذي اشتركوا حتى                                                               |
| client\_type | عدد صحيح | معرّف المراسلة التي تحتاج إلى إظهار القائمة الفرعية فيها. إذا لم تغيّر شيئًا فسيظهر جميع العملاء |

{% tabs %}
{% tab title="200: OK " %}

```javascript
[
  {
    "id": 44886,
    "tag": null,
    "created_at": 1609867984,
    "name": "John Smith",
    "tg_id": "146467928",
    "group": "155824294",
    "variables": null
  },
  {
    "id": 44889,
    "tag": null,
    "created_at": 1609867984,
    "name": "Jane Austen",
    "tg_id": "1609867984",
    "group": "155824294",
    "variables": {
      "utm_source": "some_value"
    }
  }
]
```

{% endtab %}
{% endtabs %}

### الإذن بحذف العملاء

<mark style="color:green;">**`POST`**</mark>` ``https://chatter.mavibot.ai/api/<api_key>/get_clients`

صلاحية الوصول عند توليد المفتاح: “الإذن بحذف العملاء”

المعلمات

المسار\
api key\* — رمز الوصول

الجسم\
client\_ids — قائمة بمعرّفات العملاء المراد حذفهم. الحد الأقصى 500. مثال: \[199571, 199707, 1935722]

## كيفية العمل مع المتغيرات

## إسناد المتغيرات

<mark style="color:green;">`POST`</mark> `https://chatter.mavibot.ai/api/<api_key>/save_variables`

يسمح بحفظ المتغيرات في التطبيق وفي العميل. \
يضيف طلب إسناد المتغيرات افتراضيًا إلى متغيرات المعاملة. \
إذا كنت بحاجة إلى تغيير المتغيرات في الملف الشخصي فعليك إضافة البادئة **client**. \
مثال للهاتف المحمول: client.phone&#x20;

المعلمة **clients** تسمح بإسناد المتغيرات بشكل جماعي&#x20;

مثال: {"client\_id":49177759, "variables":\
{"client.phone":"1234567890"}}

#### معلمات المسار

| Name     | النوع | الوصف        |
| -------- | ----- | ------------ |
| api\_key | لـ    | مفتاح الوصول |

#### جسم الطلب

| Name       | النوع  | الوصف                                   |
| ---------- | ------ | --------------------------------------- |
| clients    | مصفوفة | مصفوفة معرّفات العملاء لإسناد المتغيرات |
| client\_id | لـ     | معرّف العميل                            |
| المتغيرات  | كائن   | تجزئة المتغير (مفتاح/قيمة)              |

{% tabs %}
{% tab title="200: OK " %}

```javascript
import requests
import json

params = {"client_id": "25554", "variables": {"var_name": "var_value"}}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/save_variables'
requests.post(url, json=params)
```

{% endtab %}
{% endtabs %}

## الحصول على المتغيرات

<mark style="color:blue;">`GET`</mark> `https://chatter.mavibot.ai/api/<api_key>/get_variables?client_id=`

#### معلمات المسار

| Name     | النوع | الوصف      |
| -------- | ----- | ---------- |
| api\_key | لـ    | رمز الوصول |

#### معلمات الاستعلام

| Name       | النوع | الوصف        |
| ---------- | ----- | ------------ |
| client\_id | لـ    | معرّف العميل |

{% tabs %}
{% tab title="200: OK " %}

```javascript
import requests
import json


token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/get_variables?client_id=85856'
requests.get(url)
```

{% endtab %}
{% endtabs %}

## **كيفية الحصول على client\_id**

## الحصول على client\_id حسب قيمة platform\_id

<mark style="color:green;">`POST`</mark> `https://chatter.mavibot.ai/api/<api_key>/find_client_id_by_platform_id`

تُعيد الطريقة معرّف العميل لتنفيذ الطلبات إلى واجهة API

مثال على المعلمات: {"platform\_ids": \["571830542", "256865200"]}

#### معلمات المسار

| Name | النوع | الوصف        |
| ---- | ----- | ------------ |
|      | لـ    | مفتاح الوصول |

#### جسم الطلب

| Name          | النوع | الوصف                       |
| ------------- | ----- | --------------------------- |
| platform\_ids | لـ    | مصفوفة المعرفات في المراسلة |

{% tabs %}
{% tab title="200: OK " %}

```javascript
[{
"id":15099119,
"tag":null,
"created_at":1618815253,
"name":"Oscar Wilde",
"avatar":"https:\\/\\/files.salebot.pro\\/uploads\\/avatars\\/256865200.jpg",
"platform_id":"2568652",
"group":"Salebotpro_bot",
"variables":{"tg_username":"@wildeo"}},

{"id":21087377,
"tag":null,
"created_at":1626275893,
"name":"Freddie Mercury",
"avatar":"https:\\/\\/files.salebot.pro\\/uploads\\/avatars\\/571830542.jpg",
"platform_id":"571830542",
"group":"Salebotpro_bot",
"variables":{"tg_username":"@freddieisqueen"}
}]
```

{% endtab %}
{% endtabs %}

## كيفية الحصول على معرّف العميل في الدردشة المباشرة

<mark style="color:blue;">`GET`</mark> `https://chatter.mavibot.ai/api/<api_key>/online_chat_client_id?recipient=`

تتيح هذه الطريقة دمج الموقع وروبوت الدردشة، أي إذا ذهب شخص إلى الصفحة التي تحتوي على العرض الخاص، يمكنك إرسال رسالة عن العرض فورًا في الدردشة

#### معلمات المسار

| Name     | النوع | الوصف      |
| -------- | ----- | ---------- |
| api\_key | لـ    | رمز الوصول |

#### معلمات الاستعلام

| Name      | النوع | الوصف                  |
| --------- | ----- | ---------------------- |
| tag       | لـ    | وسم العميل             |
| name      | لـ    | اسم العميل             |
| recipient | لـ    | معرّف الحوار في الموقع |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{ "client_id": 36553 }
```

{% endtab %}
{% endtabs %}

من أين تحصل على recipient؟ في الموقع الذي يستخدم الدردشة المباشرة “Mavibot.ai” تحتاج إلى الحصول على الخاصية SaleBotPro.recipient\_id بمساعدة JavaScript.

![](https://lh4.googleusercontent.com/kTHJGnkdMXxirfxHrmgHcg3n9nRn35lHIiWbQ6LZyaQZ4IbO8TnOtgihTt4MdAqFa1bWujmpYDOId9ALFfmud8n-XD2AJlxep2luxjL4nCl2YgDTpdemE4wJVsgFuPw1h382oUL5)

## كيفية الحصول على معرّف العميل باستخدام رقم واتساب

<mark style="color:blue;">`GET`</mark> `https://chatter.mavibot.ai/api/<api_key>/whatsapp_client_id?phone=`

تعيد الطريقة معرّف العميل لتنفيذ الطلبات إلى واجهة API إذا كنت تعرف رقم هاتف العميل في واتساب. \
إذا لم يكن هناك عميل بهذا الرقم، فستحصل على 404.

#### معلمات المسار

| Name     | النوع | الوصف      |
| -------- | ----- | ---------- |
| api\_key | لـ    | رمز الوصول |

#### معلمات الاستعلام

| Name  | النوع | الوصف      |
| ----- | ----- | ---------- |
| phone | لـ    | رقم الهاتف |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    // الاستجابة
}
```

{% endtab %}
{% endtabs %}

## الحصول على معرّف العميل باستخدام رقم الهاتف

<mark style="color:blue;">`GET`</mark> `https://chatter.mavibot.ai/api/<api_key>/find_client_id_by_phone?phone=`

تعيد الطريقة معرّف العميل لتنفيذ الطلبات إلى واجهة API. \
يتم البحث عبر عملاء واتساب وكذلك عبر المتغيرات.

#### معلمات المسار

| Name     | النوع | الوصف      |
| -------- | ----- | ---------- |
| api\_key | لـ    | رمز الوصول |

#### معلمات الاستعلام

| Name  | النوع | الوصف      |
| ----- | ----- | ---------- |
| phone | لـ    | رقم الهاتف |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    // الاستجابة
}
```

{% endtab %}
{% endtabs %}

## الحصول على معرّف العميل عبر البريد الإلكتروني

<mark style="color:blue;">`GET`</mark> `https://chatter.mavibot.ai/api/<api_key>/find_client_id_by_email?email=`

تعيد الطريقة معرّف العميل لتنفيذ الطلبات إلى واجهة API. يتم البحث عبر المتغيرات.

#### معلمات المسار

| Name     | النوع | الوصف      |
| -------- | ----- | ---------- |
| api\_key | لـ    | رمز الوصول |

#### معلمات الاستعلام

| Name              | النوع | الوصف                   |
| ----------------- | ----- | ----------------------- |
| البريد الإلكتروني | لـ    | البريد الإلكتروني للبحث |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    // الاستجابة
}
```

{% endtab %}
{% endtabs %}

## الحصول على معرّف العميل حسب قيمة المتغير

<mark style="color:blue;">`GET`</mark> `https://chatter.mavibot.ai/api/<api_key>/find_client_id_by_var?var=&val=`

تعيد الطريقة معرّف العميل لتنفيذ الطلبات إلى واجهة API

#### معلمات المسار

| Name     | النوع | الوصف      |
| -------- | ----- | ---------- |
| api\_key | لـ    | رمز الوصول |

#### معلمات الاستعلام

| Name | النوع | الوصف                                  |
| ---- | ----- | -------------------------------------- |
| var  | لـ    | اسم المتغير الذي سيُجرى البحث من خلاله |
| val  | لـ    | قيمة المتغير                           |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    // الاستجابة
}
```

{% endtab %}
{% endtabs %}

## **ما الإمكانيات الأخرى المتاحة**

## نقل المعاملة إلى حالة MavibotCRM

<mark style="color:green;">`POST`</mark> `https://chatter.mavibot.ai/api/<api_key>/set_order_state`

يمكن الحصول على رقم المعاملة في نافذة تحرير سير العمل في MavibotCRM.

#### معلمات المسار

| Name     | النوع | الوصف        |
| -------- | ----- | ------------ |
| api\_key | لـ    | مفتاح الوصول |

#### جسم الطلب

| Name       | النوع | الوصف                                        |
| ---------- | ----- | -------------------------------------------- |
| client\_id | لـ    | معرّف العميل                                 |
| state\_id  | لـ    | رقم الحالة التي سيتم نقل معاملة العميل إليها |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    // الاستجابة
}
```

{% endtab %}
{% endtabs %}

## التحقق مما إذا كان الشخص يتابع حساب إنستغرام&#x20;

<mark style="color:blue;">`GET`</mark> `https://chatter.mavibot.ai/api/<api_key>/check_insta_subscription`

يمكن استدعاؤها بكلٍّ من طريقة POST وطريقة GET

#### معلمات المسار

| Name     | النوع | الوصف        |
| -------- | ----- | ------------ |
| api\_key | لـ    | مفتاح الوصول |

#### جسم الطلب

| Name       | النوع | الوصف                                       |
| ---------- | ----- | ------------------------------------------- |
| user\_name | لـ    | اسم المستخدم للعميل الذي تريد التحقق منه    |
| login      | لـ    | تسجيل الدخول الخاص بالبوت الجاري التحقق منه |

{% tabs %}
{% tab title="200: OK الحقل is\_follower هو الذي يحتوي على المعلومات حول ما إذا كان الشخص يتابعه أم لا" %}

```javascript
{
"username": "beyonce",
"account_id": "1463220603",
"avatar": "https://instagram.fhel6-1.fna.fbcdn.net/v/t51.2885-19/1060168..",
"real_name": "Beyonce",
"is_follower": true,
"status": 200
}
```

{% endtab %}
{% endtabs %}

## التحقق مما إذا كان رقم الهاتف يدعم واتساب

<mark style="color:blue;">`GET`</mark> `https://chatter.mavibot.ai/api/<api_key>/check_whatsapp`

**لاستخدام هذه الطريقة يجب أن يكون واتساب وMavibot متصلين**

يمكن استدعاؤها بكلٍّ من طريقة POST وطريقة GET \
يمكن تمرير رقم الهاتف بأيّ صيغة

#### معلمات المسار

| Name     | النوع | الوصف      |
| -------- | ----- | ---------- |
| api\_key | لـ    | رمز الوصول |

#### جسم الطلب

| Name  | النوع | الوصف      |
| ----- | ----- | ---------- |
| phone | لـ    | رقم الهاتف |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    // الاستجابة
}
```

{% endtab %}
{% endtabs %}

## الحصول على قائمة المراسلات المتصلة بالمشروع (بما في ذلك group\_id)

<mark style="color:blue;">`GET`</mark> `https://chatter.mavibot.ai/api/<api_key>/connected_channels`

تعيد الدالة المعلمة **group\_id** لكل مراسلة وهي التي يجب تمريرها عند تحميل العملاء&#x20;

يمكن استخدام الحقل **status** كما تُعيد أيضًا لواتساب، وتحمل قيمة: \
**NOT\_STARTED = 0** \
**STARTED = 1** \
**ASLEEP = 2** \
**STOPPED = 3**

#### معلمات المسار

| Name     | النوع | الوصف      |
| -------- | ----- | ---------- |
| api\_key | لـ    | رمز الوصول |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{'project_id': 1, 
'viber': [{
        'id': 14, 
        'uri': 'salebotstage', 
        'name': 'salebotstage', 
        'enabled': true,
        'group_id': 11}], 
'facebook': [], 
'telegram': [{
        'id': 23, 
        'short_name': 'bulls_vs_bears_bot', 
        'name': 'bulls_vs_bears_bot', 
        'enabled': true,
        'group_id': 'bulls_vs_bears_bot'}], 
'whatsapp': [] 
}
```

{% endtab %}
{% endtabs %}

## الحصول على قائمة الكتل من مخطط البوت

<mark style="color:blue;">`GET`</mark> `https://chatter.mavibot.ai/api/<api_key>/get_messages`

#### معلمات المسار

| Name     | النوع | الوصف      |
| -------- | ----- | ---------- |
| api\_key | لـ    | رمز الوصول |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    // الاستجابة
}
```

{% endtab %}
{% endtabs %}

{% hint style="success" %}
إذا كنت بحاجة إلى طرق إضافية، فيُرجى التواصل مع دعم العملاء&#x20;
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mavibot.ai/doc/ar/integrations/api/settings.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.