Quartz 4

telegram-bot-analytics

7 min readYakovenko22V

Telegram Bot Analytics

Глобальне меню → Telegram Bot Analytics

Загальна логіка сторінки

Суть

Telegram Bot Analytics — одна сторінка аналітики Telegram-ботів. Верхній блок задає контекст вибірки, нижче рендериться аналітика конкретного бота, який вибраний у фільтрі Bot.

Фронт уже підготовлений до сценарію з кількома ботами, але зараз реалізований лише один блок — BeSocial HR Bot. Коли з’являться інші боти, на цій самій сторінці для них додаються окремі секції з власною логікою, набором карток і графіків.

Доступи

РольРоутПоведінка
director/ceo/telegram_bot_analyticsПовна сторінка аналітики
hr + user.telegramBot = true/hr/telegram_bot_analyticsТа сама сторінка аналітики
hr + user.telegramBot = false/hr/telegram_bot_analyticsЕкран без доступу замість контенту

Верхній блок сторінки

  • Bot — вибір бота, для якого будується аналітика.
  • Month — базовий місяць звіту.
  • UTM — multi-select UTM-комбінацій для активного бота; якщо конкретні мітки не вибрані, фронт працює в режимі All.
  • GNR — явний запуск побудови звіту.

Після GNR фронт фіксує поточний набір Bot, Month і UTM в activeFilters, виконує bot-specific запити та оновлює картки й графіки тільки для вибраного бота. До першого GNR аналітика не будується.

Загальна поведінка сторінки

  • У виборі мають бути доступні лише ті боти, до яких користувач має доступ.
  • Якщо бот недоступний для акаунта, він не повинен бути доступним для вибору і не повинен відображати свій блок аналітики.
  • Якщо звіт ще не згенерований, сторінка показує стартову підказку обрати фільтри й натиснути GNR.
  • Якщо даних немає лише для окремого віджета, порожній стан показується локально всередині конкретної картки або графіка.

BeSocial HR Bot

Доступність бота

BeSocial HR Bot — єдиний бот, який зараз підключений на фронті.

  • Для director цей бот доступний без додаткових обмежень.
  • Для hr доступ залежить від user.telegramBot.
  • Якщо в HR немає цього доступу, бот не повинен бути доступним для вибору і його аналітика не повинна відображатися.
  • У поточній реалізації, поки бот один, для HR без user.telegramBot це означає екран без доступу для всієї сторінки.

Логіка завантаження блоку

Після кліку на GNR для BeSocial HR Bot фронт відправляє запити за вибраними фільтрами й будує картки та графіки в межах цього блоку.

Початковий цикл запитів:

  • POST /hiring-analytics/getMonthSummary
  • POST /hiring-analytics/getTrafficLeadsCR
  • POST /hiring-analytics/getCplCpa
  • POST /hiring-analytics/getFunnel
  • POST /hiring-analytics/getFunnelSteps
  • POST /hiring-analytics/getStepMedianResponseTime
  • POST /hiring-analytics/getPlatformSegmentation
  • POST /hiring-analytics/getTechnicalErrors

Окремо для списку UTM фронт ліниво викликає:

  • POST /hiring-analytics/getUtmFilters

Важлива поведінка:

  • стартове завантаження зібране через Promise.allSettled, тому падіння одного запиту не обнуляє весь екран;
  • для Traffic, Leads & Conversion Rate (CR%) Dynamics і 6-Month Total Cost Dynamics (CPL & CPA) дефолтний запит після GNR іде з groupBy: WEEK;
  • верхні два time-series графіки можуть перезапитуватись окремо при зміні Day / Week / Month;
  • помилки прилітають через global notification;
  • під час запитів використовується global loader.

Фільтри цього бота

Додаткові фільтри відсутні.

При зміні Month фронт:

  • очищає вибрані UTM;
  • скидає кеш UTM-опцій;
  • закриває UTM dropdown;
  • чекає нового явного GNR для побудови звіту з новим місяцем.

Що відображається після запиту

Після успішного запуску звіту для BeSocial HR Bot сторінка показує:

  • 4 підсумкові картки за місяць: Total Traffic, Generated Leads, Conversion Rate, Total Spend;
  • Traffic, Leads & Conversion Rate (CR%) Dynamics;
  • 6-Month Total Cost Dynamics (CPL & CPA);
  • Funnel Volumes vs Acquisition Costs by UTM;
  • Conversion Funnel & Step Drop-offs;
  • Time-to-Complete: Median Response Time (Seconds);
  • Audience Platform Segmentation;
  • Technical Errors & Bot Failures.

Логіка побудови графіків

Загальні правила

  • Усі графіки рендеряться тільки після першого GNR.
  • Кожен графік живе у власній картці та має власний порожній стан.
  • Ширина графіків адаптивна: фронт відстежує розмір контейнера через ResizeObserver.
  • Tooltip рендериться через portal у document.body, тому не обрізається межами картки.
  • Hover підсвічує не лише точку, а й активну колонку або рядок, щоб легше читати значення.

Traffic, Leads & Conversion Rate (CR%) Dynamics

  • Графік будується по вікну в 6 місяців до вибраного Month включно.
  • Діапазон фронт рахує від selectedMonth.dateTo.
  • Початковий запит іде з groupBy: WEEK.
  • Якщо користувач перемикає Day / Week / Month, фронт не агрегує дані локально, а робить новий API-запит з потрібним groupBy.
  • По X-осі:
    • DAY → dd MMM
    • WEEK → dd.MM - dd.MM
    • MONTH → MMM yyyy
  • На графіку 3 серії: traffic, leads, cr.
  • Ліва Y-вісь відповідає за абсолютні значення traffic і leads.
  • Права Y-вісь відповідає за cr у відсотках.
  • Для правої осі фронт тримає верхню межу не нижче 100%, навіть якщо фактичні значення CR менші.
  • Між лініями traffic і leads малюється напівпрозора area-заливка, яка підкреслює розрив між заходами в бот і лідами.
  • Tooltip показує Period, Traffic, Leads, CR.

6-Month Total Cost Dynamics (CPL & CPA)

  • Діапазон тут такий самий: 6 місяців до вибраного Month.
  • Початковий запит теж іде з groupBy: WEEK.
  • Перемикач Day / Week / Month запускає окремий повторний запит саме для цього графіка.
  • На графіку 2 серії: cpl і cpa.
  • Для обох серій використовується одна Y-вісь у валюті.
  • Значення осі й tooltip форматуються як currency.
  • Для дрібних значень фронт лишає десяткову частину, для більших — округляє сильніше.
  • Tooltip показує Period, CPL, CPA.

Funnel Volumes vs Acquisition Costs by UTM

  • Графік будується тільки в межах одного вибраного місяця.
  • Кожна точка X-осі — окрема UTM-комбінація.
  • Назва UTM збирається на фронті з полів у такому порядку:
    • utm_source
    • utm_medium
    • utm_campaign
    • utm_content
    • utm_manager
    • utm_account
  • Якщо кілька UTM дають однаковий нормалізований payload, фронт дедуплікує їх ще до відображення в selector.
  • Якщо в selector уже вибрано 10 міток, інші UTM-пункти рендеряться як disabled і не додаються до вибірки.
  • Графік комбінований:
    • bars для traffic і leads
    • lines для cpl і cpa
  • Ліва Y-вісь використовується для обсягів.
  • Права Y-вісь використовується для вартості.
  • Довгі UTM-підписи на X-осі обрізаються адаптивно, але повне значення лишається в tooltip.
  • Tooltip показує UTM, Leads (Bot Starts), Applications (Submits), Spend, CPL, CPA.

Conversion Funnel & Step Drop-offs

  • Це горизонтальний bar chart по step_id.
  • Довжина bar-а залежить від users.
  • Текст праворуч від bar-а фронт рахує окремо.
  • Для першого кроку підпис має формат X users (100% of traffic).
  • Для всіх наступних кроків підпис має формат X | Step CR: Y | Total CR: Z.
  • Щоб цей текст поміщався, X-вісь малюється із запасом приблизно 1.55 від найбільшого users.
  • Tooltip показує Step, Users, Step CR, Total CR, Drop-off.

Time-to-Complete: Median Response Time (Seconds)

  • Кожен step_id рендериться окремим вертикальним bar-ом.
  • Значення барів беруться з median_seconds.
  • Колір bar-а залежить від is_slow.
  • Якщо is_slow = true, крок підсвічується warning-кольором як повільний.
  • Поверх барів фронт додатково малює dashed average line.
  • Це середнє значення рахується на фронті як арифметичне середнє всіх median_seconds.
  • Якщо значення велике, фронт форматує його не лише в секундах, а як Xm Ys.
  • Tooltip показує Step, Median, Overall Average, Status.

Audience Platform Segmentation

  • Donut будується по users.
  • percentage не формує сегмент, а використовується як display-значення в legend і tooltip.
  • Колір сегмента жорстко прив’язаний до типу платформи.
  • Підтримані платформи:
    • android
    • ios
    • desktop
  • Невідомі значення не відкидаються: для них використовується fallback unknown.

Technical Errors & Bot Failures

  • Перед рендером фронт нормалізує відповідь до фіксованого порядку категорій:
    • timeout
    • input_error
    • api_fail
    • crm_error
  • Якщо якоїсь категорії немає у відповіді API, фронт однаково додає її в графік із count = 0.
  • Це зроблено, щоб структура графіка не змінювалась від запуску до запуску.
  • Для Y-осі використовуються тільки integer ticks.
  • Людські підписи категорій задаються на фронті:
    • Timeout (Dropped)
    • Input Error (Text not Button)
    • API Fail (TG issues)
    • CRM Error (Sync fail)
  • Tooltip показує назву категорії, загальний Count і всі питання, для яких виникала ця помилка, разом із кількістю помилок для кожного питання.
  • Якщо питань багато, список у tooltip має обмежену висоту та прокручується окремо від сторінки.
  • Для категорій без деталізації tooltip показує порожній стан No question details..

Нюанси цього бота

  • UTM-фільтр впливає не на всі графіки однаково.
  • У поточному фронті UTM передається лише в getMonthSummary, getTrafficLeadsCR, getCplCpa і getFunnel.
  • Графіки getFunnelSteps, getStepMedianResponseTime, getPlatformSegmentation, getTechnicalErrors будуються тільки від Month і ігнорують UTM.

Зв’язки

  • swagger → Hiring Analytics Swagger
  • Фронт викликає такі stack-маршрути:
    • POST /hiring-analytics/getUtmFilters
    • POST /hiring-analytics/getMonthSummary
    • POST /hiring-analytics/getTrafficLeadsCR
    • POST /hiring-analytics/getCplCpa
    • POST /hiring-analytics/getFunnel
    • POST /hiring-analytics/getFunnelSteps
    • POST /hiring-analytics/getStepMedianResponseTime
    • POST /hiring-analytics/getPlatformSegmentation
    • POST /hiring-analytics/getTechnicalErrors

Graph View

Backlinks