Telegram — bot + Mini App

Поле	Значення
Боти	Abitly bot · Studsearch bot
Mini App	Abitly Telegram Mini App (Next.js + @telegram-apps/sdk-react)
Бібліотеки	Bot — aiogram 3 (Python) · Mini App — @telegram-apps/sdk-react
Режим bot	long polling (один інстанс, ADR 0001)
Токени	BOT_TOKEN бота — в SSM /abitly-prod/tg-bot/ (не Railway vars) · TELEGRAM_BOT_TOKEN backend/API для initData HMAC — в SSM /abitly/{env}/backend/ · /studsearch/prod/telegram/bot_token (Studsearch)
Logger bot (окремий)	TELEGRAM_LOGGER_BOT_TOKEN + TELEGRAM_LOG_CHAT_ID — для помилок (observability)

Точки входу

• Бот-команди (повідомлення в чат) → aiogram-хендлери → читають/пишуть Postgres напряму (без HTTP до Abitly API).
• Mini App запускається з бота кнопкою з web_app button → Next.js на Railway → axios у Abitly API.

Init data validation (Mini App)

secret = HMAC-SHA256(key="WebAppData", msg=TELEGRAM_BOT_TOKEN)
expected_hash = HMAC-SHA256(serialized_init_data_without_hash, secret)

Abitly API виконує перевірку при ендпоінті POST /telegram/auth {initData} → видає JWT.

Потік повідомлень

Базовий sequence → data-flows. Повний набір UML + sequence для всіх user-сценаріїв бота → Telegram-бот: user-сценарії.

Типові проблеми

• Бот не отримує апдейти → перевірити Telegram long polling статус і логи ECS-таски.
• 409 Conflict від Telegram → два getUpdates на одному токені. На ECS — рівно 1 таска (desired_count=1, ADR 0001); перевір, чи не запущено локального/dev-інстансу на тому ж токені.
• Mini App не відкривається з бота → URL у web_app button застарів / Mini App URL у @BotFather не оновлено.
• Init data invalid у Mini App → токен у Mini App-env і у API-env різний.