Deep-links до Telegram-бота

Метадані

Поле	Значення
Статус	🟢 prod
Поверхні	web → bot (інтеграційна поверхня)
Доступність	безкоштовно
Власник	TODO:
Останнє підтвердження	2026-06-13 · curl (live prod-бандл: abitlybot, chances_, open_day_university_) + код:main

Призначення

Переводить абітурієнта з сайту в Telegram-бот без втрати контексту: бал калькулятора, ЗВО чи офер пакуються в t.me/abitlybot?start=<payload>. Єдине джерело всіх бот-URL фронтенду — src/lib/utils/telegramBot.ts; username бота задає NEXT_PUBLIC_TELEGRAM_BOT_USERNAME (без @; prod = abitlybot, env не задано → CTA ховаються).

Формати deep-link

Сценарії бота вже намальовані в bot-flows — тут лише мапа «де на сайті → який payload»:

Payload	CTA на сайті	Сценарій бота
chances_<specialityId>_<score×100>	калькулятор: банер «шанси» + popup після розрахунку (TelegramChancesBanner, TelegramScorePopup)	шанси на вступ
open_day_university_<id>	сторінка ЗВО: «дні відкритих дверей» (OpenDayTelegramLink, OpenDaysPreview)	дні відкритих дверей
<offerId> (голий id)	картки оферів і сторінка офера (пошук оферів: OfferCardActions, OfferActions)	⚠️ бот v3 не обробляє — падає в дефолтне привітання
link_<token>	не мінтиться фронтом — токен видає api-v2	прив’язка веб-акаунту
без payload	/uk/applicants (CommunityLinks)	привітання

Бал у chances_ кодується як Math.round(score × 100) (Telegram приймає в start лише [A-Za-z0-9_-], крапка викидається); бал > 250 або відсутній username → функція повертає null, банер не рендериться.

Прив’язка акаунту не наскрізна

link_<token> очікує спільний Redis між api-v2 і ботом, але в prod бот має власний sidecar-Redis, а mint-ендпоінт у api-v2 не підтверджено живим → лінкування фактично не працює (картка бота). Зворотний напрямок (бот → web, /auth/telegram-connect) — у картці автентифікації.

Дані та API

Web-сторона — суто клієнтська (URL формується в браузері, без API-викликів). Payload споживає бот: парсинг у handlers/start.py, дані — Postgres abitly (див. bot-flows). Крос-сервісний потік — data-flows.

Зв’язки з іншими фічами

• Веб-калькулятор — головний донор трафіку (chances_).
• Сторінка ЗВО і пошук оферів — CTA open-day та офер-лінки.
• Автентифікація — прив’язка акаунту в обох напрямках.

Код

Репо	Шлях	Примітка
abitly-frontend-v2	src/lib/utils/telegramBot.ts	getTelegramBotUrl + buildChancesDeepLink — єдине джерело URL
abitly-frontend-v2	src/components/pages/{calculator,universities,shared,offers}/**/Telegram*, OpenDay*, OfferCardActions.tsx	CTA-компоненти
abitly-tg-bot-v3	src/abitly_bot/handlers/start.py	роутинг payload (link_ / chances_ / open_day_university_)

Обмеження та блокери

• ?start=<offerId> фронт формує, але бот v3 цей payload ігнорує (дефолтне привітання) — контекст офера губиться. TODO: або додати хендлер у бота, або прибрати CTA.
• link_<token> — не наскрізно (sidecar-Redis ≠ shared, див. caution вище).
• chances_ зі stale speciality-id → бот мовчки відповідає «нічого не знайдено» (ремап id на 2025 — на боці бота).

Історія змін

Дата	Подія	Джерело
2026-06-13	Картку створено за discovery (live бандл + код main фронту й бота)	skill document-feature