آموزش Set Webhook ربات تلگرام | اتصال Webhook با PHP

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

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

در روش Polling، برنامه شما با متد getUpdates مرتباً از تلگرام درخواست می‌کند تا پیام‌های جدید را دریافت کند. این روش برای تست‌های ساده مناسب است، اما در پروژه‌های جدی معمولاً Webhook بهتر است؛ چون واکنش سریع‌تری دارد، بار اضافی کمتری ایجاد می‌کند و روی هاست یا سرور پایدارتر قابل مدیریت است.

پیش‌نیازهای Set Webhook

• توکن معتبر ربات که از BotFather دریافت شده باشد.
• دامنه یا زیر دامنه با SSL معتبر و فعال.
• یک فایل یا endpoint برای دریافت درخواست‌های POST تلگرام.
• امکان ثبت لاگ خطا برای بررسی درخواست‌ها و پاسخ‌ها.
• مسیر امن و غیرقابل حدس برای فایل Webhook در پروژه‌های حساس.

نمونه فایل PHP برای دریافت پیام

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

<?php
$rawBody = file_get_contents("php://input");
$update = json_decode($rawBody, true);

if (!is_array($update)) {
    http_response_code(400);
    exit("Invalid update");
}

$chatId = $update["message"]["chat"]["id"] ?? null;
$text = trim((string) ($update["message"]["text"] ?? ""));

if ($chatId && $text !== "") {
    $logLine = date("c") . " | " . $chatId . " | " . $text . PHP_EOL;
    file_put_contents(__DIR__ . "/telegram-webhook.log", $logLine, FILE_APPEND);
}

http_response_code(200);
echo "OK";

ثبت Webhook در تلگرام

بعد از آماده شدن فایل دریافت پیام و فعال بودن SSL، می‌توانید Webhook را ثبت کنید. مقدار YOUR_BOT_TOKEN را با توکن واقعی ربات و آدرس https://example.com/bot/webhook.php را با مسیر واقعی فایل خود جایگزین کنید.

https://api.telegram.org/botYOUR_BOT_TOKEN/setWebhook?url=https://example.com/bot/webhook.php

ثبت Webhook با secret_token

برای امنیت بیشتر می‌توانید هنگام ثبت Webhook یک secret_token ارسال کنید. تلگرام این مقدار را در هدر درخواست‌ها ارسال می‌کند و شما می‌توانید در فایل webhook آن را بررسی کنید.

curl -X POST "https://api.telegram.org/botYOUR_BOT_TOKEN/setWebhook"   -d "url=https://example.com/bot/webhook.php"   -d "secret_token=YOUR_RANDOM_SECRET"   -d "drop_pending_updates=true"

<?php
$secret = "YOUR_RANDOM_SECRET";
$header = $_SERVER["HTTP_X_TELEGRAM_BOT_API_SECRET_TOKEN"] ?? "";

if (!hash_equals($secret, $header)) {
    http_response_code(403);
    exit("Forbidden");
}

بررسی وضعیت و حذف Webhook

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

https://api.telegram.org/botYOUR_BOT_TOKEN/getWebhookInfo

اگر خواستید موقتاً به Polling برگردید، Webhook را حذف کنید:

https://api.telegram.org/botYOUR_BOT_TOKEN/deleteWebhook?drop_pending_updates=true

نکات امنیتی و خطایابی

سوالات متداول درباره Webhook تلگرام