Привет!

Сегодня я расскажу вам о том, как упростить процесс отправки уведомлений в Telegram с помощью новой библиотеки — easy_async_tg_notify. Если вы, как и я, часто сталкиваетесь с необходимостью отправки сообщений через Telegram от различных сервисов (проектов, скриптов), то это руководство будет для вас полезным.

Простые асинхронные уведомления в Telegram с easy_async_tg_notify

Часто в проектах требуется отправка уведомлений в Telegram, будь то текстовые сообщения, фото, документы или другие файлы. Раньше, в подобных случаях, я использовал стандартные запросы к Telegram API и описывал каждый случай отдельно (отправка текста, фото и т.д.). Но теперь есть более простой и гибкий способ благодаря библиотеке easy_async_tg_notify.

Что такое easy_async_tg_notify?

easy_async_tg_notify — это библиотека, упрощающая отправку уведомлений в Telegram бота. Она поддерживает отправку различных типов сообщений и работает асинхронно, что позволяет удобно работать с несколькими уведомлениями одновременно.

На данный момент в библиотеке реализованы следующие методы:

• send_text — отправка текстовых сообщений с форматированием.

• send_photo — отправка фото с подписью и без.

• send_document — отправка документа с подписью и без.

• send_audio — отправка аудио с подписью и без.

• send_video — отправка видео с подписью и без.

• send_venue — отправка информации о месте.

• send_contact — отправка контактных данных.

Подготовка к работе

1. Создайте токен бота через BotFather:

• Откройте Telegram и найдите @BotFather.

• Начните чат и отправьте команду /newbot.

• Следуйте инструкциям для создания бота и получите токен API.

  Более детально вопрос получения токена бота описывал в этой статье: Telegram Боты на Aiogram 3.x: Первые Шаги

2. Создайте файл .env для хранения переменных окружения:

TELEGRAM_BOT_TOKEN=ваш_токен
TELEGRAM_CHAT_ID=ваш_id
TELEGRAM_CHAT_IDS=ваш_id,другой_id,третий_id

Используйте TELEGRAM_CHAT_ID для отправки уведомлений только одному пользователю, а TELEGRAM_CHAT_IDS — для нескольких пользователей.

3. Получите свой Telegram ID:

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

   Для того чтоб узнать свой собственный телеграмм айди вам достаточно перейти в бота и нажать на «Старт»

BotFatherДля того чтоб узнать телеграмм айди другого пользователя нажмите на кнопку User и выберите пользователя ID которого вы хотите узнать.

Кроме того, данный бот позволяет узнать ID группы и канала, что так-же может быть полезным.

Кстати, хотите я вам покажу в отдельной статье как создать своего собственного бота на aiogram3, который позволит выполнять ту же функциональность, что у IDBot? Если да, то напишите об этом в комментариях.

Полученные данные поместите в .env файл.

Важный момент

Для того чтоб была возможность отправки уведомлений необходимо сделать так, чтоб бот был «знаком» с пользователем, каналом или группой.

С пользователями все проще. Достаточно вам или всем кого вы привяжете на уведомления, зайти в бота, которого вы создали, и 1 раз нажать на «Старт». После этого у бота появится возможность отправки таким пользователям уведомлений.

Что касается каналов и групп, там необходимо бота отдельно будет назначать администратором.

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

Установка библиотеки

Установите easy_async_tg_notify с помощью pip:

pip install --upgrade easy_async_tg_notify

Такая конструкция позволит вам установить актуальную и самую последнюю версию библиотеки.

Вместе с установкой подтянется httpx для асинхронных POST и GET запросов, aiofiles для асинхронной работы с файлами (байтами) и python-decouple для удобной работы с файлом .env.

Ссылку на проект с данной библиотекой на GitHub вы найдете в моем телеграмм канале «Легкий путь в Python».

Начнем писать код

Импортируем необходимые модули:

import asyncio
import os
from decouple import config
from easy_async_tg_notify import Notifier

Настроим переменные:

token = config('TELEGRAM_BOT_TOKEN')
user_id = int(config('TELEGRAM_CHAT_ID'))
users_ids = [int(id) for id in config('TELEGRAM_CHAT_IDS').split(',')]

script_dir = os.path.dirname(os.path.abspath(__file__))
photo = os.path.join(script_dir, 'telegram-logo-27.png')

Фото я импортировал для тестов. Это может быть любой другой файл.

Теперь мы можем написать свою первую асинхронную функцию для отправки сообщений. Давайте выполним отправку простого текстового уведомления одному пользователю.

async def send_msg(msg_text: str):
    async with Notifier(token) as notifier:
        await notifier.send_text(msg_text, user_id)

В данном случае мы воспользовались методом send_msg. Он принимает текст сообщений, телеграмм айди пользователя и parse_mode, который по умолчанию равен HTML.

Можно передавать как просто user_id, так и список из user_id.

Отправим уведомление.

asyncio.run(send_msg('Привет, Хабр! Это тестовое уведомление в бота'))

В логах увидим следующее:

2024-07-26 15:29:16,189 - INFO - HTTP Request: GET https://api.telegram.org/BotSercretToken/sendMessage?chat_id=5127841744&text=%D0%9F%D1%80%D0%B8%D0%B2%D0%B5%D1%82%2C%20%D0%A5%D0%B0%D0%B1%D1%80%21%20%D0%AD%D1%82%D0%BE%20%D1%82%D0%B5%D1%81%D1%82%D0%BE%D0%B2%D0%BE%D0%B5%20%D1%83%D0%B2%D0%B5%D0%B4%D0%BE%D0%BC%D0%BB%D0%B5%D0%BD%D0%B8%D0%B5%20%D0%B2%20%D0%B1%D0%BE%D1%82%D0%B0&parse_mode=HTML "HTTP/1.1 200 OK"
2024-07-26 15:29:16,190 - INFO - Сообщение отправлено в чат 5127841744.

Для отправки форматированного уведомления можно использовать теги. Так как форматирование HTML по умолчанию у нас прекрасно сработает такой код:

asyncio.run(send_msg('Привет, <b>Хабр</b>! Это тестовое уведомление в бота c HTML форматированием'))

Теперь немного усложним задачу. Добавим фото с подписью, которое будет отправлено через 1 секунду после отправки текстового сообщения.

async def send_msg_photo(msg_text: str, caption: str):
    async with Notifier(token) as notifier:
        await notifier.send_text(msg_text, user_id)
        await asyncio.sleep(1)
        await notifier.send_photo(photo_path=photo, to_chat_ids=user_id, caption=caption)

При отправке фото или любого другого медиафайла, можно отправить подпись (caption).

Запустим функцию

asyncio.run(send_msg_photo('<b>Хабр</b>, это демонстрация отправки 2 сообщений.', 'Моя подпись к фото'))

Логи

2024-07-26 15:42:39,256 - INFO - HTTP Request: GET https://api.telegram.org/BotSecretToken/sendMessage?chat_id=5127841744&text=%3Cb%3E%D0%A5%D0%B0%D0%B1%D1%80%3C%2Fb%3E%2C%20%D1%8D%D1%82%D0%BE%20%D0%B4%D0%B5%D0%BC%D0%BE%D0%BD%D1%81%D1%82%D1%80%D0%B0%D1%86%D0%B8%D1%8F%20%D0%BE%D1%82%D0%BF%D1%80%D0%B0%D0%B2%D0%BA%D0%B8%202%20%D1%81%D0%BE%D0%BE%D0%B1%D1%89%D0%B5%D0%BD%D0%B8%D0%B9.&parse_mode=HTML "HTTP/1.1 200 OK"
2024-07-26 15:42:39,257 - INFO - Сообщение отправлено в чат 5127841744.
2024-07-26 15:42:40,588 - INFO - HTTP Request: POST https://api.telegram.org/BotSecretToken/sendPhoto "HTTP/1.1 200 OK"
2024-07-26 15:42:40,589 - INFO - Photo отправлен в чат 5127841744.

Данные успешно отправлены. Лгика отправки файлов, контактов и прочие методы особо не будут отличаться от приведенных выше примеров.

Использование в синхронных проектах

Если вы работаете с синхронным кодом, вы можете использовать asyncio.run:

def sync_funk():
    print('Тут какая-то логика')
    time.sleep(2)
    asyncio.run(send_msg_photo('<b>Хабр</b>, это демонстрация отправки 2 сообщений.', 'Моя подпись к фото'))
    time.sleep(1)
    print('Скрипт завершен')

    
sync_funk()

Заключение

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

Если данная библиотека показалась вам полезной - ставьте лайки, подписывайтесь и оставляйте комментарии. Этого будет достаточно, чтоб мотивировать меня писать новые подобные библиотеки и подробные обзоры на них.

До скорого!