Форматирование и отправка сообщений в python-telegram-bot.

Представленные здесь фрагменты кода форматирования/отправки сообщений в Teegram применяются как к автоматическому способу получения обновлений (при помощи telegram.ext), так и к ручному (пользовательскому).

Внимание! Пакеты python-telegram-bot версии 13.x будут придерживаться многопоточной парадигмы программирования (на данный момент актуальна версия 13.14). Пакеты версий 20.x и новее будут полностью асинхронными и на октябрь 2022 года, первый из них находится в предрелизе. Дополнительно смотрите основные изменения в пакете python-telegram-bot версии 20.x.

Если используется подмодуль telegram.ext, то можно получить chat_id в функции обратного вызова обработчика с помощью метода update.message.chat_id. Напоминаем, что в функцию обратного вызова обработчика автоматически передаются объекты update и context в качестве аргументов. Доступ к экземпляру bot можно получить из объекта context. Например, для отправки текстового сообщения: context.bot.send_message().

Примечание. Как правило, можно отправлять сообщения пользователям, передавая их идентификатор пользователя в качестве chat_id. Если у бота есть чат с пользователем, то он отправит сообщение в этот чат.

Содержание:

Варианты отправки сообщений в Teegram;
Форматирование сообщения (жирный, курсив, и т.д.);
Обработка сущностей в сообщении (хэштеги, URL-адреса и т.д.).

Варианты отправки сообщений в Teegram.

Отправка текстового сообщения в Teegram.

Доступ к экземпляру bot можно получить из объекта context. Например, для отправки текстового сообщения: context.bot.send_message().

# для версии 13.x 
bot.send_message(chat_id=chat_id, text="Текст сообщения...")
# для версии 20.x
await bot.send_message(chat_id=chat_id, text="Текст сообщения...")

Примечание: метод .send_message (как и любой из методов .send_* класса telegram.Bot()) возвращает экземпляр класса telegram.Message(), поэтому его можно использовать в коде позже.

Дополнительно смотрите описание метода sendMessage в Telegram API.

Ответ на полученное сообщение о время обновления.

# для версии 13.x 
update.message.reply_text("Текст ответа на сообщение.")
# для версии 20.x 
await update.message.reply_text("Текст ответа на сообщение.")

Примечание: метод update.message.reply_text() представляет собой ссылку на метод context.bot.send_message() с теми же значениями по умолчанию и уже переданным chat_id.

Существуют эквиваленты этого метода для ответа на сообщение фотографиями, звуком и т. д., и подобные ссылки существуют во всей библиотеке python-telegram-bot.

Отправка действия в чат.

Чтобы сообщить пользователю, что что-то происходит на стороне бота - используйте следующий код:

# для версии 13.x 
bot.send_chat_action(chat_id=chat_id, action=telegram.constants.ChatAction.TYPING)
# для версии 20.x 
await bot.send_chat_action(chat_id=chat_id, action=telegram.constants.ChatAction.TYPING)

В качестве альтернативы, если есть несколько команд и хочется повторять приведенный выше фрагмент кода во всех командах, то смотрите раздел "Использование декораторов в python-telegram-bot". Там же найдете описание класса constants.ChatAction.

Описание метода sendChatAction в Telegram API

Форматирование сообщения (жирный, курсив, и т.д.).

Telegram поддерживает некоторые параметры форматирования текста. Все подробности о том, что поддерживается, можно найти в официальной документации. Имейте в виду, что придется экранировать специальные символы, как описано в документации. Библиотека python-telegram-bot также предлагает вспомогательную функцию для экранирования текста Markdown. Для экранирования текста HTML можно использовать html.escape из стандартной библиотеки.

Можно форматировать текст с помощью любого метода/типа API, имеющего аргумент parse_mode. В дополнение к редактированию текста, необходимо передавать один из режимов разбора, доступных в классе telegram.constants.ParseMode, в аргумент parse_mode. Начиная с обновления 5.0 Bot API (версия 13.1), также можно передать список telegram.MessageEntities в параметр entity.

Примечание. В обновлении API 4.5 Telegram представил Markdown v2, который поддерживает вложенные объекты и требует другого экранирования, чем Markdown v1. В официальной документации API Markdown v1 упоминается как устаревший режим, следовательно следует предпочесть Markdown v2. Для удобства, не забывайте также использовать метод message.reply_markdown_v2() вместо message.reply_markdown() и т. д.

Отправка текстового сообщения с форматированием Markdown.

# для версии 13.x 
bot.send_message(chat_id=chat_id, 
                 text="*bold* _italic_ `fixed width font` [link](http://google.com)\.", 
                 parse_mode=telegram.constants.ParseMode.MARKDOWN_V2)
# для версии 20.x 
await bot.send_message(chat_id=chat_id, 
                 text="*bold* _italic_ `fixed width font` [link](http://google.com)\.", 
                 parse_mode=telegram.constants.ParseMode.MARKDOWN_V2)

Ответ на сообщение с форматированием Markdown:

# для версии 13.x 
update.message.reply_markdown_v2(text="*bold* _italic_ `fixed "
                                 "width font` [link](http://google.com)\.")
# для версии 20.x 
await update.message.reply_markdown_v2(text="*bold* _italic_ `fixed "
                                 "width font` [link](http://google.com)\.")

Отправка текстового сообщения с форматированием HTML.

# для версии 13.x 
bot.send_message(chat_id=chat_id, 
                 text='<b>bold</b> <i>italic</i> <a href="http://google.com">link</a>.', 
                 parse_mode=telegram.constants.ParseMode.HTML)
# для версии 20.x 
await bot.send_message(chat_id=chat_id, 
                 text='<b>bold</b> <i>italic</i> <a href="http://google.com">link</a>.', 
                 parse_mode=telegram.constants.ParseMode.HTML)

Ответ на сообщение с форматированием HTML:

# для версии 13.x 
update.message.reply_html(text='<b>bold</b> <i>italic</i> ' 
                          '<a href="http://google.com">link</a>.'")
# для версии 20.x 
await update.message.reply_html(text='<b>bold</b> <i>italic</i> ' 
                          '<a href="http://google.com">link</a>.'")

Обработка сущностей в сообщении (хэштеги, URL-адреса и т.д.).

Чтобы обрабатывать сущности в сообщениях, необходимо использовать класс telegram.MessageEntity. Для этого нужно извлечь сущности и соответствующий им текст из объекта telegram.Message с помощью telegram.Messag.parse_entities.

Объект telegram.MessageEntity представляет собой специальную сущность в текстовом сообщении. Например, хэштеги, имена пользователей, URL-адреса и т.д.

`Messag.parse_entities(types=None)`:

Метод Messag.parse_entities() возвращает dict, который сопоставляет telegram.MessageEntity со строкой. Он содержит сущности из этого сообщения, отфильтрованные по их атрибуту telegram.MessageEntity.type в качестве ключа, и текст, которому принадлежит каждая сущность, в качестве значения dict.

Обратите внимание, что этот метод всегда следует использовать вместо атрибута entities, поскольку он вычисляет правильную подстроку из текста сообщения на основе кодовых точек UTF-16.

Аргумент types (List[str], необязательный) - список типов telegram.MessageEntity в виде строк. Если атрибут type объекта содержится в этом списке, то он будет возвращен. По умолчанию - это список всех типов.

Рассмотрим пример, который проверяет наличие URL-адресов в сообщении и печатает их на экране.

# Словарь, который отображает сущность в текст
entities = message.parse_entities()
for ent in entities:
    txt = entities[ent]
    if ent.type == ent.TEXT_LINK:
        # Текст со встроенным URL
        print(f"{txt} - {ent.url}")
    elif ent.type == ent.URL:
        # Обычный URL
        print(txt)

Для таких вещей, как извлечение только ссылок из сообщений Telegram, лучше использовать стороннее расширение ptbcontrib.extract_urls.

Предоставляет два метода, позволяющих легко извлекать гиперссылки из сообщений.

Поддерживает:

как простые ссылки, так и объекты сообщений,
как обычные сообщения, так и подписи,
извлечение исключительно прямых ссылок на сообщения Telegram.