# المتغيرات

## كيفية استخدام المتغيرات

دعنا نستكشف ما هي المتغيرات وكيفية استخدامها بفعالية عند إنشاء روبوتات الدردشة في MaviBot.

{% hint style="danger" %}
**يرجى الانتباه إلى الحدود التالية للنظام الخاصة بالمتغيرات والثوابت ضمن مشروع واحد:**

**متغيرات القالب:**

* **الحد الأقصى للعدد:** 100 متغير
* **الحد الأقصى لطول الاسم:** 100 حرف

**ثوابت المشروع:**

* **الحد الأقصى للعدد:** 50 ثابتًا
* **الحد الأقصى لطول الاسم:** 100 حرف
* **الحد الأقصى لطول القيمة:** 5,000 حرف
  {% endhint %}

المتغير هو موقع تخزين مُسمّى للبيانات، ويُعرَّف بواسطة تسمية نصية فريدة.

<div data-with-frame="true"><figure><img src="/files/3f5f62f3207b61fd7f2455088782929e3a2dec64" alt=""><figcaption></figcaption></figure></div>

&#x20;                                          *الشكل 1: متغير باسم `total`، يخزن مبلغًا للدفع*.

يوفر MaviBot عدة أنواع من المتغيرات:

1. [متغيرات مدمجة ](#built-in-variables)
2. [متغيرات النظام](#system-variables)&#x20;
3. متغيرات يعرّفها المستخدم — وهي التي تنشئها بنفسك داخل المشروع.

**لإعلان متغير** يعني إسناد قيمة إلى حاوية مسماة. وبعبارة أخرى، فإن عبارة مثل ***a=0*** هي إعلان المتغير ***a***. لقد أخبرنا المنشئ للتو (أعلنا له) أننا سنخزن رقمًا في المتغير ***a***، وفي الوقت الحالي، هذه القيمة هي ***0***.

**إسناد قيمة إلى متغير** يحمل المعنى نفسه.

العبارات **"إسناد قيمة دالة إلى متغير"** أو **"تعيين متغير ليكون مساويًا لدالة"** تُستخدم أيضًا بشكل شائع. المبدأ نفسه: بدلًا من إسناد قيمة محددة، تقوم بإسناد ناتج دالة. على سبيل المثال: **s\_id = tg\_send\_message(platform\_id, "مرحبًا!")** في هذه الحالة، سيتم تخزين ناتج الدالة في المتغير.

**لإعادة ضبط متغير** يعني إسناد القيمة **0**.

[**الدوال والطرائق**](/doc/ar/chatbot/functions/almtghyrat.md#functions-for-working-with-variables)  هي مجموعات أوامر مُعرّفة مسبقًا تم إعدادها مسبقًا بواسطة MaviBot. تتطلب معظم الدوال معاملات - وهي القيم التي يمكن للدالة أو الطريقة فهمها. وبمجرد أن يتلقى الروبوت المعاملات اللازمة، ينفذ أمرًا محددًا.

**`tg_send_message(platform_id, "مرحبًا!")` —** تقوم هذه الدالة بإرسال الرسالة "مرحبًا!" في Telegram.

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

<p align="center"><em>الشكل 2. مثال على متغير باسم text1 تم إسناده إلى دالة.</em></p>

### <mark style="color:red;">**قواعد العمل مع المتغيرات:**</mark>

1. يمكن أن يبدأ اسم المتغير فقط بـ **حرف**؛ ولا يمكن أن يبدأ برقم.

   **Age1 - ✅ صحيح**  &#x20;

   1Age - ❌ <mark style="color:red;">غير صحيح</mark>

   **age1 -** **✅ صحيح**   <mark style="color:blue;">- الخيار الموصى به</mark> <br>
2. لا يمكن أن يحتوي المتغير على مسافات أو أحرف خاصة، باستثناء الشرطة السفلية (\_).

   **Name\_Surname - ✅ صحيح** &#x20;

   Name Surname - ❌ <mark style="color:red;">غير صحيح</mark>

   **nameSurname** **- ✅ صحيح**   <mark style="color:blue;">- الخيار الموصى به</mark><br>

   لا يمكن استخدام الكلمات المحجوزة في لغات البرمجة كأسماء متغيرات، على سبيل المثال: print، true، false، count، sum، وما إلى ذلك.<br>
3. <mark style="color:$primary;">يُمنع</mark> <mark style="color:red;">**بشكل صارم**</mark> <mark style="color:$primary;">باستخدام</mark> أسماء المتغيرات المدمجة ومتغيرات النظام للمتغيرات التي يعرّفها المستخدم. يمكنك العثور على قائمة هذه المتغيرات هنا. <mark style="color:red;">**رابط**</mark>
4. <mark style="color:blue;">**نوصي بـ:**</mark>
   * استخدم أسماء لاتينية (إنجليزية) للمتغيرات.
   * استخدم أسماء متغيرات قصيرة ولكن ذات معنى، على سبيل المثال: totalSum، pay\_name، <mark style="color:red;">**ns**</mark>، name\_client، إلخ.

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

ضع اسم المتغير بين أقواس معقوفة **#{}**. يمكنك الإشارة إلى قيمته في حقل نص الرسالة بهذه الطريقة. ومع ذلك، في حقل "Calculator"، يجب الإشارة إلى قيمة المتغير ببساطة بواسطة اسمه، دون أي صياغة إضافية.

{% hint style="danger" %}
الـ **#{}** يتيح لك البناء استرجاع قيمة متغير. ويُستخدم في حقل "نص الرسالة" لإدراج قيمة المتغير داخل النص.
{% endhint %}

مثال:

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

{% hint style="success" %}
يدعم النظام المتغيرات المتداخلة، حيث تكون قيمة أحد المتغيرات جزءًا من اسم متغير آخر. على سبيل المثال: **#{q#{test#{i}}}**
{% endhint %}

في حقل "Calculator"، أشِر إلى المتغيرات بأسمائها دون استخدام الصيغة #{}. على سبيل المثال، إذا كان لدينا متغيران: السعر (sum) والكمية (num).

`num = 10`

`sum = 1500`

<div data-with-frame="true"><figure><img src="/files/36d49e98b2861aa10b0cd8f18a3744919ba5c142" alt=""><figcaption></figcaption></figure></div>

### كيفية عرض المجموع الكلي&#xD;

أدخل ما يلي في الحاسبة:

`total_sum = sum1 * num2` **✅ صحيح**

<div data-with-frame="true"><figure><img src="/files/05b15565b9501618e233818f200f7b1cbd06c509" alt=""><figcaption></figcaption></figure></div>

**كيفية&#x20;*****عدم*****&#x20;القيام بذلك:**

`total_sum = #{sum1} * #{num2}` - ❌ <mark style="color:red;">غير صحيح</mark>

### كيفية حذف متغير من الروبوت

لحذف (مسح) متغير، أدخل أحد ما يلي في حقل "Calculator":
\
YourVariableName =
\
أو
\
YourVariableName = ""

بعد علامة يساوي، اترك مسافة أو استخدم علامات اقتباس مزدوجة (أو مفردة).

{% hint style="warning" %} <mark style="color:red;">**يرجى الانتباه!**</mark> من المهم استخدام البادئة الصحيحة للدلالة على الجهة التي ينتمي إليها المتغير.

لمتغيرات مستوى المشروع (المخزنة في إعدادات المشروع)، استخدم البادئة **project:**
\
مثال:
&#x20;*project.YourVariableName =*
&#x20;أو
&#x20;*project.YourVariableName = ""*

لمتغيرات مستوى العميل، استخدم البادئة **client**:
\
مثال:
&#x20;*client.YourVariableName =* أو
&#x20;*client.YourVariableName = ""*

لمتغيرات مستوى الصفقة، لا حاجة إلى بادئة.
{% endhint %}

## متغيرات مدمجة

فيما يلي قائمة المتغيرات المدمجة:

**#{none}** - تجاهل الرسالة

**#{api\_key}** - رمز API المستخدم في استدعاءات Salebot API

**#{attachment\_url}** - يحتوي على رابط المرفق

**#{attachments}** - مصفوفة JSON لعناوين URL الخاصة بالمرفقات من رسالة المستخدم

**#{avatar}** - رابط صورة المستخدم الرمزية (تظهر في قسم "العملاء")

**#{client\_id}** - معرّف العميل في المُنشئ، ويُستخدم أيضًا في طلبات API

**#{client\_type}** - نوع المراسِل الذي جاء منه العميل (تُوصف القيم \[هنا])

**#{current\_date}** - التاريخ الحالي بصيغة dd.mm.yyyy، بناءً على المنطقة الزمنية للمشروع

**#{current\_time}** - الوقت الحالي بصيغة hh:mm، بناءً على المنطقة الزمنية للمشروع

**#{custom\_answer}** - الرد المستلم من الخادم المحدد في حقل "Server response URL"

**#{message\_from\_outside}** - نوع الرسالة الواردة. القيم الممكنة:\
\&#xNAN;*رسالة عادية = 0*\
*رسالة مرسلة عبر API = 1*\
*إشعار callback (خلفية صفراء في الحوار) = 3*\
*إشعار هاتفي (خلفية زرقاء فاتحة في الحوار) = 5* \
*يُنشأ هذا المتغير مع كل رسالة واردة ولكنه لا يظهر في بطاقة العميل.*
\
*يمكنك استخدامه في حقل "Variable for comparison" لإعداد الشروط لمشغلات الكتل والاتصالات.*

**#{date\_of\_creation}** - تاريخ إضافة المستخدم إلى الروبوت أو مراسلته لأول مرة

**#{full\_name}** - الاسم الكامل للمستخدم (الاسم الأول واسم العائلة)

**#{group}** - الروبوت الذي يرتبط به العميل (يظهر كـ "مرتبط بالروبوت" في بطاقة العميل)

**#{main\_client\_id}** - معرّف العميل الرئيسي ضمن مجموعة من بطاقات العملاء المرتبطة

**#{message\_id}** - معرّف حالة المحادثة الحالية مع العميل (القيمة الافتراضية NONE)

**#{messenger}** - اسم المراسِل الذي جاء منه العميل

\#{name} - الاسم الأول للمستخدم

\#{next\_day} - تاريخ الغد بصيغة dd.mm.yyyy (مفيد لجدولة الرسائل)

**#{order\_id}** - معرّف الطلب (معرّف العميل ومعرّف الطلب الداخلي مفصولان بشرطة)

**#{order}** - محتويات الطلب المقدم من المستخدم

**#{platform\_id}** - معرّف العميل في منصة المراسلة

**#{question}** - الرسالة المرسلة من المستخدم

**#{timestamp}** - الطابع الزمني الحالي بما في ذلك أجزاء الألف من الثانية

**#{time\_of\_creation}** - وقت إضافة المستخدم إلى الروبوت أو مراسلته لأول مرة

**#{wa\_bot}** - رقم WhatsApp الذي راسله المستخدم (مفيد لتمريره إلى حقول CRM وتوزيع العملاء المحتملين بين المديرين)

**#{weekday}** - يوم الأسبوع كرقم (الاثنين = 1، الثلاثاء = 2، إلخ.)

#### **قيم client\_type**

<table><thead><tr><th width="195.3359375">القيمة</th><th width="211.8125">المراسِل</th></tr></thead><tbody><tr><td>1  </td><td>لـ Telegram </td></tr><tr><td>2  </td><td>لـ Viber</td></tr><tr><td>3  </td><td>لـ Facebook</td></tr><tr><td>5  </td><td>للدردشة عبر الإنترنت</td></tr><tr><td>10</td><td>لـ Instagram</td></tr><tr><td>14 </td><td>البريد الإلكتروني </td></tr><tr><td>16</td><td>حساب Telegram Business </td></tr><tr><td>21</td><td>حساب Telegram</td></tr><tr><td>22</td><td>TikTok</td></tr></tbody></table>

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

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

{% hint style="info" %}
يمكنك العثور على متغيرات نظام إضافية في التوثيق. وهي موجودة ضمن الأقسام ذات الصلة باستخدامها.
{% endhint %}

**phone** - رقم الهاتف

**notSubscribed** - إذا كانت قيمة المتغير تساوي 1، فهذا يعني أن العميل ألغى الاشتراك في الرسائل ولن يتلقى أي رسائل

**clientBlocked** - العميل محظور، والروبوت لا يعمل معه

**story\_url** - معرّف قصة Instagram التي ردّ عليها العميل

**viewed\_page** - الصفحة التي يكتب منها المستخدم في الدردشة عبر الإنترنت

**wa\_bot** - رقم هاتف روبوت WhatsApp

{% hint style="info" %}
لمعرفة المتغيرات التي يمكن إنشاؤها أثناء الدفع، راجع أدلة التكامل الخاصة بخدمات الدفع في قسم "[نظام الدفع](/doc/ar/aldfa.md)".
{% endhint %}

## متغيرات مخصصة

تنقسم المتغيرات المخصصة إلى:

* متغيرات المشروع (وتُسمى أيضًا المتغيرات المشتركة)
* [متغيرات العميل](#custom-variables)&#x20;
* [متغيرات الصفقة](#key-deal-variables) (وتُسمى أيضًا المتغيرات العادية)
* [الثوابت](#how-to-set-constant-variables)&#x20;

سيتم شرح كل نوع من المتغيرات أدناه.

{% hint style="info" %}
يرجى تجنب استخدام الأسماء نفسها لأنواع مختلفة من المتغيرات لتفادي الارتباك عندما يعرض Builder أو يستخدم قيمة مختلفة عما كنت تتوقعه.
{% endhint %}

{% hint style="info" %}
عند إسناد قيمة إلى متغير، من المهم تحديد نوعه باستخدام البادئة المناسبة:

**client.** (لمتغيرات العميل) و **project.** (لمتغيرات المشروع). لا تُستخدم أي بادئة لمتغيرات الصفقة.

يتم حذف البادئة عند استرجاع قيمة المتغير.

مثال:
&#x20;لنتخيل أنك تريد إنشاء متغير مشروع باسم like ليعمل كعداد للإعجابات من عملائك.

**project.like = 0 - إعلان، يتم مرة واحدة**

في الكتلة التي تحتاج فيها إلى عدّ الإعجابات، اكتب:
&#x20;**project.like = like + 1**
{% endhint %}

{% hint style="info" %}
ترتيب أولوية المتغيرات:
&#x20;متغيرات الصفقة لها أعلى أولوية، تليها متغيرات العميل، ثم متغيرات المشروع.
{% endhint %}

#### **معرّف المراسِل (platform\_id)**

**معرّف المراسِل (platform\_id)** هو معرّف المستخدم/الدردشة/القناة داخل المراسِل. للعثور عليه، افتح المحادثة مع العميل المطلوب في قسم "العملاء". على الجانب الأيمن من نافذة الدردشة، انتقل إلى علامة التبويب "**حول العميل** - **متغيرات النظام"** أو علامة التبويب "**الكل"** .

الـ **`platform_id`** هو متغير دائم ينشئه النظام ويمثل معرّف المراسِل الفريد للمستخدم.

* **الاستمرارية:** يبقى هذا المعرف ثابتًا للمستخدم. حتى إذا حذفت سجله من المنشئ، فسيظل `platform_id` نفسه عند إعادة التسجيل.
* **المصدر:** يتم تعيين المعرف بواسطة منصة المراسلة (مثل Telegram أو WhatsApp) عندما يتفاعل المستخدم مع الروبوت لأول مرة.

يوضح المثال التالي كيف يظهر `platform_id` في بطاقة العميل.

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

يوجد المتغير platform\_id للمستخدمين العاديين وكذلك للمجتمعات والقنوات والدردشات.

للحصول على **platform\_id** (معرّف المراسِل) لقناة Telegram التي يكون الروبوت فيها مشرفًا، ما عليك سوى إرسال رسالة إلى القناة من حسابك الشخصي. سيؤدي ذلك تلقائيًا إلى إنشاء حوار بين الروبوت والقناة.

يمكنك نسخ قيمة **platform\_id** الخاصة بالقناة في قسم "حول العميل".

في Telegram، يبدأ معرّف المراسِل للقنوات دائمًا بعلامة ناقص (-). عند استخدام الدوال، تأكد من تضمين القيمة كاملة، بما في ذلك علامة الناقص.&#x20;

## كيفية استخدام المتغيرات

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

لذا، لننشئ كتلة البداية:

<div data-with-frame="true"><figure><img src="/files/580b75c9b09feeff2f772a950517e04fba8315a0" alt=""><figcaption></figcaption></figure></div>

**الخطوة 1: أنشئ كتلة "شكرًا"**

أنشئ كتلة جديدة برسالة تشكر المستخدم على إدخاله.

**الخطوة 2: اضبط الانتقال**

على الاتصال المؤدي إلى هذه الكتلة، اضبط المشغل التالي:

1. فعّل **"User inputs data"** المفتاح.
2. في **"Input data"** ، أدخل اسم المتغير: **`name`**.

<div data-with-frame="true"><figure><img src="/files/779cb2a3ba272ee4c2eeaa2e7f1310da3ce9823e" alt=""><figcaption></figcaption></figure></div>

يتم تخزين إدخال المستخدم في المتغير **`Name`** . يمكن إعادة استخدام هذه القيمة في أي كتلة لاحقة باستدعاء المتغير باستخدام الصيغة `#{Name}` ، مثل: `مرحبًا، #{Name}!`.

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

سيعمل الروبوت على النحو التالي:

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

والآن لنجعل المهمة أكثر تعقيدًا قليلًا.&#x20;

في هذه الكتلة نفسها، سنسأل المستخدم عمّا إذا كان مهتمًا بالسكن الأساسي (الجديد) أم الثانوي (إعادة البيع):

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

بعد ذلك، أنشئ اتصالات من زري "السكن الأساسي" و"السكن الثانوي" في كتلة "Chat".

<div data-with-frame="true"><figure><img src="/files/58f9036e64bd4c3cf01462a8de940f4fb3f896b3" alt=""><figcaption></figcaption></figure></div>

والآن لننظر إلى الطريقة الثانية لاستخدام المتغيرات داخل الكتل.

اختر الكتلة اليمنى وأدخل النص التالي في حقل "Calculator":
&#x20;**client\_interest = السكن الأساسي**. في الكتلة اليسرى، أدخل:
&#x20;**client\_interest = السكن الثانوي**.

<div data-with-frame="true"><figure><img src="/files/5b4894a309cc85d8c8d70f16f1e847edf732935a" alt=""><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/56891f1643a48f92463710f6ffbaea6685d44948" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
يتم إسناد متغير إلى المستخدم عند انتقاله إلى أي من هذه الكتل. ويمكننا استخدامه لاحقًا عند إنشاء طلب.
{% endhint %}

بعد ذلك، سنسأل العميل عن ميزانيته لشراء العقار في هذه الكتل، وننشئ كتلتين إضافيتين بأسهم تؤدي إليهما بناءً على مشغلات رد العميل.

<div data-with-frame="true"><figure><img src="/files/8cdbd6980b9a9111d04babfe4d7c2db90ce695fb" alt=""><figcaption></figcaption></figure></div>

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

<div data-with-frame="true"><figure><img src="/files/8c9a467278d6bd984f55f0e94b8184922a966f17" alt=""><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/2a786a807385856f2c235fb758f86d2f5ecd4bcd" alt=""><figcaption></figcaption></figure></div>

من الكتلة **"ما هي ميزانيتك؟"**، أنشئ اتصالًا واضبط شرط تشغيل لتقسيم المستخدمين بناءً على مدخلاتهم.

1. في إعدادات الاتصال، فعّل خانة الاختيار الخاصة بـ **"User enters data"**.
2. خصّص اسم متغير (مثل، `budget`) لتخزين رد العميل.
3. في **"Variable"** ، استخدم المتغير المدمج `#{question}` (الذي يحتوي على آخر رسالة أرسلها المستخدم) لإنشاء شرط.
   * **مثال:** `#{question} <= 1000000`

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

{% hint style="warning" %}
بالنسبة إلى جميع الاتصالات إلى كتل **"Leads"** ، فعّل **"User enters data"** وحدّد المتغير.
{% endhint %}

يمكنك أيضًا تحديد متغير إضافي مباشرةً في كتلة **"Leads"** لإعطاء معلومات أكثر شمولًا عن الصفقة.

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

الآن غيّر نوع آخر كتلتين إلى "Leads" وشاهد النتائج:

دعنا نختبر التدفق أثناء العمل:

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

يمكنك مراجعة الصفقة المنشأة وبيانات العميل المخزنة بالانتقال إلى قسم **"العملاء"** وفتح المحادثة ذات الصلة. ستكون متغيرات الصفقة مرئية هناك.

<div data-with-frame="true"><figure><img src="/files/7070a07b3231ecae8fe027b1045cfa6967aeefe5" alt=""><figcaption></figcaption></figure></div>

الآن أنت تعرف كيفية استخدام المتغيرات بثلاث طرق مختلفة على الأقل:

1. إسناد أسماء متغيرات إلى بيانات إدخال المستخدم (مثل "Name"، "Budget")
2. إسناد قيمة متغير عند الانتقال إلى كتلة (مثل client\_interest = السكن الأساسي)

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

لعرض متغيرات العميل، انتقل إلى قسم **"العملاء"** وافتح بطاقة العميل الخاصة به.

<div data-with-frame="true"><figure><img src="/files/3e358b1468c58ad7e8da106826659cf06a2e7060" alt=""><figcaption></figcaption></figure></div>

تُعرض المتغيرات في قائمة داخل بطاقة العميل:

* يشغل كل متغير سطرًا خاصًا به.
* الـ **اسم المتغير** يظهر على اليسار.
* وقيمته المقابلة **value** تُعرض على اليمين.

**لتعديل متغير:**

مرّر المؤشر فوق سطره في القائمة لإظهار زر إجراء. يتيح لك النقر على هذا الزر:

* تعديل اسم المتغير.
* تعديل قيمة المتغير.
* حذف المتغير بالكامل.

<div data-with-frame="true"><figure><img src="/files/381ba74f13125225643148e99cf318700840714a" alt="" width="375"><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/29aedfdf16ec1d0953e0d0c87687a088782dfe41" alt="" width="375"><figcaption></figcaption></figure></div>

{% hint style="info" %}
لا يمكن تعديل متغيرات النظام!
{% endhint %}

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

{% hint style="info" %}
لا يتم حذف متغيرات العميل أو إعادة ضبطها أو فقدانها عند استخدام كتلة "End of data collection" (الكتلة الحمراء).
{% endhint %}

يمكن تعيين متغير العميل بطريقتين: بشكل صريح وبشكل ضمني.
\
الطريقة الصريحة لتعريف متغير هي تعيينه في حقل "Calculator" لإحدى كتل المسار.&#x20;

مثال: `client.age = 28` أو `client.age = 28:`

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

الطريقة الضمنية هي تعيين متغير في حقل إدخال البيانات الخاص بالسهم.

مثال:

لننشئ كتلة نطلب فيها اسم العميل، وننشئ أيضًا كتلة أسفلها:

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

بعد ذلك، انتقل إلى إعدادات الاتصال وفعّل خيار "User enters data".

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

استخدم الدالة `client.` بادئة عند تسمية متغيرك (مثل، `client.name`) لتخزين إدخال المستخدم. يمكن بعد ذلك الإشارة إلى هذا المتغير في الرسائل اللاحقة على أنه `#{client.name}`.

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

{% hint style="success" %}
تُستخدم متغيرات العميل تمامًا مثل المتغيرات العادية في المنشئ، ولكن دون **client** بادئة.
{% endhint %}

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

{% hint style="info" %}
لا يتم حذف المتغيرات العامة أو إعادة ضبطها أو فقدانها عند استخدام كتلة "Leads" (الكتلة الحمراء).
{% endhint %}

تكون المتغيرات العامة متاحة لجميع مستخدمي الروبوت. وهي مثالية للتحكم في سلوك الروبوت أو تسهيل التفاعل بين المستخدمين المختلفين.

**مثال على حالة الاستخدام:**\
يمكن لمستخدم واحد نشر عنصر في قناة سوق من خلال تعيين متغير (مثل، `project.latest_listing`)، ويمكن لجميع المستخدمين الآخرين رؤيته والرد عليه.

#### **صيغة الإسناد**

لإنشاء متغير عام أو تحديثه، استخدم `project.` البادئة في Calculator:

**أمثلة:**

* `project.product_shop = 28`
* `project.age = 28`

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

يمكن استخدامها دون أي بادئة.

لنرَ كيف تُعرض البيانات في الجدول.

<div data-with-frame="true"><figure><img src="/files/8692a694fa6ec8c5859a47c0646bc826f8f5c00f" alt=""><figcaption></figcaption></figure></div>

الآن، شغّل كتلة "Start" في وضع الاختبار.

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

يمكننا رؤية البيانات التي كُتبت في المتغير من الجدول في الرسالة المرسلة من الروبوت. وبما أننا أشرنا إلى المتغير في الرسالة باستخدام الصيغة `#{}` ، فقد عُرضت البيانات المخزنة فيه في دردشة الروبوت.

{% hint style="info" %}
تُشرح المزيد من التفاصيل حول كيفية العمل مع الدالة get\_records\_from\_table() في المقال "[مساعد ذكي مع جدول MaviBot](/doc/ar/chatbot/ai/tables.md)".
{% endhint %}

الـ `project.` سمحت البادئة للدالة بكتابة بيانات الجدول مباشرةً إلى المتغيرات العامة للمشروع، المتاحة في **"Variables"** .

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

يمكنك تعديل متغيرات المشروع في إعدادات المشروع.

### مثال: استخدام متغيرات المشروع

أنشئ نظامًا يعيّن رقمًا تسلسليًا لكل عميل جديد يدخل إلى الروبوت.

**التنفيذ:**

1. انتقل إلى **إعدادات المشروع**.
2. أنشئ متغير مشروع جديدًا (مثل، `project.client_counter`).

<div data-with-frame="true"><figure><img src="/files/9dd433fdb45761e3463fd5fd9a14c8ca81be92cc" alt=""><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/9ac6bc7644f926b4dab393e05ac835395f1cdd85" alt=""><figcaption></figcaption></figure></div>

3. عيّن قيمته الأولية (مثل، `0`) والتي تعني **"لا يوجد عملاء في الروبوت"**:

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

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

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

في كتلة البداية الخاصة بالروبوت، أضف منطقًا يقوم بـ:

1. زيادة قيمة متغير المشروع بمقدار 1.
2. إسناد القيمة الجديدة إلى متغير خاص بالعميل للمستخدم الحالي.

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

{% hint style="info" %}
لا تنسَ تعيين قيد حتى لا يمكن زيادة العداد لنفس العميل مرتين.
{% endhint %}

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

## كيفية تعيين متغيرات ثابتة

الثوابت هي قيم ثابتة تبقى دون تغيير (أو نادرًا ما تتغير) طوال دورة حياة المشروع.

**الفرق الرئيسي عن المتغيرات العامة:**

على عكس المتغيرات العامة، فإن الثوابت **خاصة بالعميل**. إذا تم تعديل قيمة ثابت، فإن التغيير ينطبق فقط على جلسة ذلك العميل الفردي.

**حالات الاستخدام الشائعة:**

الثوابت مثالية لتخزين البيانات الثابتة مثل:

* أسعار المنتجات وخصومات العملاء
* رموز التكامل ومفاتيح API
* معلومات الاتصال بالبائع أو الدعم
* أي قيم إعداد ثابتة أخرى

### مثال: استخدام متغيرات ثابتة

على سبيل المثال، قد يكون خصم العميل 10% افتراضيًا، لكنه يتغير إلى 25% عند إدخال رمز ترويجي.

في "إعدادات المشروع" → "Constants"، أدخل: Discount : 10

<div data-with-frame="true"><figure><img src="/files/614563c0b5c4c9c16e199d17285a685c8a918147" alt=""><figcaption></figcaption></figure></div>

لإدخال رمز ترويجي، أضف كتلة "Trigger"، حيث نُسند المتغير **discount** قيمة 25.

<div data-with-frame="true"><figure><img src="/files/75a91179499a9999fc5c5026fbb1a3beef9c0441" alt=""><figcaption></figcaption></figure></div>

اعرض المتغير الذي يُظهر مقدار الخصم في الكتلة الخضراء:

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

**الخطوة 1: اضبط الانتقال التلقائي**\
أنشئ اتصالًا مع **مؤقت صفر ثانية** من الكتلة الرمادية. يضمن ذلك تطبيق الخصم فورًا واستمرار العميل إلى الرسالة في كتلة البداية.

**الخطوة 2: اختبر التدفق**\
الآن، اكتب رسالة إلى الروبوت لتفعيل واختبار التسلسل بالكامل.

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

الخصم القياسي هو 10% بدون رمز ترويجي. ومع ذلك، فإن إدخال رمز ترويجي صالح يغير الوضع.

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

وبالتالي، بعد إدخال رمز الترويج، أصبح المتغير "discount" لهذا العميل 25. <br>

حدث هذا لأن تعيينًا مثل discount = 25 حدد القيمة لمتغير الصفقة، بدلًا من تغيير قيمة الثابت الذي يحمل الاسم نفسه.

## متغيرات الصفقة الرئيسية

**name** - اسم الصفقة. يُستخدم المصطلح **Name** للنسخة الدولية من المشروع.

**description** - وصف الصفقة. **الوصف** يُستخدم في النسخة الدولية من المشروع

**budget** - مبلغ الصفقة (رقم).

لتعديل المتغيرات باستخدام طلب API /set\_order\_vars، يجب استخدام الأسماء الواردة في[هذا الدليل كما هي تمامًا](#how-to-set-client-variables)، بما في ذلك حساسية حالة الأحرف وإصدار المشروع.

## القيود

{% hint style="warning" %}
الحد الأقصى لطول اسم المتغير: 500 حرف

الحد الأقصى لطول قيمة المتغير: 100,000 حرف

الحد الأقصى لعدد المتغيرات لكل عميل أو صفقة: 1,000 حرف.
{% endhint %}

## كيفية العمل مع المتغيرات بشكل صحيح

### *متى يجب أن تُحيط قيمة المتغير بعلامات اقتباس؟*

*على سبيل المثال، <mark style="color:yellow;">**client\_id = 1202020202**</mark> أو <mark style="color:green;">**client\_id = '1202020202'**</mark>?*

كلا الخيارين من حيث الصياغة صحيحان وظيفيًا. استخدام علامات الاقتباس حول قيمة لا يؤثر إلا على تمييزها البصري في محرر الحاسبة.

ومع ذلك، فإن اتباع اصطلاحات ترميز متسقة يحسن قابلية القراءة والصيانة:

* **احذف علامات الاقتباس** لـ **القيم** العددية (مثل، `discount = 25`).
* **استخدم علامات الاقتباس** لـ **لـ** العددية (مثل، `status = "active"`).

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

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

<div data-with-frame="true"><figure><img src="/files/0ce07fa51b1bfd6df36456e002271968c06e28c9" alt=""><figcaption></figcaption></figure></div>

*ما الصياغة الصحيحة لتمرير المعرفات مثل Client ID أو Site ID أو Block ID أو Certificate ID إلى الدوال — هل يجب إحاطتها بعلامات اقتباس؟*

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

لا ينبغي إحاطة المعرف بعلامات اقتباس عند تمريره إلى طريقة أو دالة:

<div data-with-frame="true"><figure><img src="/files/10a2bbf037748567460187f94b77650064de6e65" alt=""><figcaption></figcaption></figure></div>

### أيّهما يجب استخدامه: علامات الاقتباس المزدوجة أم المفردة؟

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

<div data-with-frame="true"><figure><img src="/files/14179ea0795e6f4a1dfa999aa876d1436c9f9f61" alt=""><figcaption></figcaption></figure></div>

### كيف يجب وضع المسافات؟&#x20;

هل يعمل الأمر بالطريقة نفسها إذا كانت هناك مسافة بين المتغير وعلامة يساوي (على سبيل المثال، *<mark style="color:blue;">ans="yes"</mark>, <mark style="color:purple;">ans = "yes"</mark>, <mark style="color:orange;">ans= "yes"</mark>, <mark style="color:red;">ans ="yes"</mark>?*

<div data-with-frame="true"><figure><img src="/files/22dd45dbb9ae3b08db4b4bc51456e844454ea746" alt=""><figcaption></figcaption></figure></div>

لا تؤثر المسافات على عمل الطرق أو المتغيرات أو الدوال. ومع ذلك، يُنصح باستخدام المسافات في الكود لتحسين قابلية القراءة.

### كيفية كتابة التعليقات في الحاسبة بشكل صحيح

{% hint style="success" %}
**لمزيد من التفاصيل حول كيفية كتابة التعليقات في الحاسبة، يرجى الاطلاع على** [**هذه المقالة**](/doc/ar/chatbot/functions/alaalh-alhasbh.md)**.**
{% endhint %}

## كيفية مقارنة المتغيرات

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

{% hint style="info" %}
إليك كيفية تقسيم القمع [حسب برامج مراسلة مختلفة أو حسب حسابات مختلفة لنفس برنامج المراسلة موضح هنا.](/doc/ar/faq/alaselh-alshaeah.md#how-can-i-split-a-funnel-by-messengers)
{% endhint %}

#### **المعاملات المدعومة:**

"**+**": جمع \
"**-**"': طرح \
"**\***" *الضرب* \
"**/**": *القسمة*\
"**%**'"*: باقي القسمة* \
"**^**" "**\*\***": الأس \
"**و**" "**AND**" "**&&**": AND المنطقي \
"**أو**" "**OR**" "**||**": OR المنطقي

معاملات المقارنة:\
"**==**" — يساوي\
"**!=**" — لا يساوي\
"**>**" — أكبر من\
"**<**" — أصغر من \
"**>=**" — أكبر من أو يساوي\
"**<=**" — أصغر من أو يساوي

{% hint style="warning" %}
**مهم!** \
للتحقق من أن **وسم المتغير المدمج** (وسم تشغيل الروبوت) غير موجود في بطاقة العميل، استخدم طريقة المقارنة التالية:\
\
`tag == "NONE"`
{% endhint %}

يجب مقارنة المتغيرات في الشرط ضمن حقل "Variable" (سواء في إعدادات الاتصال أو في إعدادات الكتلة):

**مثال على مقارنة متغير في حقل "Variable" لكتلة تشغيل.**

<div data-with-frame="true"><figure><img src="/files/107be9507b7ce8805fd0b8fc531a960ecea7b581" alt=""><figcaption></figcaption></figure></div>

**مثال على مقارنة متغير في حقل "Variable" لِاتصال كتلة.**

<div data-with-frame="true"><figure><img src="/files/2ee49e0c252124a8cc7752be88e96569d7d431cf" alt=""><figcaption></figcaption></figure></div>

#### **كيف تعمل المتغيرات والمشغلات معًا**

لكي يتم تفعيل الاتصال، **يجب استيفاء كلا المشغلين**:

1. الشرط في **"مشغّل"** .
2. منطق المقارنة في **"Variable"** .

#### **فهم حقل "Variable"**

إذا أدخلت اسم متغير فقط (مثل، `client_type`) في **"Variable"** الحقل بدون تعبير، فإن النظام يتحقق من *وجود* أو *منطقية* قيمة المتغير. وهو لا **عدم** يقارنها بالإدخال الخام للمستخدم.

**مثال:**\
يتحقق الإعداد أدناه مما إذا كان العميل من واتساب من خلال التحقق من أن `client_type` المتغير يساوي `6` (حيث `6` يمثل واتساب).

`client_type == 6`

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

المثال أدناه يعمل بالطريقة نفسها تمامًا:

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

{% hint style="warning" %}
يرجى الملاحظة! \
لا يمكنك تحديد قيم متعددة لمقارنة المتغير في حقل "Trigger".

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

هذا غير صحيح!

إذا كنت بحاجة إلى مقارنة عدة متغيرات، فحدد قيمها في حقل "Variable".

هذه الخيارات صحيحة.

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

{% hint style="info" %}
client\_type == 3 انتقال إذا كانت قيمة المتغير تساوي **3**\
attachments != None انتقال إذا كان المتغير يحتوي على أي قيمة\
attachments == None انتقال إذا لم يكن المتغير مضبوطًا\
product\_quantity >= 100 انتقال إذا كانت كمية المنتج أكبر من أو تساوي **100**\
product\_quantity <= 100 انتقال إذا كانت كمية المنتج أقل من أو تساوي **100**\
name == "John" انتقال إذا كان اسم المتغير يساوي John

للتحقق مما إذا كان المتغير فارغًا أم لا، استخدم التعابير التالية:\
\&#xNAN;**"#{value}" == ""**  \
**"#{value}" != ""** <br>

(حيث **value** هو اسم المتغير).

تعيد نتيجة عملية المقارنة قيمة منطقية: **True** أو **خطأ**.
{% endhint %}

{% hint style="warning" %}
الحد الأقصى لطول التعبير: 1000 حرف
{% endhint %}

{% hint style="warning" %}
سيتم إرجاع القيمة الافتراضية كنتيجة عند محاولة مقارنة قيم من أنواع مختلفة.

"==" - خطأ                       "<" - خطأ\
"!=" - صحيح                          ">=" - خطأ \
">" - خطأ                          "<=" - خطأ
{% endhint %}

{% hint style="warning" %}
**مهم!** \
للتحقق من أن **وسم المتغير المدمج** (وسم تشغيل الروبوت) غير موجود في بطاقة العميل، استخدم طريقة المقارنة التالية:\
\
`tag == "NONE"`
{% endhint %}

**مثال:** روبوت يتحقق من عمر المستخدم (`العمر`).

* إذا لم يتم توفير `age < 18`، يرسل رسالة للقُصَّر.
* إذا لم يتم توفير `age >= 18`، يرسل رسالة للبالغين.

<div data-with-frame="true"><figure><img src="/files/461e11e40728f6c46e2237c7ccc793f337486c09" alt=""><figcaption></figcaption></figure></div>

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

لاحظ أن المسار يتضمن كتلة بدون مشغّل، مع اتصالات زمنية تنطلق منها.&#x20;

صُممت هذه الكتلة عمدًا لتوضيح كيفية بناء المسارات حيث لا يتفاعل الروبوت مع إجراءات المستخدم، بل مع نتائج الحساب. في الخطوة الأولى، يتم حفظ الإجابة في متغير، ثم تتم المقارنة. تم ضبط التأخير على الأسهم إلى 0 للحصول على استجابة فورية.

المقارنة **"Age >= 18"** يمكن التعبير عنها أيضًا على أنها **"أكبر من أو يساوي 18."**

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

{% hint style="danger" %}
يرجى ملاحظة الأخطاء في المشغلات:

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

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

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

**لا يمكن لعدد أن يكون أكبر من 18 وأصغر من 18 ومساويًا لـ 18 في الوقت نفسه!**

هذه المشغلات بلا معنى. كل عدد إما أقل من 18 أو أكبر من 18 أو يساوي 18.
{% endhint %}

{% hint style="warning" %} <mark style="color:red;">**مهم!**</mark>&#x20;

يجب كتابة المشغلات المنطقية مع المتغيرات في <mark style="color:red;">**"Variable"**</mark> الحقل، وليس في حقل "Trigger"!
{% endhint %}

على سبيل المثال، في الصورة أدناه، سيتم تشغيل الكتلة إذا <mark style="color:green;">**كان المتغير phone مُعبّأً**</mark> (أي، غير مساوٍ لـ **None**):

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

يوضح المثال التالي كيفية دمج المعاملات:

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

إذا كان لدى العميل متغير عمر بقيمة بين 18 و99، فسيتم تشغيل الكتلة. إذا كان المتغير مفقودًا، أو كان العمر أقل من 18 أو أكبر من 99، فلن يتم تفعيل الكتلة.

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

إذا قمت بمقارنة متغير بقيمة بين علامتي اقتباس، فتأكد من عدم وجود مسافات بين علامات الاقتباس والقيمة؛ وإلا فقد تفشل الكتلة في التشغيل أو تتصرف بشكل غير صحيح!

<mark style="color:green;">**صحيح**</mark> (بدون مسافة <mark style="color:red;">**قبل علامة الاقتباس**</mark> أو <mark style="color:red;">**بعد القيمة my\_new\_bot**</mark>):

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

<mark style="color:red;">**غير صحيح**</mark> (مع وجود مسافة قبل علامة الاقتباس):

<img src="/files/b7f538166632f085f06d149be7d3536f22f0499c" alt="" data-size="original">
{% 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/chatbot/functions/almtghyrat.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.