# متغيرات الأوامر

> كل متغيرات الأوامر في KickBot مع أمثلة، من {{sender.followage}} لمدة المتابعة على Kick إلى الأرقام العشوائية وطلبات API في ردود الدردشة.

Source: https://kickbot.com/ar/docs/chat-bot/command-variables

المتغيرات عناصر نائبة في رد الأمر. يضع KickBot مكانها القيمة الحالية في كل مرة يُنفَّذ فيها الأمر. مثلًا، رد `!followage` الذي فيه `{{sender.followage}}` ينشر منذ متى يتابع المشاهد قناتك على Kick. تعمل المتغيرات في [الأوامر المخصصة](https://kickbot.com/ar/docs/chat-bot/custom-commands) وفي ردود [الأوامر المدمجة](https://kickbot.com/ar/docs/chat-bot/built-in-commands).

اكتب كل متغير بقوسين معقوفين على كل جانب، تمامًا كما في هذه الصفحة. حالة الأحرف مهمة: `{{sender.username}}` يعمل، و`{{Sender.Username}}` لا يعمل.

## أضف متغيرًا إلى رد

1. افتح أمرًا في صفحة [الأوامر المخصصة](https://kickbot.com/dashboard/commands)، أو اضغط على **إضافة أمر**.
2. تحت مربع **الرد**، استخدم **إدراج متغير**. اختر مجموعة (**المرسل**، أو **البثّاث**، أو **المستخدم الموسوم / المعامل**، أو **البث**، أو **عشوائي**، أو **طلب API**).
3. اضغط على متغير. يضيفه KickBot في موضع المؤشر.

تعرض معاينة **في دردشة Kick** قيمًا نموذجية، فتتحقق من الرد قبل الحفظ.

![قائمة إدراج متغير مع فتح مجموعة البث، ومعاينة بقيم نموذجية لمدة المتابعة والفئة والمشاهدين](https://kickbot.com/docs/images/chat-bot/command-variables/01-variables.webp "تملأ المعاينة قيمًا نموذجية. في الدردشة، يستخدم KickBot القيم الحقيقية.")

تستخدم الأمثلة أدناه مشاهدًا اسمه KickBotDev في قناة اسمها yourchannel.

## المرسل

المشاهد الذي كتب الأمر.

| المتغير | ما ينشره | مثال على الناتج |
| --- | --- | --- |
| `{{sender.username}}` | اسم المشاهد كما في رابط قناته (بأحرف صغيرة) | `kickbotdev` |
| `{{sender.followers}}` | عدد متابعي قناة المشاهد نفسه | `128` |
| `{{sender.followage}}` | منذ متى يتابع المشاهد قناتك | `4 months 12 days` |
| `{{sender.url}}` | رابط قناة المشاهد على Kick | `https://kick.com/kickbotdev` |
| `{{sender.bio}}` | النبذة التعريفية (bio) في ملف المشاهد الشخصي على Kick | `Variety streamer from Texas` |
| `{{sender.instagram}}` | اسم Instagram في ملف المشاهد الشخصي على Kick | `yourhandle` |
| `{{sender.twitter}}` | اسم X (Twitter) في ملف المشاهد الشخصي على Kick | `yourhandle` |
| `{{sender.youtube}}` | YouTube في ملف المشاهد الشخصي على Kick | `yourhandle` |
| `{{sender.discord}}` | Discord في ملف المشاهد الشخصي على Kick | `discord.gg/your-server-code` |
| `{{sender.tiktok}}` | اسم TikTok في ملف المشاهد الشخصي على Kick | `yourhandle` |
| `{{sender.facebook}}` | اسم Facebook في ملف المشاهد الشخصي على Kick | `yourhandle` |

### مدة المتابعة على Kick

إذا لم يكن المشاهد يتابع قناتك، ينشر KickBot هذا بدلًا من ردك: `@kickbotdev is not following @yourchannel`.

يستخدم الأمر المدمج `!followage` هذا المتغير. رده هو `@{{sender.username}} has been following for {{sender.followage}}`، فيظهر في الدردشة هكذا: `@kickbotdev has been following for 4 months 12 days`.

## البثّاث

أنت، مالك القناة.

| المتغير | ما ينشره | مثال على الناتج |
| --- | --- | --- |
| `{{streamer.username}}` | اسم قناتك كما في رابط قناتك | `yourchannel` |
| `{{streamer.followers}}` | عدد متابعيك | `2450` |
| `{{streamer.url}}` | رابط قناتك على Kick | `https://kick.com/yourchannel` |
| `{{streamer.bio}}` | نبذتك التعريفية على Kick | `Chill streams every night` |
| `{{streamer.instagram}}` | اسم Instagram في ملفك الشخصي على Kick | `yourhandle` |
| `{{streamer.twitter}}` | اسم X (Twitter) في ملفك الشخصي على Kick | `yourhandle` |
| `{{streamer.youtube}}` | YouTube في ملفك الشخصي على Kick | `yourhandle` |
| `{{streamer.discord}}` | Discord في ملفك الشخصي على Kick | `discord.gg/your-server-code` |
| `{{streamer.tiktok}}` | اسم TikTok في ملفك الشخصي على Kick | `yourhandle` |
| `{{streamer.facebook}}` | اسم Facebook في ملفك الشخصي على Kick | `yourhandle` |

> **Caution:** تقرأ متغيرات الملف الشخصي (النبذة التعريفية، و Instagram، و X، و YouTube، و Discord، و TikTok، و Facebook) الملف الشخصي على Kick. إذا كان الحقل فارغًا في الملف الشخصي، يبقى المتغير في الرد كنص عادي، مثلًا `{{streamer.tiktok}}`. استخدمها فقط للملفات الشخصية التي يكون فيها الحقل مملوءًا.

## المستخدم الموسوم والمعامل

نص أو اسم يكتبه المشاهد بعد الأمر. مثلًا، يكتب مشاهد `!so @SomeChannel` أو `!hug @friend`.

| المتغير | ما ينشره | مثال لـ `!so @SomeChannel great stream` |
| --- | --- | --- |
| `{{param}}` | كل النص بعد الأمر | `@SomeChannel great stream` |
| `{{taggedUser.username}}` | الاسم بعد أول `@` | `SomeChannel` |
| `{{taggedUser.url}}` | رابط القناة الموسومة | `https://kick.com/SomeChannel` |
| `{{taggedUser.followers}}` | عدد متابعي القناة الموسومة | `57` |
| `{{taggedUser.followage}}` | منذ متى يتابع المشاهد الموسوم قناتك | `2 months 3 days` |

للمستخدم الموسوم أيضًا متغيرات الملف الشخصي: `{{taggedUser.bio}}` و `{{taggedUser.instagram}}` و `{{taggedUser.twitter}}` و `{{taggedUser.youtube}}` و `{{taggedUser.discord}}` و `{{taggedUser.tiktok}}` و `{{taggedUser.facebook}}`.

إذا لم يذكر المشاهد أحدًا بعلامة @، يكون `{{taggedUser.username}}` فارغًا. إذا لم يكن الاسم الموسوم قناة على Kick، فلا تعمل متغيرات البحث (المتابعون، والنبذة التعريفية، وحقول الملف الشخصي الأخرى)، وينشر KickBot `404 tagged user not found` بدلًا من الرد.

مثال: رد الأمر المدمج `!so` (shout-out) هو `Go check @{{taggedUser.username}}'s channel! {{taggedUser.url}}`.

## البث

بثك الحالي. تعمل هذه المتغيرات أثناء بثك المباشر.

| المتغير | ما ينشره | مثال على الناتج |
| --- | --- | --- |
| `{{stream.title}}` | عنوان بثك | `Chill stream, come hang out` |
| `{{stream.category}}` | فئة بثك | `Just Chatting` |
| `{{stream.viewers}}` | عدد مشاهديك الآن | `342` |

عندما تكون غير متصل، لا يستطيع KickBot قراءة بثك، فلا ينشر الأمر الذي فيه هذه المتغيرات رده المعتاد. قد ينشر `404 stream not found` بدلًا منه.

## عشوائي

استخدمها للألعاب والأوامر الترفيهية. في كل تنفيذ تُختار قيمة جديدة.

| المتغير | ما ينشره | مثال على الناتج |
| --- | --- | --- |
| `{{randomRange(1,100)}}` | عدد صحيح من الرقم الأول إلى الثاني، والرقمان مشمولان | `42` |
| `{{randomItem("rock","paper","scissors")}}` | عنصر واحد من القائمة، ولكل عنصر الفرصة نفسها | `paper` |
| `{{randomItemPercentage("common":70,"rare":25,"legendary":5)}}` | عنصر واحد من القائمة، بالفرصة التي تحددها لكل عنصر | `common` |

القواعد:

- يأخذ `randomRange` عددين صحيحين قيمة كل منهما 0 أو أكثر. يجب ألا يكون الأول أكبر من الثاني.
- ضع كل عنصر بين علامتي تنصيص مزدوجتين مستقيمتين (`"`)، وافصل بين العناصر بفواصل. يمكن أن تحتوي العناصر على مسافات، مثلًا `"Ask again later"`.
- في `randomItemPercentage`، ضع الرقم بعد النقطتين مباشرة، دون مسافة. الأرقام أوزان. مع 70 و25 و5، يظهر العنصر الأول نحو 70 مرة من كل 100. لا يوجد `randomItemPercentage` في قائمة **إدراج متغير**. اكتبه بنفسك.

## طلب API

يجلب `{{request("https://...")}}` بيانات من عنوان ويب (API) ويضعها في الرد. استخدمه لعرض نكتة، أو رتبة في لعبة، أو أي شيء آخر تُرجعه API عامة.

```text
{{request("https://uselessfacts.jsph.pl/api/v2/facts/random").text}}
```

يفتح KickBot العنوان، ويقرأ إجابة JSON، وينشر الحقل `text`. مثلًا: `The praying mantis is the only insect that can turn its head`.

طريقة العمل:

- **اختر حقلًا.** أضف المسار بعد القوس الختامي. استخدم النقاط للأسماء و`[0]` لعناصر القوائم، مثلًا `.data[0].name`. بدون مسار، أو إذا لم يكن المسار في الإجابة، ينشر KickBot الإجابة كاملة.
- **استخدم المتغيرات في العنوان.** مثلًا، `{{request("https://example.com/rank?user={{sender.username}}").rank}}`. يضع KickBot القيمة ويجعلها آمنة لعنوان ويب (تصبح المسافة `%20`). لا يُسمح بطلب داخل طلب.
- **طلبات GET فقط.** لا يستطيع KickBot إرسال محتوى (body) أو ترويسات (headers). إذا كانت API تحتاج إلى مفتاح، فضعه في العنوان كمعامل استعلام (query parameter).
- **الحدود.** عناوين `http` و `https` على الإنترنت العام فقط. ينتظر KickBot حتى 3 ثوانٍ للإجابة، لذلك استخدم API تجيب بسرعة وبإجابة قصيرة.

> **Caution:** أي شخص يستطيع رؤية إعدادات أوامرك يستطيع رؤية مفتاح API في العنوان. استخدم مفاتيح لا تقرأ إلا بيانات عامة.

## متغيرات أخرى

تعمل هذه المتغيرات لكنها ليست في قائمة **إدراج متغير**.

| المتغير | ما ينشره | مثال على الناتج |
| --- | --- | --- |
| `{{user}}` | اسم المشاهد بأحرفه الكبيرة كما هي | `KickBotDev` |
| `{{sender.fullUsername}}` | اسم المشاهد مع `@` قبله | `@KickBotDev` |
| `{{commands}}` | كل الأوامر المفعّلة، مفصولة بفواصل | `commands, followage, lurk, me, so, welcome, discord` |

يستخدم الأمر المدمج `!commands` المتغير `{{commands}}`. رده هو `Enabled commands: {{commands}}`.

## أخطاء شائعة

- **قوس واحد بدل قوسين.** يبقى `{sender.username}` نصًا عاديًا. استخدم `{{sender.username}}`.
- **اسم مكتوب بخطأ.** المتغير غير المعروف، مثل `{{sender.name}}`، يمنع الأمر من نشر رد. قارن الكتابة بهذه الصفحة.
- **علامات تنصيص منحنية.** يحتاج `randomItem` و `request` إلى علامات تنصيص مستقيمة (`"`). بعض الهواتف ومحررات النصوص تحوّلها إلى علامات منحنية (`“ ”`). اكتبها في لوحة التحكم لتكون في أمان.

## الأسئلة الشائعة

**كيف أصنع أمر followage على Kick؟**

لدى KickBot أمر مدمج `!followage` مفعّل في كل قناة. لصنع أمرك الخاص، أضف أمرًا برد مثل `@{{sender.username}} has followed for {{sender.followage}}`.

**كيف أعرض اسم المشاهد في أمر؟**

استخدم `{{sender.username}}` للاسم كما في رابط القناة، أو `{{user}}` للاسم بأحرفه الكبيرة. أضف `@` قبله إذا أردت أن يعرضه Kick كإشارة، مثلًا `@{{sender.username}}`.

**هل يستطيع أمر عرض عدد مشاهديّ أو عنوان بثي؟**

نعم. استخدم `{{stream.viewers}}` و `{{stream.title}}`. يعملان أثناء بثك المباشر.