Telegram Bot API 10.4: عندما تصبح الرسالة تطبيقاً صغيراً

2026-11-12
الرسالة صارت سطح تطبيق: ويدجت تفاعلي ومحفظة TON داخل الدردشة. دليل عملي لمطوّري بوتات Telegram على إصدار 10.4.
في التاسع من نوفمبر، أصدرت Telegram إصدار Bot API 10.4، وهو أكبر تغيير في واجهة البوتات منذ سنوات. السبب بسيط في الوصف: صار بإمكان البوت أن يرسل رسالة تحتوي ويدجت HTML تفاعلياً، فيرى المستخدم أزراراً وبيانات ونماذج داخل فقاعة المحادثة نفسها.
المعنى العملي أن التطبيق الصغير لم يعد يحتاج إلى فتح نافذة Web App منفصلة. يمكن أن يعيش داخل الرسالة، ويتفاعل معها المستخدم من دون مغادرة الدردشة. وأضافت Telegram معه دعماً لمحفظة TON داخل الواجهة نفسها.
هذا ليس تحديثاً للمستخدم العادي، بل للمطوّر. من يبني بوتاً اليوم عليه أن يقرر: هل يبني داخل Telegram أم يبقى خارجها؟
ما الجديد في Telegram Bot API 10.4
أربعة محاور رئيسية في هذا الإصدار. الأول الويدجت: صنف Widget وحقل widget يُضافان إلى Message وExternalReplyInfo، وطريقة sendWidget لإرسال رسالة تحتوي ويدجت HTML، وطريقة sendSharedWidget لإعادة إرسال ويدجت مشارك.
الثاني الاستعلامات: صنف WidgetQuery وحقل widget_query في Update، لاستقبال ما يفعله المستخدم داخل الويدجت، مع أنواع فرعية تشرح طبيعة الطلب: بيانات عادية، أو بيانات موقّعة من محفظة TON، أو إشعار بتحويل من المحفظة.
الثالث التحرير: editMessageWidgetData لتغيير بيانات ويدجت داخل رسالة، وeditSharedWidgetData لتغيير البيانات العامة لويدجت مشارك. والرابع الأوامر السريعة: رسائل مؤقتة (Ephemeral) يمكن للبوت إرسالها رداً على ضغط زر في أي محادثة تقريباً.
ويدجت Telegram: كيف تعمل داخل المحادثة
الويدجت في هذا الإصدار ليس صورة ولا ملفاً، بل سطح تفاعلي يُبنى بـ HTML ويُرسل داخل رسالة. المستخدم يرى النتيجة النهائية فقط: شبكة أزرار، أو جدول بيانات، أو نموذج إدخال.
ولأنه مبني على HTML، فإن حدود التصميم أوسع من لوحات المفاتيح التقليدية (Inline Keyboard) التي كانت محدودة بالأزرار والنصوص. هذا فرق كبير لمن يحاول بناء متجر أو نموذج حجز أو لوحة نتائج داخل الدردشة.
الشرط الأساسي: الويدجت في بيئة الإنتاج يُرسل إلى المحادثات الخاصة فقط. لا مجموعات، ولا قنوات، في هذا الإصدار. وهذا القيد يحدد من يستطيع استخدامه اليوم.
تطبيقات صغيرة في Telegram بلا مغادرة الدردشة
الفكرة التي تبيعها Telegram هنا واضحة: لا مزيد من التبديل بين التطبيقات. الويدجت داخل الرسالة يعني أن الطلب والدفع والتأكيد يمكن أن تحدث في مكان واحد.
ولهذا جاء دعم محفظة TON في الإصدار نفسه. أصناف TonWalletCard وTonNft وTonWalletTransfer تسمح للبوت بعرض بطاقة المحفظة، واستقبال بيانات موقّعة، وإظهار رسالة خدمة عند التحويل. أي أن الدفع لم يعد يحتاج رابطاً خارجياً.
هذا هو الفرق بين «بوت يرسل رابط دفع» و«بوت يستقبل الدفع». الأول يخرج المستخدم من التطبيق، والثاني يبقيه. ولمن يبيع شيئاً عبر Telegram، الفرق بين الاثنين هو الفرق بين سلة تُغلق وسلة تُنسى.
الموارد والأدوات المتاحة الآن
لا يوجد «رمز تفعيل» لهذا الإصدار. ما يوجد هو موارد رسمية يستخدمها المطوّر مباشرة، وكلها متاحة اليوم بلا تسجيل.
- BOTFATHER: البوت الرسمي لإنشاء البوتات وتعديل إعداداتها، وهو نقطة البداية لأي ويدجت.
- CORE.TELEGRAM.ORG: التوثيق الكامل لـ Bot API، وفيه صفحة التغييرات التي تسرد كل صنف وطريقة أُضيفت في 10.4.
- HTML: لغة بناء الويدجت نفسها، وهي التي تحدد ما يمكن عرضه داخل الرسالة.
- API: الواجهة التي يتصل بها البوت، وتشمل الطرق الجديدة sendWidget وanswerWidgetQuery وeditMessageWidgetData.
- TON: محفظة المستخدم داخل Telegram، وهي مصدر البيانات الموقّعة وإشعارات التحويل.
- WEBAPP: التطبيقات الصغيرة القائمة، التي يمكنها الآن أن ترسل ويدجت بدل فتح نافذة كاملة.
- STARS: عملة Telegram الداخلية، ومرتبطة بطريقة إدارة الهدايا في هذا الإصدار.
- BOTNEWS: القناة الرسمية التي تُعلن التحديثات قبل نشر التوثيق.
هذه القائمة هي ما تحتاجه فعلاً. أي «أداة» أو «حزمة» تبيعها مواقع خارجية لبناء ويدجت Telegram ليست رسمية، ولا تحتاجها.
كيف ترسل ويدجت Telegram خطوة بخطوة
الترتيب التالي هو المسار الرسمي كما ورد في التوثيق، لا اختصاراً.
- أنشئ البوت عبر BotFather واحتفظ بالرمز (Token).
- تأكد أن البوت يملك صلاحية can_send_other_messages في المحادثة المستهدفة، فهي التي تسمح بإرسال الويدجت.
- اتصل بطريقة sendWidget وأرسل محتوى HTML مع chat_id للمستخدم.
- انتظر استعلاماً في Update يحمل الحقل widget_query، وهو ما يفعله المستخدم داخل الرسالة.
- أجب عبر answerWidgetQuery، أي ما يعادل استرداد النتيجة (Redeem) في المتاجر: البوت يرد على إجراء المستخدم من دون رسالة جديدة.
- إن احتجت تحديث البيانات لاحقاً، استخدم editMessageWidgetData بدل إرسال رسالة ثانية.
- لإعادة إرسال ويدجت شاركه المستخدم، استخدم sendSharedWidget مع العنوان المناسب.
ملاحظة تقنية مهمة: الويدجت المُرسل يحمل حماية محتوى تلقائية، أي أنه لا يمكن تحويله. ومن يحاول استخدام copyMessage على رسالة ويدجت لن يحصل على شيء.
لماذا قد لا يعمل ويدجت Telegram
أربعة أسباب شائعة، وكلها موثّقة.
- الإرسال إلى مجموعة أو قناة: غير مدعوم في بيئة الإنتاج، والويدجت مخصص للمحادثات الخاصة.
- محاولة الإرسال رداً على استعلام inline: غير مدعوم في الإنتاج أيضاً، رغم وجود الأصناف اللازمة في الواجهة.
- صلاحية مفقودة: من دون can_send_other_messages لن يمر الطلب.
- محاولة التحويل أو النسخ: الحماية مفعّلة، والنسخ لا يعمل بطبيعته.
سبب خامس محتمل: البوت يستخدم مكتبة قديمة لا تعرف الحقول الجديدة. التحديث إلى نسخة تدعم 10.4 شرط أساسي، وإلا سترى الحقل في الاستجابة ولا تعرف كيف تقرأه.
ماذا يعني هذا لمطوّري بوتات Telegram
ثلاث نتائج عملية. الأولى أن بوتات المتاجر والحجوزات صارت قادرة على العمل داخل المحادثة بالكامل، وهذا يوسّع ما يمكن بناؤه بلا موقع ولا تطبيق.
الثانية أن الاعتماد على Web App سيتراجع في الحالات البسيطة. من كان يفتح نافذة كاملة لملء نموذج من ثلاثة حقول، يمكنه الآن عرض النموذج في الرسالة نفسها.
الثالثة أن قيود الإنتاج تحدد السقف. محادثات خاصة فقط، وبلا inline، وبلا تحويل. هذه ليست تفاصيل هامشية، بل ما يفرق بين فكرة جميلة وبوت يعمل فعلاً.
جدول: ما أضافه Telegram Bot API 10.4
| المجال | ما أُضيف | القيد |
|---|---|---|
| الويدجت | Widget، sendWidget، sendSharedWidget | محادثات خاصة فقط |
| الاستعلامات | WidgetQuery، answerWidgetQuery | يحتاج تحديث المكتبة |
| التحرير | editMessageWidgetData، editSharedWidgetData | البيانات العامة فقط في المشارك |
| محفظة TON | TonWalletCard، TonNft، TonWalletTransfer | يحتاج محفظة مرتبطة |
| الرسائل المؤقتة | ردود Ephemeral على الأزرار | ليست في قنوات الرسائل المباشرة |
| عام | أسماء مستخدمين ثانوية تنتهي بـ agent أو ai أو app أو game | لمشتركي Premium فقط |
الخلاصة
Bot API 10.4 ينقل الرسالة من نص إلى سطح تطبيق. الويدجت والمحفظة والاستعلامات معاً تعني أن الدردشة صارت مكاناً للعمل لا للكلام فقط، وهذا أكبر تغيير في واجهة البوتات منذ سنوات.
نزّل Telegram من APKPure وثبّته لتجرّب البوتات التي تستخدم الويدجت، وتأكد من رقم الإصدار لأن الواجهة تحتاج نسخة حديثة لعرض العناصر التفاعلية. وإن كنت مطوّراً، ابدأ من التوثيق الرسمي وابنِ نموذجاً واحداً صغيراً قبل أن تعيد بناء منتجك كله. وتحذير أخير يخص أمان حسابك: لا بوت رسمي يطلب رمز تسجيل الدخول أو رمز التحقق، وأي بوت يفعله فهو انتحال.