Автозвіти в Telegram: щоденні KPI без відкриття дашборда

Більшість власників малого бізнесу живуть у Telegram. Дашборд можна відкрити раз на тиждень, а повідомлення від бота о 8:00 прочитають щодня. Тому я майже завжди доповнюю дашборд коротким автозвітом — і часто саме він стає головним інструментом.

#Що має бути в ранковому зведенні

Правило: зведення читається за 15 секунд. Не більше 5–7 рядків:

1. 3–4 головні KPI за вчора з порівнянням (з тим самим днем тижня або середнім за 4 тижні).
2. Одне-два відхилення, що потребують уваги, з поясненням.
3. Посилання на розділ дашборда.

DATUMPANEL · Вівторок, 14 жовтня
Виручка: 52 300 ₴ (+11% до мин. вівторка)
Замовлень: 66 · середній чек 792 ₴
Витрати на рекламу: 11 900 ₴ · MER 4,4
⚠ Meta: CPC +38% за 3 дні — новий креатив вигорає
→ Відкрити маркетинг

Цифри умовні.

#Які звіти бувають

#Як формулювати аномалії

Погано: «Конверсія −18%». Добре: «Конверсія з мобільних −18% (iOS). Checkout на iOS завантажується довше. Перевірте останній реліз».

Правила для алертів:

• поріг відносно норми, а не фіксований: падіння нижче середнього за 4 тижні того ж дня тижня мінус 2 стандартних відхилення;
• мінімальний обсяг — не сповіщати про −50% на 4 замовленнях;
• дедуплікація — не слати те саме щогодини;
• пояснення — розбивка, де саме сталося (канал, пристрій, категорія). Тут добре працює ШІ-асистент, що формулює причину простою мовою.

#Як це працює технічно

1. Пайплайн оновлює вітрини вночі (ETL).
2. Планувальник (cron) о 7:55 запускає скрипт звіту.
3. Скрипт читає вітрину daily_kpi, рахує порівняння, перевіряє правила аномалій.
4. Повідомлення надсилається методом sendMessage Telegram Bot API у чат користувача або групу.

import os, requests

TOKEN = os.environ["TELEGRAM_BOT_TOKEN"]  # лише зі змінних середовища сервера

def send(chat_id: int, text: str) -> None:
    r = requests.post(
        f"https://api.telegram.org/bot{TOKEN}/sendMessage",
        json={"chat_id": chat_id, "text": text, "parse_mode": "HTML", "disable_web_page_preview": True},
        timeout=10,
    )
    r.raise_for_status()

Важливі деталі:

• бот може писати користувачу лише після того, як той натиснув Start — це обмеження Telegram;
• у групах бота треба додати, а для читання повідомлень — налаштувати режим приватності;
• для форматування використовуйте HTML-режим і екрануйте <, >, & у даних;
• Telegram обмежує частоту відправки — для сотень отримувачів потрібна черга.

#Безпека

• Токен бота — секрет. Зберігайте лише в змінних середовища сервера, ніколи в коді, репозиторії чи фронтенді.
• Якщо токен потрапив у чат чи скріншот — перевипустіть його через @BotFather.
• Звіти з фінансами — лише в особисті чати або закриті групи з контрольованим складом.
• Зберігайте список chat_id з ролями: хто отримує які звіти.
• Не передавайте персональні дані клієнтів у повідомленнях — лише агрегати.

#Налаштування для користувача

У кабінеті DATUMPANEL користувач сам вказує свій Telegram ID і обирає звіти та розклад. Щоб дізнатися ID, достатньо написати боту на кшталт @userinfobot; щоб бот міг писати — натиснути Start у боті кабінету.

#Типові помилки

• Звіт на 30 рядків, який перестають читати через тиждень.
• Алерти без порогу обсягу — шум і «втома від сповіщень».
• Токен у фронтенд-коді або публічному репозиторії.
• Звіт без посилання на деталі.
• Звіт приходить, коли дані ще не оновились.

#Чекліст

• Ранкове зведення — до 7 рядків
• Порівняння з тим самим днем тижня
• Алерти з порогом відносно норми і мінімальним обсягом
• Звіт запускається після успішного оновлення даних
• Токен — лише на сервері
• Отримувачі й ролі задокументовані
• Посилання на дашборд у кожному повідомленні

#Покроково: бот ранкового звіту

Якщо дані вже у сховищі, все налаштовується за пів дня:

1. Створіть бота через @BotFather і збережіть токен як секрет у планувальнику чи середовищі сервера — ніколи в коді.
2. Додайте бота в групу (або нехай кожен отримувач почне з ним чат) і запишіть chat ID.
3. Напишіть запит, що повертає вчорашні числа і порівняння.
4. Сформуйте повідомлення — короткий текст на кілька рядків і, за бажанням, одна картинка-графік.
5. Заплануйте запуск після оновлення даних і перевірок, із запасним повідомленням, якщо вони не пройшли.

import os, requests

def send(chat_id: str, text: str) -> None:
    url = f"https://api.telegram.org/bot{os.environ['TG_BOT_TOKEN']}/sendMessage"
    r = requests.post(url, json={"chat_id": chat_id, "text": text,
                                 "parse_mode": "HTML", "disable_web_page_preview": True}, timeout=15)
    r.raise_for_status()

def fmt(v, prev):
    d = (v - prev) / prev * 100 if prev else 0
    arrow = "▲" if d >= 0 else "▼"
    return f"{v:,.0f} ({arrow}{abs(d):.0f}%)".replace(",", " ")

row = query_yesterday()   # виручка, замовлення, реклама, маржа + той самий день минулого тижня
text = (
    f"<b>Вчора, {row.day:%d.%m}</b>\n"
    f"Виручка: {fmt(row.revenue, row.revenue_lw)} грн\n"
    f"Замовлення: {fmt(row.orders, row.orders_lw)}\n"
    f"Реклама: {fmt(row.spend, row.spend_lw)} грн\n"
    f"Маржа після реклами: {fmt(row.margin, row.margin_lw)} грн\n"
    f"{row.note}\n"
    f"<a href=\"{DASHBOARD_URL}\">Дашборд</a>"
)
send(CHAT_ID, text)

Найцінніше — рядок note: одне речення за правилами, наприклад «Витрати Meta +40% при незмінних замовленнях», «Немає замовлень з Google Ads з 14:00» чи «Усі канали в межах норми». Параметри форматування й обмеження — в документації Bot API.

#Приклад: щотижневий звіт власнику

П'ять рядків, і кожне число пов'язане з рішенням, яке може ухвалити власник. Рядок «Дія» необов'язковий, але власники частіше діють за звітами, де він є.

#Правила сповіщень про аномалії

Надсилайте сповіщення в інший чат, ніж щоденний звіт, щоб вони не губилися, і тримайте список коротким. Якщо сповіщення спрацьовує щодня — виправте поріг або приберіть його.

#Хто що отримує

Один звіт для всіх — звична перша версія, і її рідко читають довго. Краще розділити:

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

#Графіки в повідомленнях

Невеликий графік допомагає, коли форма важливіша за число, — наприклад, тренд виручки за 14 днів. Згенеруйте його на сервері як PNG (підійде будь-яка бібліотека графіків) і надішліть через sendPhoto. Тримайте його простим: одна лінія, світлий фон, великі підписи, які читаються на телефоні, і підписане останнє значення. Щонайбільше один графік на повідомлення — решта має жити в дашборді.

#Мова і тон звіту

Звіт пишіть мовою команди і без жаргону. «Конверсія в оплату впала до 1,2% (зазвичай 1,6%)» зрозуміліше за «CR −25% WoW». Позначайте не лише погане, а й нормальне: рядок «усе в межах норми» щодня вчить довіряти звіту, а не лише лякатися його.

#Часті запитання

#Чи можна отримувати графіки, а не лише текст?

Так, бот може надсилати зображення (sendPhoto) — наприклад, PNG-графік тренду. Але для щоденного зведення текст читається швидше.

#Чи безпечно надсилати фінансові дані в Telegram?

За умови, що звіт іде в особистий чат чи закриту групу, токен захищено, а персональних даних клієнтів у повідомленні немає. Для чутливих компаній можна обмежитись відсотками без абсолютних сум.

#Скільки коштує бот?

Telegram Bot API безкоштовний. Витрати — лише на сервер, де працює скрипт, і на налаштування.

#Чи можна те саме в Slack чи email?

Так, логіка та сама — змінюється лише канал доставки.