Используем Telegram Bot API для уведомлений от сервера

Когда на сервере настроено уже совсем всё, а повозиться ещё хочется, очевидно, что настало время приводить в порядок отчёты. Это такая предпоследняя стадия DevOps болезни. Последняя стадия — это документация, но до неё, по-моему, вообще никто не доживает, поэтому инженеры придумали отговорку “docs as code”.

¹ Cосиски сами на себя скидку не найдут.

² Buddy — это CI/CD SaaS работающий по типу Travis и заточенный под сборку и деплой веб-сайтов.

Практически во всех современных серерных приложениях для CI/CD уже есть поддержка уведомлений через имеил, или тимчатики вроде Slack, или Gitter. Есть даже куча экзотических интеграций, которые реализованы через плагины, и расширения. Я же столкнулся с ситуацией когда отчёты нужно слать от лица самописного сервера¹ и от новёхонького, «ещё не трендового» buddy.works², который на момент написания заметки умел только имейл.

Ума не приложу зачем бы мне хотелось хранить в своём ящике отчёты о провалившихся попытках сборки и публикации крошечного веб-сайта.

³ Ещё 2-3 года назад для подобных целей я использовал Pushbullet, но из-за своих бесконечных пивотов они, по-моему, сами запутались в собственном продукте и теперь позиционируют его как “SMS on PC”. Что на чём?!

С Telegram Bot API³ у меня за 10 минут получилось отправить уведомление в любимый мессенджер. Это «дёшево», платформонезависимо и, вообще: создано для того, чтобы все кругом этим пользовались. Особенно после того как появится достаточное количество сторонних библиотек фокусирующих тамошнюю рутину на конкретных задачах.

Прежде чем инвестировать это время, знайте, что за 10 минут можно научиться, например, ориентироваться в пространстве по звёздам, что значительно более полезно. Особенно, если вы флибустьер, живёте в 17 веке и у вас есть любимый абордажный крюк.

Будем честны: самое сложное, что прилетит к вам в чатик через 10 минут будет “Hello World!”

Arrr!

1. Основы

⁴ Потому что стабильных истербителей для продолжения начатой аналогии не существует.

Telegram Bot API это типичный RESTful полностью соответствующий философии самого мессенджера. Это значит, что интерфейс простой, как русский истребитель, быстрый, как американский истребитель и стабильный, как злой брат-близнец российской экономики⁴. Фактически, всё что вам необходимо сделать для скорейшей отправки своего первого сообщения в чат через API — открыть специальным образом составленный URL из адресной строки браузера. URL может выглядеть примерно так:

https://api.telegram.org/bot202476:AAFnfWKwWbMkxLsTydJHyO58Zca/sendMessage?chat_id=14760083&text=Hello+World!

Для того, чтобы это сделать, помимо текста сообщения, понадобится ещё уникальный токен вашего бота и ID чата, в который сообщение будет отправлено.

2. Регистрируем собственного бота и получаем его токен

I’m gonna make you an offer you can’t refuse

Для того, чтобы зарегистрировать собственного бота в Telegram, вам понадобится помощь другого бота, которого зовут BotFather. Он предложит придумать имя, которое будет отображаться в списке контактов и юзернейм ботонейм по которому ваш бот будет доступен через ссылки и в поиске. Позже, при помощи BotFather, можно будет изменять специфические настройки бота, или установить для него юзерпик ботопик.

На последнем шаге регистрации вы получите токен необходимый для авторизации бота.

3. Получаем ID чата

Не смотря на то, что бот пока ничего не умеет, сейчас он уже доступен для поиска и добавления в чаты.

• Добавьте его в свой список контактов. Проще всего это сделать пройдя по ссылке вида t.me/botname
• Отправьте ему любое сообщение
• Через браузер открывайте ссылку https://api.telegram.org/bot%TOKEN%/getUpdates заменив %TOKEN% на строку, которую вам выдал BotFather ранее

Вы увидите JSON, который будет содержать все необходимые данные о последнем сообщении.

{
    "ok":true,
    "result": [{
        "update_id":850632785496,
        "message": {
            "message_id":81,
            "from": {
                "id":629040432,
                "first_name":"Mikhail",
                "last_name":"Sannikov",
                "username":"Atarity"
            },
            "chat": {
                "id":629040432,
                "first_name":"Mikhail",
                "last_name":"Sannikov",
                "username":"Atarity",
                "type":"private"
            },
            "date":1486899978,
            "text":"Go!"
        }
    }]
}

Из этих данных интерес для вас представляет поле id из группы chat. Всё: токен и ID чата у нас на руках. Теперь можно слать в него сообщения уже от лица бота.

4. Hello World

URL для отправки сообщения конструируется таким образом:

https://api.telegram.org/bot%TOKEN%/sendMessage?chat_id=%CHAT_ID%&text=Hello+World!

Согласно API можно передавать значительно больше параметров и даже использовать простейшее форматирование для текста, но для Hello World всё это не понадобится. В общем: it works!

5. Выполянем из .sh

⁵ API позволяет ботам присылать вам файлы, картинки и пр. Например, можно прикрепить к сообщению файл с логами или консольный вывод с которым на сервере умер ваш скрипт.

Чтобы превратить посылку сообщений из браузера в по-настоящему полезные уведомления или даже отчёты⁵ придётся закопаться чуть глубже. Проверьте, что на хосте установлен curl.

Если речь, про сборку чего бы то ни было, например сайта, внутри вашего CI/CD пайплайна, то простейший bash-скрипт для короткого отчёта может выглядеть так:

# Заранее определены в env:
# TG_KEY — токен бота в телеграм
# CHAT_ID — ID чата
# TMP_STIME — системное время начала сборки
# TMP_COMMITS_COUNT — количество коммитов в репозитории
# TMP_COMMIT_MESSAGE — сообщение коммита из которого происходит сборка
# GITHUB_SHA — SHA подпись коммита

ELATIME=$(( $(date +%s) - $TMP_STIME ))
TMSTR="$(printf '%dm:%ds\n' $(($ELATIME%3600/60)) $(($ELATIME%60)))"
URL="https://api.telegram.org/bot$TG_KEY/sendMessage"
TTL="10"
PARSER="Markdown"
TEXT="*%F0%9F%8E%AA STAGING SUCCESS* %0Acommit *#$TMP_COMMITS_COUNT* with message \`$TMP_COMMIT_MESSAGE\` done and deployed in *$TMSTR*. %0ARev. $GITHUB_SHA %0Ahttps://st.snnkv.com"
curl -s --max-time $TTL -d "chat_id=$CHAT_ID&parse_mode=$PARSER&disable_web_page_preview=1&text=$TEXT" $URL >/dev/null

Впервые я использовал такого бота для того, чтобы получать статусы о сборке и деплое этого самого сайта через Buddy. Обратите внимание на то, как сделаны переводы строк в сообщении — всё содержимое посылки должно быть url-кодировано. Ещё в этом конкретном случае применяется Markdown для расстановки жирности.

Вот так полученные уведомления выглядят у меня в телефоне.

6. Бонус: Эмодзи

Если вы хотите использовать эмодзи в своих сообщениях, не достаточно просто отправить что-то типа :scream:. Чтобы парсер распознал эмодзи, они тоже должны быть url-кодированы. Для этого нужно открыть таблицу эмодзи и найти там нужный символ и в содержимом колонки Bytes (UTF-8) заменить все \x на %. Например, для :scream: строка \xF0\x9F\x98\xB1 превратиться в %F0%9F%98%B1.

7. Итог

Простой и довольно гибкий способ станет ещё лучше после того как погромисты напишут для него миллион обёрток. А пока, подытожим:

1. Регистрируешь бота при помощи бота
2. Начинаешь с ним диалог из чата в который хочешь получать уведомления
3. Шлёшь любую бурду однострочной командой используя лишь токен и идентификатор чата

⚠️ Каменты в режиме эксперимента. Нужна регистрация на GitHub и необходимо дать разрешение боту Giscus. Если это неприемлемо, можно комментировать прямо на GitHub.