aiogram.types: работа с объектами телеграмм в боте

Модуль aiogram.types обеспечивает более удобное и понятное взаимодействие с различными объектами и сущностями, используемыми в Telegram API. Что это за объекты и сущности?

Примеры, приведенные в статье, реализованы на версии aiogram 2x

Содержание

Объекты aiogram.types
Класс user
Класс message
Класс chat
Работа с встроенными кнопками
Класс InlineKeyboardButton
Класс InlineKeyboardMarkup
Текстовые кнопки
Как выровнять кнопки на клавиатуре?
Как к текстовой кнопке привязать команду?
Работа с медиа данными от пользователя
Создание опроса с помощью бота

Объекты aiogram.types

User: Представляет информацию о пользователе Telegram. Содержит такие поля, как идентификатор пользователя, имя пользователя, имя и фамилия и другие данные.
Message: Содержит информацию о сообщении, отправленном в чат. Включает в себя текст сообщения, информацию о чате, отправителе и дате отправки.
Chat: Предоставляет информацию о чате. Может быть как групповым чатом, так и личным диалогом. Включает в себя идентификатор чата, название (для групповых чатов), и другие свойства.
InlineKeyboardButton: Представляет кнопку встроенной клавиатуры. Позволяет создавать интерактивные кнопки для быстрого взаимодействия с пользователем.
InlineQuery: Содержит информацию о встроенном запросе пользователя. Используется, например, для создания ботов, которые могут отвечать на запросы прямо из поля ввода сообщений.
Update: Представляет обновление в чате, такое как новое сообщение, изменение состава участников и другие события.
KeyboardButton: Представляет кнопку на пользовательской клавиатуре. Может быть использована для создания пользовательских интерфейсов с кнопками.
CallbackQuery: Содержит информацию о callback-запросе, который генерируется при нажатии на кнопку с callback-данными. Позволяет реализовывать интерактивные действия в боте.
Audio: Информация о аудиофайле, отправленном пользователем. Включает в себя длительность, название, исполнителя и другие данные.
PhotoSize: Представляет размер одной из фотографий, отправленных пользователем или доступных в чате.
Document: Информация о документе (например, PDF, архивы и другие файлы), отправленном пользователем.
Sticker: Данные о стикере, отправленном или полученном в чате.
Video: Информация о видеофайле, отправленном пользователем. Включает в себя длительность, размер, превью и другие параметры.
Voice: Информация о голосовом сообщении, отправленном пользователем.
Venue: Предоставляет информацию о местоположении (месте встречи), например, координаты, название, адрес и другие данные.
Location: Содержит информацию о географическом местоположении.

И это только небольшая часть типов, предоставляемых модулем aiogram.types. Эти типы помогают упростить работу с данными, получаемыми из Telegram API, и делают код более читаемым и понятным.

Класс user

Объект класса User из модуля aiogram.types представляет информацию о пользователе Telegram. Этот класс содержит различные атрибуты, которые предоставляют доступ к данным о пользователе, а также может использоваться для отправки сообщений и взаимодействия с ним.

Вот некоторые атрибуты и методы класса User:

Атрибуты:

id: Уникальный идентификатор пользователя.
is_bot: Булевое значение, указывающее, является ли пользователь ботом.
first_name: Имя пользователя.
last_name: Фамилия пользователя (может быть None).
username: Имя пользователя (username) без «@» (может быть None).
language_code: Код языка, на котором пользователь взаимодействует с ботом.

Бот, который приветствует пользователя.

from aiogram import Bot, types
from aiogram.dispatcher import Dispatcher
from aiogram.utils import executor

API_TOKEN = 'YOUR_BOT_API_TOKEN'
bot = Bot(token=API_TOKEN)
dp = Dispatcher(bot)

@dp.message_handler(commands=['start'])
async def start_command(message: types.Message):
    user = message.from_user
    
    # Отправляем приветственное сообщение с упоминанием пользователя
    await message.reply(f"Привет, {user.get_mention()}!")

if __name__ == '__main__':
    executor.start_polling(dp, skip_updates=True)

В данном примере бот реагирует на команду /start и отправляет пользователю приветственное сообщение с упоминанием его имени. Обратите внимание, что в данном случае объект user получен из атрибута from_user объекта Message.

Не забудьте заменить ‘YOUR_BOT_API_TOKEN’ на реальный API-токен вашего бота, чтобы код работал правильно.

Класс message

Работу с сообщениями, мы разбирали в отдельном уроке по сообщениям.

Класс chat

Объект класса Chat из модуля aiogram.types представляет информацию о чате в Telegram. Этот класс содержит различные атрибуты, которые предоставляют доступ к данным о чате, а также может использоваться для отправки сообщений и взаимодействия с чатом.

Вот некоторые атрибуты и методы класса Chat:

Атрибуты:

id: Уникальный идентификатор чата.
type: Тип чата (private, group, supergroup или channel).
title: Название чата (для групповых чатов и супергрупп).
username: Имя чата (username) без «@» (для каналов и супергрупп).
first_name: Имя пользователя (для личных диалогов).
last_name: Фамилия пользователя (для личных диалогов).
description: Описание чата (может быть None).
invite_link: Ссылка на приглашение в чат (если доступна).

Методы:

ban(chat_id, user_id): Этот метод позволяет банить пользователя в чате. Он может использоваться для запрета пользователю отправлять сообщения и взаимодействовать с чатом.
unban(chat_id, user_id): Данный метод служит для разблокировки пользователя в чате после бана.
leave(chat_id): Позволяет боту покинуть чат.
get_member(chat_id, user_id): Получает информацию о члене чата по его ID.
get_administrators(chat_id): Получает список администраторов чата.
set_title(chat_id, title): Устанавливает название для чата, если это возможно.
promote(chat_id, user_id): Повышает пользователя до администратора чата.

Пример бота, который выдает информацию о чате, где задействована команда /info

from aiogram import Bot, types
from aiogram.dispatcher import Dispatcher
from aiogram.utils import executor

API_TOKEN = 'YOUR_BOT_API_TOKEN'
bot = Bot(token=API_TOKEN)
dp = Dispatcher(bot)

@dp.message_handler(commands=['info'])
async def chat_info(message: types.Message):
    chat = message.chat
    
    # Отправляем информацию о чате
    info = f"ID чата: {chat.id}\nТип чата: {chat.type}\n"
    
    if chat.type == 'private':
        info += f"Имя пользователя: {chat.first_name} {chat.last_name}"
    elif chat.type in ['group', 'supergroup']:
        info += f"Название чата: {chat.title}"
    elif chat.type == 'channel':
        info += f"Имя канала: {chat.title} ({chat.username})"
    
    await message.reply(info)

if __name__ == '__main__':
    executor.start_polling(dp, skip_updates=True)

Работа с встроенными кнопками

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

При нажатии на текстовую кнопку, боту передается сообщение с текстом, написанным на кнопке.

Объекты класса InlineKeyboardButton и InlineKeyboardMarkup используются для создания встроенной (inline) клавиатуры в ботах Telegram. Встроенная клавиатура позволяет пользователям взаимодействовать с ботом, выбирая опции или выполняя действия, прямо из поля ввода сообщения.

Класс `InlineKeyboardButton`

Этот класс представляет собой кнопку во встроенной клавиатуре. Вот некоторые атрибуты и методы:

Атрибуты:

text: Текст кнопки.
callback_data: Данные, которые будут переданы обратно боту при нажатии кнопки.

Класс `InlineKeyboardMarkup`

Этот класс представляет собой встроенную клавиатуру, содержащую кнопки. Вот некоторые методы:

Методы:

add(): Добавляет кнопку или несколько кнопок к клавиатуре.
insert(): Вставляет кнопку в определенное место в клавиатуре.
row(): Добавляет кнопки в одной строке.
clear(): Удаляет все кнопки из клавиатуры.

Пример бота с инлайн кнопкой:

from aiogram import Bot, types
from aiogram.dispatcher import Dispatcher
from aiogram.utils import executor

API_TOKEN = 'YOUR_BOT_API_TOKEN'
bot = Bot(token=API_TOKEN)
dp = Dispatcher(bot)

@dp.message_handler(commands=['start'])
async def start_command(message: types.Message):
    keyboard = InlineKeyboardMarkup()
    button = InlineKeyboardButton(text="Нажми меня", callback_data="button_pressed")
    keyboard.add(button)
    
    await message.reply("Привет! Нажми кнопку:", reply_markup=keyboard)

@dp.callback_query_handler(lambda query: query.data == "button_pressed")
async def button_pressed(query: types.CallbackQuery):
    await query.answer("Вы нажали на кнопку!")

if __name__ == '__main__':
    executor.start_polling(dp, skip_updates=True)

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

Текстовые кнопки

Объект класса KeyboardButton из модуля aiogram.types используется для создания кнопок на пользовательской клавиатуре в ботах Telegram. Эти кнопки позволяют пользователям взаимодействовать с ботом, выбирая опции или отправляя текстовые команды.

Вот некоторые атрибуты и методы класса KeyboardButton:

Атрибуты:

text: Текст, который будет отображаться на кнопке.

from aiogram import Bot, types
from aiogram.dispatcher import Dispatcher
from aiogram.utils import executor

API_TOKEN = 'YOUR_BOT_API_TOKEN'
bot = Bot(token=API_TOKEN)
dp = Dispatcher(bot)

@dp.message_handler(commands=['start'])
async def start_command(message: types.Message):
    keyboard = types.ReplyKeyboardMarkup(resize_keyboard=True)
    button = types.KeyboardButton(text="Привет!")
    keyboard.add(button)
    
    await message.reply("Привет! Нажми кнопку:", reply_markup=keyboard)

@dp.message_handler(lambda message: message.text == "Привет!")
async def greet(message: types.Message):
    await message.reply("Привет! Как дела?")

if __name__ == '__main__':
    executor.start_polling(dp, skip_updates=True)

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

Обратите внимание, что использование пользовательских клавиатур стоит осторожно, так как слишком много кнопок может создать путаницу у пользователей, и нежелательное использование может нарушить пользование чатами и диалогами.

Как выровнять кнопки на клавиатуре?

Для выравнивания кнопок на пользовательской клавиатуре в Telegram можно использовать атрибуты и методы, предоставляемые классом ReplyKeyboardMarkup или InlineKeyboardMarkup, в зависимости от того, какой тип клавиатуры вы используете.

ReplyKeyboardMarkup:

Для выравнивания кнопок с помощью ReplyKeyboardMarkup можно использовать метод row(). Этот метод добавляет кнопки в одну строку на клавиатуре.

from aiogram.types import ReplyKeyboardMarkup, KeyboardButton

keyboard = ReplyKeyboardMarkup(resize_keyboard=True)
button1 = KeyboardButton(text="Кнопка 1")
button2 = KeyboardButton(text="Кнопка 2")

keyboard.row(button1, button2)

Как к текстовой кнопке привязать команду?

При нажатии текстовой кнопки, в бот отправляется текст, содержащийся на кнопке. Часто необходима обработка нажатия кнопки. Это делается через специальный обработчик callback_query_handler

from aiogram import Bot, types
from aiogram.dispatcher import Dispatcher
from aiogram.utils import executor

API_TOKEN = 'YOUR_BOT_API_TOKEN'
bot = Bot(token=API_TOKEN)
dp = Dispatcher(bot)

@dp.callback_query_handler(lambda query: query.data == "info_command")
async def info_callback(query: types.CallbackQuery):
    await query.answer()  # Ответ на callback-запрос, чтобы убрать уведомление
    await bot.send_message(query.from_user.id, "Вы запросили информацию. Вот результат...")

@dp.message_handler(commands=['start'])
async def start_command(message: types.Message):
    keyboard = types.InlineKeyboardMarkup()
    button = types.InlineKeyboardButton(text="Информация", callback_data="info_command")
    keyboard.add(button)
    
    await message.reply("Привет! Нажми кнопку для получения информации:", reply_markup=keyboard)

if __name__ == '__main__':
    executor.start_polling(dp, skip_updates=True)

В этом примере, когда пользователь нажимает кнопку «Информация», бот отправляет callback-запрос с callback_data="info_command". Обработчик info_callback реагирует на этот запрос и выполняет команду для отправки информации.

Обратите внимание, что использование InlineKeyboardButton с callback_data более гибкое, чем передача текстовой команды в тексте кнопки. Вы можете передавать разные значения callback_data для разных действий, и в обработчиках CallbackQuery легко идентифицировать, какое действие было выполнено пользователем.

Работа с медиа данными от пользователя

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

from aiogram import Bot, types
from aiogram.dispatcher import Dispatcher
from aiogram.utils import executor

API_TOKEN = 'YOUR_BOT_API_TOKEN'
bot = Bot(token=API_TOKEN)
dp = Dispatcher(bot)

@dp.message_handler(content_types=types.ContentTypes.PHOTO)
async def handle_photo(message: types.Message):
    for photo in message.photo:
        await message.reply(f"Вы отправили фотографию с размером {photo.width}x{photo.height} пикселей.")

if __name__ == '__main__':
    executor.start_polling(dp, skip_updates=True)

@dp.message_handler(content_types=types.ContentTypes.VIDEO)
async def handle_video(message: types.Message):
    video = message.video
    await message.reply(f"Вы отправили видео длительностью {video.duration} секунд и размером {video.width}x{video.height} пикселей.")

@dp.message_handler(content_types=types.ContentTypes.VOICE)
async def handle_voice(message: types.Message):
    voice = message.voice
    await message.reply(f"Вы отправили голосовое сообщение длительностью {voice.duration} секунд.")

@dp.message_handler(content_types=types.ContentTypes.DOCUMENT)
async def handle_document(message: types.Message):
    document = message.document
    await message.reply(f"Вы отправили документ {document.file_name} с размером {document.file_size} байт.")

В каждом из этих примеров бот реагирует на разные типы медиа, получая информацию о свойствах каждого медиа и отправляя пользователю соответствующее сообщение с этой информацией. Обратите внимание, что обработчики определяются с помощью атрибута content_types и соответствующих типов медиа из aiogram.types.ContentTypes.

Создание опроса с помощью бота

from aiogram import Bot, types
from aiogram.dispatcher import Dispatcher
from aiogram.utils import executor

API_TOKEN = '6238867400:AAFzm3FlEgMaXxBZhTzqYWAzEcsFCCp-EDk'
bot = Bot(token=API_TOKEN)
dp = Dispatcher(bot)

polls = {}  # Словарь для хранения созданных опросов

@dp.message_handler(commands=['start'])
async def start_command(message: types.Message):
    await message.reply("Привет! Для создания опроса используйте /question")

@dp.message_handler(commands=['question'])
async def create_poll(message: types.Message):
    user_id = message.from_user.id
    polls[user_id] = {"question": "", "options": []}
    polls[user_id]["step"] = "adding_question"
    await message.reply("Введите вопрос для опроса:")

@dp.message_handler(commands=['answer'])
async def add_option(message: types.Message):
    user_id = message.from_user.id
    if user_id in polls:
        await message.reply("Введите вариант ответа:")
        polls[user_id]["step"] = "adding_option"
    else:
        await message.reply("Для начала создайте опрос с помощью /question")

@dp.message_handler(commands=['send'])
async def send_poll(message: types.Message):
    user_id = message.from_user.id
    if user_id in polls:
        poll_data = polls[user_id]
        if poll_data["question"] and poll_data["options"]:
            markup = types.ReplyKeyboardMarkup(resize_keyboard=True)
            for option in poll_data["options"]:
                markup.add(types.KeyboardButton(text=option))
            await message.reply(poll_data["question"], reply_markup=markup)
        else:
            await message.reply("Пожалуйста, введите вопрос и добавьте варианты ответов")
    else:
        await message.reply("Создайте опрос с помощью /question")

@dp.message_handler(lambda message: message.from_user.id in polls and "step" in polls[message.from_user.id])
async def process_poll_creation(message: types.Message):
    user_id = message.from_user.id
    poll_data = polls[user_id]

    if poll_data["step"] == "adding_question":
        poll_data["question"] = message.text
        poll_data["step"] = "adding_option"
        await message.reply("Введите вариант ответа:")
    elif poll_data["step"] == "adding_option":
        poll_data["options"].append(message.text)
        await message.reply("Вариант ответа добавлен. Добавьте еще или используйте /send для отправки опроса.")

if __name__ == '__main__':
    executor.start_polling(dp, skip_updates=True)

В этом примере бот позволяет пользователям создавать опросы, добавлять варианты ответов и отправлять опросы в произвольный чат. Каждый пользователь может иметь только один активный опрос. Бот сохраняет данные об опросе в словаре polls.