الرسائل والأزرار
أنشئ رد البوت من نصوص وصور وأزرار وأسئلة، واحفظ أجوبة المستخدم.
في هذه الصفحة
ليرسل البوت نصًا وصورة وزر «اختيار»، أضف فعل إرسال رسالة. يتكوّن الرد من أجزاء منفصلة تسمى كتلًا: مثل صورة المنتج ثم وصفه مع أزرار تحته. تُسمى الأزرار تحت الرسالة أيضًا أزرارًا مضمّنة.
يمكن للفعل نفسه طرح سؤال وانتظار الجواب، مثل طلب رقم هاتف وحفظه في بيانات العميل. فيما يلي إعداد الكتل والأزرار وخطوات الحوار.
كتل الرسالة
انقر إضافة كتلة واختر ما ترسله؛ يمكنك جمع نص ترحيبي وصورة وملف برنامج الدرس:
- نص: نص منسق حتى 4096 حرفًا، مع الاستبدالات والأزرار.
- صورة: صورة مع تعليق.
- ملف: مستند مع تعليق.
- رسالة صوتية: OGG/OPUS أو MP3 أو M4A، حتى 50 ميغابايت، يعرضها Telegram كرسالة صوتية (
sendVoice). - GIF: رسوم متحركة أو MP4 بلا صوت حتى 50 ميغابايت (
sendAnimation). - رسالة فيديو دائرية: MP4 مربع حتى 60 ثانية (
sendVideoNote)، بلا تعليق. عند كل إرسال يُرفع ملف مكتبة الوسائط من جديد؛ لا تقبل Telegram فيsendVoiceأوsendAnimationأوsendVideoNoteمعرّفfile_idجاء من طريقة أخرى. - عرض بطاقات متتابعة (carousel): من 2 إلى 10 بطاقات، كل منها بصورة وتعليق وأزرار خاصة. في Telegram يتنقل المستخدم بزرّي «‹ ›» داخل رسالة واحدة عبر
editMessageMediaإذا كان لكل صورةfile_idصالح، إما محددًا في البطاقة أو مُستخرجًا لملف مكتبة الوسائط. إذا تعذر الحصول على معرّف صالح لصورة واحدة، تُرسل كل البطاقات كرسائل صور منفصلة. وفي القنوات الأخرى، مثل VK، تُرسل منفصلة أيضًا. تحتفظ كل بطاقة بتعليقها وأزرارها. - تأخير: انتظار عدد من الثواني قبل الكتلة التالية.
- ذكاء اصطناعي: رد ينشئه النموذج من تعليمات.
- تفاعل: استدعاء تفاعل آخر، مع انتظار تنفيذه اختياريًا.
تعمل الرسائل الصوتية وGIF والفيديو الدائري والبطاقات في التفاعلات كباقي الكتل، وتدخل في الإرسال الجماعي السريع للتفاعل؛ انظر الإرسال الجماعي.
يمكن سحب الكتل لتغيير ترتيبها. اختر العرض بالترتيب أو عشوائيًا لتنويع الردود. يمكنك ترك قائمة البوت الرئيسية كما هي، أو تعيين أخرى، أو إخفاؤها.
خيارات الكتلة
تملك كتل النص والوسائط خيارات: تثبيت، دون صوت، منع إعادة التوجيه، إخفاء كمفاجأة (spoiler)، دون معاينة روابط، حذف تلقائي بعد N ثانية.
الأزرار المضمّنة
اضبط نص الزر ونوعه داخل الكتلة:
- نص: يرسل العبارة بوصفها جوابًا من المستخدم. في Telegram وVK تظهر لوحة مفاتيح للرد؛ قد يجيب الضغط عن سؤال أو يشغّل تفاعلًا بالنص. في WhatsApp وInstagram وMessenger وأداة الموقع يظهر زر جواب دون لوحة دائمة.
- رابط: يفتح URL.
- تطبيق ويب: يفتح Telegram Mini App؛ انظر Mini App.
- استدعاء تفاعل: يشغّل تفاعلًا آخر.
- Inline query (استعلام مضمّن): يضع «@bot query» في حقل كتابة المحادثة الحالية أو يعرض اختيار محادثة أخرى (
switch_inline_query/switch_inline_query_current_chat). يعمل في Telegram فقط بعد تفعيل وضع inline عبر/setinlineلدى @BotFather. لا يجيب GetMyBot عن هذه الاستعلامات، إذ لم يُنفذanswerInlineQuery؛ لذا يجهز الزر نص الاستعلام ولا يجري البحث. - Prefilled text (نص جاهز): رابط
https://t.me/<bot>?text=…يفتح المحادثة مع نص في حقل الكتابة دون إرساله (prefill). - Payment link (رابط دفع): يفتح URL الدفع الإلزامي الذي ينشئه فعل إنشاء الدفع. ينتقل إلى صفحة دفع خارجية، وليس فاتورة Telegram أصلية.
- إشعار: يعرض نصًا بعد الضغط دون تشغيل تفاعل أو تمرير بيانات Carry. في Telegram إشعار قصير أو نافذة حتى 200 حرف، وفي VK شريط قصير حتى 90 حرفًا بلا نافذة.
النص أو النص الجاهز
| المهمة | نوع الزر وإعداده | نتيجة الضغط |
|---|---|---|
| اختيار «نعم» في استبيان | «نص» بعبارة «نعم»، مع انتظار الرسالة للرد | يصل جواب «نعم» إلى خطوة الحوار |
| تجهيز رسالة إلى البوت | «Prefilled text» بعبارة «اكتب»، والنص «أريد تقديم طلب» | يظهر النص مسودة في حقل الكتابة؛ يعدله المستخدم ويرسله بنفسه |
عبارة الزر والنص الجاهز حقلان مختلفان. النص الجاهز لا يرسل رسالة ولا يشغّل تفاعلًا وحده.
ينقل زر تفاعل الضغط إلى البوت كحدث منفصل يسمى تقنيًا callback. لا ينشئ «Inline query» أو «Prefilled text» هذا الحدث، لأنهما يعملان داخل تطبيق Telegram؛ لذلك لا يدعمان answerCallbackQuery ولا تمرير بيانات Carry.
رمز الزر ولونه
يمكن إظهار رمز تعبيري مميز قبل نص الزر. أدخل معرّفه في Premium emoji ID (icon_custom_emoji_id) كعدد صحيح موجب من 64 بت. مثلًا تُقرأ 007 على أنها 7. تُرفض الأحرف أو الصفر أو العدد السالب أو الكبير جدًا؛ يُحفظ الزر بلا رمز.
لا تُظهر Telegram الرمز إلا لبوت يملك الصلاحية اللازمة: اسمًا إضافيًا عبر Fragment، أو Telegram Premium للمالك عند الإرسال المباشر لمحادثة خاصة أو مجموعة. في الحالات الأخرى تتجاهله Telegram دون استبداله برمز عادي.
يضبط النمط اللون: عادي بلا لون، Primary أزرق، Success أخضر، Danger أحمر. اسم الحقل التقني style.
يسمح خيار لمرة واحدة (يُلغى بعد الضغط) (single_use) باستعمال بيانات الزر المحفوظة مرة واحدة فقط، مثل تأكيد الاختيار. يُضبط تغيير نص الزر وحذف الرسالة بشكل مستقل في سلوك الضغط.
خيارات الأزرار
الخيار علامة يمكن تشغيلها أو إيقافها في المحرر:
- في سطر جديد: يبدأ الزر صفًا جديدًا.
- تمديد على كامل العرض: يضعه وحده في صف؛ ويبدأ الزر التالي صفًا جديدًا أيضًا.
رسم تقريبي؛ الأقواس المربعة أزرار:
صف واحد: [الكتالوج] [المساعدة]
سطر جديد: [الكتالوج]
[المساعدة]
العرض كله: [ المساعدة ]
تدعم Telegram وVK الصفوف والألوان. يبقى ترتيب الصفوف بعد إعادة فتح التحرير. لا يعمل الرمز المميز إلا مع اتصال Telegram المتوافق. لا يوجد خيار «فتح داخل Telegram»: لا يتيح Bot API التحكم في ذلك بعلامة كهذه.
حدود القنوات
اختر الاتصال للكتلة أو للزر. مع «كل القنوات» يعرض المحرر القدرات المشتركة فقط، ولا يسمح بحفظ نوع غير مدعوم:
- Telegram: URL وMini App والتفاعل والإشعار أو النافذة، والصفوف والألوان والرمز المميز إذا امتلك البوت الصلاحية.
- VK: URL والتفاعل وsnackbar والصفوف والألوان. يتاح VK Mini App وVK Pay عند اختيار اتصال VK متوافق.
- WhatsApp: زر URL واحد من نوع CTA دون أزرار أخرى في الرسالة نفسها. حتى 3 أزرار جواب عادية؛ من 4 إلى 10 تظهر قائمة. نص الزر حتى 20 حرفًا. لا صفوف أو ألوان أو Mini App أو إشعارات.
- Instagram / Messenger: يرسل الموصل الحالي أزرار جواب سريعة فقط، بنص حتى 20 حرفًا. لا يدعم URL أو Mini App أو الإشعارات أو الصفوف أو الألوان.
- أداة الموقع: URL وأزرار جواب، بلا صفوف أو ألوان أو إشعارات.
- البريد الإلكتروني: روابط، ومنها رابط الدفع؛ لا أزرار جواب أو إشعارات.
يمكن ضبط عدد أعمدة الأزرار المنشأة من قائمة للقنوات التي تدعم الصفوف فقط. وتحدد القنوات الأخرى ترتيبها بنفسها. تُفحص حدود عدد الأزرار وطول النص عند الإرسال.
ما يحدث عند الضغط
للأزرار التي تنقل الضغط إلى البوت، يمكن استبدال الرسالة بنص أو محتوى تفاعل آخر، أو حذف الرسالة، أو إضافة تسمية أو حفظ معامل إن دعمت القناة ذلك. تغيير عبارة الزر نفسه بعد الضغط يعمل في Telegram فقط، مثل تحويل «احجز» إلى «تم الاختيار». دعم VK لتعديل الرسالة لا يعني قدرته على تغيير عبارة الزر.
تنتظر Telegram تأكيد الضغط عبر answerCallbackQuery. يرسله GetMyBot عادةً ويزيل مؤشر التحميل. خيار «تخطي answerCallbackQuery» يوقف هذا التأكيد.
في حقل Text on press (notification) لزر «تفاعل» يمكن كتابة تأكيد قصير مثل «اخترت الدرس» (حتى 200 حرف في Telegram و90 في VK، مع دعم الاستبدالات). تعرضه Telegram عادةً لحظة فوق المحادثة. خيار Show as a popup (alert) متاح في Telegram فقط ويستخدم answerCallbackQuery مع show_alert. إذا كان النص فارغًا، يزيل البوت مؤشر التحميل فقط. وعند تفعيل تخطي answerCallbackQuery لا يظهر النص ولا النافذة.
بيانات الزر (Carry)
يتذكر Carry العنصر الذي يخصه الزر. إذا حمل المعطف والفستان زر «اشترِ»، فاحفظ product_id=101 للمعطف وproduct_id=102 للفستان. عند ضغط زر الفستان، تحصل الخطوة التالية على {{ctx.product_id}} بقيمة 102.
اسم الإعداد في المحرر البيانات المرسلة عند الضغط. المفتاح هو اسم القيمة، والقيمة رقم أو نص أو استبدال. يحفظها البوت عند إرسال الرسالة، ثم يضعها عند الضغط في ctx للتفاعل. بيانات كل زر منفصلة.
تُحدد مدة صلاحية بيانات الزر، بالثواني (ttl_seconds أو TTL) بالثواني؛ 3600 ساعة. يختار 0 الافتراضي، وهو 30 يومًا. بعد المدة لا تتاح البيانات. خيار لمرة واحدة (يُلغى بعد الضغط) (single_use) يحذفها بعد أول ضغطة. لا يتغير السعر المحفوظ تلقائيًا عند تحديث الكتالوج؛ افحص السعر الحالي بمعرّف المنتج قبل الدفع. انظر الأزرار الديناميكية والمعاملات.
الأزرار الديناميكية
إذا كانت المنتجات أو الدروس قائمة جاهزة، فلا تنشئ كل زر يدويًا. تحول كتلة أزرار ديناميكية من قائمة كل عنصر إلى زر. حدد موضع القائمة في ctx واسم العنصر المؤقت وعدد الأزرار في الصف وقالب النص. مثلًا، يُدخل {{item.name}} اسم المنتج الحالي. انظر الأزرار الديناميكية والمعاملات.
الرموز التعبيرية المميزة في النص
يُدخل زر التنسيق رمز تعبيري مميز في كتلة النص الوسم <tg-emoji emoji-id="…">🙂</tg-emoji>. يرى مستخدم Telegram Premium الرمز المخصص، ويرى غيره الرمز الاحتياطي داخل الوسم. يعمل في وضعَي HTML وMarkdown. المعرّف رقم حتى 32 خانة؛ يمكن معرفته عبر getCustomEmojiStickers أو بإعادة توجيه رسالة فيها الرمز إلى بوت مثل @idstickerbot.
رابط البوت والنص الجاهز
يفتح t.me/<bot>?start=<parameter> أمر /start <parameter> في Telegram. لا يمكن بهذا الرابط فتح المحادثة مع تمرير المعامل دون تشغيل /start. اختر ما يناسبك:
- بدء صامت: في التفاعل ذي مُشغِّل الأمر /start وقيمة وسم رابط البدء المطلوبة، اترك فعل «إرسال رسالة» بلا كتل. لن يظهر رد ملحوظ على
/start، لكن الوسم متاح بالفعل في سياق الحدث لشروط التفاعل وأفعاله الأخرى. - Prefilled text (نص جاهز): الرابط
https://t.me/<bot>?text=<text>، سواء في زر «Prefilled text» أو زر رابط عادي، يفتح المحادثة والنص في حقل الكتابة دون إرساله. لا يعمل/start؛ يرسل المستخدم النص بنفسه. - إرسال تلقائي باسم المستخدم عند فتح الرابط: لا يتيحه Bot API؛ لا يستطيع البوت إرسال رسالة باسم الشخص. أقرب بديل هو رابط
?start=وتفاعل يرد بالنص المطلوب باسم البوت.
الرد المتوقع (خطوات الحوار)
يمكن لكتلة نصية انتظار رد المستخدم، فتتوقف الخطوات حتى يجيب. تشكل عدة خطوات متتابعة استبيانًا أو سلسلة أسئلة داخل المحادثة.
نوع المحتوى المتوقع
يمكن انتظار نص أو اختيار من خيارات أو صورة أو فيديو أو فيديو دائري أو صوت أو مستند أو رسالة صوتية أو موقع أو جهة اتصال أو تقويم أو نرد. إن أرسل الشخص نوعًا مختلفًا، لا تُقبل إجابته في هذه الخطوة.
فحص النص
يمكن فحص الإجابة النصية كهاتف أو بريد إلكتروني أو رابط أو تاريخ أو وقت أو صيغة. إذا انتظر البوت هاتفًا ووصل نص آخر، يعرض رسالة خطأ. تستخدم صيغة الفحص الصيغة الموسعة: تعيد نصًا فارغًا عند النجاح، ونص الخطأ عند الرفض.
حفظ الجواب
يمكن حفظ جواب المستخدم في معامل، ليصبح متاحًا بصيغة {{param.key}} وفي الشروط. هكذا تجمع خطوات الحوار ملفًا مصغرًا للعميل.
الأخطاء والتذكير والمهلة
- رسالة خطأ الفحص: ما يظهر إذا لم تجتز الإجابة الفحص.
- تذكير: ما يُرسل إذا لم يرد المستخدم.
- إيقاف الانتظار عند انتهاء المهلة: متى يتوقف البوت عن الانتظار؛ ويمكنه عندها تشغيل تفاعل لإنهاء الاستبيان بلطف. يظهر هذا التفاعل في الروابط باسم «مهلة الانتظار»، ويظهر التفاعل مع الجواب باسم «الرد المتوقع».
الخروج من الخطوة بأمر
يزيل /cancel أو الكلمة الروسية «отмена» الانتظار ويجيب «Отменено.»، أو يشغّل تفاعل الإلغاء إن ضُبط. تُعد الأوامر الأخرى إجابات افتراضيًا وتخضع للفحص كأي نص، ما قد يبقي المستخدم في الخطوة. عند تفعيل أوامر البوت (مثل /start) تقطع الانتظار (escape_on_command)، يزيل أي أمر الانتظار بصمت ويُنفذ كالمعتاد.
الاستبدالات
يُدخل زر الاستبدالات بيانات المرسل ({{first_name}} و{{username}} و{{user_id}})، والحدث ({{text}} و{{chat_id}} و{{datetime}})، والمعاملات ({{param.key}}). القائمة الكاملة في الاستبدالات والصيغ.
زر قائمة البوت
يختار فعل Menu button قائمة البوت العادية أو الأوامر أو زر Mini App بنص وURL. يمكن تطبيقه على المحادثة الحالية أو إعداد البوت العام، مثل Mini App شخصية لعميل واحد. يعتمد توفره على إمكانات القناة.
ما التالي؟
- الاستبدالات والصيغ: القيم في النصوص والأزرار.
- الأفعال: بقية أفعال التفاعل.
- Mini App: زر تطبيق الويب.