Настройка вебхука Telegram-бота: полное руководство для разработчиков

Настройка вебхука Telegram-бота подключает ваш сервер к потоку обновлений Telegram, чтобы сообщения поступали в реальном времени, а не в цикле опроса. Если вы создаете пользовательского бота с помощью Bot API, вебхуки являются стандартным производственным путем: Telegram отправляет каждое обновление на вашу конечную точку HTTPS, и ваш код отвечает.

Это руководство проведет вас через предварительные условия, регистрацию, пример рабочего обработчика, проверку, устранение неполадок и объяснит, когда управляемая платформа, такая как TeleClaw, имеет больше смысла, чем самостоятельное размещение.

Основные выводы

• Вебхуки и длинный опрос взаимоисключающие. Установка вебхука отключает getUpdates до тех пор, пока вы его не удалите.
• HTTPS обязателен. Ваша конечная точка должна иметь TLS 1.2+, соответствующий сертификат и порт 443, 80, 88 или 8443.
• Зарегистрируйтесь с помощью setWebhook, проверьте с помощью getWebhookInfo. Проверяйте last_error_message, когда обновления перестают поступать.
• Используйте secret_token, чтобы подтвердить, что запросы поступают от Telegram, а не от случайных сканеров, обращающихся к вашему URL.
• Альтернатива без кода: TeleClaw обрабатывает хостинг и доставку, поэтому вы полностью пропускаете серверный уровень.

Вебхуки против длинного опроса: что выбрать

Telegram предлагает два способа получения обновлений. Согласно FAQ по ботам, вы выбираете один метод для каждого бота. Вы не можете запускать оба одновременно.

Длинный опрос — самый быстрый способ создания прототипов. Ваш бот вызывает getUpdates в цикле, обрабатывает каждую партию и продвигает смещение. Нет домена, нет сертификата, нет открытого порта.

Вебхуки меняют модель. Telegram отправляет HTTPS POST на ваш URL всякий раз, когда кто-то отправляет сообщение боту. Это устраняет запросы на холостой опрос и сокращает время реакции, что важно для ботов поддержки, платежных потоков и модерации групп в масштабе.

Если вы все еще регистрируете самого бота, начните с нашего руководства по созданию Telegram-бота, чтобы получить токен от BotFather, прежде чем продолжить здесь.

Предварительные условия для настройки вебхука Telegram-бота

Прежде чем вызывать setWebhook, убедитесь, что ваша инфраструктура соответствует требованиям Telegram из официального руководства по вебхукам:

• Токен бота от @BotFather (см. руководство по созданию бота, ссылка выше).
• Публичный домен с действительным TLS-сертификатом. Самоподписанные сертификаты работают только в том случае, если вы загружаете открытый ключ через параметр certificate.
• Поддерживаемый порт на вашем сервере: 443 (по умолчанию), 80, 88 или 8443. Другие порты отклоняются.
• CN или SAN сертификата должны совпадать с доменом в вашем URL вебхука. Сертификаты с подстановочными знаками могут не работать. Перенаправления не поддерживаются.
• Входящий доступ POST из подсетей Telegram 149.154.160.0/20 и 91.108.4.0/22.

Для локальной разработки откройте localhost через туннель (ngrok, Cloudflare Tunnel или аналогичный), который предоставляет вам публичный URL HTTPS. Проверьте, что туннель возвращает HTTP 200 для POST-запросов, прежде чем регистрировать вебхук.

Шаг 1: Создайте конечную точку вебхука

Вашему серверу нужен маршрут, который принимает POST-запросы, анализирует объект JSON Update и быстро возвращает HTTP 200. Медленные обработчики заставляют Telegram повторять попытки и в конечном итоге сообщать об ошибках в getWebhookInfo.

Минимальный пример Node.js с Express:

import express from 'express';

const app = express();
app.use(express.json());

const SECRET = process.env. WEBHOOK_SECRET;

app.post('/webhook', (req, res) => {
 if (SECRET && req.get('X-Telegram-Bot-Api-Secret-Token')!== SECRET) {
 return res.sendStatus(403);
 }

 const update = req.body;
 // Process update.message, update.callback_query, etc.
 console.log('Update ID:', update.update_id);

 res.sendStatus(200);
});

app.listen(443);

Python с Flask следует тому же шаблону: чтение JSON из request, проверка секретного заголовка, если он настроен, обработка обновления, возврат 200.

Отвечайте быстро. Тяжелая работа (запись в базу данных, вызовы AI API) должна отправляться в фоновую очередь. Telegram ожидает быстрого подтверждения. Вы также можете ответить в строке, вернув тело JSON с полем method вместо выполнения отдельного вызова API, как описано в примечаниях к вебхукам Bot API.

Шаг 2: Настройте вебхук Telegram-бота с помощью setWebhook

Как только ваша конечная точка будет запущена, зарегистрируйте ее в Bot API. Замените <TOKEN> и URL на ваши значения.

Использование curl:

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
 -H "Content-Type: application/json" \
 -d '{
 "url": "https://yourdomain.com/webhook",
 "secret_token": "my_random_secret_abc123",
 "max_connections": 40,
 "allowed_updates": ["message", "callback_query", "chat_join_request"],
 "drop_pending_updates": false
 }'

Справочник по параметрам:

• url (обязательно): Ваша конечная точка HTTPS. Используйте пустую строку для удаления вебхука.
• secret_token (необязательно): 1-256 символов (A-Z, a-z, 0-9, _, -). Telegram отправляет его в заголовке X-Telegram-Bot-Api-Secret-Token.
• max_connections (необязательно): 1-100 одновременных подключений. По умолчанию 40.
• allowed_updates (необязательно): Ограничивает типы обновлений, которые вы получаете. Уменьшает размер полезной нагрузки, если вы обрабатываете только сообщения.
• drop_pending_updates (необязательно): Установите true, чтобы отбросить ожидающие обновления при переключении вебхуков.
• certificate (необязательно): Загрузите файл вашего открытого ключа для самоподписанных сертификатов.

Успешный ответ выглядит как {"ok":true,"result":true,"description":"Webhook was set"}.

Шаг 3: Проверьте с помощью getWebhookInfo

Всегда немедленно подтверждайте регистрацию. Это ваш первый инструмент для устранения неполадок, когда обновления перестают поступать.

curl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo"

Пример ответа:

{
 "ok": true,
 "result": {
 "url": "https://yourdomain.com/webhook",
 "has_custom_certificate": false,
 "pending_update_count": 0,
 "max_connections": 40,
 "allowed_updates": ["message", "callback_query", "chat_join_request"]
 }
}

Следите за этими полями:

• url: Пустое значение означает, что вебхук неактивен (бот находится в режиме длинного опроса).
• pending_update_count: Ожидающие обновления, ожидающие доставки. Растущее число сигнализирует о сбоях доставки.
• last_error_date и last_error_message: Причина последней ошибки. Исправьте основную причину, затем Telegram автоматически повторит попытку.
• ip_address: Какой IP-адрес Telegram в настоящее время обращается к вашей конечной точке.

Отправьте тестовое сообщение вашему боту с реального аккаунта Telegram. Если pending_update_count остается равным нулю, а журналы вашего сервера показывают POST-запрос, настройка вебхука Telegram-бота работает.

Пример вебхука Telegram-бота: обработчик запросов на присоединение

Боты для запросов на присоединение (потоки допуска в стиле Guardian) нуждаются в типе обновления chat_join_request. Наше руководство по боту Guardian охватывает продуктовую сторону. Вот подключение вебхука.

Зарегистрируйтесь с включенными запросами на присоединение:

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
 -d "url=https://yourdomain.com/webhook" \
 -d "allowed_updates=[\"chat_join_request\",\"message\"]"

Логика обработчика (псевдокод):

if (update.chat_join_request) {
 const { chat, from, invite_link } = update.chat_join_request;
 // Запустите логику проверки, затем одобрите или отклоните через Bot API
 await approveChatJoinRequest(chat.id, from.id);
}

Telegram доставляет запросы на присоединение в виде push-обновлений, поэтому вебхуки естественным образом подходят для ботов допуска, которые должны отвечать до истечения срока действия запроса.

Удаление вебхука Telegram-бота и возврат к опросу

Нужно отладить локально с помощью getUpdates? Сначала удалите вебхук.

Вариант A с deleteWebhook:

curl -X POST "https://api.telegram.org/bot<TOKEN>/deleteWebhook" \
 -d "drop_pending_updates=true"

Вариант B с setWebhook и пустым URL:

curl "https://api.telegram.org/bot<TOKEN>/setWebhook?url="

Оба метода повторно включают длинный опрос. Если вы пропустите этот шаг, getUpdates ничего не вернет, потому что вебхук все еще зарегистрирован на ваш производственный URL.

Устранение распространенных ошибок вебхуков

Когда getWebhookInfo показывает ошибки, сопоставьте сообщение с исправлением:

Запускайте getWebhookInfo по расписанию в продакшене. Раннее обнаружение last_error_message предотвращает часы бесшумной потери сообщений.

Пропустите сервер: управляемые боты с TeleClaw

Не каждому боту нужна пользовательская инфраструктура вебхуков. Если ваша цель — AI-помощник для группы или бизнес-канала, хостинг и доставка обновлений — это решенные проблемы.

TeleClaw подключает ваш токен BotFather к управляемой среде выполнения на базе OpenClaw. Вы настраиваете личность, базу знаний и правила модерации на панели управления. Платформа обрабатывает конечные точки HTTPS, масштабирование и маршрутизацию моделей ИИ. Добавьте @claw в качестве администратора группы и запускайте без написания обработчика вебхуков.

Изучите, что может делать управляемый бот, на странице функций TeleClaw. Для полного пошагового руководства без кода см. наше руководство по созданию Telegram-чатбота без кода.

Пользовательские вебхуки по-прежнему имеют смысл, когда вам нужен полный контроль: проприетарные бэкенды, регулируемое хранение данных или нестандартная обработка обновлений. Для всего остального операционные расходы на управление сертификатами, мониторинг и обработку повторных попыток быстро накапливаются.

Заключение

Настройка вебхука Telegram-бота сводится к четырем шагам: развернуть конечную точку HTTPS, вызвать setWebhook, проверить с помощью getWebhookInfo и отслеживать ошибки. Используйте secret_token для проверки запросов, ограничьте allowed_updates тем, что вы обрабатываете, и делайте обработчики быстрыми.

Разработчики, которые хотят получать производственные push-уведомления без запуска серверов, могут использовать TeleClaw вместо этого. Вставьте свой токен, настройте поведение ИИ и сосредоточьтесь на том, что говорит бот, а не на том, как приходят обновления.

Готовы запустить AI-бота без управления вебхуками? Добавьте @claw в свою группу Telegram →