Глоссарий терминов¶

Справочник ключевых понятий, используемых в руководстве по интеграции вебхуков Telegram Bot API, настройке Nginx и спецификации OpenAPI.

Telegram Bot API¶

Webhook: Архитектурный паттерн push-доставки событий, при котором серверы Telegram автоматически отправляют HTTP POST-запрос с данными события на указанный публичный URL веб-сервера бота сразу после его возникновения.
Long Polling: Метод pull-получения событий через регулярные HTTP-запросы getUpdates, при котором сервер Telegram удерживает соединение открытым до появления новых данных или истечения таймаута.
Update: Базовый объект Telegram Bot API в формате JSON, представляющий входящее событие (новое сообщение, нажатие inline-кнопки, редактирование поста и др.).
update_id: Уникальный возрастающий идентификатор события Update. Служит для контроля очерёдности обработки сообщений и подтверждения доставки.
Secret Token (X-Telegram-Bot-Api-Secret-Token): Секретная строка (1–256 символов), передаваемая сервером Telegram в одноимённом HTTP-заголовке при каждом вебхук-запросе для проверки подлинности источника трафика.
allowed_updates: Параметр метода setWebhook, задающий список типов событий, которые бот хочет получать (например, ["message", "callback_query"]), отсекая ненужный трафик на стороне Telegram.
drop_pending_updates: Флаг в запросе setWebhook, позволяющий очистить очередь накопившихся неотправленных обновлений Telegram при переключении или перезапуске вебхука.
max_connections: Параметр метода setWebhook (значения от 1 до 100), ограничивающий максимальное количество одновременных HTTPS-соединений серверов Telegram к вебхук-эндпоинту.
API-токен бота (Bot Token): Уникальный строковый ключ вида 123456:ABC-DEF..., выданный @BotFather, необходимый для аутентификации запросов к Telegram Bot API и идентификации конкретного бота в URL методов.
Callback Query: Входящее событие, возникающее при нажатии пользователем на кнопку встроенной клавиатуры (Inline Keyboard), требующее обязательного ответа через метод answerCallbackQuery.

Сетевая инфраструктура и Nginx¶

Reverse Proxy (Обратный прокси): Промежуточный сервер (в проекте — Nginx), принимающий входящие HTTPS-запросы от серверов Telegram и перенаправляющий их на внутренний сервис бота, скрывая реальную топологию бэкенда от внешней сети.
SSL/TLS Termination (Терминация SSL): Процесс расшифровки входящего HTTPS-трафика на уровне обратного прокси (Nginx) и передача расшифрованного HTTP-запроса сервису бота, освобождающий приложение бота от вычислительных затрат на криптографию.
Upstream (Апстрим): Целевой бэкенд-сервер или группа серверов (в данном случае локальный процесс бота, например 127.0.0.1:8000), на который Nginx пересылает запросы через директиву proxy_pass.
Self-Signed Certificate (Самоподписанный сертификат): Сертификат открытого ключа, сгенерированный и подписанный самим разработчиком (без участия доверенного центра сертификации). Для работы с Telegram Webhook требует обязательной передачи публичной части .pem при вызове setWebhook.
Let's Encrypt / Certbot: Общедоступный доверенный центр сертификации (CA) и сопутствующая консольная утилита автоматизации, выпускающие бесплатные валидные SSL/TLS-сертификаты, не требующие отдельной загрузки в Telegram.
proxy_set_header: Директива Nginx, используемая для проброса оригинальных клиентских заголовков (Host, X-Real-IP, X-Forwarded-For, X-Forwarded-Proto) к локальному сервису бота, позволяющая приложению видеть реальный IP-адрес серверов Telegram.
Брандмауэр / Межсетевой экран (Firewall / UFW): Программный инструмент фильтрации сетевого трафика в Linux (ufw), используемый для открытия необходимых портов (80, 443) и защиты закрытых внутренних портов сервиса бота от прямого доступа из интернета.
A-запись (DNS A Record): Запись в системе доменных имён (DNS), связывающая доменное имя вебхука с публичным IPv4-адресом сервера для маршрутизации входящих запросов от Telegram.
OpenSSL: Консольная криптографическая утилита, применяемая в проекте для генерации криптографически стойкого секретного токена (openssl rand -hex 32) и создания самоподписанных SSL/TLS-сертификатов.

Спецификация и API-контракты¶

OpenAPI 3.0: Общепринятый машинно-читаемый стандарт (спецификация в формате YAML/JSON) для формального описания контрактов REST API: доступных эндпоинтов, параметров, схем данных и кодов ответов.
Swagger UI: Инструмент визуализации спецификации OpenAPI в виде интерактивной веб-страницы, позволяющий изучать схему данных и выполнять тестовые HTTP-запросы напрямую из браузера.
WebhookInfo: Объект данных Telegram Bot API, возвращаемый методом getWebhookInfo и содержащий диагностические сведения: текущий URL вебхука, число ожидающих доставки обновлений и текст последней ошибки соединения.
multipart/form-data: Формат кодирования тела HTTP-запроса (Content-Type), применяемый для передачи бинарных файлов (в проекте — для загрузки файла публичного сертификата при вызове setWebhook).