وبهوک ربات تلگرام چیست؟ راهنمای اتصال ربات به سایت و سرویس‌ها

یک مشتری در ربات تلگرام پیام می‌فرستد و انتظار دارد همان لحظه وضعیت سفارش خود را ببیند. ربات شما باید پیام را دریافت کند، از سامانه سفارش اطلاعات بگیرد و پاسخ بدهد. سؤال اصلی این است: ربات از کجا می‌فهمد پیام جدیدی رسیده است؟ یکی از راه‌ها این است که مرتب از سرور تلگرام بپرسد «خبری شده؟». راه دیگر، استفاده از وبهوک ربات تلگرام است؛ یعنی تلگرام هنگام رسیدن رویداد، آن را به آدرس مشخصی در سرور شما می‌فرستد.

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

وبهوک چیست و در ربات تلگرام چگونه کار می‌کند؟

Webhook در اصل یک آدرس اینترنتی برای دریافت اعلان رویداد است. در ربات تلگرام، شما یک نشانی HTTPS را با متد setWebhook ثبت می‌کنید. بعد از آن، وقتی به‌روزرسانی مرتبطی برای ربات وجود داشته باشد، سرور تلگرام درخواست POST حاوی داده JSON را به همان نشانی ارسال می‌کند.

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

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

تفاوت Webhook و Long Polling چیست؟

تلگرام دو روش اصلی دریافت Update دارد که برای یک ربات در حالت عادی هم‌زمان استفاده نمی‌شوند. در Long Polling برنامه با getUpdates منتظر دریافت رویدادها می‌ماند؛ این روش برای نمونه‌سازی روی لپ‌تاپ یا محیطی بدون آدرس عمومی راحت است. در Webhook تلگرام به سرور عمومی شما درخواست می‌فرستد.

هیچ‌کدام به‌تنهایی تضمین‌کننده سرعت بالاتر یا نبود قطعی نیستند. کیفیت پیاده‌سازی، شبکه و منطق مدیریت خطا نقش تعیین‌کننده دارند. انتخاب Webhook معمولاً زمانی جذاب‌تر می‌شود که از قبل یک وب‌سایت یا API قابل‌دسترسی دارید.

قبل از راه‌اندازی وبهوک چه چیزهایی لازم داریم؟

نخست با @BotFather ربات بسازید و توکن آن را دریافت کنید. این توکن کلید دسترسی به ربات است؛ نمایش آن در آموزش عمومی، ارسال در چت‌های غیرضروری یا ثبت در مخزن کد می‌تواند کنترل ربات را به خطر بیندازد.

در کنار توکن، به یک سرور یا سرویس میزبانی نیاز دارید که درخواست‌های HTTPS را دریافت کند. دامنه باید به مقصد درست اشاره کند و گواهی TLS معتبر داشته باشد. برای سرویس معمول Bot API، تلگرام پورت‌های مشخصی از جمله ۴۴۳، ۸۰، ۸۸ و ۸۴۴۳ را برای وبهوک پشتیبانی می‌کند؛ مسیر رایج و مناسب برای استفاده عمومی، HTTPS روی پورت ۴۴۳ است.

یک مسیر مستقل مانند https://bot.example.com/telegram/webhook انتخاب کنید. این نشانی صرفاً مثال است و باید با دامنه خودتان جایگزین شود. همچنین مکانیسم نگه‌داری امن اطلاعات محرمانه و ثبت گزارش خطا بدون افشای توکن را آماده کنید.

ثبت وبهوک با setWebhook؛ قدم‌به‌قدم

فرض می‌کنیم متغیرهای محیطی BOT_TOKEN و WEBHOOK_SECRET را در محیط اجرای خود به‌صورت امن تعریف کرده‌اید. سپس می‌توان وبهوک را با درخواست POST ثبت کرد:

curl -X POST "https://api.telegram.org/bot${BOT_TOKEN}/setWebhook" \  --data-urlencode "url=https://bot.example.com/telegram/webhook" \  --data-urlencode "secret_token=${WEBHOOK_SECRET}"

تلگرام نتیجه را در یک پاسخ JSON اعلام می‌کند. اگر ok برابر true باشد، فراخوانی موفق بوده است. البته موفق بودن ثبت وبهوک به‌تنهایی تضمین نمی‌کند که Endpoint شما درخواست‌های بعدی را بدون مشکل پردازش خواهد کرد.

برای بررسی وضعیت فعلی از getWebhookInfo استفاده کنید:

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

در خروجی به url، تعداد pending_update_count و در صورت وجود، last_error_message توجه کنید. افزایش صف انتظار یا خطاهای تکراری می‌تواند نشان دهد گواهی، مسیر، فایروال یا پاسخ‌گویی برنامه مشکل دارد. در گزارش‌هایی که ذخیره می‌کنید، توکن را از URL پاک کنید.

نمونه داده‌ای که تلگرام برای سرور می‌فرستد

ساختار ساده‌شده یک پیام متنی می‌تواند شبیه این باشد؛ شناسه‌ها و متن صرفاً نمونه‌اند:

{  "update_id": 123456789,  "message": {    "message_id": 52,    "chat": {"id": 1122334455, "type": "private"},    "text": "/start"  }}

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

همچنین شناسه چت و شناسه کاربر را یکی فرض نکنید؛ در گروه‌ها و سناریوهای دیگر یکسان بودن آن‌ها تضمین نشده است. داده ورودی کاربر را همواره نامطمئن در نظر بگیرید، حتی اگر از مسیر ربات دریافت شده باشد.

احراز درخواست: secret_token چه کمکی می‌کند؟

هنگام فراخوانی setWebhook می‌توانید پارامتر secret_token را مشخص کنید. تلگرام آن را در هدر X-Telegram-Bot-Api-Secret-Token درخواست‌های وبهوک قرار می‌دهد. Endpoint باید مقدار دریافتی را با مقدار مورد انتظار مقایسه کند و درخواست نامعتبر را نپذیرد.

این مکانیزم باید کنار HTTPS و محدودسازی دسترسی قرار بگیرد، نه به‌جای آن‌ها. از رشته‌ای غیرقابل‌حدس استفاده کنید، آن را در کد عمومی قرار ندهید و در صورت احتمال افشا تعویضش کنید. طبق مستندات Bot API، طول مجاز secret token بین ۱ تا ۲۵۶ کاراکتر است و تنها حروف لاتین، رقم، خط تیره و زیرخط پذیرفته می‌شوند.

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

معماری اتصال ربات تلگرام به سایت فروشگاهی

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

در این میان نکته ظریفی وجود دارد: داشتن کد سفارش نباید لزوماً به معنی مجوز دیدن اطلاعات آن باشد. سیستم باید بررسی کند سفارش متعلق به حساب تأییدشده است یا کاربر واقعاً برای دسترسی به آن مجاز است. در غیر این صورت، ربات به مسیری برای افشای اطلاعات مشتریان تبدیل می‌شود.

برای اعلان‌های خروجی، مثل «سفارش ارسال شد»، الزاماً به وبهوک ورودی نیاز ندارید؛ وب‌سایت می‌تواند در زمان رخداد، خودش متد sendMessage را فراخوانی کند. پس وبهوک برای دریافت رویدادهای تلگرام است و ارسال پیام از سامانه شما مسئله جداگانه‌ای محسوب می‌شود.

وقتی سرور کند می‌شود یا درخواست تکرار می‌شود چه کنیم؟

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

بازگشت سریع پاسخ موفق قبل از ذخیره مطمئن داده هم خطرناک است؛ ممکن است اطلاعات در میانه راه گم شوند. ترکیب ثبت پایدار رویداد، جلوگیری از پردازش تکراری و پایش خطاها از هر ترفند ظاهراً سریع مهم‌تر است.

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

چند خطای رایج هنگام اتصال وبهوک

آدرس ثبت شده، اما پیام‌ها نمی‌رسند

از getWebhookInfo شروع کنید. مسیر اشتباه، گواهی نامعتبر، مسدود بودن پورت، هدایت نادرست در پراکسی معکوس و خطای سمت برنامه از علت‌های متداول‌اند. درست باز شدن آدرس در مرورگر کافی نیست؛ Endpoint باید درخواست POST تلگرام را هم بپذیرد.

هم‌زمان getUpdates هم اجرا شده است

وقتی وبهوک فعال است، getUpdates برای همان ربات کار نمی‌کند. اگر می‌خواهید موقتاً به Polling برگردید، ابتدا با deleteWebhook وبهوک را حذف کنید. گزینه حذف Updateهای معوق را فقط زمانی استفاده کنید که آگاهانه می‌خواهید آن پیام‌ها را از دست بدهید.

ربات از یک پیام چند پاسخ می‌فرستد

ممکن است Update تکرار شده باشد یا چند بخش کد برای یک نوع رویداد پاسخ ارسال کنند. صرفاً اضافه کردن تأخیر راه‌حل نیست. مسیر ثبت رویداد، منطق تشخیص تکرار و ثبت وضعیت کار را بررسی کنید.

داده‌های خصوصی در لاگ ذخیره می‌شود

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

آیا ربات تلگرام بدون وبهوک هم قابل‌استفاده است؟

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

پرسش‌های متداول درباره وبهوک ربات تلگرام

آیا برای وبهوک به هاست خارجی نیاز است؟

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

آیا می‌توان چند وبهوک برای یک ربات ثبت کرد؟

در مدل معمول Bot API، برای یک ربات یک نشانی وبهوک فعال تعریف می‌شود. اگر چند سامانه نیازمند رویدادها هستند، می‌توانید رویداد را در سرور خود به مصرف‌کننده‌های مجاز توزیع کنید.

آیا وبهوک هزینه جداگانه‌ای به تلگرام پرداخت می‌کند؟

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

آیا می‌توان بدون نوشتن کد، ربات را به سایت متصل کرد؟

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

جمع‌بندی؛ ربات فقط یک پنجره چت نیست

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