Назад в блог

Telegram-бот или push API: уведомления для алертов разработчика

Telegram-бот или push API: уведомления для алертов разработчика

Спросите группу разработчиков, как они получают алерты от своих скриптов, и половина ответит: «Telegram-бот». Он бесплатный, Telegram и так стоит на телефоне, а первое сообщение настраивается за десять минут.

Но это чат, который выполняет работу пейджера. Так продолжается, пока важный алерт не приходит в один поток с групповыми чатами или пока имя файла с подчёркиванием не ломает сообщение. В этой статье честно разобрана настройка Telegram: где он работает, где нет и как тот же алерт выглядит через API push-уведомлений.

Настройка Telegram от начала до конца

  1. Создайте бота. Напишите @BotFather, отправьте /newbot, выберите имя и username, оканчивающийся на bot. Вы получите токен вида 110201543:AAH....
  2. Сначала поздоровайтесь. Боты не могут начать диалог первыми, поэтому откройте бота и отправьте ему любое сообщение. Для группы добавьте бота в группу.
  3. Узнайте chat id. Вызовите getUpdates и возьмите message.chat.id из ответа:
curl -s "https://api.telegram.org/bot$TG_TOKEN/getUpdates" | jq '.result[].message.chat.id'

Обновления хранятся 24 часа, а getUpdates перестаёт работать, как только для бота установлен вебхук. Id групп отрицательные, а id супергрупп начинаются с -100.

  1. Отправьте алерт:
curl -s "https://api.telegram.org/bot$TG_TOKEN/sendMessage" \
  -d chat_id="$TG_CHAT_ID" \
  -d text="Backup failed on db-01"

Это вся интеграция: два секрета в файле окружения и один HTTP-вызов.

Где Telegram работает хорошо

  • Он ничего не стоит. В FAQ Telegram сказано, что боты могут писать своим пользователям бесплатно.
  • Он там, где вы находитесь. Телефон, десктопные и веб-клиенты, всё синхронизировано.
  • Группы бесплатны. Добавьте бота в командный чат, и все увидят алерт и смогут обсудить его в одной ветке.
  • Он уже открыт. Никакого нового приложения и нового аккаунта.

Для несрочных уведомлений вроде «ночной отчёт готов» трудно найти что-то лучше.

Где он неудобен

Все алерты звучат одинаково

У Bot API есть ровно один способ управлять доставкой: disable_notification, который отправляет сообщение без звука. Приоритета нет, уровня «срочно» нет, ничего не пробивает режим «Не беспокоить». Ошибка резервного копирования в 3 часа ночи приходит так же, как стикер в групповом чате, а если отключить звук в чате, чтобы избавиться от шума, вместе с ним отключатся и алерты.

Форматирование будет мешать

При parse_mode=MarkdownV2 символы _ * [ ] ( ) ~ > # + - = | { } . ! и обратный апостроф нужно экранировать обратной косой чертой вне форматирования. А в алертах как раз полно таких символов: имена файлов, номера версий, URL, стек-трейсы. Одна неэкранированная точка в db-01.internal, и Telegram отклоняет сообщение с ошибкой 400, так что алерт о сбое тоже не доходит. Режим HTML безопаснее, но всё равно придётся экранировать <, > и & во всём, что вы отправляете.

Токен — это и есть бот

Токен попадает в путь URL каждого запроса, и документация Telegram прямо говорит: кто его знает, тот управляет вашим ботом. На практике такой URL оказывается в истории оболочки, логах CI и в любом другом месте, куда записываются адреса запросов. Если токен утёк, /token в BotFather выпустит новый, и тогда придётся обновить каждый скрипт.

Кнопки требуют работающего бота

Inline-кнопки могут открывать URL, и это нормально. Кнопка, которая что-то делает, например «перезапустить сервис», использует callback_data, и пока ваш бот не ответит на нажатие, у пользователя крутится индикатор. Значит, должен постоянно работать процесс, который слушает обновления, а это больше, чем хочет иметь cron-задача.

Всплески упираются в лимиты

Telegram просит ботов не превышать одно сообщение в секунду в одном чате и 20 сообщений в минуту в группе. Направьте болтливый вебхук на группу, и получите 429 Too Many Requests с полем retry_after — как раз тогда, когда что-то идёт не так и алерты сыплются быстрее всего.

Сервисы не могут писать в него напрямую

GitHub, Stripe, Grafana и Sentry отправляют вебхуки со своим JSON. Bot API ожидает chat_id и text. Между ними нужен посредник: небольшой сервер, serverless-функция или поток в n8n или Zapier. Этот ретранслятор — ещё одна вещь, которую нужно поддерживать в работе.

Алерты живут в мессенджере

Сообщения бота — обычные сообщения Telegram, которые хранит Telegram и которые смешаны с вашими личными чатами. Чтобы найти инциденты за прошлый месяц, придётся прокручивать чат, а не фильтровать историю по источнику.

Тот же алерт через push API

Вот алерт о резервном копировании, отправленный в Pocket Alert с приоритетом и кнопкой, которая открывает журнал задачи:

curl -X POST https://api.pocketalert.app/v1/messages \
  -H "Token: $PA_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Backup failed",
    "message": "db-01.internal: pg_dump exited with code 1",
    "level": "high",
    "actions": [{ "type": "view", "label": "Open log", "value": "https://ci.example.com/jobs/4821" }]
  }'

Что меняется:

  • Один секрет, в заголовке. API-ключ в заголовке Token, а не токен в URL плюс chat id.
  • Обычный текст на входе и на выходе. Никаких правил экранирования. Точки, подчёркивания и скобки доходят как есть.
  • Приоритет для каждого сообщения. silent, low, default, high или critical. На iPhone high и critical проходят через Фокусирование как уведомления с учётом времени, а на Android критический алерт обходит режим «Не беспокоить». См. критические алерты.
  • Кнопки без бота. До трёх кнопок действий: открыть URL, вызвать HTTP-эндпоинт или скопировать значение. Ничего не нужно держать запущенным, чтобы слушать нажатия.
  • Сервисы отправляют напрямую. У каждого вебхука свой URL. GitHub или Grafana отправляет собственный JSON, а плейсхолдеры вроде %alerts.0.labels.alertname% подставляют поля в уведомление. Каждый вызов записывается в историю вебхуков.
  • Собственная история. Алерты хранятся в отдельном приложении и панели, сгруппированные по приложениям, а не среди ваших чатов.

Когда Telegram всё же лучший выбор

Если говорить честно:

  • Большой объём при ограниченном бюджете. Telegram бесплатен и не имеет дневной квоты, кроме собственных лимитов частоты. На бесплатном тарифе Pocket Alert доступно 50 сообщений в день; больше — на платном тарифе от $6 в месяц.
  • Алерты, которые запускают обсуждение. Если цель — чтобы команда обсуждала алерт прямо там, где он появился, групповой чат с этим справится, а push-уведомление нет.
  • Сначала десктоп и веб. Если вы работаете за ноутбуком, десктопный клиент Telegram показывает алерты там, куда вы и так смотрите. Приложения Pocket Alert рассчитаны на iPhone и Android, а история доступна в веб-панели.

Схема, которая подходит многим командам: держать группу в Telegram для обсуждений и ежедневных сводок, а всё, что должно разбудить человека, отправлять push-уведомлением с уровнем важности.

FAQ

Может ли сообщение от Telegram-бота обойти режим «Не беспокоить»?

Со стороны бота — нет. Bot API не имеет настройки приоритета, есть только disable_notification, которая делает сообщение беззвучным. Пробиться через Фокусирование на iPhone можно только если получатель добавит Telegram в исключения приложений, но тогда пройдут все уведомления Telegram, а не только алерты.

Как узнать свой chat id в Telegram?

Отправьте боту любое сообщение, затем вызовите https://api.telegram.org/bot<token>/getUpdates и возьмите message.chat.id. Если результат пустой, обновление может быть старше 24 часов или у бота установлен вебхук, а при активном вебхуке getUpdates не работает.

Почему мой алерт в Telegram падает с ошибкой 400?

Обычно из-за неэкранированного символа в режиме MarkdownV2 или HTML. Уберите parse_mode, чтобы отправлять простой текст, или экранируйте все зарезервированные символы перед отправкой.

Настроить push API сложнее, чем Telegram-бота?

Примерно так же. В Pocket Alert вы устанавливаете приложение, копируете API-ключ из панели и отправляете один POST-запрос. Искать chat id не нужно, и создавать бота тоже.

Можно ли отправлять в оба сервиса?

Да. Многие команды держат Telegram для обсуждений и отправляют как push-уведомления алерты, требующие реакции. Скрипт может вызывать оба API, а большинство сервисов, которые отправляют вебхуки, принимают более одного URL.

Создайте бесплатный аккаунт Pocket Alert и выполните curl-запрос выше или сначала прочитайте что такое API push-уведомлений. Если вы рассматриваете другие варианты, в обзоре альтернатив есть Pushover, ntfy, Bark, Gotify и другие.

Поделиться статьёй