بوتات تيليجرام ونجوم Stars: دليل الإجراءات المدفوعة

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

الجزء المربك ليس الزر، بل عملية التسليم. يحتاج المشتري إلى نجوم كافية، ويحتاج البوت إلى فاتورة نظيفة، وينبغي ألّا يُفتح الإجراء المدفوع إلا بعد أن يؤكّد تيليجرام الدفع.

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

إجابة سريعة

يعمل الإجراء المدفوع لبوت تيليجرام على أفضل وجه حين تُبقي العرض صغيراً وقابلاً للتحقق.

استخدم هذا التدفق:

1. حدّد إجراءً مدفوعاً واحداً.
2. أرِ المشتري ما سيحصل عليه.
3. أرسل فاتورة نجوم مقابل ذلك الإجراء.
4. افحص طلب ما قبل الدفع قبل قبول الدفع.
5. لا تسلّم إلا بعد حدث دفع ناجح.
6. خزّن مرجع الدفع كي لا يكون الدعم والاسترداد مجرد تخمين.
7. أخبر المشترين كيف يحصلون على النجوم قبل لحظة الفتح.

تصف مستندات دفع النجوم في تيليجرام تسلسل الفاتورة الأساسي للسلع والخدمات الرقمية: sendInvoice، وpre_checkout_query، وanswerPreCheckoutQuery، وsuccessful_payment، ثم التسليم. تستخدم Bot API الرمز XTR كرمز عملة للنجوم في هذه المدفوعات.

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

ماذا يغطّي هذا الدليل

استخدم هذا الدليل للإجراءات المدفوعة التي يسلّمها البوت، مثل:

• فتح ملف قابل للتنزيل؛
• إنشاء تقرير خاص؛
• إضافة أرصدة إلى حساب بوت؛
• فتح أمر مدفوع؛
• تسليم قائمة تحقق أو حزمة مطالبات أو مخطّط أو قالب مخصّص؛
• منح وصول إلى خدمة لمرة واحدة يتولّاها البوت.

لا تخلط ذلك بكل تدفقات نجوم تيليجرام.

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

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

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

الخطوة 1: حدّد الإجراء المدفوع

لا تبدأ بالفاتورة. ابدأ بالشيء الذي يحصل عليه المشتري.

تبدو وعود الإجراء المدفوع الضعيفة هكذا:

• "وصول مميّز."
• "افتح المزيد."
• "ادعم البوت."
• "احصل على محتوى إضافي."

تُنشئ هذه العبارات أسئلة دعم لأن المشتري لا يستطيع تحديد ما الذي يتغيّر بعد الدفع.

أما وعد الإجراء المدفوع الأقوى فمحدّد:

• "أنشئ تقرير تدقيق خاصاً واحداً."
• "افتح حزمة قوالب PDF الكاملة."
• "أضف 50 رصيداً إلى رصيد بوتك."
• "شغّل أمر المخطّط المتقدّم مرة واحدة."
• "افتح قائمة التحقق الخاصة لهذا الدرس."

قبل تسعير أي شيء، اكتب جملة واحدة:

بعد الدفع، يحصل المشتري على ________.

إذا كانت الجملة غامضة، فسيبدو تدفق البوت غامضاً أيضاً.

الخطوة 2: أرسل فاتورة النجوم

بالنسبة لفاتورة بوت قياسية، فإن طريقة Bot API في تيليجرام هي sendInvoice. وبالنسبة لمدفوعات النجوم، تستخدم الفاتورة رمز عملة النجوم XTR.

قائمة تحقق عملية للفاتورة:

• اضبط currency على XTR؛
• أبقِ رمز المزوّد فارغاً لمدفوعات النجوم حيث تسمح مستندات تيليجرام بذلك؛
• استخدم عنصر سعر واحداً لدفعة نجوم؛
• ضع مرجع طلبك الداخلي في الـ payload؛
• أبقِ العنوان والوصف قصيرين بما يكفي ليتعرّف المشتري على الإجراء؛
• لا تعِد استخدام الـ payload نفسه لإجراءات غير مرتبطة.

الـ payload مهم لأن شاشة الدفع ليست نظام طلباتك بأكمله. لا يزال بوتك بحاجة إلى معرفة المستخدم والإجراء والسعر الذي تخصّه هذه الفاتورة.

عادةً ما تتضمّن بيانات الـ payload الداخلية الجيدة:

• معرّف المستخدم المشتري؛
• معرّف الإجراء المدفوع؛
• مبلغ النجوم المتوقّع؛
• الطابع الزمني للطلب؛
• nonce أو معرّف طلب فريد؛
• حالة مثل created أو pending أو paid أو delivered أو refunded.

أبقِ نص الفاتورة العام إنسانياً. ينبغي ألّا يرى المشتري معرّفات داخلية أو صياغة المطوّرين.

عنوان فاتورة سيّئ:

SKU_XTR_CMD_ADV_2026

عنوان فاتورة أفضل:

تقرير مخطّط متقدّم

وصف فاتورة سيّئ:

نفّذ الإجراء المدفوع بعد التحقق من رد الاستدعاء.

وصف فاتورة أفضل:

افتح تقرير مخطّط خاصاً واحداً من هذا البوت.

الخطوة 3: تعامل مع ما قبل الدفع كحاجز أمان

يرسل تيليجرام استعلام ما قبل الدفع قبل اكتمال الدفع. تعامل معه كفحص أمان نهائي، لا كإجراء شكلي.

قبل الموافقة، تأكّد من أن:

• المستخدم لا يزال مطابقاً للطلب؛
• الإجراء المدفوع لا يزال موجوداً؛
• مبلغ النجوم المتوقّع لا يزال مطابقاً؛
• الإجراء لا يزال متاحاً؛
• الطلب لم يُدفَع أو يُلغَ من قبل؛
• الـ payload لم تنتهِ صلاحيته.

إذا لم يتطابق شيء ما، فارفض استعلام ما قبل الدفع برسالة خطأ واضحة. لا تدع فاتورة قديمة تفتح الإجراء الخطأ.

هذا مهم بوجه خاص للبوتات التي تبيع عناصر محدودة أو وصولاً موقوتاً أو مخرجات مولَّدة. قد ينقر مستخدم على رابط فاتورة قديم بعد تغيّر العرض. ينبغي أن يعرف بوتك ما يفعله.

الخطوة 4: لا تسلّم إلا بعد النجاح

نقرة الزر ليست دفعاً. والموافقة في مرحلة ما قبل الدفع ليست تسليماً. سلّم بعد أن يرسل تيليجرام حدث الدفع الناجح.

يبدو تدفق التسليم النظيف هكذا:

1. استقبل successful_payment.
2. طابقه مع الطلب الداخلي.
3. خزّن معرّف خصم الدفع من تيليجرام.
4. ضع علامة "مدفوع" على الطلب.
5. سلّم الإجراء المدفوع.
6. ضع علامة "تم التسليم" على الطلب.
7. أرسل رسالة تأكيد قصيرة إلى المشتري.

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

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

الخطوة 5: اجعل توقيت شحن المشتري واضحاً

يسهل نسيان جانب المشتري. عادةً ما يختبر صانعو المحتوى البوت بينما لديهم نجوم بالفعل. أما المشترون الحقيقيون فقد يصلون برصيد فارغ.

تقول مستندات دفع النجوم في تيليجرام إنه يمكن للمستخدمين الحصول على النجوم عند الحاجة قبل الدفع مقابل السلع والخدمات الرقمية. لا يعني ذلك أن الخطوة الإضافية بلا احتكاك لكل مشترٍ. إذا كان إجراؤك المدفوع يُطلَق في وقت محدّد، فحذّر الجمهور مبكراً.

يمكن لرسالة إطلاق بسيطة أن تقول:

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

هنا يندمج MyStars بشكل طبيعي. لا يحتاج صانع المحتوى إلى إخراج المشتري من تيليجرام من أجل الإجراء المدفوع نفسه. كل ما يحتاجه هو أن يكون لدى المشترين نجوم جاهزة قبل لحظة الفتح. وجّه المشترين إلى شحن نجوم تيليجرام قبل الإصدار، لا بعد أن يصبحوا محبَطين بالفعل.

إذا كنت تطلق أيضاً إصدارات وسائط مدفوعة، فاستخدم خطة إطلاق الوسائط المدفوعة لجدولة الإعلانات التشويقية وتذكيرات المشتري والقياس بعد الإطلاق.

فروع القرار

إذا كانت القيمة المدفوعة ملفاً أو قالباً

أبقِ الدفع لمرة واحدة. سلّم الملف بعد الدفع الناجح، ثم أرسل رسالة قصيرة بأسلوب الإيصال.

لا تجعل المشتري يطلب الملف من مشرف يدوياً. فذلك يحوّل تدفق البوت إلى طابور دعم.

إذا كانت القيمة المدفوعة تقريراً مولَّداً

أخبر المشتري بما إذا كان التقرير فورياً أم في قائمة الانتظار.

إذا كان الإنشاء قد يفشل، فافصل تأكيد الدفع عن حالة التسليم:

• مدفوع، قيد الإنشاء؛
• مدفوع، تم التسليم؛
• مدفوع، فشل - الدعم مطلوب.

هذا يجعل الاسترداد والدعم أسهل.

إذا كانت القيمة المدفوعة أرصدة

أضف الأرصدة فقط بعد الدفع الناجح. أظهِر الرصيد الجديد فوراً.

إذا كانت الأرصدة تنتهي صلاحيتها، فقل ذلك قبل الدفع. تُنشئ قواعد انتهاء الصلاحية المخفية شكاوى.

إذا كانت القيمة المدفوعة وسائط

استخدم التدفق الصحيح. يمكن لفاتورة بوت أن تبيع سلعة أو خدمة رقمية، لكن للوسائط المدفوعة طريقتها الخاصة في Bot API وسلوكها كمنتج. إذا كنت تبيع فتح صورة/فيديو/وسائط، فقارن التدفق مع دليل مشتري الوسائط المدفوعة في تيليجرام قبل البناء.

إذا كانت القيمة المدفوعة وصولاً إلى قناة

قد يكون ذلك اشتراك Star أو تدفق وصول آخر، لا إجراء بوت لمرة واحدة. أبقِ الوصول الشهري والإجراءات المدفوعة لمرة واحدة والوسائط المدفوعة منفصلة في نصوصك.

أخطاء يجب تجنّبها

• بيع وعد مميّز غامض دون توضيح ما الذي يُفتَح.
• اعتبار نقرة الزر دفعاً.
• التسليم بعد ما قبل الدفع بدلاً من بعد الدفع الناجح.
• نسيان تخزين معرّف خصم الدفع من تيليجرام.
• إعادة استخدام صيغة payload واحدة لإجراءات غير مرتبطة.
• ترك روابط الفواتير القديمة تفتح عروضاً تغيّرت.
• إخفاء انتهاء الصلاحية أو حدود الاستخدام حتى ما بعد الدفع.
• استخدام تسميات المطوّرين في نص الفاتورة الظاهر للمشتري.
• توجيه المشترين إلى الشحن فقط بعد أن يكون الإطلاق قد بدأ بالفعل.
• تسمية كل تدفق نجوم بـمنشورات مدفوعة، ما قد يخلط بين الوسائط المدفوعة والاشتراكات وفواتير البوت ومحتوى القنوات النصي فقط.

استكشاف الأخطاء وإصلاحها

المشتري يقول إنه دفع، لكن البوت لم يفتح

أسباب محتملة:

• لم يستقبل البوت successful_payment أو لم يعالجه؛
• لم يتطابق معرّف الطلب الداخلي مع الـ payload؛
• فشل التسليم بعد الدفع؛
• وضع البوت علامة "مدفوع" على الطلب لكن ليس "تم التسليم".

الإصلاح:

• ابحث بمعرّف المستخدم ومعرّف الطلب؛
• افحص معرّف خصم الدفع المخزّن؛
• تحقّق من حالة الإجراء المدفوع؛
• سلّم يدوياً إذا نجح الدفع وكان العنصر صالحاً؛
• سجّل الفشل كي لا يتكرّر العطل نفسه.

المشتري لا يستطيع الدفع لأنه لا يملك نجوماً

سبب محتمل:

• وصل المشتري إلى لحظة الدفع دون نجوم كافية جاهزة.

الإصلاح:

• أضف تذكيراً قبل الإطلاق؛
• ضمّن رابط شحن نجوم تيليجرام في تعليمات الإطلاق؛
• أبقِ رسالة دفع البوت قصيرة وواضحة؛
• لا تدفن إرشاد الشحن داخل إعلان طويل.

يفشل ما قبل الدفع

أسباب محتملة:

• انتهت صلاحية الطلب؛
• الـ payload مشوّه؛
• تغيّر المبلغ المتوقّع؛
• لم يعد الإجراء المدفوع متاحاً؛
• عالج البوت الطلب بالفعل.

الإصلاح:

• أعِد رسالة خطأ واضحة؛
• دع المستخدم ينشئ فاتورة جديدة؛
• تجنّب الفشل الصامت دون تفسير.

يصل طلب استرداد أو دعم

أسباب محتملة:

• دفع المشتري مقابل الإجراء الخطأ؛
• فشل التسليم؛
• كان نص العرض غير واضح؛
• توقّع المشتري اشتراكاً أو فتح وسائط، لكنه اشترى إجراء بوت.

الإصلاح:

• افحص معرّف خصم الدفع وسجل التسليم؛
• قرّر ما إذا كان الاسترداد مناسباً وفق سياستك والطرق المتاحة في تيليجرام؛
• أعِد صياغة العرض إذا أساء عدة مشترين فهم النقطة نفسها.

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

هل يمكن لبوت تيليجرام قبول النجوم مقابل إجراء مدفوع؟

نعم، تغطي مستندات دفع النجوم في تيليجرام السلع والخدمات الرقمية المباعة عبر البوتات والتطبيقات المصغّرة. في فاتورة البوت، الأجزاء المهمة هي رمز عملة النجوم XTR، ومعالجة ما قبل الدفع، وتأكيد الدفع الناجح، والتسليم بعد الدفع.

ماذا يعني XTR؟

XTR هو رمز العملة الذي يستخدمه تيليجرام للنجوم في تدفق الدفع عبر Bot API. استخدمه لفواتير النجوم بدلاً من التعامل مع النجوم كرمز عملة ورقية عادي.

هل تحتاج فواتير النجوم إلى رمز مزوّد دفع؟

تقول مستندات Bot API في تيليجرام بتمرير رمز مزوّد فارغ لمدفوعات نجوم تيليجرام حيث يظهر هذا المعامل. راجع مستندات Bot API الحالية قبل التنفيذ لأن تفاصيل الواجهة قد تتغير.

متى يجب أن يسلّم البوت الإجراء؟

بعد حدث الدفع الناجح، وليس بعد نقر المستخدم على زر الدفع، وليس فقط بعد الموافقة في مرحلة ما قبل الدفع.

ماذا لو لم يكن لدى المشتري نجوم كافية؟

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

هل الإجراء المدفوع للبوت هو نفسه الوسائط المدفوعة؟

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

هل يمكن استرداد مدفوعات النجوم؟

تتضمّن Bot API في تيليجرام refundStarPayment لمدفوعات النجوم الناجحة. خزّن معرّف خصم الدفع وحالة طلبك الداخلية لتتمكّن من إدارة الدعم وقرارات الاسترداد بوضوح.

المصادر والأدلة

• إطلاق نجوم تيليجرام: Telegram Stars: Pay for Digital Goods and More.
• تدفق دفع النجوم للبوتات: Telegram Stars Payments.
• معاملات فاتورة البوت: Bot API sendInvoice.
• نطاق الوسائط المدفوعة: Bot API sendPaidMedia.
• إعلان اشتراكات Star والوسائط المدفوعة: Telegram Super Channels, Star Reactions and Subscriptions.
• شروط النجوم ونطاق الرصيد: Telegram Stars Terms.

قائمة التحقق النهائية

قبل أن تطلق إجراء بوت مدفوعاً:

• الإجراء المدفوع محدّد؛
• عنوان الفاتورة قابل للقراءة من البشر؛
• يرتبط الـ payload بطلب داخلي واحد؛
• يُفحَص مبلغ النجوم قبل الدفع؛
• يحدث التسليم بعد الدفع الناجح؛
• يستطيع الدعم العثور على معرّف الخصم وحالة التسليم؛
• يعرف المشترون كيف يشحنون النجوم قبل مطالبة البوت.