Обработчики взаимодействия с ботом в aiogram

Обновления в телеграм боте

Каждый раз, когда пользователь отправляет сообщение или выполняет какое-либо действие в чате, Telegram сервер генерирует обновление и отправляет его боту. AIOGram отвечает за асинхронную обработку этих обновлений.

Обновления в AIOGram представляются в виде объектов определенных классов, предоставляемых библиотекой aiogram. Каждый класс соответствует определенному типу обновления (например, сообщение, команда, запрос о подтверждении и т. д.). Объекты обновлений содержат информацию о событии, такую как идентификатор чата, идентификатор пользователя, текст сообщения, тип медиа и другие данные, необходимые для обработки события.

Примеры различных типов обновлений, которые могут быть обработаны AIOGram:

1. Обновление сообщения (MessageUpdate):
Включает информацию о текстовом сообщении, отправленном пользователем.

2. Обновление команды (CommandUpdate):
Содержит информацию о команде, которую пользователь отправил боту. Например, когда пользователь отправляет «/start» или «/help».

3. Обновление запроса о подтверждении (CallbackQueryUpdate):
Используется для обработки нажатий на кнопки с подтверждением (inline keyboards) в сообщениях бота.

4. Обновление редактирования сообщения (EditedMessageUpdate):
Происходит, когда пользователь редактирует уже отправленное ранее сообщение.

5. Обновление входа/выхода участников из группы (ChatMemberUpdate):
Содержит информацию о том, когда новый пользователь входит в чат или когда существующий пользователь покидает чат.

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

Примеры, приведенные в этой статье работают на версии aiogram 2x

Обработка обновлений. message_handler и его параметры

Функция message_handler из библиотеки aiogram используется для создания обработчиков входящих сообщений. Она принимает несколько параметров, которые позволяют настроить условия, при которых обработчик будет вызываться. Вот список основных параметров, которые могут быть использованы с message_handler:

1. commands: Список команд, на которые обработчик будет реагировать. Команды должны начинаться с символа «/», например, commands=['start', 'help'].

2. commands_prefix: Префикс, который будет использоваться для обработки команд. По умолчанию равен «/».

3. content_types: Список типов контента, которые обработчик будет обрабатывать. Например, content_types=[types.ContentType.TEXT, types.ContentType.PHOTO]. Если не указан, обработчик будет реагировать на все типы контента.

4. regexp: Паттерн регулярного выражения, с помощью которого можно обрабатывать сообщения, соответствующие заданному шаблону. Например, regexp=r"^hello\s\d+" будет обрабатывать сообщения, начинающиеся с «hello», за которыми идет одна или более цифр.

5. text: Точный текст, который должен содержаться в сообщении, чтобы обработчик был вызван. Например, text="привет" будет обрабатывать сообщения, содержащие точный текст «привет».

6. text_contains: Подстрока, которую должно содержать сообщение, чтобы обработчик был вызван. Например, text_contains="привет" будет обрабатывать сообщения, содержащие слово «привет».

7. state: Состояние, в котором должен находиться пользователь, чтобы обработчик был вызван. Может быть использован для реализации машины состояний.

8. is_reply: Флаг, указывающий, должно ли сообщение быть ответом на другое сообщение.

9. is_forwarded: Флаг, указывающий, является ли сообщение пересланным сообщением.

10. user_id: Идентификатор пользователя, от которого должно быть получено сообщение.

11. chat_id: Идентификатор чата, в котором должно быть получено сообщение.

12. chat_type: Тип чата, в котором должно быть получено сообщение (например, `types.ChatType.PRIVATE`, `types.ChatType.GROUP` и т. д.).

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

Приоритет обработчиков

Приоритет обработчиков в AIOGram определяется порядком их определения в коде. Когда обновление (например, текстовое сообщение) попадает под условия нескольких обработчиков, будет вызван первый обработчик, который был определен и соответствует условиям данного обновления.

Пример. Даны три обработчика, которые готовы обработать введенную команду /help. Какой обработчик в итоге сработает?

@dp.message_handler(regexp=r'^/help\d*')
async def handle_regexp(message: types.Message):
    await message.answer('Ваше сообщение начинается с текста "/help"')


@dp.message_handler(commands=['help'])
async def handle_help(message: types.Message):
    # Отправляем сообщение с инструкциями по использованию бота
    help_message = """
    Привет! Я бот.
    Вот некоторые доступные команды:
    - /start: Начать взаимодействие с ботом
    - /help: Получить справку о командах бота
    """
    await message.reply(help_message)


@dp.message_handler(text_contains='help')
async def handle_contain(message: types.Message):
    await message.answer('Ваше сообщение содержит текст "help"')

Сработает тот, который идет первым в коде — @dp.message_handler(regexp=r'^/help\d*')

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

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

Обработка текстовых сообщений

В AIOGram обработчики входящих сообщений реализуются с помощью декораторов. Декораторы — это специальные функции, которые позволяют изменить поведение другой функции, добавляя к ней дополнительную логику или функциональность.

Для создания обработчика входящего сообщения вы должны использовать декоратор message_handler из библиотеки aiogram. Этот декоратор позволяет указать, какие типы сообщений обработчик будет обрабатывать (текстовые сообщения, аудио, фото и т. д.) и какие условия должны быть выполнены, чтобы вызвать этот обработчик.

Вот пример простого обработчика входящего текстового сообщения:

import asyncio
from aiogram import Bot, Dispatcher, types
from aiogram.types import Message

# Вставьте сюда токен вашего бота
BOT_TOKEN = 'YOUR_BOT_TOKEN'

# Инициализация бота и диспетчера
bot = Bot(token=BOT_TOKEN)
dp = Dispatcher(bot)

# Обработчик текстовых сообщений
@dp.message_handler(content_types=types.ContentType.TEXT)
async def on_text_message(message: Message):
await message.answer(f"Вы написали: {message.text}")

async def main():
# Старт асинхронного цикла
await dp.start_polling()

if __name__ == '__main__':
asyncio.run(main())

В приведенном выше примере мы определили обработчик on_text_message, который реагирует на текстовые сообщения. Когда пользователь отправляет текстовое сообщение, обработчик вызывается, и в ответ на сообщение отправляется ответ с тем же текстом, что был получен от пользователя.

Обратите внимание, что в декораторе @dp.message_handler(content_types=types.ContentType.TEXT) мы указали, что обработчик реагирует только на текстовые сообщения (тип контента text). Вы можете настроить обработчик так, чтобы он реагировал на различные типы контента, такие как аудио, фото, видео и другие.

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

Обработка команд

Как отличить команду от текстового сообщения

Обработчик текстовых сообщений также будет реагировать на команды бота, так как команды бота являются частным случаем текстовых сообщений. Команды бота начинаются с символа «/», например, «/start», «/help» и т. д.

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

Для того чтобы обработать команды бота отдельно от обычных текстовых сообщений, вы можете использовать декоратор message_handler из библиотеки aiogram с параметром commands. Этот декоратор позволяет определить обработчики именно для команд бота.

Вот пример кода с использованием message_handler+commands:

import asyncio
from aiogram import Bot, Dispatcher, types

# Вставьте сюда токен вашего бота
BOT_TOKEN = 'YOUR_BOT_TOKEN'

# Инициализация бота и диспетчера
bot = Bot(token=BOT_TOKEN)
dp = Dispatcher(bot)

# Обработчик команды /start
@dp.message_handler(commands=['start'])
async def on_start(message: types.Message):
await message.answer("Привет! Я ваш телеграм бот.")

# Обработчик команды /help
@dp.message_handler(commands=['help'])
async def on_help(message: types.Message):
await message.answer("Это помощь для бота.")

# Обработчик текстовых сообщений
@dp.message_handler(content_types=types.ContentType.TEXT)
async def on_text_message(message: types.Message):
await message.answer(f"Вы написали: {message.text}")

async def main():
# Старт асинхронного цикла
await dp.start_polling()

if __name__ == '__main__':
asyncio.run(main())

В приведенном выше примере мы определили два обработчика команд /start и /help, а также обработчик для текстовых сообщений. Теперь, когда пользователь отправляет команду /start или `/help`, соответствующий обработчик будет вызван и выполнит необходимые действия. Если пользователь отправляет другую команду или текстовое сообщение, будет вызван обработчик on_text_message.

Если пользователь введет не команду /start, а напишет просто start, что произойдет?

В приведенном мной примере, если пользователь введет не команду /start, а просто слово «start», то это сообщение будет обработано обработчиком on_text_message, так как обработчик команды `/start` определен только для полного текста «/start».

Вот как будет происходить обработка:

1. Если пользователь отправит команду /start:
Обработчик `on_start` будет вызван, и бот отправит ответ «Привет! Я ваш телеграм бот.»

2. Если пользователь отправит просто «start» или любой другой текст:
Обработчик on_text_message будет вызван, и бот отправит ответ «Вы написали: [текст сообщения]».

Таким образом, если пользователь введет текст, не являющийся точным соответствием одной из определенных команд (например, «/start» или «/help»), он будет рассматриваться как обычное текстовое сообщение и будет обработан обработчиком on_text_message.

Для того чтобы более точно обрабатывать входящие команды и исключать возможность путаницы с обычными текстовыми сообщениями, вы можете использовать декоратор commands_handler с параметром `commands_prefix=»/»`:

from aiogram import Bot, Dispatcher, types

# ...

# Обработчик команды /start
@dp.message_handler(commands=['start'], commands_prefix="/")
async def on_start(message: types.Message):
await message.answer("Привет! Я ваш телеграм бот.")

# ...

Теперь обработчик команды /start будет реагировать только на точное совпадение «/start», и просто «start» будет рассматриваться как обычное текстовое сообщение. Это поможет избежать путаницы и более точно обрабатывать входящие команды.

Обработка кнопки, привязанной к сообщению (Inline Keyboard Button)

Под кнопкой с подтверждением (Inline Keyboard Button) понимается интерактивный элемент в сообщениях Telegram, который позволяет пользователям нажимать на кнопку и отправлять обратную связь боту. Кнопка с подтверждением находится прямо внутри текста сообщения и может быть использована для различных целей, таких как отправка команд, выбор опций, ответ на вопросы и многое другое.

Основные характеристики кнопки с подтверждением:

1. Текст кнопки: Это текст, который отображается на кнопке и виден пользователю.
2. Callback Data: Каждая кнопка с подтверждением связана с определенной строкой данных (Callback Data). Когда пользователь нажимает на кнопку, эта строка данных отправляется обратно боту вместе с информацией о событии. Это позволяет боту определить, какую кнопку нажал пользователь.
3. Уникальность: Каждая кнопка с подтверждением должна иметь уникальный Callback Data, чтобы бот мог правильно идентифицировать, какую кнопку нажал пользователь.
4. Отображение: Кнопка с подтверждением может быть отображена как обычный текст, ссылка или кнопка с определенным действием.

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

Для создания и отправки кнопок с подтверждением вам потребуется использовать функции и классы из библиотеки aiogram (или аналогичной библиотеки для работы с Telegram API). Кнопки с подтверждением особенно полезны для создания многофункциональных и более удобных телеграм ботов.

Запрос о подтверждении

Запрос о подтверждении (Callback Query) — это тип обновления, который может быть отправлен Telegram боту, когда пользователь нажимает на кнопку с подтверждением (Inline Keyboard) в сообщении бота.

Когда пользователь нажимает на кнопку с подтверждением, Telegram отправляет обновление в бота с информацией о данном действии. Это обновление называется «Callback Query», и оно содержит следующую информацию:

— data: Строка данных, которая связана с нажатой кнопкой. Эта информация может быть определена вами при создании кнопки и использоваться для определения дальнейшего действия.

— from: Информация о пользователе, который нажал кнопку.

— message: Информация о сообщении, в котором была нажата кнопка.

— chat_instance: Уникальный идентификатор чата, в котором произошло действие.

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

Для создания кнопок с подтверждением и обработки запросов о подтверждении вам потребуется использовать функции и классы из библиотеки aiogram. Это позволит вам легко добавлять интерактивность в вашего телеграм бота и предоставлять пользователям более удобный способ взаимодействия с ним.

Пример обработки

import asyncio
from aiogram import Bot, Dispatcher, types

# Вставьте сюда токен вашего бота
BOT_TOKEN = 'YOUR_BOT_TOKEN'

# Инициализация бота и диспетчера
bot = Bot(token=BOT_TOKEN)
dp = Dispatcher(bot)

# Обработчик запросов о подтверждении
@dp.callback_query_handler()
async def on_callback_query(callback_query: types.CallbackQuery):
    # Выводим информацию о запросе о подтверждении в консоль
    print(f"Получен запрос о подтверждении от пользователя с ID {callback_query.from_user.id}")
    print(f"Callback Data: {callback_query.data}")

    # Отправляем ответное сообщение после нажатия кнопки
    await callback_query.answer(text="Вы нажали на кнопку с подтверждением!")

async def main():
    # Создаем inline клавиатуру с кнопкой с подтверждением
    inline_keyboard = types.InlineKeyboardMarkup()
    inline_keyboard.add(types.InlineKeyboardButton(text="Нажми меня!", callback_data="confirm"))

    # Отправляем сообщение с кнопкой с подтверждением
    await bot.send_message(chat_id='USER_CHAT_ID', text="Нажмите кнопку с подтверждением:", reply_markup=inline_keyboard)

    # Старт асинхронного цикла
    await dp.start_polling()

if __name__ == '__main__':
    asyncio.run(main())

В данном примере, когда бот запускается, он отправляет сообщение с кнопкой «Нажми меня!» и привязывает к ней Callback Data «confirm». Когда пользователь нажимает на кнопку, срабатывает обработчик on_callback_query, который выводит информацию о запросе о подтверждении в консоль и отправляет ответное сообщение, содержащее текст «Вы нажали на кнопку с подтверждением!».