Webhook یا Long Polling؟ بهترین روش اتصال ربات تلگرام

یک ربات تلگرام را با getUpdates روی لپ‌تاپ اجرا می‌کنید؛ پیام‌ها درست می‌رسند. همان ربات را روی سرور دارای HTTPS منتقل می‌کنید و تصمیم می‌گیرید Webhook فعال کنید. آیا حتماً سرعت بیشتر می‌شود؟ آیا روش جدید در قطع ارتباط خارجی پایدارتر است؟ برای انتخاب میان Webhook یا Long Polling، پاسخ را باید از جهت ارتباط، مدل پردازش، رفتار هنگام خطا و معماری زیرساخت گرفت؛ نه از این تصور که یکی همیشه «حرفه‌ای‌تر» است.

این مطلب یک راهنمای تصمیم معماری اتصال ربات تلگرام است. جدول ویژگی‌ها، محاسبه تقریبی هزینه شبکه، تأثیر قطعی و تست عملی هر دو روش را بررسی می‌کنیم. اگر به نمونه‌کد کنترلر Laravel، Secret، ذخیره Update و صف نیاز دارید، آموزش ساخت ربات تلگرام با Laravel مسیر اجرای آن را پوشش می‌دهد؛ این مقاله قرار نیست نسخه دوم همان آموزش باشد.

تفاوت Webhook و Long Polling در یک جمله چیست؟

در Long Polling برنامه شما به Telegram Bot API وصل می‌شود و با getUpdates برای رویداد جدید منتظر می‌ماند. در Webhook خود تلگرام با رسیدن Update به HTTPS مقصد شما درخواست می‌فرستد. تفاوت بنیادی، جهت آغاز ارتباط و مسئولیت نگهداری آن است؛ هر دو روش در نهایت Updateهای Bot API را دریافت می‌کنند و هر دو باید برای تحویل تکراری یا شکست پردازش آماده باشند.

جدول مقایسه Webhook و Long Polling برای ربات تلگرام

معیار	Webhook	Long Polling
جهت ارتباط	Telegram به URL شما POST می‌زند	Worker شما از Telegram رویداد می‌گیرد
نیاز به HTTPS عمومی	بله، مقصد معتبر و قابل دسترس می‌خواهد	خیر، ارتباط خروجی کفایت می‌کند
نیاز به Worker دریافت‌کننده	وب‌سرور برای دریافت و Queue برای کار سنگین	فرایند Polling پیوسته و مدیریت Offset
وابستگی به ورودی دیتاسنتر	بالا؛ مسیر تلگرام تا HTTPS شما باید کار کند	ندارد؛ اما ارتباط خروجی به API ضروری است
رفتار هنگام شکست	تحویل مجدد احتمالی پس از پاسخ ناموفق	بازیابی از Offset و صف ذخیره‌شده
پیکربندی توسعه محلی	نیاز به URL عمومی یا محیط آزمایشی	معمولاً راه‌اندازی ساده‌تر
مقیاس‌پذیری	چند Worker پردازش پشت یک Webhook	مالکیت Offset و جلوگیری از Poller هم‌زمان
امنیت ورودی	TLS، Secret Header، محدودیت درخواست	نگهداری Token و امنیت فرایند خروجی

هیچ ردیفی به‌تنهایی برنده را تعیین نمی‌کند. مثلاً داشتن URL عمومی سالم الزاماً به معنای اتصال خروجی قابل‌اعتماد برای ارسال پیام نیست. همچنین Polling با فرایند مدیریت‌نشده ممکن است پس از Restart پیام‌ها را دیر دریافت یا تکراری پردازش کند.

Webhook دقیقاً چگونه Update را تحویل می‌دهد؟

پس از ثبت آدرس با متد setWebhook، تلگرام رویداد را به URL HTTPS مقصد ارسال می‌کند. سرور باید درخواست را با کنترل لازم بپذیرد و پاسخ HTTP مناسب بدهد. اگر قبل از ثبت پایدار رویداد، 200 برگردانید و سپس Worker از کار بیفتد، ممکن است برنامه شما منطق پیام را اجرا نکرده باشد؛ پاسخ موفق به Telegram برابر با پاسخ نهایی ربات به کاربر نیست.

Secret Header چه کمکی می‌کند و چه چیزی را تضمین نمی‌کند؟

پارامتر secret_token در setWebhook باعث می‌شود مقدار تعیین‌شده در Header با نام X-Telegram-Bot-Api-Secret-Token ارسال شود. مقصد با مقایسه امن می‌تواند درخواست‌های بدون Secret را رد کند. این روش امضای HMAC بدنه نیست و نباید جای TLS، مدیریت Secret یا کنترل Replay را بگیرد. برای جزئیات رفتار و پارامترهای پشتیبانی‌شده، مستندات رسمی setWebhook تلگرام مرجع اصلی است.

Long Polling چگونه کار می‌کند و Offset چه نقشی دارد؟

در Polling، کلاینت getUpdates را با timeout و در صورت نیاز offset می‌خواند. با ورود Update، آن را دریافت می‌کند؛ برای تأیید عبور از رویداد، Offset در درخواست بعدی جلو برده می‌شود. طبق قرارداد Bot API، وقتی getUpdates با Offset بالاتر از شناسه Update فراخوانی شود، Updateهای قبل از آن تأییدشده محسوب می‌شوند. بنابراین زمان پیشروی Offset به اندازه ثبت پایدار رویداد اهمیت دارد.

اگر Offset را زودتر از ذخیره Update جلو ببریم چه می‌شود؟

فرض کنید Update شماره ۲۰۵ آمده است؛ برنامه قبل از ثبت آن در دیتابیس، Offset را روی ۲۰۶ قرار می‌دهد و سپس قطع می‌شود. درخواست بعدی ممکن است دیگر آن Update را تحویل نگیرد. الگوی امن‌تر این است که Update ابتدا با شناسه یکتا پایدار ثبت شود، سپس Offset بالاتر درخواست شود. اگر ثبت موفق اما پردازش شکست خورد، کار در صف مستقل بازیابی می‌شود.

یک Poller اصلی برای هر Bot داشته باشید یا مالکیت Offset را به‌صورت هماهنگ مدیریت کنید. چند فرایند بدون هماهنگی که هم‌زمان getUpdates می‌زنند، می‌توانند با تداخل و خطا روبه‌رو شوند؛ افزودن Workerهای پردازش بهتر از افزودن Pollerهای بی‌هماهنگ است.

نمونه واقعی: بات سازمانی بدون IP ورودی عمومی

یک برنامه در شبکه داخلی سازمان قرار دارد و مجوز بازکردن درگاه ورودی HTTPS ندارد، اما دسترسی خروجی مجاز به Bot API دارد. در چنین معماری، Long Polling می‌تواند ساده‌تر باشد، چون Telegram نیازی به آغاز اتصال به داخل شبکه ندارد. فرایند باید تحت Supervisor یا systemd اجرا شود و امکان بازیابی وضعیت پس از Restart داشته باشد.

برعکس، اگر یک Endpoint عمومی، TLS معتبر و زیرساخت Queue دارید، Webhook می‌تواند تحویل رویداد را با معماری HTTP موجود هماهنگ کند. این مزیت برای پروژه‌ای که درون‌سازمانی است، ممکن است اصلاً کاربرد نداشته باشد.

تأخیر پیام کدام روش کمتر است؟

نمی‌توان بدون اندازه‌گیری گفت Webhook همیشه سریع‌تر است. در Long Polling، درخواست می‌تواند برای رویداد جدید باز بماند؛ بنابراین لزوماً منتظر چرخه ثابت چندثانیه‌ای نیست. در Webhook نیز تأخیر به زمان تحویل شبکه، سرعت پاسخ HTTP و Queue وابسته است. معیار عملی p95 زمان دریافت Update تا ثبت و پاسخ نهایی است، نه فقط تعداد درخواست‌های HTTP.

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

امنیت Webhook و Polling چه تفاوتی دارد؟

Webhook یک سطح ورودی عمومی ایجاد می‌کند؛ بنابراین اعتبارسنجی Secret، TLS، محدودیت نرخ درخواست و کنترل اندازه Payload ضروری‌اند. در Polling مسیر ورودی عمومی لازم نیست، ولی یک فرایند بلندمدت با Bot Token کار می‌کند؛ اگر Token در Log، آرگومان فرایند یا محیط مشترک افشا شود، کنترل ربات به خطر می‌افتد. در هر دو روش، Token نباید سمت مرورگر باشد و دسترسی Worker باید محدود بماند.

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

اختلال سرور ایرانی: جهت اتصال تصمیم را تغییر می‌دهد

در بعضی شبکه‌های داخل ایران، دسترسی ورودی از مسیرهای بین‌المللی با دسترسی خروجی به مقصد خارجی رفتار متفاوتی دارد. اگر تلگرام نتواند HTTPS مقصد شما را ببیند اما ارتباط خروجی سرور به Bot API برقرار باشد، Webhook مستقیم مناسب نیست و Long Polling ممکن است عملی باشد. اگر خروجی به Bot API قطع است، Polling نیز کار نمی‌کند و حتی با دریافت موفق Webhook، ارسال پاسخ می‌تواند شکست بخورد.

هر مسیر را به‌صورت مستقل آزمایش کنید: resolve شدن دامنه، برقراری TCP، اعتبار TLS، کد پاسخ HTTP و دسترسی مجاز حساب. موفقیت از لپ‌تاپ مدیر یا یک دیتاسنتر دیگر کافی نیست. برای تحلیل جزئی‌تر محدودیت‌ها، راهنمای مشکلات اتصال ربات تلگرام در سرور ایران را ببینید. هیچ روش انتخابی، محدودیت قراردادی یا شبکه‌ای را به‌طور تضمینی رفع نمی‌کند.

چهار سناریو و روش پیشنهادی برای شروع آزمایش

سناریو	روش مناسب برای آزمون	شرط تصمیم
توسعه محلی بدون آدرس HTTPS	Long Polling	یک Poller پایدار و مدیریت Offset
سرویس Laravel دارای HTTPS عمومی	Webhook	تحویل پایدار، Secret و Queue فعال
شبکه داخلی بدون ورودی عمومی	Long Polling	خروجی مجاز به Bot API و مدیریت Worker
چند ربات با پروژه‌های مصرف‌کننده مجزا	هسته تحویل مرکزی + معماری ورودی مناسب	تفکیک Bot، Retry و امضای مقصد

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

جابجایی از Long Polling به Webhook بدون از دست دادن Update

در تغییر معماری، هم‌زمان Polling و Webhook را برای دریافت معمول Update یک Bot فعال فرض نکنید. پیش از Cutover، رویدادهای ثبت‌شده و Offset آخر را کنترل کنید، پردازشگر جدید را با Bot آزمایشی بسنجید و سپس Webhook را ثبت کنید. درباره Updateهای معوق، پارامتر drop_pending_updates در Bot API وجود دارد، اما فعال‌کردن آن می‌تواند رویدادهای دریافت‌نشده را حذف کند و برای مهاجرت Production نباید بدون تصمیم روشن استفاده شود.

1. قبل از تغییر، شناسه آخرین رویداد پردازش‌شده و تعداد Pendingهای داخلی را ثبت کنید.
2. مقصد جدید را با HTTPS، Secret و پاسخ سریع در محیط آزمایش بررسی کنید.
3. Polling قدیمی را با کنترل وضعیت Stop کنید و از فعال‌نبودن Poller موازی مطمئن شوید.
4. Webhook را طبق مستندات رسمی برای همان Bot ثبت و وضعیت getWebhookInfo را بررسی کنید.
5. یک رویداد آزمایشی بفرستید؛ دریافت، ثبت، پردازش و ارسال پاسخ را جدا تأیید کنید.
6. برای بازگشت اضطراری، روش حذف Webhook و ادامه دریافت از Offset کنترل‌شده را از قبل آماده کنید.

این فرایند باید با داده و سیاست صف واقعی شما تطبیق داده شود. هدف «بدون از دست رفتن» است، اما بدون تست روی نسخه مشخص Bot API و وضعیت شبکه، تضمین صفر خطا منصفانه نیست.

نمونه دستور برای بررسی وضعیت، نه اجرای بی‌ملاحظه تغییر

با Bot Token آزمایشی می‌توان وضعیت Webhook را از getWebhookInfo دید. مثال زیر برای مستندسازی روش است و نباید با Token واقعی در Shell چندکاربره اجرا شود؛ وجود Token در آرگومان Process و تاریخچه فرمان می‌تواند خطر داشته باشد.

# Illustrative only: use a secret-aware operator tool in production.
curl -sS "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getWebhookInfo"

# Long polling is unavailable while a webhook is set.
curl -sS "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates?timeout=10"

پاسخ API ممکن است اطلاعات مربوط به خطای تحویل و زمان آن را نشان دهد. این داده را با Log خود برنامه تطبیق دهید؛ یک خطا به‌تنهایی علت قطعی را مشخص نمی‌کند. شرح رسمی پارامترهای getUpdates و getWebhookInfo باید مرجع باشد.

اگر چند ربات دارید، مسئله فقط Polling در برابر Webhook نیست

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

Avaztek Telegram چه جایگاهی در انتخاب معماری دارد؟

Avaztek Telegram طبق معرفی رسمی محصول، زیرساخت مرکزی برای دریافت و ثبت رویدادهای Webhook، تفکیک Bot و شرکت، صف تحویل، Retry و ارسال امضاشده به برنامه مقصد است. این معماری به‌ویژه وقتی چند ربات یا چند پروژه به یک مسیر تحویل قابل پیگیری نیاز دارند قابل بررسی است؛ تمرکز آن صرفاً جایگزین‌کردن دستور getUpdates نیست.

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

پرسش‌های متداول درباره Webhook و Long Polling

Webhook سریع‌تر از Long Polling است؟

لزوماً نه. Long Polling می‌تواند درخواست باز برای رویداد تازه نگه دارد و Webhook هم به شبکه و صف وابسته است. مقایسه معتبر باید زمان دریافت تا پردازش نهایی را در شرایط یکسان بسنجد.

آیا Telegram به یک ربات اجازه Webhook و getUpdates هم‌زمان می‌دهد؟

برای دریافت معمول Update از این دو روش به شکل هم‌زمان استفاده نمی‌شود. وقتی Webhook فعال است، باید پیش از Polling مناسب آن را حذف و وضعیت رویدادهای معوق را مدیریت کنید.

برای ربات روی سرور ایران کدام روش بهتر است؟

پاسخ به جهت ارتباط قابل دسترس بستگی دارد. اگر مسیر ورودی از Telegram به سرور مشکل دارد اما ارتباط خروجی مجاز برقرار است، Polling ارزش آزمایش دارد؛ در صورت اختلال خروجی هم Polling کار نمی‌کند.

چرا پیام‌های ربات بعد از Restart دوباره می‌آیند؟

ممکن است Update قبلاً دریافت اما تأیید یا به شکل پایدار ثبت نشده باشد. در Polling مدیریت Offset و در Webhook پاسخ HTTP و Idempotency باید بررسی شوند. تکرار تحویل لزوماً خطای Telegram نیست.

آیا برای Webhook باید Laravel Queue داشته باشیم؟

برای کار سنگین، صف کمک می‌کند سریع پاسخ HTTP بدهید و پردازش را جدا انجام دهید. برای کار بسیار کوتاه می‌توان بدون صف کار کرد، اما ثبت پایدار رویداد، Timeouts و بازیابی خطا همچنان باید طراحی شوند.

آیا Avaztek Telegram فقط Webhook است؟

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

جمع‌بندی: جهت اتصال و بازیابی خطا، معیار اصلی انتخاب‌اند

Webhook زمانی منطقی است که مقصد عمومی HTTPS سالم دارید و می‌خواهید دریافت رویداد با معماری وب شما هماهنگ شود. Long Polling برای محیط‌های بدون ورودی عمومی یا توسعه محلی ساده‌تر است، به شرط مدیریت Worker و Offset. در هر دو حالت، رویداد را پیش از تأیید پایدار ثبت کنید، پردازش تکراری را کنترل کنید و مسیر واقعی شبکه را آزمایش کنید. برای چند ربات یا چند پروژه، Avaztek Telegram را به‌عنوان یک معماری تحویل مرکزی بررسی کنید.