# الدوال (API) في الآلة الحاسبة

{% hint style="warning" %}
تتوفر وظائف واجهة برمجة التطبيقات فقط في خطط "Business" و"MaviBot AI".
{% endhint %}

## MaviBot API

<mark style="color:red;">**الأسطورة:**</mark>\ <mark style="color:red;">**!**</mark> -المعاملات المطلوبة

### كيفية إرسال ردّ نداء

#### **callback()**

{% hint style="danger" %}
يمكنك إرسال ردّ نداء إلى عميل آخر فقط.

لا يمكنك إرسال ردّ نداء إلى نفسك!
{% endhint %}

<details>

<summary>الوصف</summary>

**callback(client\_id, callback\_message)**

المعلمات:

<mark style="color:red;">**!**</mark>**&#x20;client\_id** - معرّف العميل

<mark style="color:red;">**!**</mark>**&#x20;callback\_message** - نص رسالة ردّ النداء

</details>

<details>

<summary>مثال</summary>

ردّ النداء هو رسالة نظام خاصة يتعرّف عليها الروبوت كأمر لتنفيذ إجراء محدد. هذه الرسالة غير مرئية للمستخدم وتُسجَّل فقط داخل ملف العميل للمعالجة الداخلية.

لنرسل ردّ نداء إلى العميل باستخدام client\_id=73704021

<div data-with-frame="true"><figure><img src="/files/89bfd0379550f32eebb647137fc8c6412fdfdbf2" alt="" width="563"><figcaption></figcaption></figure></div>

بعد ذلك، نضبط الاستجابة لهذا الردّ الندائي في الكتلة مع الشرط.

</details>

<details>

<summary>مثال على الكود للنسخ</summary>

```
callback('73704021', 'callback TEST123')

callback(client_id, 'callback TEST123')
```

</details>

### كيفية إرسال ردّ نداء في تيليجرام

#### **tg\_callback()**

<details>

<summary>الوصف</summary>

**tg\_callback(platform\_id , callback\_message,group\_id, business\_connection\_id)**

المعاملات:

<mark style="color:red;">**!**</mark>**&#x20;platform\_id** -  معرّف عميل تيليجرام

<mark style="color:red;">**!**</mark>**&#x20;callback\_message** - نص رسالة ردّ النداء

&#x20;**group\_id** -  معرّف روبوت تيليجرام

**tg\_business -** للاستخدام مع عملاء الأعمال، تُمرَّر القيمة "1".

</details>

<details>

<summary>مثال</summary>

هذا مثال على المعاملات المطلوبة:

<div data-with-frame="true"><figure><img src="/files/7527c6f8ddf40ca231f7aded5831d4669fe71441" alt="" width="563"><figcaption></figcaption></figure></div>

هذا مثال على المعاملات الاختيارية

<div data-with-frame="true"><figure><img src="/files/7aecad1b4b9780a7519aa7d6547c90f1933c0dac" alt="" width="563"><figcaption></figcaption></figure></div>

</details>

<details>

<summary>مثال على الكود للنسخ</summary>

```
tg_callback('73704021', 'callback TEST123')

tg_callback(platform_id, 'callback TEST123', None, 1)
```

</details>

### كيفية إضافة إعادة توجيه للروبوت مع وسم استجابةً لزر ردّ النداء؟

<details>

<summary>الوصف</summary>

**tg\_callback\_url\_open(callback\_query\_id, url)**

المعاملات: \ <mark style="color:red;">**!**</mark>**&#x20;callback\_query\_id** - يتيح لك هذا المعرّف تحديد الشخص الذي ضغط الزر وعرض إشعار تنبيه له،\ <mark style="color:red;">**!**</mark>**&#x20;url** - URL- يحدد الروبوت والمعامل (يظهر بالشكل: t.me/your\_bot?start=XXXX، وبدلًا من your\_bot - اسم الروبوت)

</details>

### **كيفية إرسال رسالة إلى العميل**

**message() | platform\_message() | whatsapp\_message()**

{% hint style="info" %}
لتخزين النص مع فواصل الأسطر في متغير، اضبط القيمة كما يلي:

`text = "السطر الأول من النص" + "\n" + "السطر الثاني من النص" + "\n" +"السطر الثالث من النص"`
{% endhint %}

<details>

<summary>الوصف</summary>

**message(client\_id, text, message\_id, timeout)**

المعاملات:\ <mark style="color:red;">**!**</mark>**&#x20;client\_id** - معرّف العميل\ <mark style="color:red;">**!**</mark>**&#x20;text** - نص الرسالة\
**message\_id** - معرّف الكتلة. إذا تركت حقل النص فارغًا (") وملأت هذا المعامل، فسيتم إرسال النص من الكتلة المحددة إلى العميل.

*ملاحظة: إذا مرّرت المعامل message\_id إلى الدالة message، فسيظل تنفيذ الكتلة كاملًا، وسيُنقَل العميل المحدد في المعامل client\_id إلى الكتلة التي مررتها في message\_id.*

\
**timeout** - تأخير الرسالة أو وقت الإرسال المجدول. يمكنك استخدام المعامل timeout لتأخير إرسال الرسالة:\
a) تأخير بالثواني (حتى 3600 ثانية). إذا تجاوزت القيمة 3600، فستُرسل الرسالة بعد ساعة واحدة. إذا كانت القيمة سالبة، فستُرسل الرسالة فورًا. مثال: timeout = 50                                                                                                                 &#x20;

b) تاريخ ووقت محددان بالصيغة dd.mm.yyyy hh:mm، مثال: timeout = '03.04.2022 15:00'. إذا تم تحديد تاريخ في الماضي، فستُرسل الرسالة فورًا.

**platform\_message(platform\_id, text, client\_type,  message\_id, timeout,group\_id)**

المعلمات:\ <mark style="color:red;">**!**</mark>**&#x20;platform\_id** -  معرّف العميل في المراسِل\ <mark style="color:red;">**!**</mark>**&#x20;text** - نص الرسالة\
**client\_type -** نوع المراسِل، معامل اختياري. إذا لم يُحدَّد، فسيُبحث عن العميل في المراسِل نفسه الذي يرسل منه الروبوت الرسالة. وإذا تم تحديده، فسيتم العثور على العميل ضمن قاعدة بيانات المراسِل المحدد. يمكنك العثور على أنواع المراسلات [هنا.](/doc/ar/chatbot/functions/almtghyrat.md#how-to-work-with-variables)\
**message\_id** - معرّف الكتلة. إذا تم تحديده، فسيتلقى العميل الرسالة من الكتلة المحددة، وليس القيمة من معامل النص.\
**timeout** - وقت الإرسال أو التأخير. وهو مشابه للمعامل الذي يحمل الاسم نفسه في الدالة message().\
**group\_id** - معرّف الروبوت

**whatsapp\_message(phone, text, message\_id)**

المعلمات:\ <mark style="color:red;">**!**</mark>**&#x20;phone**- رقم هاتف العميل المسجَّل عليه واتساب\ <mark style="color:red;">**!**</mark>**&#x20;text** - نص الرسالة\
**message\_id** - هو معرّف الكتلة. إذا تُرك حقل النص فارغًا ('') وتم ضبط هذا المعامل، فسيتلقى العميل محتوى الرسالة من الكتلة المحددة.

{% hint style="info" %}
يجب توصيل روبوت واتساب بالمشروع.
{% endhint %}

</details>

<details>

<summary>مثال</summary>

مثال بسيط على إرسال رسالة باستخدام client\_id:

<div data-with-frame="true"><figure><img src="/files/beb0305c5d2e2f5b65373a7d7b8e641b978c139a" alt="" width="563"><figcaption><p>إرسال رسالة باستخدام client_id</p></figcaption></figure></div>

خيارات مختلفة لإرسال رسالة باستخدام client\_id:

<div data-with-frame="true"><figure><img src="/files/e30c7a0c8e72d5912a8be43025352d6adb8233a7" alt="" width="563"><figcaption><p>خيارات مختلفة لإرسال رسالة </p></figcaption></figure></div>

مثال على إرسال رسالة عبر platform\_message():

<div data-with-frame="true"><figure><img src="/files/f9deb5a0590ee13147af92241e30ccd76f41093b" alt="" width="563"><figcaption></figcaption></figure></div>

</details>

<details>

<summary>مثال على الكود للنسخ</summary>

```
/*إرسال رسالة باستخدام client_id*/
message(73704021, 'Message text for client')
/*إرسال رسالة باستخدام client_id مع تأخير 30 ثانية*/
message(73704021, 'Hi! Thanks for writing..','',30)
/*إرسال رسالة من الكتلة 3190 بواسطة client_id في 03.04.2022 الساعة 3 مساءً*/
message(73704021, '',3190, '03.04.2022 3pm')

/*إرسال رسالة في واتساب*/
whatsapp_message('79999999999', 'Message text for the client')
```

</details>

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

get\_client\_id\_by\_platform\_i&#x64;**()**

<details>

<summary>الوصف</summary>

**get\_client\_id\_by\_platform\_id(client\_type, platform\_id , group)**&#x20;

بعد التنفيذ، ستُرجع الدالة client\_id إذا تم العثور على عميل يطابق الشروط المحددة؛ وإلا فستُرجع None.

<mark style="color:red;">**!**</mark> **client\_type** - المراسِل. لقيمة client\_type اقرأ [هذه المقالة](/doc/ar/chatbot/functions/almtghyrat.md).&#x20;

<mark style="color:red;">**!**</mark> **platform\_id** - معرّف العميل في المراسِل المحدد.

**group**  - وهو معامل مطلوب إذا كان أكثر من روبوت مراسِل واحد متصلًا.

{% hint style="warning" %}
إذا كانت عدة مراسلات من النوع نفسه متصلة في المشروع، فسيكون البحث بناءً على جميع المراسلات المتصلة من هذا النوع.

في هذه الحالة، نوصي بتمرير المعامل group.
{% endhint %}

</details>

### الدالة لطلبات GET:  requests\_get(url, answer\_type, headers, params, auth, proxy)&#x20;

<details>

<summary>الوصف</summary>

<mark style="color:red;">**!**</mark>**&#x20;url** - هو الرابط الذي يتم تقديم الطلب إليه

**answer\_type**  – معامل اختياري يحدد ما الذي يجب إرجاعه من استجابة الخادم: ('status' – يعيد رمز حالة الاستجابة؛ 'json' – يعيد جسم JSON للاستجابة؛ 'text' – يعيد النص الخام للاستجابة، وأي قيمة أخرى (بما فيها الافتراضية) تعيد استجابة بالشكل: '{"status": status\_code, "data": data}')

**headers** - معامل اختياري لتمرير ترويسات الطلب،&#x20;

**params** - هو *get* معاملات الطلب (يمكن أيضًا تضمينها مباشرةً في الرابط)،

**auth** - هو معامل اختياري مفيد لمصادقة واجهة برمجة التطبيقات. إذا كنت لا تريد استخدام أي معامل اختياري لكنك تحتاج إلى التالي، فمرّر 0 هنا.

**proxy** -  هو معامل اختياري؛ يقبل قيمة واحدة: "de"، والتي تمرّر الطلب عبر عنوان IP أوروبي.

</details>

### دوال لطلبات POST

<details>

<summary>الوصف</summary>

requests\_post(url, answer\_type, headers, data, json\_data, auth, proxy)

<mark style="color:red;">**!**</mark>**&#x20;url** - هو الرابط الذي يتم تقديم الطلب إليه،

**answer\_type** - هو معامل اختياري يحدد ما الذي يجب إرجاعه من استجابة الخادم: ('status' – يعيد رمز حالة الاستجابة؛ 'json' – يعيد جسم JSON للاستجابة؛ 'text' – يعيد النص الخام للاستجابة، وأي قيمة أخرى (بما فيها الافتراضية) تعيد استجابة بالشكل: '{"status": status\_code, "data": data}')

**headers** - هو معامل اختياري لتمرير ترويسات الطلب

**data** - هو معامل اختياري؛ ويمثل جسم الطلب عندما لا تعمل الواجهة مع json.

&#x20;**json\_data** - هو معامل اختياري؛ ويمثل أيضًا جسم الطلب. يجب استخدام أحد هذين المعاملين فقط في كل مرة.

{% hint style="warning" %}
يرجى ملاحظة: قد تمنع بعض إعدادات الترويسات إرسال الطلب بنوع معين من الجسم.
{% endhint %}

**auth** - هو معامل اختياري مفيد لمصادقة واجهة برمجة التطبيقات. إذا كنت لا تريد استخدام أي معامل اختياري لكنك تحتاج إلى التالي، فمرّر 0 هنا

**proxy** - هو معامل اختياري؛ يقبل قيمة واحدة: "de"، والتي تمرّر الطلب عبر عنوان IP أوروبي.

</details>

### دوال لطلبات PUT

<details>

<summary>الوصف</summary>

requests\_put(url, answer\_type, headers, data, auth, proxy)

<mark style="color:red;">**!**</mark>**&#x20;url** - هو الرابط الذي يتم تقديم الطلب إليه

**answer\_type** - هو معامل اختياري يحدد ما الذي يجب إرجاعه من استجابة الخادم: ('status' – يعيد رمز حالة الاستجابة؛ 'json' – يعيد جسم JSON للاستجابة؛ 'text' – يعيد النص الخام للاستجابة، وأي قيمة أخرى (بما فيها الافتراضية) تعيد استجابة بالشكل: '{"status": status\_code, "data": data}')

**headers** - هو معامل اختياري لتمرير ترويسات الطلب

**data** - هو معامل اختياري؛ ويمثل جسم الطلب عندما لا تعمل الواجهة مع json.

**auth** - هو معامل اختياري مفيد لمصادقة واجهة برمجة التطبيقات. إذا كنت لا تريد استخدام أي معامل اختياري لكنك تحتاج إلى التالي، فمرّر 0 هنا

proxy - هو معامل اختياري؛ يقبل قيمة واحدة: "de"، والتي تمرّر الطلب عبر عنوان IP أوروبي.

**data\_is\_json** هو معامل اختياري.\
إذا تم ضبطه، فسيتم إرسال البيانات الممررة في `data` بصيغة JSON.\
لتفعيله، مرّر `'1'`.

</details>

### دوال لطلبات PATCH

requests\_patch(url, answer\_type, headers, data, auth, proxy)

<details>

<summary>الوصف</summary>

<mark style="color:red;">**!**</mark>**&#x20;url** - هو الرابط الذي يتم تقديم الطلب إليه

**answer\_type** - هو معامل اختياري يحدد ما الذي يجب إرجاعه من استجابة الخادم: ('status' – يعيد رمز حالة الاستجابة؛ 'json' – يعيد جسم JSON للاستجابة؛ 'text' – يعيد النص الخام للاستجابة، وأي قيمة أخرى (بما فيها الافتراضية) تعيد استجابة بالشكل: '{"status": status\_code, "data": data}')

**headers** - هو معامل اختياري لتمرير ترويسات الطلب

**data** - هو معامل اختياري؛ ويمثل جسم الطلب عندما لا تعمل الواجهة مع json.

**auth** - هو معامل اختياري مفيد لمصادقة واجهة برمجة التطبيقات. إذا كنت لا تريد استخدام أي معامل اختياري لكنك تحتاج إلى التالي، فمرّر 0 هنا

proxy - هو معامل اختياري؛ يقبل قيمة واحدة: "de"، والتي تمرّر الطلب عبر عنوان IP أوروبي.

</details>

### دوال لطلبات DELETE

requests\_delete(url, answer\_type, headers, data, json\_data, auth, proxy)

<details>

<summary>الوصف</summary>

<mark style="color:red;">**!**</mark>**&#x20;url** - هو الرابط الذي يتم تقديم الطلب إليه

**answer\_type** - هو معامل اختياري يحدد ما الذي يجب إرجاعه من استجابة الخادم: ('status' – يعيد رمز حالة الاستجابة؛ 'json' – يعيد جسم JSON للاستجابة؛ 'text' – يعيد النص الخام للاستجابة، وأي قيمة أخرى (بما فيها الافتراضية) تعيد استجابة بالشكل: '{"status": status\_code, "data": data}')

**headers** - هو معامل اختياري لتمرير ترويسات الطلب

data -  هو معامل اختياري؛ ويمثل جسم الطلب عندما لا تعمل الواجهة مع json.

json\_data - هو اختياري ويمكن استخدامه أيضًا كجسم للطلب. ومع ذلك، يجب استخدام خيار واحد فقط في كل مرة

auth - هو معامل اختياري مفيد لمصادقة واجهة برمجة التطبيقات. إذا كنت لا تريد استخدام أي معامل اختياري لكنك تحتاج إلى التالي، فمرّر 0 هنا

proxy - هو معامل اختياري؛ يقبل قيمة واحدة: "de"، والتي تمرّر الطلب عبر عنوان IP أوروبي.

</details>

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

<details>

<summary>الوصف</summary>

get\_block\_name\_by\_id(block\_id)

<mark style="color:red;">**!**</mark>**&#x20;block\_id** — معرّف الكتلة (id)&#x20;

</details>


---

# 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/chatbot/functions/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.