# منشئ API

يمكن تشغيل بعض وظائف طلبات واجهة البرمجة في الحاسبة.

تُرسل الطلبات عبر **POST** أو **GET** الطريقة إلى عنوان URL بالتنسيق التالي:

**<https://chatter.mavibot.ai/api/{api\\_key}/{action}>**

حيث:

**api\_key** — مفتاح الوصول إلى واجهة البرمجة المُنشأ في إعدادات المشروع.

<figure><img src="/files/368f142ead764bb740bc9313e2690a80e2895cb6" alt=""><figcaption></figcaption></figure>

{% hint style="success" %}
لاستخدام الرمز في طلب عبر URL، تحتاج أولًا إلى إنشاء مفتاح API.

تتوفر التعليمات الخاصة بذلك في قسم "إنشاء مفتاح API". <mark style="color:red;">**رابط**</mark>
{% endhint %}

{% hint style="danger" %}
عند نسخ عنوان URL من هذه الصفحة، قد يظهر فراغ ويجب إزالته.

مثال على رابط غير صحيح:
&#x20;<https://chatter.mavibot.pro> /api/callback

إذا بقي الفراغ بعد .pro فلن يعمل الطلب.
{% endhint %}

{% hint style="warning" %}
لا تستخدم أحرفًا محظورة عند إرسال طلب GET.

تأكد من فهم التنسيق الصحيح لطلبات GET.
{% endhint %}

## **كيفية إنشاء مفتاح API**

{% hint style="success" %}
تظل ميزة إنشاء مفتاح API القديمة تعمل كما كانت، لكنها غير متاحة للمشاريع الجديدة.

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

إذا كنت بحاجة إلى إنشاء مفاتيح جديدة، فاستخدم الإعدادات المُحدثة.
{% endhint %}

لإنشاء مفتاح API، انتقل إلى إعدادات المشروع:

<figure><img src="/files/8e57e0e2316241fd425d54d54040c6376e933b09" alt="" width="301"><figcaption></figcaption></figure>

بعد ذلك، انتقل إلى قسم "التكاملات":

<figure><img src="/files/e4a3e334db98173a0f381f78c20b4fd7f3b9f073" alt="" width="563"><figcaption></figcaption></figure>

ستجد زر "إضافة مفتاح API" في قسم "التكاملات":

<figure><img src="/files/1afb069c11c6e8d3c4010b13e7049dfd0937105f" alt=""><figcaption></figcaption></figure>

بعد النقر على الزر، ستُفتح نافذة منبثقة تحتوي على إعدادات الوصول وخيارات إنشاء مفتاح API:

<figure><img src="/files/fbf449385a299b588206df543dce98aa45bfd02c" alt=""><figcaption></figcaption></figure>

بعد ذلك، تحتاج إلى تحديد أذونات الوصول لمفتاح API:

<figure><img src="/files/d4dc7db6b701e3dd35ad108429d3e34f60ff391c" alt=""><figcaption></figcaption></figure>

ستعمل وظيفة API وفقًا لأذونات الوصول التي تحددها.

{% hint style="warning" %}
يرجى الانتباه!

تعتمد وظيفة API على أذونات الوصول التي تحددها: إذا أنشأت مفتاح API بصلاحية القراءة فقط لمعلومات العميل ثم استخدمته لإرسال رسالة إلى عميل أو تعديل متغيراته، فسيفشل طلب API.
\
يتم تحديد الصلاحية المطلوبة لكل طلب API في بطاقة طلب API:

<img src="/files/f0a0ab0e73e94bacbd41443297823eab36b95706" alt="" data-size="original">
{% endhint %}

بعد ذلك، أدخل اسمًا لمفتاح API:

<figure><img src="/files/2442b53463e0ed82235e2488d7faba103ea0ccf6" alt=""><figcaption></figcaption></figure>

أنشئ مفتاح API بالنقر على زر "إنشاء":

<figure><img src="/files/5bcf4477fae0de389fad84cc07353654c7751005" alt=""><figcaption></figcaption></figure>

После чего нажмите "Готово" и ключ api добавится в раздел:

<figure><img src="/files/ac22839d5e5dddf33dcc652f8fc0e6ed53386f2f" alt=""><figcaption></figcaption></figure>

يمكنك إضافة عدد غير محدود من مفاتيح API حسب الحاجة، مع تخصيص أذونات وصول مختلفة لكل مفتاح.

<figure><img src="/files/a4732bf07d15711a0d649256a70125542c3cc6b4" alt=""><figcaption></figcaption></figure>

بعد ذلك، تحتاج إلى تعيين مفتاح أساسي للمشروع. يتيح لك ذلك استخدام المفتاح في عنوان URL للطلب باستخدام العنصر النائب #{api\_key}.

للقيام بذلك، انقر على زر "{+}" الموجود على يمين مفتاح API المطلوب:

<figure><img src="/files/9d9c7db4775fe82c26a412c001fb1a5bdbbc1859" alt=""><figcaption></figcaption></figure>

ستظهر بعد ذلك تسمية بجانب المفتاح تشير إلى أنه مفتاح المشروع الأساسي.

<figure><img src="/files/803e80cd155d0786f89894b835d811c8c56c1a9f" alt=""><figcaption></figcaption></figure>

يمكنك الوصول إلى مفتاح المشروع الأساسي عبر api\_key: ما عليك سوى إنشاء المفتاح المطلوب، وتعيين أذوناته، وتحديده كمفتاح المشروع الأساسي. ثم في الحاسبة، استخدم عنوان URL للطلب مع العنصر النائب #{api\_key}، والذي سيحتوي على قيمة مفتاح المشروع الأساسي.

<figure><img src="/files/8ac699f972b5dd9090fc7af000d361a9f2c6afa9" alt=""><figcaption><p>URL запроса</p></figcaption></figure>

<figure><img src="/files/1521bcbdefb82ffa79610e3fca23870883a6de4d" alt=""><figcaption></figcaption></figure>

أي مفاتيح أخرى تم إنشاؤها مع إعدادات الوصول ستُعتبر مفاتيح ثانوية. في عنوان URL للطلب، يمكنك استخدام قيمتها بدلًا من #{api\_key}. للقيام بذلك، انسخ قيمة المفتاح الثانوي:

<figure><img src="/files/aef68be9adb98c4ce481f329711f26e2efae12b3" alt=""><figcaption></figcaption></figure>

وألصقها في عنوان URL للطلب بدلًا من #{api\_key}:

<figure><img src="/files/585cc43c2e38f17d461f11f101e94f73b7c88dc1" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
يتم تعيين مفتاح API المُنشأ بالطريقة القديمة افتراضيًا كمفتاح المشروع الأساسي ويملك جميع الصلاحيات.
{% endhint %}

{% hint style="danger" %}
ملاحظة!&#x20;

إذا حذفت المفتاح المُعيَّن كمفتاح المشروع الأساسي، فستحتاج إلى تعيين مفتاح جديد يدويًا كمفتاح أساسي.
{% endhint %}

{% hint style="success" %}
يرجى الانتباه!&#x20;

إذا كانت لديك مفاتيح API تم إنشاؤها بالطريقة القديمة، فستستمر في العمل بشكل طبيعي. لا يمكن إنشاء مفاتيح API جديدة من النوع القديم.
{% endhint %}

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

![إعدادات المشروع](/files/a92a960eabcc138e7b9e6ab7d875f7f6ecbe863d)

ستُرسل كل رسالة واردة أو صادرة كطلب 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": "نص خطأ تسليم الرسالة"
}
```

إذا أعاد الطلب خطأ، فلن تتم إعادة المحاولة. وحتى إذا أعاد الخادم أخطاء، ستستمر الإشعارات في الإرسال.

### كيفية إنشاء طلب JSON

انتقل إلى إعدادات الكتلة التي ستُسجَّل فيها البيانات في الجدول.&#x20;

<figure><img src="/files/a8dfeccdc0437cbc98f40ff8030cd05797bd325e" alt=""><figcaption></figcaption></figure>

1. أضف قسمًا لطلب API.
2. اختر POST-JSON كنوع الطلب.
3. ثم ابدأ بملء حقول الطلب:

<figure><img src="/files/1cf28b8119db6666926a1e37fa9a94cdd88edddc" alt=""><figcaption></figcaption></figure>

**عنوان URL للطلب** — المسار إلى الدالة التي سيتم استدعاؤها. في الوثائق، يظهر هذا دائمًا في السطر الأول بجانب نوع الطلب:

<figure><img src="/files/981113448779b4540fd0383bb964432379d5b387" alt=""><figcaption></figcaption></figure>

**القيم المحفوظة** — قائمة بمعاملات الاستجابة مع أسماء المتغيرات التي يجب حفظ النتائج فيها، بالتنسيق التالي:

> **request\_parameter -> your\_variable**
>
> إذا كانت الاستجابة تحتوي على معاملات ذات بنية معقدة، فقم بتحليلها كما يلي:
>
> * > "cell\_number":{"row":4,"col":2}\
>   > \
>   > \
>   > cell\_number|row ->String; \
>   > cell\_number|col -> Column<br>

**ترويسات الطلب** — املأها إذا لزم الأمر. ويشمل ذلك عادةً تنسيق البيانات و/أو رمز الوصول.

**معاملات JSON** — جسم الطلب، حيث تحدد معلمات البيانات بصيغة JSON. مثال:

**{"client\_id": "#{recipient\_id\_in\_builder}", "message":"Hello!"}**

لفهم بنية الاستجابة، اكتب #{custom\_answer} في حقل Message لإخراج قيمة المتغير.<br>

<figure><img src="/files/01addfce58f651735f69e4f06cfd3118e1095c18" alt=""><figcaption><p>استلام نتيجة طلب API كرسالة</p></figcaption></figure>

بعد ذلك، تسرد الوثائق المعاملات المسموح بها في قسم "Body":&#x20;

<figure><img src="/files/417de48344d11d5950ef28eb9daa223d3d2512b5" alt="" width="551"><figcaption></figcaption></figure>

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

يمكن الآن تنفيذ الطرق المدرجة إما كطلبات POST أو GET.

* [callback](#zapusk-bota)
* [whatsapp\_callback](#zapusk-bota)
* [message](#otpravka-soobshenii)
* [whatsapp\_message](#otpravka-soobshenii)

في السابق، كانت طرقنا تحتوي على معاملات ثابتة (مثل **client\_id** و **fb\_id**لتفعيل إجراءات المشتركين، مما فرض بعض القيود عند التكامل مع خدمات الطرف الثالث.

يمكنك الآن تحديد معامل الطلب الذي يجب أن يستخدمه SaleBot للعثور على معرّف المستخدم. استخدم معاملًا يبدأ بـ **بادئة value\_**، على سبيل المثال، **value\_user\_id** أو **value\_group\_id**.

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

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

هذا مفيد عند إعداد استقبال webhook من موقع ويب.

**لتحديد المتغير الذي يحتوي على client\_id**، استخدم المعامل value\_client\_id وقدم اسم المعامل الذي يحمل هذه القيمة.

**لتحديد المتغير الذي يحتوي على رقم الهاتف**، استخدم value\_phone.

**لتحديد المتغير الذي يحتوي على البريد الإلكتروني،** استخدم value\_email.

**لتحديد المتغير الذي يحتوي على user\_id**، استخدم value\_user\_id.

**لتحديد المتغير الذي يحتوي على group\_id**، استخدم value\_group\_id.

**لتحديد المتغير الذي يحتوي على الرسالة نفسها في webhook**، استخدم value\_message (يتم تمريره بالطريقة نفسها مثل المعاملات الأخرى).

مثال:

في العنوان، حدِّد 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.pro/api/d3f31dabef80ddeb73d43938b4ef8bb0/callback`\
`{"client_id":49177759, "message":"Hello world"}`

كما ترى، فإن اسم المعامل الذي يحتوي على القيمة يسبقه **value\_**.

{% hint style="warning" %}
يرجى الانتباه!&#x20;

تُنشئ بعض الأحداث إشعارات نظام داخل المشروع.

على سبيل المثال، توجد إشعارات نظام تحتوي على حقل رسالة غير فارغ ولكنها لا تتضمن نص العميل.

وفي الوقت نفسه، قد يُنشئ المشروع أيضًا webhooks للرسائل بمحتوى محدد، مثل "message: new\_chat\_member".

لذلك، من المهم التحقق من المحتوى: فإما أن يكون إشعارًا نظاميًا أو webhook لحدث محدد.
{% endhint %}

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

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

<details>

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

URL запроса: <https://chatter.mavibot.ai/api/#{api\\_key}/callback><br>

يمكن استخدام هذه الطريقة لتشغيل مسار تحويل لعميل أو لتأكيد إجراء على مورد خارجي. لن يرى العميل هذه الرسالة.<br>

**يرجى ملاحظة: سيتم حفظ أي معاملات تمررها أيضًا في المتغير**

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

صلاحية الوصول عند إنشاء مفتاح: **"صلاحية تعديل/حذف معلومات العميل"**.

<img src="/files/e4d5fd90341e978ea28070652ceb27f0c7cdfadc" alt="" data-size="original">

المسار

api key\* - رمز الوصول

Body

client\_phone - رقم الهاتف المستخدم للبحث عن العميل

client\_email - البريد الإلكتروني المستخدم للبحث عن العميل

client\_id - معرّف العميل في الباني

message - نص الرسالة

resume\_bot - True (معامل اختياري). إذا كان البوت متوقفًا مؤقتًا، يُستخدم هذا لإعادة تشغيله.&#x20;

مثال: resume\_bot = True

time\_shift - رقم. إذا تم تحديده، فستُرسل الرسالة بعد عدد الثواني المحدد من الوقت الحالي.

send\_time - التاريخ والوقت بالتنسيق "%Y-%m-%d %H:%M:%S" (مثال: "2024-10-16 13:15:59"). هذا يحدد التاريخ والوقت لإرسال الرسالة. إذا تم تحديد كل من time\_shift وsend\_time، فستكون الأولوية لـ time\_shift.

```
import requests
import json

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

</details>

### بدء تشغيل البوت باستخدام رقم WhatsApp

<details>

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

URL request: <https://chatter.mavibot.ai/api/\\>\<api\_key>/whatsapp\_callback

يمكن لهذه الطريقة تشغيل بوت WhatsApp بعد تسجيل العميل على الموقع أو تقديم طلب باستخدام رقم هاتفه.

**يرجى ملاحظة: سيتم حفظ أي معاملات تمررها أيضًا في المتغير**

صلاحية الوصول عند إنشاء مفتاح: **"صلاحية تعديل أو حذف معلومات العميل"**.

<img src="/files/e4d5fd90341e978ea28070652ceb27f0c7cdfadc" alt="" data-size="original">

المسار

api key\* - رمز الوصول

Body

name - اسم العميل\
message - نص الرسالة\
phone - رقم هاتف العميل\
bot\_id - معرّف البوت\
resume\_bot - True (معامل اختياري). إذا كان البوت متوقفًا مؤقتًا، فاستخدم هذا لاستئنافه. مثال: resume\_bot = True

time\_shift - رقم. إذا تم تحديده، فستُرسل الرسالة بعد عدد الثواني المحدد من الوقت الحالي.

send\_time - التاريخ والوقت بالتنسيق "%Y-%m-%d %H:%M:%S" (مثال: "2024-10-16 13:15:59"). هذا يحدد التاريخ والوقت لإرسال الرسالة. إذا تم تحديد كل من time\_shift وsend\_time، فستكون الأولوية لـ time\_shift.

</details>

### بدء تشغيل البوت باستخدام معرّف Telegram

<details>

<summary><mark style="color:green;">POST</mark> https://chatter.mavibot.pro/api/#{api_key}/tg_callback</summary>

URL request: <https://chatter.mavibot.pro/api/#{api\\_key}/tg\\_callback>

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

**يرجى ملاحظة: سيتم حفظ أي معاملات تمررها أيضًا في المتغيرات.**

صلاحية الوصول عند إنشاء مفتاح: **"صلاحية تعديل أو حذف معلومات العميل"**.

<img src="/files/e4d5fd90341e978ea28070652ceb27f0c7cdfadc" alt="" data-size="original">

المسار

api key\* - رمز الوصول

Body

message - نص الرسالة\
user\_id - معرّف مستخدم Telegram\
group\_id - اسم البوت (ينتهي بـ bot)\
resume\_bot - True (معامل اختياري). إذا كان البوت متوقفًا مؤقتًا، فاستخدم هذا لاستئنافه. مثال: resume\_bot = True

time\_shift - رقم. إذا تم تحديده، فستُرسل الرسالة بعد عدد الثواني المحدد من الوقت الحالي.

send\_time - التاريخ والوقت بالتنسيق "%Y-%m-%d %H:%M:%S" (مثال: "2024-10-16 13:15:59"). هذا يحدد التاريخ والوقت لإرسال الرسالة. إذا تم تحديد كل من time\_shift وsend\_time، فستكون الأولوية لـ time\_shift.

</details>

### إرسال رسائل callback إلى قائمة عملاء حسب platform\_id

<details>

<summary><mark style="color:green;">POST</mark>  https://chatter.mavibot.ai/api/#{api_key}/send_callback_by_platform_id</summary>

URL request: <https://chatter.mavibot.ai/api/#{api\\_key}/send\\_callback\\_by\\_platform\\_id>

عندما يتم العثور على عملاء لديهم platform\_id من القائمة داخل المشروع، سيتم إرسال callback بالنص الموجود في حقل callback\_text.\
\ <mark style="color:red;">**الحد: طلب واحد = بحد أقصى 300 إرسال**</mark>&#x20;

مثال على معلمات الطلب:\
{"platform\_ids":\[407184121, "79609879898", "2rwewefw"], "callback\_text": "test\_callback"}

صلاحية الوصول عند إنشاء مفتاح: **"صلاحية تعديل أو حذف معلومات العميل"**.

<img src="/files/e4d5fd90341e978ea28070652ceb27f0c7cdfadc" alt="" data-size="original">

المسار

api key\* - رمز الوصول

Body

platform\_ids - قائمة معرّفات العملاء في المراسِل\
callback\_text - نص callback\
group\_id - معرّف البوت

time\_shift - رقم. إذا تم تحديده، فستُرسل الرسالة بعد عدد الثواني المحدد من الوقت الحالي.

send\_time - التاريخ والوقت بالتنسيق "%Y-%m-%d %H:%M:%S" (مثال: "2024-10-16 13:15:59"). هذا يحدد التاريخ والوقت لإرسال الرسالة. إذا تم تحديد كل من time\_shift وsend\_time، فستكون الأولوية لـ time\_shift.

</details>

### إرسال رسالة callback إلى عميل عبر البريد الإلكتروني

<details>

<summary><mark style="color:green;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/email_callback</summary>

URL request: <https://chatter.mavibot.ai/api/#{api\\_key}/email\\_callback>

يمكن لهذه الطريقة تشغيل بوت البريد الإلكتروني بعد تسجيل العميل على الموقع أو تقديم طلب باستخدام بريده الإلكتروني. ستعثر الطريقة على بريد العميل الإلكتروني أو تنشئه إذا لم يكن موجودًا.

صلاحية الوصول عند إنشاء مفتاح: **"صلاحية تعديل أو حذف معلومات العميل"**.

<img src="/files/e4d5fd90341e978ea28070652ceb27f0c7cdfadc" alt="" data-size="original">

**يرجى ملاحظة: سيتم حفظ أي معاملات تمررها أيضًا في المتغير**

المسار

api key\* - رمز الوصول

Body

name - اسم العميل\
message - نص الرسالة\
email - عنوان البريد الإلكتروني\
email\_id\_bot - عنوان بريد البوت الإلكتروني\
resume\_bot - True (معامل اختياري).&#x20;

إذا كان البوت متوقفًا مؤقتًا، فاستخدم هذا لاستئنافه. مثال: resume\_bot = True

time\_shift - رقم. إذا تم تحديده، فستُرسل الرسالة بعد عدد الثواني المحدد من الوقت الحالي.

send\_time - التاريخ والوقت بالتنسيق "%Y-%m-%d %H:%M:%S" (مثال: "2024-10-16 13:15:59"). هذا يحدد التاريخ والوقت لإرسال الرسالة. إذا تم تحديد كل من time\_shift وsend\_time، فستكون الأولوية لـ time\_shift.

</details>

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

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

**attachment\_type** — يمكن أن يكون: **صورة، فيديو، رابط، ملف، أو صوت**.
\
عند إرسال مرفق، يكون معامل الرسالة اختياريًا.

**buttons** — يحدد الأزرار التي ستُرفق بالرسالة. يتوافق تنسيق الأزرار مع إعدادات الأزرار المتقدمة.

يمكن تمرير الأزرار بطريقتين: مع تلميح للمراسلات التي لا تدعم الأزرار، أو بدونه.

مثال على معامل الأزرار:

```
"buttons": {
  "hint": "سيتم عرض هذا النص في WhatsApp",
  "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
    }
  ]
}
```

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

<details>

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

URL запроса: <https://chatter.mavibot.ai/api/#{api\\_key}/message>

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

صلاحية الوصول عند إنشاء مفتاح: **"صلاحية تعديل أو حذف معلومات العميل"**.

<img src="/files/e4d5fd90341e978ea28070652ceb27f0c7cdfadc" alt="" data-size="original">

المسار

api key\* - رمز الوصول

Body

message\_id - رقم الكتلة للإرسال\
message - نص الرسالة\
client\_id - معرّف العميل في الباني\
attachment\_type - نوع عرض الملف. مطلوب إذا تم توفير attachment\_url.\
attachment\_url - رابط الملف\
buttons - الأزرار

time\_shift - رقم. إذا تم تحديده، فستُرسل الرسالة بعد عدد الثواني المحدد من الوقت الحالي.

send\_time - التاريخ والوقت بالتنسيق "%Y-%m-%d %H:%M:%S" (مثال: "2024-10-16 13:15:59"). هذا يحدد التاريخ والوقت لإرسال الرسالة. إذا تم تحديد كل من time\_shift وsend\_time، فستكون الأولوية لـ time\_shift.

```
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)

# إرسال مرفق
params = {
    "message": "some message",
    "client_id": "1234565",
    "attachment_type": "video/image/file",
    "attachment_url": "https://qwreqw"
}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/message'
requests.post(url, json=params)

# في 'attachment_type'، حدّد إما 'video' أو 'image' أو 'file'
# حسب نوع المرفق: فيديو أو صورة أو مستند.
```

</details>

### إرسال رسالة في WhatsApp

<details>

<summary><mark style="color:green;">POST</mark> https://chatter.salebot.pro/api/&#x3C;api_key>/whatsapp_message</summary>

URL запроса: <https://chatter.mavibot.pro/api/\\>\<api\_key>/whatsapp\_message

يتيح لك إرسال رسالة باسم البوت المتصل إلى الرقم المحدد. يجب أخذ whatsapp\_bot\_id من قسم "المراسِلات والدردشات". يتم تعيين معرّف فريد لكل حساب WhatsApp متصل بواسطة الباني.

صلاحية الوصول عند إنشاء مفتاح: **"صلاحية تعديل أو حذف معلومات العميل"**.

<img src="/files/e4d5fd90341e978ea28070652ceb27f0c7cdfadc" alt="" data-size="original">

المسار

api key\* - رمز الوصول

Body

message\_id - رقم الكتلة للإرسال\
whatsapp\_bot\_id - معرّف بوت WhatsApp الذي يجب إرسال الرسالة من خلاله\
attachment\_url - رابط الملف\
attachment\_type - نوع عرض الملف. مطلوب إذا تم توفير attachment\_url.\
message - نص الرسالة\
phone - رقم هاتف المستلم

time\_shift - رقم. إذا تم تحديده، فستُرسل الرسالة بعد عدد الثواني المحدد من الوقت الحالي.

send\_time - التاريخ والوقت بالتنسيق "%Y-%m-%d %H:%M:%S" (مثال: "2024-10-16 13:15:59"). هذا يحدد التاريخ والوقت لإرسال الرسالة. إذا تم تحديد كل من time\_shift وsend\_time، فستكون الأولوية لـ time\_shift.

```
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)
```

</details>

### إرسال رسائل جماعية

<details>

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

URL request: <https://chatter.mavibot.ai/api/#{api\\_key}/broadcast>

تتيح لك هذه الطريقة بدء بث جماعي.

يمكنك استخدام <mark style="color:red;">**أحد الخيارات التالية المتبادلة حصريًا**</mark>:

1. معامل list — سيتم إرسال البث إلى القائمة المحددة من العملاء.
2. معامل clients — سيتم إرسال البث إلى مصفوفة من معرّفات العملاء.
3. معاملات platform\_ids وgroup\_id — سيتم إرسال البث إلى مصفوفة من platform\_ids (معرّفات المراسِل) للبوت المحدد (group\_id).
4. إذا لم يتم توفير أي من المعاملات المذكورة أعلاه، فلن يتم إرسال البث.

المعاملات المطلوبة: message (و/أو attachment\_type وattachment\_url) أو message\_id.

صلاحية الوصول عند إنشاء مفتاح: **"صلاحية تعديل أو حذف معلومات العميل"**.

<img src="/files/e4d5fd90341e978ea28070652ceb27f0c7cdfadc" alt="" data-size="original">

**المسار**

api key\* - رمز الوصول

**Body**

**list** - رقم القائمة التي يجب إرسال البث إليها

clients - معرّفات العملاء في الباني

message - نص الرسالة

platform\_ids - معرّفات المستلمين في المراسِل. يجب استخدامها مع المعامل المطلوب group\_id

group\_id - مطلوب فقط عند استخدام platform\_ids. يتم تجاهله مع الخيارات الأخرى. يحدد البوت الذي سيُستخدم للإرسال إلى platform\_ids المحددة

attachment\_url - رابط الملف

attachment\_type - نوع عرض الملف. مطلوب إذا تم توفير attachment\_url.

buttons - الأزرار

message\_id - رقم الكتلة للإرسال

shift — عدد الثواني بين الرسائل. القيمة الافتراضية هي 0.2.

time\_shift - رقم. إذا تم تحديده، فستُرسل الرسالة بعد عدد الثواني المحدد من الوقت الحالي.

send\_time - التاريخ والوقت بالتنسيق "%Y-%m-%d %H:%M:%S" (مثال: "2024-10-16 13:15:59"). هذا يحدد التاريخ والوقت لإرسال الرسالة. إذا تم تحديد كل من time\_shift وsend\_time، فستكون الأولوية لـ time\_shift.

```
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)
```

</details>

### استرجاع سجل الرسائل

<details>

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

URL request: <https://chatter.mavibot.ai/api/#{api\\_key}/get\\_history?client\\_id=>

يمكن الحصول على معامل client\_id هنا. <mark style="color:red;">**رابط**</mark>

صلاحية الوصول عند إنشاء المفتاح: **"صلاحية قراءة معلومات العميل"**.

<img src="/files/238cace464e6de2fa2136aba0d1d61a03504afbf" alt="" data-size="original">

**المسار**

api key\* - رمز الوصول

**Body**

client\_id - معرّف العميل

limit - عدد العناصر في الاستجابة. الافتراضي: 2000، الحد الأقصى: 2000

start\_date - تاريخ بداية فترة الاختيار (مطلوب إذا تم تحديد stop\_date)، الصيغة: dd.mm.yyyy&#x20;

stop\_date - تاريخ نهاية فترة الاختيار (مطلوب إذا تم تحديد start\_date)، الصيغة: dd.mm.yyyy

```
{
  "status": "success",
  "result": [
    {
      "id": 104500,
      "answered": true,
      "client_replica": false,
      "message_id": 390,
      "message_from_outside": 0,
      "created_at": 1587895014,
      "text": "Meow meow",
      "attachments": {
        
      },
      "delivered": true,
      "error_message": "true",
      "manager_id": 12486,
      "manager_email": "example@mail.com"
    },
  ]
}
```

</details>

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

<details>

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

URL запроса: <https://chatter.mavibot.ai/api/#{api\\_key}/clear\\_history?client\\_id=>

يحذف سجل الدردشة&#x20;

صلاحية الوصول عند إنشاء مفتاح: **"صلاحية تعديل/حذف معلومات العميل"**.

<img src="/files/e4d5fd90341e978ea28070652ceb27f0c7cdfadc" alt="" data-size="original">

**المسار**

api key\* - رمز الوصول

**Body**

client\_id - معرّف العميل

```
import requests
import json


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

</details>

## كيفية إسناد العملاء

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

<details>

<summary><mark style="color:green;">POST</mark>  https://chatter.mavibot.ai/api/#{api_key}/assign_to_user</summary>

URL request: <https://chatter.mavibot.ai/api/#{api\\_key}/assign\\_to\\_user>

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

صلاحية الوصول عند إنشاء مفتاح: **"صلاحية تعديل/حذف معلومات العميل"**.

<img src="/files/e4d5fd90341e978ea28070652ceb27f0c7cdfadc" alt="" data-size="original">

**المسار**

api key\* - رمز الوصول

**Body**

client\_id - معرّف العميل\
email - بريد الموظف الإلكتروني (اختياري)

```
import requests
import json

params = {"client_id":"#{client_id}","email":"xxxxx@mail.ru"}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.mavibot.ai/api/{token}/broadcast'
requests.post(url, json=params)
```

</details>

### استيراد العملاء إلى النظام

<details>

<summary><mark style="color:green;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/load_clients</summary>

URL request: <https://chatter.mavibot.pro/api/#{api\\_key}/load\\_clients>

تتيح لك هذه الطريقة استيراد العملاء إلى النظام. عند رفع عملاء WhatsApp، يمكنك إدخال الرقم بأي تنسيق، سواء مع اللاحقة @s.whatsapp.net أو بدونها.

يمكن الحصول على معرّف المجموعة (group\_id) هنا عبر /api/\<api\_key>/connected\_channels. (إذا كان client\_type = 13 (الهاتف)، فإن group\_id يكون سلسلة فارغة: ""). <mark style="color:red;">**رابط**</mark>

يمكن العثور على نوع المراسِل الذي جاء منه العميل (client\_type) هنا. <mark style="color:red;">**رابط**</mark>

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

صلاحية الوصول عند إنشاء مفتاح: **"صلاحية تعديل أو حذف معلومات العميل"**.

<img src="/files/e4d5fd90341e978ea28070652ceb27f0c7cdfadc" alt="" data-size="original">

**المسار**

api key\* - رمز الوصول

**Body**

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

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

</details>

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

<details>

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

URL request: <https://chatter.mavibot.ai/api/\\>\<api\_key>/add\_to\_list

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

صلاحية الوصول عند إنشاء مفتاح: **"صلاحية تعديل أو حذف معلومات العميل"**.

<img src="/files/e4d5fd90341e978ea28070652ceb27f0c7cdfadc" alt="" data-size="original">

**المسار**

api key\* - رمز الوصول

**Body**

list\_id - رقم القائمة\
clients - مصفوفة معرّفات العملاء

مثال:\
JSON parameters\
{"list\_id":1170282, "clients":\[411262772, 646410963]}

</details>

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

<details>

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

URL request: <https://chatter.mavibot.ai/api/#{api\\_key}/remove\\_from\\_list>

يزيل العملاء من قائمة

صلاحية الوصول عند إنشاء مفتاح: **"صلاحية تعديل أو حذف معلومات العميل"**.

<img src="/files/e4d5fd90341e978ea28070652ceb27f0c7cdfadc" alt="" data-size="original">

**المسار**

api key\* - رمز الوصول

**Body**

list\_id - رقم القائمة\
clients - مصفوفة أرقام العملاء في باني Mavibot (قيم client\_id)

</details>

### استرجاع قائمة العملاء

<details>

<summary><mark style="color:blue;">GET</mark> https://chatter.mavibot.ai/api/&#x3C;api_key>/get_clients</summary>

**URL request:** <https://chatter.mavibot.a/aipi/\\>\<api\_key>/get\_clients

صلاحية الوصول عند إنشاء مفتاح: **"صلاحية تعديل أو حذف معلومات العميل"**.

<img src="/files/238cace464e6de2fa2136aba0d1d61a03504afbf" alt="" data-size="original">

**المسار**

api key\* - رمز الوصول

**Body**

offset – الإزاحة من العنصر الأول

limit – عدد العناصر في الاستجابة / الافتراضي: 500، الحد الأقصى: 500

list – رقم القائمة

reverse – يشير إلى الترتيب العكسي (من أقدم سجل إلى أحدث سجل). يعمل هذا المعامل فقط إذا لم يتم تحديد القائمة.

يعيد الحالة ومصفوفة من العناصر.

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

</details>

### استرجاع قائمة مشتركي البوت في أي مراسل

<details>

<summary><mark style="color:blue;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/subscribers</summary>

URL request: <https://chatter.mavibot.ai/api/#{api\\_key}/subscribers>

يسترجع معلومات العملاء من مراسل محدد.

*<mark style="color:red;">ملاحظة!</mark>* لا تعيد هذه الطريقة المتغيرات.

صلاحية الوصول عند إنشاء مفتاح: **"صلاحية تعديل أو حذف معلومات العميل"**.

<img src="/files/238cace464e6de2fa2136aba0d1d61a03504afbf" alt="" data-size="original">

**المسار**

api key\* - رمز الوصول

**Body**

page
\
tag – الوسم المحدد في صفحة الاشتراك
\
group – معرّف مجموعة VK المرتبط بها المشترك
\
date\_from – تم الاشتراك بعد هذا التاريخ (طابع زمني)
\
date\_to – تم الاشتراك قبل هذا التاريخ (طابع زمني)
\
client\_type – معرّف المراسِل الذي سيتم استرجاع قائمة المشتركين له. إذا لم يتم تحديده، فسيتم إرجاع جميع العملاء

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

</details>

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

### تعيين المتغيرات

<details>

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

URL request: <https://chatter.mavibot.ai/api/#{api\\_key}/save\\_variables>

&#x20;<mark style="color:green;">**!**</mark>**&#x20;**<mark style="color:$success;">**لا ينطبق أي حد على هذا الطلب.**</mark>&#x20;

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

صلاحية الوصول عند إنشاء مفتاح: **"صلاحية تعديل أو حذف معلومات العميل"**.

<img src="/files/238cace464e6de2fa2136aba0d1d61a03504afbf" alt="" data-size="original">

**تحديث**: تتيح لك معلمة clients تعيين المتغيرات دفعة واحدة.
\
مثال: {"client\_id":49177759, "variables":{"client.phone":"88888888888"}}

**المسار**

api key\* - رمز الوصول

**Body**

clients – مصفوفة من معرّفات العملاء لتعيين المتغيرات

client\_id – معرّف العميل

variables – تجزئة المتغيرات (أزواج مفتاح-قيمة)

```
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)
```

</details>

### استرجاع المتغيرات

<details>

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

URL request: <https://chatter.mavibot.ai/api/#{api\\_key}/get\\_variables?client\\_id=>

صلاحية الوصول عند إنشاء مفتاح: **"صلاحية تعديل أو حذف معلومات العميل"**.

<img src="/files/238cace464e6de2fa2136aba0d1d61a03504afbf" alt="" data-size="original">

مثال: <https://chatter.mavibot.ai/api/d3f31dabef80ddeb73d43938b4ef8bb0/get\\_variables?client\\_id=49177759>

**المسار**

api key\* - رمز الوصول

**Body**

client\_id - معرّف العميل

```
import requests
import json


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

</details>

## كيفية استرجاع معرّف العميل (client\_id)

### استرجاع client\_id باستخدام قيمة platform\_id

<details>

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

**URL request:** <https://chatter.mavibot.ai/api/#{api\\_key}/find\\_client\\_id\\_by\\_platform\\_id>

صلاحية الوصول عند إنشاء مفتاح: **"صلاحية تعديل أو حذف معلومات العميل"**.

<img src="/files/238cace464e6de2fa2136aba0d1d61a03504afbf" alt="" data-size="original">

**المسار**

api key\* - رمز الوصول

**Body**

platform\_ids - مصفوفة المعرّفات في المراسِل\
group\_id - معرّف البوت

```
[{
"id":15099119,
"tag":null,
"created_at":1618815253,
"name":"ОЛЬГА БЕЛИК",
"avatar":"https:\\/\\/files.mavibot.ai\\/uploads\\/avatars\\/256865200.jpg",
"platform_id":"2568652",
"group":"Mavibotai_bot",
"variables":{"tg_username":"@belik"}},

{"id":21087377,
"tag":null,
"created_at":1626275893,
"name":"John Smith",
"avatar":"https:\\/\\/files.mavibot.ai\\/uploads\\/avatars\\/571830542.jpg",
"platform_id":"571830542",
"group":"Mavibotai_bot",
"variables":{"tg_username":"@jsmith61"}
}]
```

</details>

### استرجاع معرّف العميل من الدردشة المباشرة

<details>

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

URL request: <https://chatter.mavibot.ai/api/#{api\\_key}/online\\_chat\\_client\\_id?recipient=>

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

صلاحية الوصول عند إنشاء مفتاح: "صلاحية تعديل أو حذف معلومات العميل".

<img src="/files/e4d5fd90341e978ea28070652ceb27f0c7cdfadc" alt="" data-size="original">

**المسار**

api key\* - رمز الوصول

**Body**

tag - الوسم (وسم العميل)\
name - اسم العميل\
recipient - معرّف الحوار على موقع ويب

#### من أين تحصل على **recipient؟**&#x20;

يمكنك الحصول عليه على الموقع الذي يحتوي على الدردشة المباشرة من Mavibot.ai، استخدم JS للحصول على الخاصية **MavibotAi.recipient\_id**.

<img src="/files/96f6c3ad6d43d4168987841f30bc1f3fe50787af" alt="" data-size="original">

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

</details>

### استرجاع client\_id بواسطة رقم WhatsApp

<details>

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

URL request: <https://chatter.mavibot.ai/api/#{api\\_key}/whatsapp\\_client\\_id?phone=>

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

صلاحية الوصول عند إنشاء مفتاح: "صلاحية تعديل أو حذف معلومات العميل".

<img src="/files/238cace464e6de2fa2136aba0d1d61a03504afbf" alt="" data-size="original">

**المسار**

api key\* - رمز الوصول

**Body**

phone - رقم الهاتف\
group\_id - معرّف البوت

</details>

### استرجاع client\_id بواسطة رقم الهاتف

<details>

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

URL request: <https://chatter.mavibot.ai/api/\\>\<api\_key>/find\_client\_id\_by\_phone?phone=&#x20;

تعيد هذه الطريقة معرّف العميل لإجراء طلبات API.

يتم البحث سواءً بين عملاء واتساب أو عبر المتغيرات.

صلاحية الوصول عند إنشاء مفتاح: "صلاحية تعديل أو حذف معلومات العميل".

<img src="/files/238cace464e6de2fa2136aba0d1d61a03504afbf" alt="" data-size="original">

**المسار**

api key\* - رمز الوصول

**Body**

phone - رقم الهاتف

</details>

### استرجاع client\_id حسب البريد الإلكتروني

<details>

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

عنوان طلب URL: <https://chatter.mavibot.ai/api/#{api\\_key}/find\\_client\\_id\\_by\\_email?email=&#x20>;

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

صلاحية الوصول عند إنشاء مفتاح: "صلاحية تعديل أو حذف معلومات العميل".

<img src="/files/238cace464e6de2fa2136aba0d1d61a03504afbf" alt="" data-size="original">

**المسار**

api key\* - رمز الوصول

**Body**

email - البريد الإلكتروني للبحث

</details>

### استرجاع client\_id حسب قيمة المتغير

<details>

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

عنوان طلب URL: <https://chatter.mavibot.ai/api/#{api\\_key}/find\\_client\\_id\\_by\\_var?var=\\&val=>

تعيد هذه الطريقة معرّف العميل لإجراء طلبات API.

صلاحية الوصول عند إنشاء المفتاح: "صلاحية قراءة معلومات العميل"

<img src="/files/238cace464e6de2fa2136aba0d1d61a03504afbf" alt="" data-size="original">

**المسار**

api key\* - رمز الوصول

**Body**

**var -** اسم المتغير الذي سيتم البحث به\
**val -** قيمة المتغير\
**group\_id -** معرّف المجموعة\
**search\_in -** مرِّر القيمة 'order' للبحث في متغيرات الصفقة؛ يبحث حتى ثلاث متغيرات لعملاء المشروع ويعيد قائمة بالعملاء الذين لديهم جميع المتغيرات المحددة.

</details>

### استرجاع معرّف أحدث عميل تم إنشاؤه حسب قيمة المتغير

<details>

<summary><mark style="color:blue;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/find_latest_client_id_by_var?var=&#x26;val=</summary>

عنوان طلب URL: <https://chatter.mavibot.ai/api/#{api\\_key}/find\\_latest\\_client\\_id\\_by\\_var> ?var=\&val=

تعيد هذه الطريقة معرّف أحدث عميل تم إنشاؤه لإجراء طلبات API. وهي تبحث في متغيرات العميل والصفقة معًا.

صلاحية الوصول عند إنشاء المفتاح: "صلاحية قراءة معلومات العميل"

<img src="/files/238cace464e6de2fa2136aba0d1d61a03504afbf" alt="" data-size="original">

**المسار**

api key\* - رمز الوصول

**Body**

**var -** اسم المتغير الذي سيتم البحث به\
**val -** قيمة المتغير

</details>

### استرجاع قائمة بقيم client\_id حسب قيمة المتغير

<details>

<summary><mark style="color:blue;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/find_all_client_id_by_var?var=&#x26;val=</summary>

عنوان طلب URL: <https://chatter.mavibot.ai/api/#{api\\_key}/find\\_all\\_client\\_id\\_by\\_var?var=\\&val=>

تعيد هذه الطريقة قائمة بمعرّفات العملاء الذين لديهم المتغير المحدد بالقيمة المحددة.

صلاحية الوصول عند إنشاء المفتاح: "صلاحية قراءة معلومات العميل"

<img src="/files/238cace464e6de2fa2136aba0d1d61a03504afbf" alt="" data-size="original">

**المسار**

api key\* - رمز الوصول

**Body**

**var -** اسم المتغير الذي سيتم البحث به\
**val -** قيمة المتغير

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

</details>

### استرجاع قائمة بقيم client\_id بناءً على عدة قيم لمتغيرات مختلفة

<details>

<summary><mark style="color:blue;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/find_all_client_id_by_several_vars?var=val</summary>

عنوان طلب URL: <https://chatter.mavibot.ai/api/#{api\\_key}/find\\_all\\_client\\_id\\_by\\_several\\_vars?var=val>

صلاحية الوصول عند إنشاء المفتاح: "صلاحية قراءة معلومات العميل".

<img src="/files/238cace464e6de2fa2136aba0d1d61a03504afbf" alt="" data-size="original">

**المسار**

api key\* - رمز الوصول

**Body**

variable1 - القيمة1

variable2 - القيمة2

variable3 - القيمة3

```
{
 "status":"success","client_ids":[93891114]
}
```

</details>

### البحث حسب المتغيرات

<details>

<summary><mark style="color:green;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/find_clients</summary>

عنوان طلب URL: <https://chatter.mavibot.ai/api/#{api\\_key}/find\\_clients>

تبحث هذه الطريقة حسب المتغيرات وتعيد قائمة بمعرّفات العملاء الذين يطابقون شروط الاستعلام.

افتراضيًا، يتم البحث في متغيرات العميل (مُوصى به): {"q": {"result": "ok", "var": "home", "var": "60"}} – يجب أن يمتلك العميل جميع المتغيرات المحددة

البحث في متغيرات الصفقة، يجب أن يكون أحد المتغيرات المحددة موجودًا على الأقل: {"q": {"result": "ok", "var": "home", "var": "60"}, "search\_in": "order", "include\_all": False}

اسم متغير العميل يساوي إحدى قيم القائمة: {"q": {"name": {"\_in": \["Joe", "Jane", "Donald"]}}}

اسم متغير العميل لا يساوي أيًّا من قيم القائمة: {"q": {"name": {"\_not\_in": \["Joe", "Jane", "Donald"]}}}

اسم متغير العميل لا يساوي "Joe": {"q": {"name": {"\_not": "Joe"}}}

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

صلاحية الوصول عند إنشاء المفتاح: "صلاحية قراءة معلومات العميل"

<img src="/files/238cace464e6de2fa2136aba0d1d61a03504afbf" alt="" data-size="original">

المعلمات

**المسار**

api key\* - رمز الوصول

**Body**

q – معلمة مطلوبة، تحتوي على شروط الاستعلام للبحث في المتغيرات

search\_in – يحدد متغيرات أي كيان سيتم البحث فيها؛ إذا لم يُحدَّد، فسيتم البحث في متغيرات العميل. يمكن أن يأخذ القيمة order.

include\_all – هل يجب استيفاء جميع الشروط في q؛

False – إذا تطابق شرط واحد على الأقل، يتم اختيار الكيان

```
نجاح
{"status":"success","client_ids":[41203, 5622354, 785212]} 
{"status":"success","client_ids":[]} 
{"status": "fail", "message": "Parameter "q" required"} {"status": "fail", "message": "Error in parameter format"}
خطأ
{"status":"fail","message":"Something went wrong"}
```

</details>

## كيفية التعامل مع الصفقات

### استرجاع معرّف الصفقة الحالية

<details>

<summary><mark style="color:blue;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/get_current_order_id</summary>

**URL request:** <https://chatter.mavibot.ai/api/#{api\\_key}/get\\_current\\_order\\_id>

صلاحية الوصول عند إنشاء المفتاح: "صلاحية قراءة معلومات CRM".

<img src="/files/a26b9d7e715e690f8843e71649827f90c3f9cc50" alt="" data-size="original">

**المسار**

api key\* - رمز الوصول

**Body**

client\_id - معرّف العميل

```
استجابة ناجحة: {"status":"success","order_id":40632}، حيث
order_id - معرّف الصفقة الحالية
استجابة خطأ: {"status":"client_not_found"}
```

</details>

### استرجاع قائمة الصفقات

<details>

<summary><mark style="color:blue;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/get_orders</summary>

**URL request:** <https://chatter.mavibot.ai/api/#{api\\_key}/get\\_orders>

صلاحية الوصول عند إنشاء المفتاح: "صلاحية قراءة معلومات CRM"

<img src="/files/a26b9d7e715e690f8843e71649827f90c3f9cc50" alt="" data-size="original">

**المسار**

api key\* - رمز الوصول

**Body**

client\_id - معرّف العميل

**order\_status** - مرحلة الصفقة: \
0 - الصفقات النشطة\
1 - الصفقات الناجحة\
2 - الصفقات غير الناجحة

```
استجابة ناجحة: {"status":"success","order_id":[40338,40340,40341]} 
استجابة خطأ: {"status":"client_not_found"}
```

</details>

### نقل صفقة إلى المرحلة التالية في مسار Mavibot

<details>

<summary><mark style="color:green;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/move_order_to_next_state</summary>

**URL request:** <https://chatter.mavibot.ai/api/#{api\\_key}/move\\_order\\_to\\_next\\_state>

صلاحية الوصول عند إنشاء المفتاح: "صلاحية تعديل/حذف معلومات CRM"

<img src="/files/a677f3896213282dd3f2b7240f4998d2de65a768" alt="" data-size="original">

**المسار**

api key\* - رمز الوصول

**Body**

client\_id - معرّف العميل

**order\_id** - معرّف الصفقة

```
استجابة ناجحة: 
{"status":"success","state_id":37}، حيث 
state_id - معرّف المرحلة في MavibotCRM 
استجابة خطأ: 
{"status":"client_not_found"}
```

</details>

### استرجاع بيانات الصفقة

<details>

<summary><mark style="color:green;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/get_order_vars</summary>

**URL request:** <https://chatter.mavibot.ai/api/#{api\\_key}/get\\_order\\_vars>

صلاحية الوصول عند إنشاء المفتاح: "صلاحية قراءة معلومات CRM"

<img src="/files/a26b9d7e715e690f8843e71649827f90c3f9cc50" alt="" data-size="original">

**المسار**

api key\* - رمز الوصول

**Body**

client\_id - معرّف العميل

**order\_id** - معرّف الصفقة

variables - مصفوفة المتغيرات\
(الصيغة:\["var\_name1", "var\_name2"])

```
استجابة ناجحة: 
{"status":"success","result":{"var_name1":"111","var_name2":"13.04.2023"}} 

مثال على خطأ: 
{"status":"client_not_found"}
```

</details>

### إضافة متغيرات الصفقة

<details>

<summary><mark style="color:green;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/set_order_vars</summary>

**URL request:** <https://chatter.mavibot.ai/api/#{api\\_key}/set\\_order\\_vars>

صلاحية الوصول عند إنشاء المفتاح: "صلاحية تعديل/حذف معلومات CRM"

<img src="/files/a677f3896213282dd3f2b7240f4998d2de65a768" alt="" data-size="original">

**المسار**

api key\* - رمز الوصول

**Body**

client\_id - معرّف العميل

**order\_id** - معرّف الصفقة

variables - قاموس من المتغيرات (المفتاح هو اسم المتغير، والقيمة هي ما يجب حفظه في ذلك المتغير)\
(الصيغة:{"var\_name": "var\_velue"})

```
استجابة ناجحة: {"status":"success"} 
استجابة خطأ: {"status":"order 12345 not found"}
```

</details>

### إنشاء صفقة

<details>

<summary><mark style="color:green;">POST</mark> https://chatter.mavibot.ai/api/#{api_key}/create_order</summary>

**URL request:** <https://chatter.mavibot.ai/api/#{api\\_key}/create\\_order>

صلاحية الوصول عند إنشاء المفتاح: "صلاحية تعديل/حذف معلومات CRM"

<img src="/files/a677f3896213282dd3f2b7240f4998d2de65a768" alt="" data-size="original">

**المسار**

api key\* - رمز الوصول

**Body**

client\_id - معرّف العميل

name - اسم الصفقة

description - وصف الصفقة

budget - مبلغ الصفقة

يجب تحديد أحد المعلمات التالية في الطلب: client\_id أو email أو phone.
\
إذا تم توفير عدة معلمات، فسيتم استخدام واحدة فقط. ترتيب الأولوية هو: client\_id > phone > email.
\
إذا تم توفير phone أو email ولم يوجد عميل بهذا رقم الهاتف أو البريد الإلكتروني، فسيتم إنشاء عميل جديد.

```
استجابة ناجحة: {"status":"success","order_id":40654}، 
حيث إن order_id هو معرّف الصفقة النشطة الجديدة.
استجابة خطأ: {"status":"client_not_found"}
```

</details>

### نقل صفقة إلى مرحلة في MavibotCRM

<details>

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

**URL request:** <https://chatter.mavibot.ai/api/#{api\\_key}/set\\_order\\_state>

صلاحية الوصول عند إنشاء المفتاح: "صلاحية تعديل/حذف معلومات CRM"

<img src="/files/a677f3896213282dd3f2b7240f4998d2de65a768" alt="" data-size="original">

**المسار**

api key\* - رمز الوصول

**Body**

client\_id - معرّف العميل

state\_id - رقم المرحلة التي يجب نقل صفقة العميل إليها

</details>

### استرجاع معرّف مرحلة القمع في Mavibot CRM

<details>

<summary><mark style="color:blue;">GET</mark> https://chatter.mavibot.ai/api/#{api_key}/get_order_state</summary>

**URL request:** <https://chatter.mavibot.ai/api/#{api\\_key}/get\\_order\\_state>

صلاحية الوصول عند إنشاء المفتاح: "صلاحية قراءة معلومات CRM"

<img src="/files/a26b9d7e715e690f8843e71649827f90c3f9cc50" alt="" data-size="original">

**المسار**

api key\* - رمز الوصول

**Body**

client\_id - معرّف العميل

state\_id - معرّف الصفقة (إذا لم يُحدَّد، فستُرجع الطريقة معرّف مرحلة الصفقة الحالية)

```
مثال على استجابة ناجحة:
{'status': 'success', 'state_id': 123456}

مثال على استجابة غير ناجحة:
{'status': 'order not found'}
```

</details>

## ما القدرات الأخرى المتاحة؟

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

<details>

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

**URL request:** <https://chatter.mavibot.ai/api/#{api\\_key}/check\\_whatsapp>

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

صلاحية الوصول عند إنشاء مفتاح: "صلاحية تعديل أو حذف معلومات العميل".

<img src="/files/238cace464e6de2fa2136aba0d1d61a03504afbf" alt="" data-size="original">

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

**المسار**

api key\* - رمز الوصول

**Body**

phone - رقم الهاتف المطلوب التحقق منه

</details>

### الحصول على قائمة تطبيقات المراسلة المتصلة بالمشروع

<details>

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

عنوان طلب URL: <https://chatter.mavibot.ai/api/\\>\<api\_key>/connected\_channels

صلاحية الوصول عند إنشاء مفتاح: "صلاحية تعديل أو حذف معلومات العميل".

<img src="/files/238cace464e6de2fa2136aba0d1d61a03504afbf" alt="" data-size="original">

تعيد الدالة المعلمة group\_id لكل تطبيق مراسلة، والتي يجب استخدامها عند استيراد العملاء.

بالنسبة إلى واتساب، تعيد أيضًا **status** حقلًا يمكن أن يأخذ القيم التالية:<br>

**NOT\_STARTED = 0**\
**STARTED = 1**\
**ASLEEP = 2**\
**STOPPED = 3**

**المسار**

api key\* - رمز الوصول

```
{'project_id': 1, 
'viber': [{
        'id': 14, 
        'uri': 'mavibotstage', 
        'name': 'mavibotstage', 
        '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': [], 
'avito': [], 
'ok': [], 
'vkontakte': [{
        'id': 33, 
        'group': '143414131',
        'group_id': '143414131'}]
}
```

</details>

### استرجاع قائمة الكتل من مسار البوت

<details>

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

**URL request:** <https://chatter.mavibot.ai/api/\\>\<api\_key>/get\_messages

صلاحية الوصول عند إنشاء مفتاح: "صلاحية تعديل أو حذف معلومات العميل".

<img src="/files/238cace464e6de2fa2136aba0d1d61a03504afbf" alt="" data-size="original">

**المسار**

api key\* - رمز الوصول

</details>

### استرجاع بيانات العميل المتداخلة

<details>

<summary>delimiter</summary>

لاسترجاع client\_id و/أو رقم هاتف العميل من القواميس المتداخلة (وليس في المستوى الأول)، استخدم معلمة delimiter.

أضف ما يلي إلى رابط الطلب:

?delimiter=1\&delimiter\_value\_client\_id={key1}1{key2}\&delimiter\_value\_phone={key1}1{key2}&#x20;

حيث:

?delimiter=1 – قيمة الفاصل التي تفصل بين المفاتيح {key1}1{key2}1{key3}

delimiter\_value\_client\_id={key1}1{key2} – لاسترجاع معرّف العميل

delimiter\_value\_phone={key1}1{key2} – لاسترجاع رقم هاتف العميل

{key1}, {key2}, … – مفاتيح تحتوي على القيم (يمكن أن تتضمن أي أحرف باستثناء الفاصل). يمكنك استخدام عدد غير محدود من المفاتيح:\
?delimiter=1\&delimiter\_value\_client\_id={key1}1{key2}1{key3}1{key4}1{key5}1{key6}. \
**تُمرَّر المفاتيح من دون أقواس معقوفة.**

استخدم الفاصل بين المفاتيح. على سبيل المثال، إذا كان delimiter=2، فسيكون {key1}2{key2}2{key3}; وإذا كان delimiter=5، فسيكون {key1}5{key2}5{key3}. تأكد من أن المفتاح لا يحتوي على حرف الفاصل.

مثال:

<https://chatter.mavibot.a/aipi/\\>\<api\_key>/callback<mark style="color:yellow;">**?delimiter=1\&delimiter\_value\_client\_id={key1}1{key2}\&delimiter\_value\_phone={key1}1{key2}**</mark>&#x20;

يمكنك أيضًا استرجاع المعرّف فقط أو رقم الهاتف فقط:&#x20;

<https://chatter.salebot.pro/api/\\>\<api\_key>/callback<mark style="color:green;">**?delimiter=1\&delimiter\_value\_client\_id={key1}1{key2} -**</mark> فقط معرّف العميل؛

<https://chatter.salebot.pro/api/\\>\<api\_key>/callback<mark style="color:green;">**?delimiter=1delimiter\_value\_phone={key1}1{key2}**</mark> - فقط رقم الهاتف؛

طرق API:

1. بدء البوت: <https://chatter.mavibotbot.ai/api/\\>\<api\_key>/callback
2. بدء البوت بواسطة رقم واتساب: <https://chatter.mavibotbot.ai/api/\\>\<api\_key>/whatsapp\_callback
3. بدء البوت بواسطة معرّف تيليغرام: <https://chatter.mavibotbot.ai/api/\\>\<api\_key>/tg\_callback
4. إرسال رسالة callback إلى عميل البريد الإلكتروني: <https://chatter.mavibotbot.ai/api/\\>\<api\_key>/email\_callback
5. إرسال رسالة إلى العميل: <https://chatter.mavibotbot.ai/api/\\>\<api\_key>/message
6. إرسال رسالة واتساب: <https://chatter.mavibotbot.ai/api/\\>\<api\_key>/whatsapp\_message
7. إرسال رسائل جماعية: <https://chatter.mavibotbot.ai/api/\\>\<api\_key>/broadcast
8. تعيين المتغيرات: <https://chatter.mavibotbot.ai/api/\\>\<api\_key>/save\_variables
   \\

</details>

{% hint style="success" %}
إذا كنت بحاجة إلى طرق إضافية، يُرجى التواصل مع الدعم.
{% 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/alaml-ma-api/mnshe-api.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.