چرا ربات تلگرام جواب نمی‌دهد؟ عیب‌یابی Webhook، getUpdates و Pending Updates

اگر ربات تلگرام جواب نمی‌دهد، قبل از تغییر کد یا خرید سرویس جدید، مسیر دریافت Update را مشخص کنید: ربات یا با Webhook پیام را دریافت می‌کند یا با Long Polling و متد getUpdates؛ این دو روش هم‌زمان قابل استفاده نیستند. سپس با getMe اعتبار توکن، با getWebhookInfo وضعیت Webhook و تعداد Pending Updates، با لاگ برنامه رسیدن Update و با یک درخواست آزمایشی توانایی ارسال پاسخ را جداگانه بسنجید. این تفکیک ساده مشخص می‌کند خرابی در تلگرام، شبکه، SSL، اجرای پردازه، منطق برنامه یا منابع میزبانی است و جلوی آزمون‌وخطای پرهزینه را می‌گیرد.

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

فهرست مطالب

• تشخیص سریع در ده دقیقه
• انتخاب Webhook یا getUpdates
• عیب‌یابی Webhook، HTTPS و SSL
• عیب‌یابی getUpdates، Long Polling و خطای 409
• تحلیل Pending Updates و صف معوق
• بررسی پردازه، لاگ و منطق برنامه
• طراحی health check و مانیتورینگ
• چک‌لیست انتخاب هاست ربات تلگرام
• پرسش‌های متداول

وقتی ربات تلگرام جواب نمی‌دهد از کجا شروع کنیم؟

نشانه «جواب نمی‌دهد» به‌تنهایی اطلاعات کافی ندارد. ابتدا دقیق بنویسید چه اتفاقی می‌افتد: آیا هیچ Update وارد برنامه نمی‌شود؟ Update می‌رسد اما پاسخ ارسال نمی‌شود؟ فقط Callback Query یا فایل‌ها مشکل دارند؟ پاسخ با چند دقیقه تأخیر می‌رسد؟ خرابی دائمی است یا پس از مدتی کارکرد ظاهر می‌شود؟ هرکدام مسیر متفاوتی دارد. برای نمونه، رسیدن Update در لاگ و نبود پاسخ معمولاً نگاه را از Webhook به منطق handler، دسترسی خروجی یا خطای sendMessage می‌برد؛ اما خالی بودن کامل لاگ ورودی، Webhook، Poller یا شبکه را در اولویت قرار می‌دهد.

مدل چهارلایه برای محدودکردن دامنه خطا

لایه	پرسش تشخیصی	شاهد قابل اعتماد	اقدام اول
Telegram API	توکن معتبر است و API پاسخ می‌دهد؟	پاسخ getMe و کد HTTP	توکن را بدون نمایش در لاگ آزمایش کنید
دریافت Update	Webhook یا Polling فعال و یکتا است؟	getWebhookInfo یا لاگ Poller	روش فعال را مشخص و روش دیگر را متوقف کنید
اجرای برنامه	پردازه زنده و آماده پردازش است؟	process manager، exit code، لاگ startup	علت توقف یا restart loop را پیدا کنید
منطق و خروجی	handler اجرا و پاسخ پذیرفته می‌شود؟	update_id، correlation id، پاسخ sendMessage	خطای برنامه و درخواست خروجی را جدا بررسی کنید

این جدول ترتیب بررسی را نیز مشخص می‌کند. تغییر تصادفی SSL، نصب دوباره کتابخانه یا ری‌استارت مکرر ممکن است موقتاً نشانه را پنهان کند، اما علت را معلوم نمی‌کند. در یک رخداد واقعی، زمان شروع اختلال، آخرین تغییر کد یا تنظیمات، آخرین Update موفق و اولین خطای تکرارشونده را ثبت کنید. همین چهار نقطه زمانی معمولاً میان «خرابی پس از انتشار نسخه»، «انقضای گواهی»، «توقف worker» و «افزایش بار» تمایز ایجاد می‌کند.

Runbook ده‌دقیقه‌ای

1. با getMe بررسی کنید توکن به ربات مورد انتظار تعلق دارد. توکن را در تاریخچه ترمینال، اسکرین‌شات یا تیکت عمومی نگذارید.
2. getWebhookInfo را بخوانید. URL، pending_update_count، last_error_date و last_error_message را ثبت کنید.
3. اگر URL خالی است، فقط یک Poller باید getUpdates را اجرا کند. اگر URL پر است، Poller را متوقف کنید.
4. در لاگ برنامه دنبال startup، shutdown، exception، timeout، status code و آخرین update_id بگردید.
5. یک پیام ساده به ربات بفرستید و مسیر آن را از دریافت تا ارسال پاسخ با یک شناسه پیگیری دنبال کنید.
6. اگر ورودی می‌رسد ولی پاسخ نه، sendMessage را مستقل از handler آزمایش و پاسخ API را کامل ثبت کنید.
7. در پایان، تغییر انجام‌شده و نتیجه را بنویسید؛ چند تغییر هم‌زمان ندهید.

اصل طلایی عیب‌یابی ربات این است: «رسیدن Update» و «توانایی ارسال پاسخ» دو آزمون مستقل‌اند. تا این دو را جدا نسنجید، واژه آفلاین علت واقعی را پنهان می‌کند.

Webhook یا getUpdates؛ اول مالک مسیر Update را مشخص کنید

طبق مستندات رسمی Bot API، دو راه دریافت Update وجود دارد و این دو متقابلاً انحصاری‌اند. در Webhook، تلگرام یک درخواست HTTPS POST به نشانی شما می‌فرستد. در getUpdates، برنامه با Long Polling به سرور تلگرام درخواست می‌دهد و Updateها را می‌کشد. وقتی Webhook تنظیم است، getUpdates قابل استفاده نیست. بنابراین اولین تصمیم فنی این نیست که «کدام بهتر است»، بلکه این است که «در معماری فعلی کدام روش باید تنها مالک دریافت باشد».

جدول تصمیم Webhook و Long Polling

معیار	Webhook	Long Polling با getUpdates
جهت اتصال	تلگرام به endpoint شما	برنامه شما به Bot API
نیاز اصلی	URL عمومی HTTPS و پاسخ‌گویی endpoint	پردازه پیوسته و فقط یک مصرف‌کننده فعال
نشانه خرابی رایج	last_error و رشد pending_update_count	توقف worker، offset نادرست یا چند Poller
آزمون کلیدی	getWebhookInfo و لاگ HTTP	لاگ حلقه polling و پاسخ getUpdates
مناسب برای	وب‌اپلیکیشن دارای endpoint پایدار	پردازه‌ای که می‌تواند مداوم اجرا شود

انتخاب روش باید با معماری برنامه و امکانات واقعی محیط میزبانی هماهنگ باشد. Webhook به یک endpoint عمومی، TLS سالم و مسیر وب قابل اتکا نیاز دارد. Polling به اجرای مداوم پردازه، مدیریت restart و جلوگیری از اجرای نسخه دوم نیاز دارد. هیچ‌کدام ذاتاً تضمین نمی‌کند ربات سریع‌تر یا پایدارتر باشد؛ کیفیت پیاده‌سازی، اندازه کار داخل handler، سیاست retry، ظرفیت سرویس و مشاهده‌پذیری تعیین‌کننده‌اند.

تغییر روش دریافت بدون ایجاد تداخل

برای مهاجرت از Webhook به Polling، ابتدا endpoint قبلی را از چرخه ترافیک خارج نکنید؛ ابتدا پردازش‌های درحال‌انجام را تمام، وضعیت صف را ثبت و سپس deleteWebhook را اجرا کنید. گزینه drop_pending_updates به معنای حذف Updateهای منتظر است و نباید صرفاً برای سریع‌شدن راه‌اندازی استفاده شود. بعد از تأیید خالی‌شدن URL در getWebhookInfo، فقط یک Poller را بالا بیاورید. در مسیر معکوس، Poller را متوقف کنید، قفل یا supervisor آن را کنترل کنید، Webhook را ثبت و با یک Update آزمایشی تحویل را بسنجید.

پنجره تغییر و معیار بازگشت

پیش از تغییر، معیار موفقیت بنویسید: مثلاً «سه Update متوالی دریافت شود، update_id افزایش یابد، پاسخ خروجی موفق باشد و صف رشد نکند». همچنین معیار بازگشت داشته باشید: اگر در چند دقیقه نخست last_error تکرار شد یا صف افزایشی شد، به تنظیم قبلی برگردید. این کار مانع می‌شود مهاجرت روش دریافت به یک رخداد طولانی و مبهم تبدیل شود.

یادآوری امنیتی درباره توکن

توکن Bot API یک راز عملیاتی است. آن را در URLهای قابل ثبت، خروجی عمومی curl، مخزن کد، ابزار مانیتورینگ یا متن مقاله قرار ندهید. در مثال‌های این راهنما از متغیر محیطی و placeholder استفاده شده است. اگر احتمال افشا وجود دارد، توکن را از مسیر رسمی تعویض کنید و نسخه قبلی را نامعتبر بدانید.

عیب‌یابی Webhook تلگرام، HTTPS و SSL

getWebhookInfo نقطه شروع Webhook است، نه حدس‌زدن از روی مرورگر. این متد وضعیت فعلی را برمی‌گرداند: url، وجود گواهی سفارشی، تعداد Pending Updates، آدرس IP فعلی Webhook و در صورت رخداد، زمان و پیام آخرین خطا. همچنین max_connections و allowed_updates نشان می‌دهند چه ظرفیتی و چه نوع Updateهایی تنظیم شده‌اند. تصویر این فیلدها را در لحظه خرابی ذخیره کنید؛ اجرای دوباره setWebhook ممکن است شواهد مفید را تغییر دهد.

curl -sS "https://api.telegram.org/bot${BOT_TOKEN}/getWebhookInfo"

پاسخ را فقط به «ok=true» تقلیل ندهید. URL باید دقیقاً همان endpoint مورد انتظار باشد؛ pending_update_count باید روندی قابل توضیح داشته باشد؛ last_error_message ممکن است کد HTTP، مشکل اتصال یا TLS را نشان دهد؛ allowed_updates باید شامل نوع پیامی باشد که انتظار دارید. اگر پیام عادی می‌رسد اما callback_query نه، قبل از بازنویسی handler بررسی کنید این نوع Update در فیلتر فعال حذف نشده باشد.

کد HTTP صحیح اما رفتار غلط

endpoint باید درخواست را سریع دریافت و پاسخ مناسبی برگرداند. اگر کار سنگین مانند پردازش فایل، تماس با چند API یا اجرای کوئری طولانی را پیش از پاسخ HTTP انجام دهید، timeout و تحویل مجدد محتمل می‌شود. الگوی پایدارتر این است که payload را اعتبارسنجی، update_id را ثبت، کار را به صف داخلی بسپارید و پاسخ HTTP را سریع برگردانید. سپس worker نتیجه را پردازش کند. البته صف داخلی نیز باید مانیتور شود؛ انتقال کار به صف، مشکل ظرفیت را حل نمی‌کند و فقط محل آن را عوض می‌کند.

SSL، DNS، Reverse Proxy و Redirect

مستندات رسمی تلگرام برای Webhook گواهی SSL معتبر را لازم می‌داند و پورت‌های 443، 80، 88 و 8443 را برای Bot API عمومی ذکر می‌کند. همچنین FAQ رسمی هشدار می‌دهد redirect برای Webhook پشتیبانی نمی‌شود و نام گواهی باید با دامنه مطابقت داشته باشد. بنابراین endpoint را دقیقاً روی URL نهایی تنظیم کنید؛ مسیر HTTP که به HTTPS، دامنه بدون www که به www یا یک صفحه ورود که به مسیر دیگر منتقل می‌شود، انتخاب خوبی نیست.

• رکورد DNS دامنه را از چند resolver بررسی کنید و مطمئن شوید به IP فعلی می‌رسد.
• زنجیره کامل گواهی، تاریخ اعتبار، نام دامنه و SNI را آزمایش کنید.
• قانون‌های CDN، WAF، rate limit و فایروال را برای درخواست‌های POST بررسی کنید.
• در Reverse Proxy مطمئن شوید مسیر، Host header و بدنه JSON بدون تغییر ناخواسته به برنامه می‌رسد.
• صفحه 200 عمومی کافی نیست؛ همان مسیر و همان متد POST را با بدنه مشابه آزمایش کنید.

اعتبارسنجی درخواست با secret_token

setWebhook می‌تواند secret_token دریافت کند و تلگرام آن را در هدر X-Telegram-Bot-Api-Secret-Token بفرستد. برنامه باید مقدار هدر را با راز ذخیره‌شده مقایسه کند و در صورت عدم تطابق درخواست را رد کند. این کنترل جای TLS یا نگهداری امن توکن Bot را نمی‌گیرد، اما کمک می‌کند endpoint عمومی هر POST دلخواه را به‌عنوان Update معتبر نپذیرد. راز را در کد hard-code نکنید و آن را در لاگ چاپ نکنید.

معنای چند نشانه متداول Webhook

نشانه	برداشت محتمل	بررسی بعدی
URL خالی	Webhook فعال نیست	اگر Polling انتظار می‌رود، پردازه آن را بررسی کنید
صف رو به رشد و last_error	تحویل به endpoint ناموفق است	پیام خطا، TLS، DNS و کد HTTP
صف رو به رشد بدون خطای روشن	endpoint کند یا پردازش عقب است	زمان پاسخ و ظرفیت worker/queue
پیام می‌رسد اما نوع خاص نه	allowed_updates یا handler محدود است	تنظیم فیلتر و لاگ payload
تحویل تکراری	تأیید دیر یا پردازش غیریک‌باره	idempotency بر مبنای update_id

برای جلوگیری از اثر دوباره، update_id را کلید یکتایی رخداد در نظر بگیرید. اگر پرداخت، صدور سفارش یا ارسال اعلان انجام می‌دهید، صرفاً فرض نکنید هر Update یک‌بار دیده می‌شود. نتیجه پردازش را با update_id یا کلید کسب‌وکاری مناسب ثبت کنید تا retry شبکه باعث عملیات تکراری نشود.

عیب‌یابی getUpdates، Long Polling و خطای 409 تلگرام

در Long Polling، پردازه باید مداوم زنده بماند، timeout منطقی داشته باشد و offset را درست پیش ببرد. مستندات رسمی توضیح می‌دهد getUpdates در صورت وجود Webhook کار نمی‌کند. FAQ تلگرام نیز می‌گوید برای تأیید Update باید offset را برابر آخرین update_id پردازش‌شده به‌علاوه یک قرار دهید؛ در غیر این صورت همان Updateهای تأییدنشده دوباره برمی‌گردند. بنابراین تکرار پیام همیشه مشکل تلگرام نیست و اغلب نتیجه مدیریت ناقص offset یا شکست پردازش پیش از ثبت وضعیت است.

GET https://api.telegram.org/bot<BOT_TOKEN>/getUpdates?timeout=30&offset=<LAST_UPDATE_ID_PLUS_ONE>

خطای 409 را چگونه تحلیل کنیم؟

در عمل، خطای Conflict هنگام Polling معمولاً یعنی بیش از یک مصرف‌کننده برای getUpdates فعال است یا Webhook هنوز مالک دریافت Update است. به‌جای افزودن retry سریع، فهرست پردازه‌ها، سرویس‌های systemd، supervisor، cron، container replica، نشست‌های ترمینال و نسخه قدیمی روی هاست قبلی را بررسی کنید. دو نسخه‌ای که هرکدام تصور می‌کنند تنها Poller هستند، ممکن است یکدیگر را مرتب قطع کنند و با restart خودکار، چرخه خطا را پایدار نگه دارند.

اصل Single Owner برای Polling

برای هر Bot Token دقیقاً یک Poller فعال تعریف کنید. اگر مقیاس افقی لازم است، دریافت Update را به یک جزء واحد بسپارید و پس از آن کارها را در صف داخلی بین workerها توزیع کنید. افزودن replica مستقیم به Poller بدون طراحی هماهنگی، ظرفیت را افزایش نمی‌دهد. یک قفل توزیع‌شده می‌تواند از اجرای هم‌زمان جلوگیری کند، اما قفل باید lease، تمدید و بازیابی پس از crash داشته باشد؛ در پروژه کوچک، مدیریت یک سرویس واحد ساده‌تر و قابل اعتمادتر است.

Restart loop و خطاهای پنهان startup

ممکن است supervisor وضعیت «running» نشان دهد، اما پردازه هر چند ثانیه خارج و دوباره اجرا شود. uptime پردازه، تعداد restart، exit code و نخستین exception بعد از startup را ببینید. خطاهای import، متغیر محیطی گمشده، دسترسی فایل، نسخه ناسازگار runtime یا اتصال دیتابیس می‌توانند پیش از آغاز polling برنامه را متوقف کنند. لاگ انتهایی همیشه کافی نیست؛ نخستین خطای هر چرخه معمولاً علت و خطاهای بعدی پیامدند.

استراتژی امن برای offset

offset را زمانی جلو ببرید که تصمیم روشنی درباره Update گرفته‌اید. اگر ابتدا offset را تأیید و سپس پردازش کنید، crash میان این دو مرحله ممکن است پیام را از دسترس برنامه خارج کند. اگر پس از پردازش تأیید کنید، crash می‌تواند پردازش دوباره بسازد. راه‌حل عملی، idempotency و ثبت وضعیت است: update_id را دریافت کنید، اگر قبلاً کامل شده از آن عبور کنید، عملیات را انجام دهید، نتیجه را ثبت کنید و سپس offset را جلو ببرید. برای عملیات حساس از تراکنش یا outbox متناسب با معماری استفاده کنید.

چرا Polling زنده است اما پاسخ دیر می‌رسد؟

timeout بلند در Long Polling به‌خودی‌خود تأخیر پاسخ ایجاد نمی‌کند؛ وقتی Update برسد، درخواست می‌تواند زودتر برگردد. تأخیر معمولاً از handler مسدودکننده، صف تک‌نخی، تماس خارجی کند، محدودیت اتصال دیتابیس، retry بدون backoff یا اجرای کار CPU-heavy در همان event loop می‌آید. زمان را در چند نقطه ثبت کنید: دریافت از API، شروع handler، پایان وابستگی خارجی، ارسال پاسخ و دریافت پاسخ Bot API. اختلاف این timestampها گلوگاه را نشان می‌دهد.

Pending Updates چیست و چرا بالا می‌رود؟

pending_update_count در getWebhookInfo تعداد Updateهایی را نشان می‌دهد که منتظر تحویل‌اند. عدد بالا علت نیست؛ یک شاخص است. endpoint ممکن است در دسترس نباشد، پاسخ ناموفق بدهد، کند باشد یا ظرفیت کافی برای تخلیه صف نداشته باشد. همچنین پس از یک قطعی، حتی با رفع اتصال، مدتی طول می‌کشد تا backlog پردازش شود. مهم‌تر از یک عدد منفرد، روند است: صف ثابت، کاهشی یا افزایشی؟ سرعت ورود از سرعت پردازش بیشتر است یا worker اصلاً جلو نمی‌رود؟

تلگرام Updateهای ورودی را تا زمانی که دریافت شوند نگه می‌دارد، اما طبق Bot API بیش از 24 ساعت نگهداری نمی‌کند. پس خرابی طولانی می‌تواند به از دست رفتن Updateهای قدیمی منجر شود. این محدودیت دلیل دیگری است که صرفاً به وجود صف تلگرام به‌عنوان بکاپ تکیه نکنید. رخدادهای مهم کسب‌وکار باید در سامانه خودتان با سازوکار قابل بازیابی ثبت شوند.

سه نرخ برای تحلیل صف

• نرخ ورود: در هر دقیقه چند Update جدید ایجاد می‌شود؟
• نرخ پردازش: در هر دقیقه چند Update با موفقیت کامل می‌شود؟
• سن قدیمی‌ترین پیام: قدیمی‌ترین Update پردازش‌نشده چند دقیقه یا ساعت عمر دارد؟

اگر نرخ پردازش از ورود بیشتر باشد، صف باید به‌تدریج خالی شود. اگر کمتر است، حتی پس از رفع اتصال backlog رشد خواهد کرد. افزایش worker فقط زمانی مفید است که معماری اجازه هم‌زمانی بدهد و گلوگاه مشترک، مانند دیتابیس یا API ثالث، اشباع نشده باشد. در غیر این صورت worker بیشتر ممکن است timeout و retry بیشتری بسازد.

چه زمانی drop_pending_updates خطرناک است؟

گزینه drop_pending_updates در setWebhook و deleteWebhook همه Updateهای منتظر را کنار می‌گذارد. این دکمه پاک‌سازی عمومی نیست. پیش از استفاده باید اثر کسب‌وکاری را بدانید: آیا فرمان کاربر، درخواست پشتیبانی، ثبت سفارش یا تأیید پرداخت در صف است؟ اگر حذف اجتناب‌ناپذیر شد، زمان رخداد، دلیل، بازه احتمالی داده ازدست‌رفته و برنامه جبران را ثبت کنید. در بسیاری از موارد بهتر است علت را رفع و صف را با کنترل نرخ تخلیه کنید.

تخلیه کنترل‌شده بعد از قطعی

پس از بازگشت سرویس، ابتدا concurrency را محافظه‌کارانه بالا ببرید، timeout وابستگی‌ها را محدود کنید و retry را با backoff و jitter تنظیم کنید. پردازش‌های حساس را idempotent نگه دارید. داشبورد باید هم‌زمان طول صف، نرخ خطا، latency و فشار دیتابیس را نشان دهد. اگر صف کم می‌شود اما خطا و زمان پاسخ به‌شدت بالا می‌رود، سرعت تخلیه بیش از ظرفیت واقعی است.

وقتی Update می‌رسد اما ربات پاسخ نمی‌دهد

رسیدن Update به لاگ ثابت می‌کند مسیر دریافت تا برنامه کار می‌کند، اما هنوز چند مرحله باقی است: انتخاب handler، اعتبارسنجی داده، دسترسی به دیتابیس یا API ثالث، ساخت پاسخ و فراخوانی Bot API. برای هر Update یک correlation id بسازید یا همان update_id را در همه لاگ‌های همان مسیر تکرار کنید. بدون این پیوند، میان صدها خط هم‌زمان نمی‌توان تشخیص داد کدام خطا متعلق به کدام پیام است.

لاگ مفید چه اطلاعاتی دارد؟

فیلد	کاربرد	نکته امنیتی
timestamp و timezone	ساخت timeline رخداد	زمان سرور و برنامه هماهنگ باشد
update_id و نوع Update	ردیابی و تشخیص تکرار	متن کامل پیام همیشه لازم نیست
handler و مدت اجرا	یافتن مسیر کند	نام داخلی امن است
dependency و status	تشخیص دیتابیس یا API کند	کلید و token را حذف کنید
exception و stack	یافتن محل شکست	داده شخصی را redact کنید
outbound result	تأیید ارسال پاسخ	بدنه حساس را ذخیره نکنید

لاگ باید قابل جست‌وجو و دارای retention متناسب باشد. چاپ کل payload می‌تواند اطلاعات کاربر، شماره تماس، فایل یا محتوای خصوصی را وارد سامانه لاگ کند. به‌جای آن نوع Update، شناسه‌های لازم، اندازه payload و فیلدهای تشخیصی را ثبت کنید. برای debug موقت، سطح لاگ را با زمان انقضا بالا ببرید تا حالت پرجزئیات دائمی نشود.

آزمون مستقل ارسال پاسخ

اگر handler اجرا می‌شود اما خروجی دیده نمی‌شود، یک sendMessage ساده را با همان محیط و توکن اجرا کنید. پاسخ HTTP، بدنه JSON و پارامترهای chat_id را بررسی کنید. موفقیت این آزمون یعنی اتصال خروجی و توکن اصولاً کار می‌کند و باید منطق تولید پاسخ، مجوز ربات در گفت‌وگو، قالب پیام یا نوع chat را بررسی کرد. شکست آزمون مستقل، دامنه را به شبکه خروجی، DNS، توکن، پارامترها یا پاسخ Bot API محدود می‌کند.

نکات Python، Node.js و Laravel بدون تکرار آموزش نصب

در Python بررسی کنید event loop با عملیات هم‌زمان‌نشده مسدود نشده باشد و محیط مجازی همان dependencyهای نسخه مستقر را داشته باشد. در Node.js به unhandled rejection، مصرف حافظه، بسته‌شدن process و کار CPU-heavy در حلقه رویداد توجه کنید. در Laravel یا PHP، مسیر Webhook باید از middleware نامرتبط، CSRF و redirect ناخواسته عبور نکند و queue worker واقعاً در حال اجرا باشد. این‌ها نقطه شروع‌اند؛ رفتار دقیق به کتابخانه و نسخه پروژه بستگی دارد و باید با مستندات همان dependency تطبیق داده شود.

چرا بعد از انتقال هاست ربات خاموش می‌شود؟

• متغیرهای محیطی، token، database URL یا timezone به محیط جدید منتقل نشده‌اند.
• Webhook هنوز به دامنه یا مسیر قدیمی اشاره می‌کند.
• نسخه runtime یا dependency با lockfile پروژه هماهنگ نیست.
• مجوز فایل، مسیر کاری یا محل لاگ تغییر کرده است.
• worker یا scheduler در محیط جدید به‌صورت پایدار اجرا نشده است.
• DNS یا گواهی هنوز برای دامنه جدید آماده نیست.

برای انتقال، smoke test تعریف کنید: getMe، وضعیت Webhook، اتصال دیتابیس، دریافت یک Update، ارسال یک پاسخ و restart کنترل‌شده. پس از موفقیت، محیط قدیمی را خاموش و بررسی کنید Poller دوم باقی نمانده باشد. نگه‌داشتن هر دو محیط با یک token بدون طرح مشخص، یکی از علت‌های رایج Conflict است.

Health check و مانیتورینگ ربات تلگرام

یک endpoint که همیشه «OK» می‌گوید مانیتورینگ نیست. health check را به دو سطح تقسیم کنید: liveness می‌پرسد پردازه زنده است و event loop یا worker قفل نشده؟ readiness می‌پرسد سرویس اکنون توان پردازش دارد؛ مثلاً اتصال دیتابیس برقرار است، صف داخلی از آستانه عبور نکرده و dependency حیاتی پاسخ می‌دهد. اگر این دو را مخلوط کنید، اختلال کوتاه دیتابیس ممکن است باعث restart بی‌پایان برنامه و بدترشدن رخداد شود.

شاخص‌هایی که واقعاً هشدار می‌سازند

• زمان آخرین Update دریافتی و آخرین Update پردازش‌شده، با توجه به ساعات طبیعی فعالیت ربات
• فاصله update_id دریافتی و کامل‌شده یا طول صف داخلی
• pending_update_count و last_error برای Webhook
• تعداد restart، uptime پردازه و exit code اخیر
• نرخ خطا و صدک‌های زمان پردازش handler
• نرخ موفقیت و latency درخواست‌های خروجی Bot API
• اعتبار گواهی، خطای DNS و دسترسی endpoint از بیرون
• CPU، حافظه، I/O و اتصال دیتابیس در کنار شاخص‌های برنامه

آستانه‌ها را از الگوی واقعی بسازید. هشدار «پنج دقیقه بدون Update» برای ربات کم‌ترافیک کاذب است، اما برای سامانه‌ای که هر ثانیه پیام می‌گیرد دیر محسوب می‌شود. بهتر است heartbeat مصنوعی یا آزمون end-to-end دوره‌ای داشته باشید که یک مسیر کنترل‌شده را اجرا کند، بدون آنکه پیام مزاحم برای کاربر واقعی بسازد.

هر هشدار باید Runbook داشته باشد

پیام هشدار باید سرویس، محیط، زمان شروع، شاخص عبورکرده از آستانه و لینک داشبورد یا لاگ را نشان دهد. Runbook کوتاه کنار آن بنویسید: نخست getWebhookInfo، سپس وضعیت پردازه، بعد لاگ correlation و در پایان dependencyها. اگر هر بار رخداد از حافظه افراد حل شود، زمان بازیابی طولانی و نتیجه وابسته به فرد خواهد بود.

پس از رفع مشکل چه چیزی ثبت کنیم؟

علت ریشه‌ای را با «پردازه متوقف شد» تمام نکنید. بپرسید چرا متوقف شد، چرا خودکار برنگشت، چرا هشدار دیر رسید و چرا کاربر زودتر از تیم متوجه شد. اقدام اصلاحی می‌تواند test قبل از استقرار، محدودیت replica، اصلاح timeout، چرخش secret، مانیتور صف یا بهبود مستندات باشد. برای هر اقدام مالک و موعد تعیین کنید.

سناریوهای کاربردی عیب‌یابی

سناریو ۱: بعد از انتشار نسخه جدید هیچ پیامی نمی‌رسد

ابتدا تغییرات انتشار را با زمان اولین خطا تطبیق دهید. اگر Webhook دارید، getWebhookInfo را بخوانید و status code endpoint را در access log پیدا کنید. خطای 404 به مسیر، 401 یا 403 به middleware یا WAF و 5xx به برنامه یا dependency اشاره می‌کند. نسخه قبلی را فقط وقتی بازگردانید که معیار بازگشت مشخص است؛ هم‌زمان شواهد نسخه معیوب را نگه دارید. اگر Polling دارید، startup log و dependencyهای جدید را بررسی کنید و مطمئن شوید process پس از deploy دو بار اجرا نشده است.

سناریو ۲: پیام‌ها چندبار پردازش می‌شوند

در Polling، offset و update_id را بررسی کنید. در Webhook، زمان پاسخ endpoint و retry را ببینید. سپس idempotency کسب‌وکاری را آزمایش کنید: آیا ثبت سفارش یا ارسال اعلان بر پایه update_id یکتا است؟ صرفاً حذف پیام تکراری در UI کافی نیست؛ عملیات جانبی نیز نباید دوباره انجام شود. یک replay کنترل‌شده در محیط آزمایشی کمک می‌کند رفتار crash میان پردازش و ثبت وضعیت را ببینید.

سناریو ۳: ربات در ساعات شلوغ کند می‌شود

زمان‌بندی مرحله‌ای ثبت کنید تا معلوم شود صف قبل از handler، داخل برنامه، دیتابیس یا API ثالث تشکیل می‌شود. افزایش منابع میزبانی وقتی مفید است که محدودیت CPU، حافظه یا I/O با شواهد هم‌زمان باشد. اگر dependency بیرونی گلوگاه است، worker بیشتر فقط درخواست بیشتری به همان گلوگاه می‌فرستد. cache، batch، محدودکردن concurrency و پاسخ اولیه سریع ممکن است از ارتقای کورکورانه مؤثرتر باشد.

سناریو ۴: فقط دکمه‌ها یا Callback Query کار نمی‌کنند

allowed_updates و ثبت handler مربوط را کنترل کنید. سپس callback_query.id را در لاگ و پاسخ answerCallbackQuery را بررسی کنید. ممکن است پیام متنی سالم باشد، اما فیلتر یا middleware نوع Callback را حذف کند. این سناریو نشان می‌دهد برچسب کلی «ربات جواب نمی‌دهد» چقدر گمراه‌کننده است؛ نوع Update باید بخشی از هر log و هر alert باشد.

چک‌لیست خرید هاست برای ربات تلگرام

عیب‌یابی خوب جای زیرساخت مناسب را نمی‌گیرد. هنگام انتخاب سرویس، ابتدا مدل اجرای ربات را بنویسید: Webhook دارید یا Polling؟ زبان و نسخه runtime چیست؟ پردازه باید دائمی باشد؟ queue worker یا cron دارید؟ endpoint عمومی و SSL لازم است؟ چه حجمی از لاگ نگه می‌دارید؟ سپس امکانات همان پلن را از صفحه رسمی و پشتیبانی تأیید کنید؛ از نام محصول به‌تنهایی نتیجه نگیرید.

نیاز	چرا مهم است	پرسش پیش از خرید
دسترسی ترمینال	نصب dependency، اجرای آزمون و خواندن لاگ	نوع دسترسی و محدودیت‌های آن چیست؟
اجرای پایدار پردازه	Polling و worker باید پس از خروج برگردند	روش مدیریت process و restart چیست؟
دامنه/ساب‌دامین و SSL	Webhook به endpoint HTTPS نیاز دارد	صدور و تمدید گواهی چگونه انجام می‌شود؟
Runtime سازگار	نسخه زبان و کتابخانه باید هماهنگ باشد	نسخه‌های فعلی Python، Node.js یا PHP چیست؟
لاگ و مانیتورینگ	بدون شاهد، تشخیص کند می‌شود	دسترسی به error/access log و retention چگونه است؟
منابع و محدودیت‌ها	بار هم‌زمان می‌تواند صف بسازد	CPU، RAM، I/O و process limit چگونه نمایش داده می‌شود؟
پشتیبانی	تفکیک مشکل برنامه از میزبانی زمان می‌برد	دامنه مسئولیت پشتیبانی دقیقاً چیست؟

صفحه فعلی هاست ربات تلگرام وطن هاست دسترسی ترمینال و پشتیبانی از Python، Node.js و Laravel را معرفی می‌کند. قبل از خرید، نسخه runtime، روش اجرای دائمی پروژه و نیازهای خاص کتابخانه خود را با اطلاعات روز همان صفحه و تیم فروش تطبیق دهید. اگر پروژه فقط یک سایت PHP یا وردپرسی است و worker دائمی نمی‌خواهد، ممکن است هاست لینوکس متناسب‌تر باشد؛ تصمیم باید از مدل اجرا بیاید، نه صرفاً نام سرویس.

چه زمانی هاست ربات و چه زمانی سرور مجازی؟

هاست تخصصی برای کاربری که محیط مدیریت‌شده‌تر، کنترل‌پنل و مسیر ساده‌تر می‌خواهد جذاب است. سرور مجازی کنترل بیشتری روی سیستم‌عامل، process manager، شبکه و سرویس‌های جانبی می‌دهد، اما مسئولیت امنیت، به‌روزرسانی، بکاپ و مانیتورینگ نیز بیشتر می‌شود. برای مقایسه جزئی‌تر، مقاله هاست ربات تلگرام بهتر است یا سرور مجازی را ببینید. این انتخاب نسخه واحد ندارد؛ پیچیدگی، ترافیک، نیاز به root و توان عملیاتی تیم مهم‌اند.

چک‌لیست نهایی پیش از سفارش

• روش دریافت Update و نیاز به endpoint عمومی را مشخص کرده‌ام.
• نسخه زبان، کتابخانه، dependencyهای سیستمی و دیتابیس را فهرست کرده‌ام.
• روش اجرای دائمی Poller یا queue worker را از ارائه‌دهنده پرسیده‌ام.
• مسیر SSL، دامنه، DNS و تمدید گواهی برای Webhook روشن است.
• به لاگ و شاخص‌های لازم برای عیب‌یابی دسترسی دارم.
• محدودیت منابع، پردازه، اتصال و فضای ذخیره‌سازی را با بار واقعی سنجیده‌ام.
• بکاپ، بازیابی، استقرار نسخه جدید و rollback را طراحی کرده‌ام.
• قیمت و مشخصات جاری را فقط از صفحه محصول و پیش‌فاکتور روز تأیید کرده‌ام.

اشتباه‌های رایج که زمان رفع خرابی را طولانی می‌کنند

یکی از رایج‌ترین اشتباه‌ها، تغییر هم‌زمان چند مؤلفه است: توکن عوض می‌شود، Webhook دوباره ثبت می‌شود، برنامه restart می‌شود و نسخه کتابخانه نیز ارتقا می‌یابد. حتی اگر ربات برگردد، تیم نمی‌داند کدام تغییر مؤثر بوده و دفعه بعد همان رخداد تکرار می‌شود. در عیب‌یابی حرفه‌ای، برای هر فرضیه یک آزمون کم‌خطر تعریف کنید، فقط یک متغیر را تغییر دهید و نتیجه را با زمان دقیق بنویسید. اگر تغییر برگشت‌پذیر است، روش rollback را پیش از اجرا آماده کنید.

اشتباه دوم، تکیه بر وضعیت سبز کنترل‌پنل است. «پردازه فعال»، «دامنه در دسترس» یا «گواهی نصب‌شده» فقط بخشی از زنجیره را نشان می‌دهد. پردازه ممکن است در restart loop باشد، صفحه اصلی دامنه 200 بدهد اما مسیر Webhook 403 باشد، یا گواهی برای دامنه دیگری صادر شده باشد. آزمون باید تا سطح رفتار مورد انتظار پیش برود: یک Update کنترل‌شده وارد شود، handler مناسب اجرا شود، عملیات جانبی کامل شود و پاسخ Bot API موفق برگردد.

اشتباه سوم، حذف شواهد برای بازگرداندن سریع سرویس است. پاک‌کردن لاگ، حذف صف، نصب مجدد محیط یا بازنویسی Webhook می‌تواند آخرین نشانه‌های علت را از بین ببرد. پیش از اقدام، خروجی getWebhookInfo، وضعیت پردازه، نسخه برنامه، commit مستقر، dependencyها، چند دقیقه لاگ و شاخص‌های منابع را ذخیره کنید. این snapshot کوچک هم برای تشخیص فعلی مفید است و هم برای postmortem. اطلاعات حساس، به‌ویژه token و داده شخصی کاربران، باید هنگام ذخیره و اشتراک‌گذاری حذف یا پوشانده شود.

برای دریافت کمک فنی چه اطلاعاتی در تیکت بنویسیم؟

تیکت مؤثر باید مسئله را قابل بازتولید کند، نه اینکه فقط بگوید «ربات قطع است». زمان شروع با timezone، روش دریافت Update، زبان و نسخه runtime، آخرین تغییر، متن دقیق خطا بدون secret، نتیجه getWebhookInfo با توکن حذف‌شده، وضعیت پردازه و اینکه ورودی یا خروجی کدام‌یک شکست می‌خورد را بنویسید. اگر نمونه Update لازم است، داده شخصی را ناشناس کنید. همچنین توضیح دهید چه آزمون‌هایی انجام شده و نتیجه هرکدام چه بوده است؛ این کار از تکرار مراحل و پاسخ‌های حدسی جلوگیری می‌کند.

اطلاعات تیکت	نمونه مفید	موردی که نباید ارسال شود
زمان رخداد	از ۱۲:۲۰ تهران، پس از deploy نسخه مشخص	عبارت مبهم «از دیروز»
روش دریافت	Webhook با URL و مسیر پوشانده‌شده یا Polling	گفتن صرف «API کار نمی‌کند»
شاهد	last_error، status code، exit code، update_id	اسکرین‌شات ناخوانا بدون زمان
محیط	نسخه Python/Node/PHP و نام کتابخانه	ارسال token، رمز یا فایل env
دامنه اثر	پیام متنی می‌رسد اما callback نه	عبارت کلی «هیچ‌چیز کار نمی‌کند»

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

منابع فنی رسمی

جزئیات getUpdates، setWebhook، getWebhookInfo، WebhookInfo، allowed_updates، secret_token و نگهداری Updateها در مستندات رسمی Telegram Bot API آمده است. برای offset در Long Polling و نکات گواهی Webhook نیز FAQ رسمی ربات‌های تلگرام و راهنمای رسمی Webhook مرجع مناسب‌اند. هنگام کار، نسخه فعلی کتابخانه برنامه‌نویسی خود را نیز جداگانه بررسی کنید؛ نام متدها و رفتار wrapperها ممکن است میان نسخه‌ها فرق کند.

جمع‌بندی: ربات خاموش را با شواهد برگردانید

وقتی ربات تلگرام جواب نمی‌دهد، مسئله را به یک زنجیره قابل اندازه‌گیری تبدیل کنید: اعتبار توکن، مالک واحد دریافت Update، سلامت Webhook یا Poller، وضعیت صف، اجرای handler، وابستگی‌ها و ارسال پاسخ. با getWebhookInfo، update_id، لاگ ساختاریافته و health check می‌توان بیشتر حدس‌ها را به آزمون تبدیل کرد. drop_pending_updates، restart و افزایش منابع ابزارند، نه تشخیص؛ هرکدام فقط پس از شناخت علت استفاده شوند.

اگر زیرساخت فعلی امکان اجرای پایدار پردازه، دسترسی به لاگ، ترمینال و endpoint امن را نمی‌دهد، مشخصات روز سرویس هاست ربات تلگرام را بررسی کنید و نیازهای پروژه را پیش از خرید با پلن تطبیق دهید. برای دریافت پیشنهاد دقیق، روش دریافت Update، زبان، نسخه runtime، نوع دیتابیس و الگوی تقریبی بار را آماده کنید؛ این اطلاعات انتخاب را بسیار دقیق‌تر از عبارت کلی «یک هاست قوی می‌خواهم» می‌کند.

سؤالات متداول درباره جواب ندادن ربات تلگرام