Быстрый старт

Установка

pip install vk-bot

Или через Poetry:

poetry add vk-bot

Для поддержки Redis или PostgreSQL установите с дополнительными зависимостями:

pip install "vk-bot[redis]"       # Хранилище состояний в Redis
pip install "vk-bot[postgres]"    # Хранилище состояний в PostgreSQL

Получение токена

  1. Создайте сообщество ВКонтакте (или используйте существующее).

  2. Перейдите в Управление → Работа с API → Ключи доступа.

  3. Создайте ключ с правами на сообщения сообщества.

  4. Включите Long Poll API в разделе Управление → Работа с API → Long Poll API.

  5. Отметьте нужные события (минимум: message_new, message_event).

Первый бот

Создайте файл bot.py:

from vk_bot import VKBot, types

bot = VKBot(token="YOUR_TOKEN")

@bot.message_handler(commands=["start"])
def handle_start(message: types.Message):
    bot.send_message(message.from_id, "Привет! Я бот ВКонтакте.")

@bot.message_handler()
def handle_echo(message: types.Message):
    bot.send_message(message.from_id, f"Вы написали: {message.text}")

if __name__ == "__main__":
    bot.polling()

Запустите:

python bot.py

Совет

Рекомендуется хранить токен в переменной окружения:

import os
bot = VKBot(token=os.getenv("VK_TOKEN"))

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

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

from vk_bot import types

kb = types.ReplyKeyboardMarkup(one_time_keyboard=True)
kb.add(
    types.KeyboardButton(text="Вариант А", color="primary"),
    types.KeyboardButton(text="Вариант Б", color="secondary"),
)
bot.send_message(chat_id, "Выберите вариант:", reply_markup=kb)

Обработка нажатия - обычный обработчик текста:

@bot.message_handler(func=lambda m: m.text == "Вариант А")
def handle_option_a(message: types.Message):
    bot.send_message(message.from_id, "Вы выбрали А!")

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

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

Inline-клавиатуры

Inline-кнопки встраиваются в сообщение. Нажатие генерирует callback-событие.

from vk_bot import types

kb = types.InlineKeyboardMarkup()
kb.add(
    types.InlineKeyboardButton(text="Подтвердить", callback_data="yes"),
    types.InlineKeyboardButton(text="Отменить", callback_data="no"),
)
bot.send_message(chat_id, "Вы уверены?", reply_markup=kb)

@bot.callback_query_handler(data="yes")
def handle_yes(callback: types.CallbackQuery):
    bot.answer_callback_query(
        callback_query_id=callback.id,
        user_id=callback.from_id,
        peer_id=callback.peer_id,
        text="Подтверждено!",
    )

Что дальше?