Бот для ВКонтакте на Node.js: Callback API и пример на TypeScript

Бот для ВКонтакте на Node.js: Callback API, клавиатура и пример на TypeScript

Разбираемся, как создать чат-бота для сообщества ВКонтакте на Node.js: настройка Callback API, подтверждение сервера, секретный ключ, кнопки и хранение состояния.

Бот для сообщества ВКонтакте — один из самых востребованных каналов для бизнеса: клиенты уже пишут в сообщения группы, и бот снимает с менеджеров типовые вопросы. Технически всё просто — ВКонтакте присылает события на ваш сервер, сервер отвечает через API. Но в деталях есть несколько мест, где новички теряют время: подтверждение адреса сервера, строка «ok» в ответе, секретный ключ, callback-кнопки. Разберём по шагам создание бота для ВК на Node.js и TypeScript.

Callback API или Long Poll

ВКонтакте умеет доставлять события боту двумя способами. Bots Long Poll API — ваш процесс сам периодически забирает события; не нужен публичный адрес и HTTPS, удобно для локальной разработки. Callback API — ВКонтакте сам отправляет POST-запрос на ваш сервер при каждом событии; это стандарт для продакшена, работает за балансировщиком и в serverless. В статье — Callback API: именно его использует пример ниже.

Шаг 1. Подготовка сообщества

1. Создайте сообщество (или используйте существующее) — нужны права администратора.
2. В управлении сообществом включите сообщения сообщества и в их настройках — возможности ботов.
3. В разделе «Работа с API» создайте ключ доступа с правом на сообщения сообщества. Это токен бота — храните его в .env, а не в коде.

Актуальное расположение настроек смотрите на портале dev.vk.com: интерфейс управления сообществом периодически меняется.

Шаг 2. Как устроен Callback API

Три вещи, которые нужно знать до написания кода:

• Подтверждение сервера. Когда вы указываете адрес сервера в настройках, ВКонтакте отправляет событие confirmation и ждёт в ответ строку подтверждения — она показана там же в настройках. Пока сервер не ответил правильной строкой, события не приходят.
• Ответ «ok». На каждое остальное событие сервер должен ответить строкой ok. Иначе ВКонтакте считает доставку неудачной и повторяет запрос — пользователь получает дубли ответов.
• Секретный ключ. В настройках Callback API можно задать секретный ключ — тогда он приходит в поле secret каждого события. Сверяйте его: без проверки любой, кто узнал адрес сервера, сможет слать боту поддельные сообщения.

Основные события для бота: message_new — новое сообщение пользователя и message_event — нажатие callback-кнопки.

Шаг 3. Бот на TypeScript

Разбор событий, подтверждение сервера, ответ «ok», проверку секрета и отправку через messages.send можно не писать руками: в мультиплатформенном фреймворке umbot это делает адаптер VK. Создайте проект:

npx umbot create my-vk-bot
cd my-vk-bot
npm install
npx umbot add env

В .env заполните токены. Переменные с такими именами фреймворк подхватывает из окружения сам — достаточно загрузить файл в process.env первой строкой приложения:

VK_TOKEN=vk1.a.ваш_ключ_доступа
VK_CONFIRMATION_TOKEN=строка_подтверждения_из_настроек
VK_SECRET_KEY=ваш_секретный_ключ

Логика бота:

import { Bot, FALLBACK_COMMAND } from 'umbot';
import { VkAdapter, FileAdapter } from 'umbot/plugins';

process.loadEnvFile(); // загружает .env в process.env (встроено в Node.js 20.12+)

const bot = new Bot()
    .use(new VkAdapter())
    .use(new FileAdapter()); // хранение состояния пользователей

bot.addCommand('start', ['начать', 'привет', 'меню'], (_, bc) => {
    bc.text = 'Здравствуйте! Чем помочь?';
    bc.buttons
        .addBtn('Цены', '', '', { color: 'primary' })
        .addBtn('Записаться', '', '', { color: 'positive' })
        .addBtn('Наш сайт', 'https://example.ru');
});

bot.addCommand('prices', ['цены', 'прайс', 'сколько стоит'], (_, bc) => {
    bc.text = 'Консультация — 1 500 ₽, диагностика — 3 000 ₽.';
});

bot.addCommand('booking', ['записаться', 'запись'], (_, bc) => {
    bc.text = 'Напишите удобную дату и время.';
    bc.thisIntentName = 'ask_time';
});

bot.addStep('ask_time', (bc) => {
    bc.userData.bookingTime = bc.userCommand;
    bc.text = `Записали на «${bc.userCommand}». Администратор подтвердит запись в течение часа.`;
    bc.thisIntentName = null;
});

bot.addCommand(FALLBACK_COMMAND, [], (_, bc) => {
    bc.text = 'Не понял вопрос. Выберите вариант в меню или напишите «оператор».';
    bc.buttons.addBtn('Меню');
});

bot.start('0.0.0.0', 3000);

Что происходит «под капотом»:

• на событие confirmation адаптер сам отвечает строкой подтверждения из VK_CONFIRMATION_TOKEN;
• при заданном VK_SECRET_KEY каждое событие проверяется по полю secret, чужие запросы отклоняются;
• на события платформа получает ok, повторных доставок нет;
• ответ уходит через API ВКонтакте, кнопки превращаются в клавиатуру сообщения с указанными цветами (primary, secondary, positive, negative).

Шаг 4. Подключение сервера в настройках сообщества

1. Запустите бота на сервере с HTTPS (npm run build, npm start) — например, за nginx. Для локальной проверки подойдёт туннель: ngrok или cloudflared.
2. В настройках Callback API сообщества укажите адрес сервера и нажмите «Подтвердить» — бот ответит строкой подтверждения автоматически.
3. Включите секретный ключ — тот же, что в VK_SECRET_KEY.
4. В типах событий отметьте входящие сообщения и действия с сообщениями (callback-кнопки).
5. Напишите сообществу «начать» — бот ответит меню.

Кнопки ВКонтакте: что важно знать

• Текстовая кнопка отправляет от имени пользователя свой текст — на него срабатывают обычные команды.
• Кнопка-ссылка открывает адрес и не приходит боту событием.
• Callback-кнопка не создаёт сообщение в чате, а присылает боту событие message_event; ответ на него показывается всплывающим уведомлением. В umbot payload такой кнопки попадает в команду, как обычный текст: 'buy' или {"command": "buy"} сработают как команда buy.
• Раскладка. Кнопки с одинаковой группой (options._group) окажутся в одной строке клавиатуры.

Где хранить состояние пользователя

ВКонтакте не хранит состояние диалога за бота. Если бот задаёт вопросы по шагам («введите дату»), ему нужно помнить, на каком шаге пользователь. Варианты: память процесса (данные пропадут при перезапуске), файловое хранилище (FileAdapter — подходит для одного сервера) или MongoDB (MongoAdapter — для нескольких экземпляров и продакшена). Подробности — в руководстве по фреймворку.

Типичные ошибки

• Сервер не подтверждается. Строка в VK_CONFIRMATION_TOKEN не совпадает с настройками, либо сервер недоступен снаружи.
• Бот отвечает дважды. Сервер отвечал не «ok» или слишком долго — ВКонтакте повторил доставку.
• Бот не видит сообщений. Не включены сообщения сообщества или не отмечен тип события «входящее сообщение».
• Ключ без нужных прав. Токен создан без доступа к сообщениям — отправка падает с ошибкой API.
• Секрет не проверяется. Удобно на тестах, опасно в продакшене.

Частые вопросы

Можно ли сделать бота ВКонтакте для личной страницы? Нет, боты работают от имени сообщества. Для личных страниц автоматизация запрещена правилами платформы.

Как сделать, чтобы тот же бот работал в Telegram? В umbot — подключить ещё один адаптер: логика, кнопки и состояние остаются общими. Подробнее — в статье одна кодовая база для нескольких платформ.

Может ли бот ВКонтакте писать первым? Только пользователям, которые разрешили сообществу присылать сообщения. В umbot для этого есть метод bot.send().

Куда дальше

• Интеграция с платформами в umbot — все опции адаптера VK.
• Бот для мессенджера MAX — ещё один российский мессенджер тем же кодом.
• Разработка ботов под ключ — если бот для сообщества нужен без собственной разработки.