Типы данных¶

Все типы определены в модуле vk_bot.types и основаны на Pydantic. Они автоматически создаются при получении событий - вам не нужно конструировать их вручную (за исключением клавиатур).

Message¶

Объект входящего сообщения - основной тип, с которым работает обработчик.

@bot.message_handler()
def handle(message: types.Message):
    print(message.text)       # Текст сообщения
    print(message.from_id)    # ID отправителя
    print(message.peer_id)    # ID чата
    print(message.date)       # Дата (datetime)
    print(message.chat)       # Объект Chat
    print(message.is_private) # True если личное сообщение

Основные поля:

Поле	Тип	Описание
`id`	`int`	ID сообщения
`date`	`datetime`	Время отправки
`peer_id`	`int`	ID чата
`from_id`	`int`	ID отправителя
`text`	`str`	Текст сообщения
`out`	`bool`	`True` - исходящее
`attachments`	`list[dict]`	Вложения (сырые данные)
`reply_message`	`Message \| None`	Ответ на сообщение
`fwd_messages`	`list[Message]`	Пересланные сообщения
`payload`	`dict \| None`	Payload от кнопки
`action`	`dict \| None`	Действие (приглашение и т.д.)

Полезные свойства и методы:

message.chat           # Объект Chat (создаётся из peer_id)
message.chat.type      # "private" или "group"
message.content_type   # "text", "photo", "doc", "video", и т.д.
message.is_private     # True если peer_id == from_id

message.get_photos()     # list[Photo] - извлечь фото из вложений
message.get_documents()  # list[Document] - извлечь документы

User¶

Объект пользователя VK.

user = message.from_user  # Может быть None

user.id            # 123456
user.first_name    # "Иван"
user.last_name     # "Петров"
user.full_name     # "Иван Петров"
user.mention        # "[id123456|Иван]"
user.photo_100     # URL фотографии
user.online        # True/False

Chat¶

Объект чата (личное сообщение или беседа).

chat = message.chat

chat.id      # ID чата
chat.type    # "private" или "group"
chat.title   # Название беседы (None для личных)

Создание из peer_id:

# peer_id < 2_000_000_000 → private, иначе → group
chat = types.Chat.from_peer_id(12345)

CallbackQuery¶

Событие нажатия на inline-кнопку.

@bot.callback_query_handler(data="action")
def handle(callback: types.CallbackQuery):
    callback.id         # ID события
    callback.from_id    # ID пользователя
    callback.peer_id    # ID чата
    callback.message_id # ID сообщения с кнопкой
    callback.data       # Значение callback_data кнопки

Update¶

Обёртка над событием Long Poll. Обычно используется в middleware:

@bot.middleware_handler()
def log(bot_instance, update: types.Update):
    print(update.type)            # "message_new", "message_event", и т.д.
    print(update.message)         # Message | None
    print(update.callback_query)  # CallbackQuery | None

Клавиатуры¶

Клавиатуры - единственные типы, которые вы создаёте вручную.

Reply-клавиатура (обычные кнопки)¶

Отображается под полем ввода. Нажатие отправляет текст кнопки как обычное сообщение.

kb = types.ReplyKeyboardMarkup(one_time_keyboard=True)
kb.add(
    types.KeyboardButton(text="Да", color="positive"),
    types.KeyboardButton(text="Нет", color="negative"),
)
bot.send_message(chat_id, "Вы согласны?", reply_markup=kb)

Метод add() добавляет строку кнопок. Для нескольких строк вызовите add() несколько раз:

kb = types.ReplyKeyboardMarkup()
kb.add(types.KeyboardButton(text="Строка 1, Кнопка 1"))
kb.add(
    types.KeyboardButton(text="Строка 2, Кнопка 1"),
    types.KeyboardButton(text="Строка 2, Кнопка 2"),
)

Цвета кнопок:

Значение	Описание
`"primary"`	Синяя кнопка (по умолчанию)
`"secondary"`	Белая/серая кнопка
`"positive"`	Зелёная кнопка
`"negative"`	Красная кнопка

Чтобы скрыть клавиатуру, отправьте пустую:

empty = types.ReplyKeyboardMarkup(one_time_keyboard=True)
bot.send_message(chat_id, "Клавиатура скрыта", reply_markup=empty)

Inline-клавиатура (кнопки в сообщении)¶

Встраивается прямо в сообщение. Нажатие отправляет callback-событие.

kb = types.InlineKeyboardMarkup()
kb.add(
    types.InlineKeyboardButton(text="Да", callback_data="like"),
    types.InlineKeyboardButton(text="Нет", callback_data="dislike"),
)
kb.add(
    types.InlineKeyboardButton(text="Открыть сайт", url="https://vk.com"),
)
bot.send_message(chat_id, "Оцените:", reply_markup=kb)

Параметры InlineKeyboardButton:

Параметр	Описание
`text`	Текст кнопки (обязательный)
`callback_data`	Данные для callback-обработчика
`url`	Ссылка для открытия в браузере
`vk_app_id`	ID VK Mini App
`owner_id`	Владелец VK Mini App
`hash`	Хеш для VK Mini App

Примечание

Укажите один из параметров: callback_data, url или vk_app_id.

Вложения (Attachment)¶

Типы вложений для работы с медиа:

Photo¶

photos = message.get_photos()
for photo in photos:
    print(photo.id)         # ID фото
    print(photo.owner_id)   # ID владельца
    print(photo.url)        # URL наибольшего размера
    print(photo.attachment)  # "photo-123_456_key"

Document¶

docs = message.get_documents()
for doc in docs:
    print(doc.id)         # ID документа
    print(doc.title)      # Имя файла
    print(doc.ext)        # Расширение ("pdf", "zip", ...)
    print(doc.size)       # Размер в байтах
    print(doc.url)        # URL для скачивания
    print(doc.attachment)  # "doc-123_456_key"

Video¶

video.id          # ID видео
video.owner_id    # ID владельца
video.title       # Название
video.duration    # Длительность в секундах
video.attachment  # "video-123_456_key"

Audio¶

audio.id       # ID аудио
audio.artist   # Исполнитель
audio.title    # Название
audio.duration # Длительность
audio.url      # URL потока
audio.attachment  # "audio-123_456"