وب هوک ربات تلگرام: راه‌اندازی setWebhook، بررسی و رفع خطا

به‌روزرسانی: ۷ آبان ۱۴۰۵ · 7 دقیقه مطالعه

وب هوک تلگرام یعنی به جای اینکه ربات مدام با getUpdates از تلگرام آپدیت بخواهد، تلگرام هر آپدیت را با یک درخواست HTTPS POST به آدرس سرور شما می‌فرستد. برای ست کردن وب هوک کافی است متد setWebhook را با یک آدرس HTTPS عمومی صدا بزنید. در این راهنما پیش‌نیازها، پارامترهای مهم، بررسی وضعیت با getWebhookInfo، کد دریافت آپدیت و رفع خطاهای رایج را می‌بینید.

وب هوک یا getUpdates؟

این دو روش هم‌زمان کار نمی‌کنند: تا وقتی وب هوک فعال است، getUpdates خطای 409 می‌دهد. در هر دو حالت آپدیت‌های تحویل‌نشده حداکثر 24 ساعت نگه داشته می‌شوند.

پیش‌نیازهای وب هوک ربات تلگرام

• آدرس HTTPS عمومی؛ آدرس http پذیرفته نمی‌شود.
• فقط پورت‌های 443، 80، 88 و 8443.
• گواهی SSL معتبر با پشتیبانی از TLS 1.2 به بالا که CN یا SAN آن با دامنه یکی باشد و گواهی‌های میانی (intermediate) را هم ارائه کند. گواهی خودامضا (self-signed) هم قابل استفاده است، به شرطی که فایل کلید عمومی را در پارامتر certificate آپلود کنید.
• سرور باید از طریق IPv4 در دسترس باشد (IPv6 برای وب هوک پشتیبانی نمی‌شود) و ریدایرکت هم پشتیبانی نمی‌شود.
• اگر فایروال دارید، درخواست‌ها از رنج‌های 149.154.160.0/20 و 91.108.4.0/22 می‌آیند.

ست وب هوک تلگرام با setWebhook

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/telegram/webhook",
    "secret_token": "my_secret_123",
    "allowed_updates": ["message", "callback_query"],
    "drop_pending_updates": true,
    "max_connections": 40
  }'

پاسخ موفق:

{"ok": true, "result": true, "description": "Webhook was set"}

با گواهی خودامضا، درخواست باید multipart/form-data باشد:

curl -F "url=https://203.0.113.10:8443/telegram/webhook" \
  -F "certificate=@public.pem" \
  -F "secret_token=my_secret_123" \
  "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setWebhook"

همین کار را بدون ترمینال در Bot API Tester روی متد setWebhook انجام دهید.

بررسی وضعیت با getWebhookInfo

curl https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/getWebhookInfo

{"ok": true, "result": {
  "url": "https://example.com/telegram/webhook",
  "has_custom_certificate": false,
  "pending_update_count": 12,
  "last_error_date": 1793266200,
  "last_error_message": "Connection timed out",
  "max_connections": 40,
  "allowed_updates": ["message", "callback_query"]
}}

اگر pending_update_count مدام بالا می‌رود و last_error_message پر است، تلگرام نمی‌تواند آپدیت را تحویل دهد؛ متن خطا معمولاً مشکل را نشان می‌دهد (گواهی، پورت بسته، timeout یا پاسخ غیر 2xx). اگر url خالی باشد، وب هوکی تنظیم نشده است.

دریافت آپدیت و بررسی secret token

در سرور، مقدار هدر X-Telegram-Bot-Api-Secret-Token را با توکن مخفی خود مقایسه کنید و درخواست‌های دیگر را رد کنید. نمونه با Flask:

import hmac
import os
from flask import Flask, abort, request

SECRET = os.environ["WEBHOOK_SECRET"]
app = Flask(__name__)

def handle_update(update):
    print(update["update_id"])

@app.post("/telegram/webhook")
def telegram_webhook():
    got = request.headers.get("X-Telegram-Bot-Api-Secret-Token", "")
    if not hmac.compare_digest(got, SECRET):
        abort(403)
    handle_update(request.get_json())
    return "", 200

سریع پاسخ 2xx بدهید. اگر سرور پاسخ غیر 2xx برگرداند یا دیر جواب دهد، تلگرام همان آپدیت را دوباره می‌فرستد؛ پس کارهای سنگین را به صف یا پردازش پس‌زمینه بسپارید و تکراری بودن آپدیت را با update_id تشخیص دهید.

حذف وب هوک و بازگشت به getUpdates

curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/deleteWebhook?drop_pending_updates=true"

پاسخ Webhook was deleted یعنی وب هوک حذف شد و حالا getUpdates کار می‌کند. پارامتر drop_pending_updates اختیاری است؛ اگر آپدیت‌های در صف را لازم دارید، آن را نفرستید.

رفع خطاهای رایج وب هوک

• Bad Request: bad webhook: An HTTPS URL must be provided for webhook: آدرس با http شروع شده است؛ از HTTPS استفاده کنید.
• Webhook can be set up only on ports 80, 88, 443 or 8443: پورت آدرس مجاز نیست.
• خطای 409 در getUpdates با متن Conflict: can't use getUpdates method while webhook is active; use deleteWebhook to delete the webhook first: وب هوک فعال است؛ یا از وب هوک استفاده کنید یا deleteWebhook را صدا بزنید.
• n8n روی localhost: تلگرام به localhost یا آدرس http دسترسی ندارد، پس تریگر تلگرام نمی‌تواند وب هوک ثبت کند. n8n باید با یک آدرس HTTPS عمومی (دامنه با گواهی معتبر یا تونل HTTPS) در دسترس باشد.
• ربات جواب نمی‌دهد ولی setWebhook موفق بود: last_error_message را در getWebhookInfo ببینید و باز بودن پورت و زنجیره کامل گواهی را بررسی کنید.

هنوز ربات یا توکن ندارید؟ از آموزش ساخت ربات تلگرام شروع کنید. برای پاسخ دادن به آپدیت‌ها هم آموزش ارسال پیام با ربات تلگرام را ببینید و برای پیدا کردن آیدی چت‌ها راهنمای چت آیدی تلگرام را بخوانید.