webhook

Эндпоинтов: 1

POST /api/webhook/{projectId}/{tokenId}

Приём апдейта Telegram (webhook режим)

Авторизация: Публичный

Публичный эндпоинт — Telegram Server API шлёт сюда POST без cookie и без PAT. Путь в allowlist requireApiAuth (/webhook/).

Когда используется: только если токен бота в настройках запуска имеет launchMode: webhook. При старте бот регистрирует в Telegram URL: {webhookBaseUrl}/api/webhook/{projectId}/{tokenId}

Поток:

1. Telegram → POST этот URL с JSON Update
2. Node.js (setupWebhookRoutes) проксирует body на http://localhost:{9000+tokenId}/webhook
3. Python aiohttp + aiogram (SimpleRequestHandler) обрабатывает сценарий

UI: превью URL в BotLaunchSettings (buildWebhookPreview).

Порт Python: 9000 + tokenId (константа BASE_WEBHOOK_PORT в setupWebhookRoutes.ts). В Worker Pool каждый бот внутри worker.py поднимает свой aiohttp на этом порту.

Ответ: обычно пустое body — статус копируется с Python-сервера или 200 при ошибке прокси (чтобы Telegram не ретраил апдейт, если процесс бота недоступен).

Безопасность: Node не проверяет webhookSecretToken из настроек токена — секрет можно задать только при set_webhook на стороне бота (отдельная задача). Не публикуйте URL без TLS на production.

Polling vs webhook: при launchMode: polling этот URL не регистрируется в Telegram; эндпоинт может оставаться доступным, но апдейты не приходят.

Operation ID: post_api_webhook_projectId_tokenId_761e7a576528db30

Тело запроса: TelegramWebhookUpdate

Параметры

Имя	In	Обязательный	Описание	Пример
projectId	path	да	ID проекта — часть публичного webhook URL	"266"
tokenId	path	да	ID токена — определяет порт Python (9000 + tokenId)	"233"

Пример тела запроса

{
  "update_id": 10000,
  "message": {
    "message_id": 1365,
    "date": 1441645532,
    "chat": {
      "id": 783828,
      "type": "private",
      "first_name": "User"
    },
    "text": "Привет"
  }
}

Ответы

Код	Описание
200	Апдейт принят. Body пустое (не JSON). Статус HTTP копируется с aiohttp или принудительно 200 при ошибке прокси.
400	Некорректные projectId или tokenId в path (не число)
503	Глобальный setupGuard — приложение ещё не настроено. До завершения setup (через /admin) webhook с production не работает.