Главная · Справка · Подключение бота ВКонтакте: ключ доступа и Callback API

Подключение бота ВКонтакте: ключ доступа и Callback API

Бот ВКонтакте подключается в двух местах. В «Управлении» сообщества вы включаете сообщения, создаёте ключ доступа и настраиваете Callback API, в ЧБТ — заводите канал с тремя значениями из ВКонтакте. Главное отличие от Telegram и MAX: адрес сервера ЧБТ сам не прописывает, его вставляете вы. Ниже — пять шагов в удобном порядке, что ЧБТ делает с каждым полем и как по признакам найти ошибку.

Что понадобится и в каком порядке

Права администратора сообщества. Ключи доступа и Callback API открываются в «Управлении» только администратору.
Бот в ЧБТ. Подойдёт любой тариф, включая Бесплатный: за канал ВКонтакте отдельно не платят. Если в боте уже работает Telegram или MAX, VK добавляется к нему же, и сценарий остаётся общим.
Две вкладки рядом: «Управление» сообщества и раздел «Каналы» в ЧБТ.

Порядок важен из-за одной детали. Строку подтверждения ЧБТ должен получить в момент создания канала, а адрес сервера появляется только после создания. Поэтому путь такой: ВКонтакте (шаги 1–3) → ЧБТ (шаг 4) → снова ВКонтакте (шаг 5).

Шаг 1. Сообщения и возможности ботов

«Управление» → «Сообщения» → переключатель «Сообщения сообщества» в положение «Включены». Пока он выключен, в сообществе нет кнопки «Написать», и в ЧБТ не приходит ни одного сообщения.
В том же разделе откройте «Настройки для бота»: «Возможности ботов» — «Включены», плюс галочка «Добавить кнопку «Начать»».

Зачем второй пункт. Кнопки под ответами ЧБТ отправляет как клавиатуру бота, а ВКонтакте принимает её только от сообществ с включёнными возможностями ботов: без них текстовые ответы уходят, а сообщения с кнопками — нет. Кнопка «Начать» к тому же даёт вход в сценарий: её нажатие ЧБТ считает командой /start.

Шаг 2. Ключ доступа с одним правом

«Управление» → «Работа с API» → вкладка «Ключи доступа» → «Создать ключ». В списке прав отметьте «Сообщения сообщества», остальные боту ЧБТ не нужны. Этим ключом ЧБТ делает три вещи: отправляет от имени сообщества ответы и рассылки, гасит индикатор ожидания на нажатой кнопке и при первом сообщении узнаёт имя и фамилию собеседника для карточки контакта.

Скопируйте ключ сразу после создания и держите до шага 4 — он пойдёт в поле «Токен». В ЧБТ ключ хранится в зашифрованном виде и в кабинете больше не показывается ни вам, ни команде.

Шаг 3. Callback API: версия, строка подтверждения, секрет

«Работа с API» → вкладка «Callback API». Здесь нужны три настройки, поле «Адрес» пока оставьте пустым.

«Версия API» — самая новая из списка. Ответы ЧБТ отправляет по версии 5.199, а входящее сообщение ищет внутри события в поле message. На старых версиях ВКонтакте присылает событие в прежнем формате, без этого поля, и ЧБТ его пропускает — без ошибки, просто тишина.
«Строка, которую должен вернуть сервер» — короткий код, который ВКонтакте выдал вашему сообществу. Скопируйте его целиком, без пробелов по краям.
«Секретный ключ» — по желанию. Придумайте строку из латиницы и цифр: ВКонтакте будет прикладывать её к каждому событию, а ЧБТ — сверять, и запрос с чужим секретом сценарий не запустит. Запишите секрет, он понадобится в ЧБТ.

Шаг 4. Форма «ВКонтакте» в ЧБТ

В боте ЧБТ откройте «Каналы». В блоке «Подключить новый канал» у карточки «ВКонтакте» нажмите «Подключить» — раскроется короткая подсказка и форма:

Поле формы	Что вписать
«Название канала»	Необязательно. Удобно, если сообществ несколько: по названию их легко различить в списке каналов.
«Токен»	Ключ доступа из шага 2. Единственное обязательное поле.
«VK: строка подтверждения»	Строка из Callback API (шаг 3). С пустым полем адрес не подтвердится.
«VK: секретный ключ»	Тот же секрет, что в Callback API. Если секрет в VK не задавали, оставьте поле пустым.

Нажмите «Подключить ВКонтакте». Кабинет перейдёт на «Обзор» бота — вернитесь в «Каналы». В строке нового канала после слова «ВКонтакте» стоит плашка с адресом, например app.chbt.io/webhook/vk/57, где число — номер канала в ЧБТ. Это адрес сервера для ВКонтакте.

Статус «Работает» появляется у VK-канала сразу и сам по себе ничего не доказывает: при подключении ЧБТ не обращается к ВКонтакте и ключ не проверяет. Настоящая проверка — сообщение с личной страницы, о нём ниже.

Шаг 5. Адрес сервера и типы событий

Вернитесь во вкладку «Callback API». В поле «Адрес» вставьте адрес из «Каналов», дописав в начале https://: получится https://app.chbt.io/webhook/vk/57 с вашим номером канала.
Нажмите «Подтвердить». ВКонтакте пришлёт на адрес проверочный запрос, ЧБТ ответит строкой из поля «VK: строка подтверждения», и сервер получит статус «подтверждён».
Перейдите в «Типы событий» и включите два. «Входящее сообщение» (message_new) — через него ЧБТ узнаёт и о тексте, и о нажатии «Начать». Событие callback-кнопки (message_event) — через него приходят нажатия кнопок-веток. Остальные типы можно не трогать.

Что ЧБТ делает с запросами ВКонтакте

Все события сообщества приходят на адрес канала, и ЧБТ разбирает их по порядку. Знать это не обязательно, но так проще понять признаки ошибок из следующего раздела.

Проверка адреса. На запрос подтверждения ЧБТ отвечает строкой, сохранённой в канале. Если поле было пустым, ответ — «ok», и ВКонтакте адрес не подтверждает.
Сверка секрета. Если в канале задан секрет, запрос без него или с другим секретом ЧБТ не обрабатывает, но отвечает «ok» — для ВКонтакте событие выглядит доставленным. Если секрет в канале пустой, сверки нет. Сверка идёт после подтверждения адреса, поэтому «подтверждён» в Callback API ещё не значит, что секреты совпали.
Отбор событий. В сценарий попадают только входящие сообщения и нажатия callback-кнопок. «Начать» превращается в команду /start, нажатие кнопки-ветки — в выбор этой кнопки. На остальные события ЧБТ отвечает «ok» и ничего не делает.
Кнопка отпускается сразу. На нажатие кнопки-ветки ЧБТ отвечает ВКонтакте ещё до запуска сценария, чтобы у человека не крутился индикатор ожидания.
Очередь и повторы. Событие сначала сохраняется в очередь и только потом ВКонтакте получает «ok». Если VK не дождался ответа и прислал то же событие ещё раз, ЧБТ узнаёт повтор, и сценарий второй раз не запускается.
Ответ. Сообщение уходит от имени сообщества: текст и до 10 кнопок, по две в ряд. Подпись кнопки длиннее 40 символов обрезается. Кнопка-ссылка открывает адрес, кнопка-ветка продолжает сценарий. Если ВКонтакте отправку отклонил, в «Диалогах» у ответа бота появляется пометка «не доставлено», а при наведении на неё — текст ошибки от ВКонтакте.

Проверка после подключения

Убедитесь, что сценарий включён: в «Сценариях» на его карточке плашка «Включён», а не «Черновик».
С личной страницы — своей или коллеги, не из интерфейса администратора сообщества — откройте сообщения сообщества. Если эта страница сообществу раньше не писала, увидите кнопку «Начать»: нажмите её, затем отправьте любой текст.
В ЧБТ откройте «Диалоги». Правильная картина: диалог подписан именем и фамилией этой страницы, в нём ваши сообщения и ответы бота без пометки «не доставлено». Нажмите кнопку-ветку в ответе — индикатор на кнопке гаснет сразу, следом приходит продолжение.

Если что-то пошло иначе, найдите свой признак в таблице ниже. Полный чеклист по порядку, вместе со сценарием и тарифом, — «Бот ВКонтакте молчит».

Ошибки подключения и их признаки

Что видно	Почему	Что сделать
«Подтвердить» не срабатывает, строка точно верная	Адрес без `https://`, с опечаткой или с номером удалённого канала — проверочный запрос не доходит до вашего канала в ЧБТ	Скопировать адрес заново из строки канала в «Каналах»
«Подтвердить» не срабатывает, адрес верный	В канале пустая или неточная строка подтверждения: лишний пробел, строка от другого сообщества	Подключить канал заново с точной строкой, вписать новый адрес
Сервер подтверждён, в «Диалогах» пусто	Не включено «Входящее сообщение», не совпал секрет или выбрана старая версия API	Шаги 3 и 5; секрет — одинаковый в обоих местах или пустой в обоих
Сообщение в «Диалогах» есть, у ответа бота «не доставлено»	ВКонтакте отклонил отправку: у ключа нет права «Сообщения сообщества», ключ удалён или человек запретил сообщения от сообщества	Навести на пометку и прочитать текст ошибки; ключ без права — создать новый и подключить канал заново
Статус канала «Ошибка» с текстом «токен бота отклонён (401 Unauthorized)»	Ключ удалён или отозван во ВКонтакте. ЧБТ ставит этот статус при первой неудачной отправке и пишет владельцу на почту, если уведомление «Статус ботов» не выключено	Новый ключ → канал заново → новый адрес в Callback API
Текстовые ответы приходят, сообщения с кнопками — нет	Выключены «Возможности ботов»	Шаг 1
Нет кнопки «Начать»	Не отмечено «Добавить кнопку «Начать»» или страница уже писала сообществу	Шаг 1; тест со страницы, которая сообществу ещё не писала
На кнопке-ветке крутится индикатор, ответа нет	Нажатие не дошло до ЧБТ или ЧБТ не смог на него ответить: не включено событие callback-кнопки, не совпал секрет, у ключа нет права на сообщения	Шаги 2, 3 и 5
Индикатор гаснет, продолжения нет; или бот отвечает на «Начать» и молчит на текст	Подключение работает, дело в сценарии	Раздел «Сторона ЧБТ» в чеклисте

Смена ключа, строки или секрета

Поля VK-канала после подключения не редактируются. Чтобы сменить ключ, строку подтверждения или секрет, удалите канал в «Каналах» (меню канала → «Удалить») и подключите заново. Учтите: вместе с каналом удаляется его переписка в «Диалогах», а контакты и их теги остаются. У нового канала другой номер, значит, и другой адрес — впишите его в Callback API и подтвердите ещё раз, иначе ВКонтакте продолжит слать события на старый адрес, которого больше нет.

Кнопка «Переустановить webhook» в строке VK-канала ничего не меняет во ВКонтакте: она только возвращает каналу статус «Работает». Адрес, типы событий и секрет в Callback API правятся вручную.

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

Секретный ключ обязателен?
Нет. Если поле «VK: секретный ключ» в ЧБТ пустое, секрет не сверяется. Если заполнено — в Callback API должна стоять та же строка, иначе ЧБТ отвечает ВКонтакте «ok», но событие не обрабатывает. Надёжнее всего одинаковый секрет в обоих местах или пустой в обоих.

Канал в статусе «Работает», а бот молчит. Как так?
У VK-канала статус «Работает» ставится при создании: ЧБТ в этот момент не обращается к ВКонтакте и ключ не проверяет. На «Ошибка» статус меняется, только когда ВКонтакте отклонит ключ при отправке сообщения. Проверяйте подключение сообщением с личной страницы и смотрите «Диалоги».

Какое событие включить, чтобы бот отвечал на комментарии?
Никакое: бот ЧБТ работает только в сообщениях сообщества. События о комментариях, записях на стене и вступлениях ЧБТ принимает, отвечает ВКонтакте «ok» и не обрабатывает, так что включать их незачем.

Создать бота бесплатно

Канал VK Бот молчит: чеклист Бот для сообщества: разбор Сбор заявок