پایگاه دانش GetMyBot

پروژه‌ها و کانال‌ها

ساخت پروژه، اتصال بات و بررسی وضعیت آن؛ چند کانال، تغییر توکن، توقف و بازیابی پس از مسدود شدن به‌دلیل طرح.

در این صفحه

پروژه تنظیمات، واکنش‌ها و داده‌های یک بات یا خدمت را کنار هم نگه می‌دارد. کانال آن را به محل گفت‌وگو وصل می‌کند، مانند بات Telegram، گفت‌وگوی وب‌سایت یا پیام‌رسان دیگر. برای مثال، یک مدرسه می‌تواند یک پروژه با دو کانال Telegram و وب‌سایت داشته باشد.

در پروژه‌ها پروژه بسازید و سپس کانال را به آن اضافه کنید. برای Telegram به توکن @BotFather نیاز دارید؛ این توکن کلید کنترل بات است. پروژهٔ فعال را از بالای صفحه تغییر دهید.

می‌توانید WhatsApp و VK را نیز به همان پروژه وصل کنید و از واکنش‌های مشترک استفاده کنید. راهنما: کانال‌ها و WhatsApp.

اتصال بات

  1. اگر هنوز پروژه‌ای ندارید، پروژه‌ها را باز کنید و افزودن پروژه را بزنید. در کارت پروژه افزودن کانال را بزنید و Telegram را انتخاب کنید. برای اولین بات می‌توانید از راهنمای شروع استفاده کنید.
  2. توکن @BotFather را وارد کنید و بررسی را بزنید. GetMyBot نام @username پیدا شده را نشان می‌دهد تا مطمئن شوید توکن درست است.
  3. اتصال را بزنید. توکن هنگام نگهداری رمزگذاری می‌شود و دریافت رویدادها بلافاصله آغاز می‌شود.

پس از اتصال، Telegram کنار کانال‌های دیگر در کارت پروژه دیده می‌شود. کارت، نام پروژه، @username بات، تعداد کاربران، واکنش‌های فعال و درخواست‌های امروز را نشان می‌دهد. ماندهٔ درخواست‌ها در صورتحساب یا آمار است.

چند بات

یک حساب می‌تواند چند پروژه و بات را هم‌زمان اداره کند. تعداد آنها به سقف طرح شما، یعنی «حداکثر بات‌ها»، بستگی دارد. پروژه را از بالای صفحه یا پروژه‌ها عوض کنید؛ بخش‌های «واکنش‌ها»، «چت‌ها» و «آمار» داده‌های پروژهٔ انتخاب‌شده را نشان می‌دهند.

بات چگونه پیام‌ها را دریافت می‌کند

پس از اتصال، GetMyBot رویدادهای Telegram، از جمله پیام‌ها، فشار دکمه‌ها، ورود اعضا و پرداخت‌ها را دریافت می‌کند. با توکن معتبر، تنظیم جداگانه‌ای لازم نیست. بسته به تنظیمات سرور، Telegram رویدادها را به نشانی پلتفرم می‌فرستد (وب‌هوک) یا پلتفرم مرتب آنها را از Telegram می‌گیرد (long polling).

روشن و خاموش کردن

هر بات در کارت وضعیت بات در تنظیمات، حالت روشن / خاموش دارد. بات خاموش به پیام‌ها پاسخ نمی‌دهد. تغییر حالت همان لحظه اعمال می‌شود و نیازی به اتصال دوباره نیست.

وضعیت پروژه و دسترس‌پذیری کانال

در پروژه‌ها، وضعیت پروژه جداگانه نشان داده می‌شود: فعال، مکث‌شده یا مسدودشده. این وضعیت، آزمون تحویل پیام Telegram نیست. هر کانال نیز برچسب خودش را دارد: آنلاین، بدون سیگنال، پیکربندی‌شده، غیرفعال یا پروژه غیرفعال است. پس پروژهٔ فعالی که فقط گفت‌وگوی وب دارد، نباید متوقف به نظر برسد.

اگر پروژهٔ فعال دقیقاً یک کانال Telegram روشن داشته باشد، آنلاین یعنی فرایند رسیدگی‌کننده به بات اخیراً علامت فعالیت ثبت کرده است. اگر علامت تازه‌ای نباشد، بدون سیگنال دیده می‌شود. با چند کانال Telegram روشن، پیکربندی‌شده نشان داده می‌شود، چون نمی‌توان علامت مشترک پروژه را با اطمینان به یکی از آنها نسبت داد. برای کانال‌های روشنِ دیگر پلتفرم‌ها نیز پیکربندی‌شده فقط به معنای اتصال است، نه تضمین تحویل تک‌تک پیام‌ها.

چند فرایند هم‌ارز به بات‌ها سرویس می‌دهند. هر کدام هر ۳۰ ثانیه برای باتی که اداره می‌کنند علامت فعالیت ثبت می‌کنند. علامت تا یک دقیقه و نیم تازه محسوب می‌شود تا با از دست رفتن یک علامت، وضعیت مدام تغییر نکند.

در عمل:

  • برچسب ممکن است با تأخیر به‌روز شود. پس از اتصال یا راه‌اندازی دوبارهٔ پلتفرم، «آنلاین» ممکن است در همین بازه ظاهر شود.
  • اگر یک کانال Telegram روشن بیش از چند دقیقه بدون سیگنال ماند، توکن و کارت Bot health («سلامت بات») را در تنظیمات بررسی کنید. پروژه تا وقتی خودتان آن را مکث نکنید یا پلتفرم به‌دلیل طرح مسدودش نکند، فعال می‌ماند.
  • علامت میان فرایندها مشترک است؛ به سروری که پاسخ درخواست شما را داده وابسته نیست و برای چند کانال Telegram، دسترس‌پذیری تک‌تک آنها را ثابت نمی‌کند.

وقتی بات از دسترس خارج می‌شود چه اتفاقی می‌افتد

پلتفرم هر دقیقه علامت‌های فعالیت را بررسی می‌کند. اگر برای بات روشن هیچ علامت تازه‌ای نباشد، یک رخداد قطعی ثبت می‌شود. پلتفرم علت را بررسی می‌کند و برای بازیابی بات تلاش می‌کند.

چهار علت ممکن است و در کارت Bot health دیده می‌شود:

  • وب‌هوک: Telegram رویدادها را به نشانی پلتفرم نمی‌رساند؛ پلتفرم نشانی را دوباره ثبت می‌کند.
  • توکن باطل‌شده: getMe پاسخ 401 می‌دهد. این مورد با راه‌اندازی دوباره حل نمی‌شود؛ در @BotFather توکن تازه بگیرید و آن را از تغییر توکن وارد کنید.
  • نبود سرور رسیدگی‌کننده: هیچ فرایندی رویدادها را پردازش نمی‌کند؛ پلتفرم بات را دوباره راه می‌اندازد.
  • علت نامشخص: Telegram به بررسی پاسخ نداده است.

راه‌اندازی دوباره همان کار دکمهٔ همگام‌سازی را انجام می‌دهد: توکن را با getMe بررسی می‌کند و وب‌هوک را دوباره ثبت می‌کند. میان تلاش‌ها فاصله به‌تدریج بیشتر می‌شود. زمان و نتیجهٔ هر تلاش، و متن خطا در صورت شکست، در Restart log کارت ثبت می‌شود؛ زمان تلاش بعدی نیز همان‌جا دیده می‌شود.

اگر بات بیش از آستانهٔ تنظیم‌شده در Bot health بی‌پاسخ بماند (پیش‌فرض ۵ دقیقه)، مالک در اعلان‌ها و ایمیل پیام «بات آفلاین است» می‌گیرد و چت‌های فهرست گیرندگان اعلان، پیامی از خود بات دریافت می‌کنند. برای هر رخداد فقط یک اعلان فرستاده می‌شود. وقتی علامت فعالیت برگردد، پیام «بات دوباره آنلاین شد» با مدت وقفه می‌رسد. سابقهٔ رخدادها، مدت و علت آنها نیز در همان کارت می‌ماند.

مسدود شدن به‌دلیل طرح

علاوه بر روشن و خاموش بودن، بات ممکن است مسدودشده باشد. خود پلتفرم وقتی طرح فعال دیگر تعداد بات‌های متصل را پوشش ندهد، آن را مسدود می‌کند. فقط دو علت وجود دارد:

  • عبور از سقف بات‌ها: به طرحی رفته‌اید که کمتر از تعداد بات‌های فعلی جا دارد.
  • تمدید نشدن اشتراک: طرح پولی تمام شده و طرح رایگان با سقف خودش فعال است.

بات مسدودشده پیام دریافت نمی‌کند؛ دریافت رویدادهایش واقعاً خاموش می‌شود. داده‌ها، واکنش‌ها و مشترکان باقی می‌مانند و مسدود شدن برگشت‌پذیر است.

برای بازگرداندن بات‌ها طرحی بخرید که تعداد لازم را پوشش دهد. با فعال شدن طرح، بات‌ها خودکار از قدیمی‌ترین بات‌ها به بعد تا پر شدن سقف طرح به کار برمی‌گردند. نمی‌توانید مستقیماً انتخاب کنید کدام بات زودتر بازگردد. اگر بات‌های دیگری را لازم دارید، اتصال‌های اضافی را حذف کنید و سپس طرح را بخرید.

مسدود شدن کل حساب موضوع دیگری است: در آن حالت همهٔ بات‌ها و ارسال‌های همگانی متوقف می‌شوند و نوار «حساب مسدود شده است» در پنل دیده می‌شود. رفع آن فقط از طریق پشتیبانی انجام می‌شود. پرداخت‌ها و موجودی را نیز ببینید.

پروفایل و همگام‌سازی

دکمهٔ همگام‌سازی در تنظیمات، نام بات را از Telegram به‌روز می‌کند، مثلاً اگر آن را در @BotFather عوض کرده باشید. عکس پروفایل بات به‌طور خودکار دریافت می‌شود.

تغییر توکن

اگر توکن را در @BotFather بازنشر کرده‌اید (Bot Settings ← Revoke / New token)، آن را در تنظیمات ← کانال‌ها ← Telegram 🔑 به‌روز کنید. توکن جدید باید به همان بات تعلق داشته باشد (شناسه داخلی Telegram یکسان باشد) — به این ترتیب تمام واکنش‌ها، مشترکان و داده‌ها حفظ می‌شوند. اگر کانال Telegram نمایش داده نمی‌شود، در همان پنجره «تغییر توکن» را انتخاب کنید.

انتقال بات به حسابی دیگر

تنظیمات پروژه → تغییر مالک دعوت‌نامه‌ای برای انتقال پروژه به ایمیل حساب دیگر GetMyBot می‌فرستد. دعوت‌نامه ۷۲ ساعت اعتبار دارد. تا پیش از پذیرش گیرنده، پروژه نزد شما می‌ماند و می‌توانید انتقال را لغو کنید. پس از پذیرش، مالک تغییر می‌کند و دسترسی شما به پروژه قطع می‌شود. این مسیر برای تحویل پروژه به مشتری یا همکار مناسب است.

قالب‌های بات

قالب، نسخه‌ای از تنظیمات بات و همهٔ واکنش‌های آن است که می‌توانید روی بات دیگر اعمال کنید:

  • ساخت قالب در تنظیمات، بات فعلی را با یک نام به‌صورت قالب ذخیره می‌کند.
  • اعمال قالب تنظیمات بات انتخاب‌شده را با تنظیمات قالب جایگزین می‌کند و واکنش‌های قالب را به واکنش‌های فعلی اضافه می‌کند.

برای ساخت بات‌های مشابه در چند پروژه مفید است.

نصب راهکار آماده از کاتالوگ

کاتالوگ راهکارهای آماده، راهنمای نصب دارد. پارامترها را وارد کنید، سازگاری و اتصال‌های لازم را بررسی کنید و سپس فهرست منابعی را که ساخته می‌شوند ببینید. بعد از نصب، گام‌های باقی‌مانده را انجام دهید و سناریو را با یک درخواست آزمایشی امتحان کنید.

این راهنما با اعمال قالبِ ذخیره‌شدهٔ بات در بخش قبل فرق دارد. بررسی پیش از نصب، پارامترها یا قابلیت‌های کمبود را نشان می‌دهد؛ علامت زدن یک گام به‌تنهایی ثابت نمی‌کند سرویس بیرونی کار می‌کند.

شاخص‌های راهکار آماده

بازه‌ای را برای ارزیابی عملکرد راهکار نصب‌شده انتخاب کنید. برای مقایسه، حالت موجود را برگزینید و حجم نمونه و توضیح تشخیصی را بررسی کنید. دادهٔ ناکافی و نبود امکان مقایسه با نتیجهٔ صفر تفاوت دارند.

مراحل بعدی