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

Вопрос «как подключить бота в ВК к сообществу» почти всегда упирается в одно место — подтверждение адреса сервера. Остальное настраивается кнопками, а здесь нужен сервер, который ответит так, как ждёт ВКонтакте: одной строкой, без обёртки, кодом 200. Дальше — четыре шага по порядку и то, на чём подключение ломается.

Короткий ответ

1. Шагов четыре. Ключ доступа сообщества → адрес сервера → ответ на подтверждающий запрос → подписка на типы событий. Все четыре делаются в управлении сообществом, раздел «Работа с API».
2. Подтверждение — одна строка. ВКонтакте присылает на указанный адрес запрос с типом confirmation, сервер обязан вернуть код подтверждения обычным текстом и ответить 200. JSON-обёртка, кавычки, лишний перевод строки или редирект на другой адрес — подтверждение не проходит.
3. Обязательный тип события один — «Входящее сообщение». Остальные подписываются по задаче: без «Запрета на получение сообщений» бот будет писать тем, кто его запретил, без «События в чате» не сработают нажатия на кнопки под сообщением.
4. На каждое событие сервер отвечает ok. Быстро, до тяжёлой работы. Если ответа нет, ВКонтакте повторит доставку, и человек получит ответ дважды — поэтому нужен отсев повторов по идентификатору сообщения.
5. Главное свойство канала. Сообщество ВКонтакте может написать подписчику первым и бессрочно. Окна в 24 часа у ВК нет — чужое ограничение, попавшее в разговор по инерции.

Что такое Callback API ВКонтакте и чем он отличается от Long Poll

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

Разница чисто практическая.

• Callback API требует публичного адреса по https с действующим сертификатом. Зато сервер ничего не опрашивает и не держит соединение сам.
• Long Poll обходится без публичного адреса и годится, когда бот живёт на машине без домена или на ноутбуке разработчика. Но кто-то должен постоянно держать процесс опроса живым.

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

Шаг 1. Ключ доступа сообщества: какие права выдать

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

Ключ сообщества — не ключ пользователя. Ключ, полученный от лица человека, действует от лица человека: отправить сообщение от имени сообщества им нельзя. Частая ошибка первого подключения — ключ есть, запросы уходят, ответ «нет доступа».

Права выдаются по задаче, а не «все на всякий случай». Для переписки нужны сообщения сообщества. Если бот отвечает на комментарии под записями — добавляются права на стену. Если ведёт учёт подписчиков — права на участников. Лишние права ничего не улучшают, но расширяют ущерб при утечке ключа.

Сообщения сообщества включаются отдельно. Ключ с правами не включает переписку сам: в настройках сообщества сообщения включаются одним переключателем, возможности ботов — другим. При выключенных возможностях ботов клавиатура под сообщением не появится, хотя API примет запрос без ошибки.

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

Шаг 2. Адрес сервера и ответ на подтверждение

Адрес указывается там же, в «Работе с API» → Callback API. Требования простые, а нарушение любого из них выглядит одинаково — «сервер не подтверждён».

1. Доступен из интернета по https, с действующим сертификатом. Локальный адрес, закрытый порт, просроченный сертификат — доставки не будет.
2. Принимает POST с телом в JSON и отвечает сам, а не отправляет на другой адрес. Проверьте, что по адресу нет редиректа: со слешем на без слеша, с http на https, с домена на «www» — любой ломает подтверждение.
3. Отвечает кодом 200. Ответ 500, 404 или редирект ВКонтакте считает неудачей.

Само подтверждение выглядит так: ВКонтакте отправляет на адрес запрос, в котором type равен confirmation, и ждёт в ответ код подтверждения — строку, показанную в настройках сообщества. Ответ должен содержать только эту строку. Не {"response": "код"}, не строку в кавычках, не страницу с кодом внутри, не строку с переводом строки на конце, если фреймворк его добавляет. На этом месте спотыкаются чаще всего: в интерфейсе любая ошибка выглядит одинаково — «сервер не отвечает».

Там же задаются два поля, о которых легко забыть.

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

Версия API. От неё зависит форма события, а не только набор полей. В версиях 5.103 и новее входящее сообщение приходит объектом, внутри которого лежат message и client_info; в более старых поля сообщения лежали плоско. Код, написанный под старую форму, после смены версии перестаёт находить текст сообщения — и молчит, не падая: это одна из причин, по которым бот ВКонтакте не отвечает в личных сообщениях.

Шаг 3. Типы событий: что подписать, а что не нужно

После подтверждения адреса включаются типы событий. Подписка «на всё» — плохая идея: пойдёт поток событий, которые никто не обрабатывает, и в журнале станет нечего искать.

Минимальный рабочий набор для бота-ответчика: входящее сообщение, исходящее сообщение, разрешение и запрет на сообщения. Кнопки добавляют событие в чате. Приветствие новым подписчикам — подписку на сообщество. В Telegram роль такого переключателя играет режим приватности, из-за которого бот не видит сообщения в группе.

Шаг 4. Проверка: как убедиться, что события действительно идут

Подтверждённый адрес не означает работающего бота. Подтверждение проверяет один запрос, а дальше поток идёт другой. Порядок проверки — от входа к сценарию, а не наоборот.

1. Написать в сообщество с обычного аккаунта, а не с того, который им управляет. Со своего же аккаунта легко перепутать ответ из интерфейса сообщества с обращением человека: первое приходит как message_reply, второе — как message_new.
2. Посмотреть сырое тело запроса. Не разобранный объект, а то, что пришло. У себя мы держим сырой журнал входящих по всем каналам и открываем его первым: если записи нет, виновата доставка, а не сценарий.
3. Проверить, что сервер отвечает ok и отвечает быстро. Тяжёлую работу — вызов ИИ, запрос в CRM, отправку файла — выполнять после ответа. Иначе ВКонтакте не дождётся, повторит доставку, и человек получит два одинаковых ответа.
4. Отсеивать повторы по идентификатору сообщения. Повторная доставка — штатное поведение, а не сбой. Бот обязан узнавать событие, которое уже обработал.
5. Проверить, что события нужного типа включены. Классика: сообщения ходят, а кнопки не работают, потому что «Событие в чате» осталось невыбранным.

Точное число повторных попыток и предел времени на ответ лежат в документации ВКонтакте для разработчиков — на память их не называем. Если сервер перестал отвечать, ВКонтакте может его отключить.

Частые ошибки подключения

• Ключ пользователя вместо ключа сообщества. Запросы уходят, отправка сообщений отвечает ошибкой доступа.
• Подтверждение отдаётся в JSON. Нужна голая строка кода и статус 200, ничего больше.
• Редирект на адресе вебхука. Со слешем на без слеша или с http на https — подтверждение не пройдёт.
• Подписан только message_new. Бот работает, но пишет людям, которые запретили сообщения, и не видит ответов операторов из интерфейса ВКонтакте.
• Сменили версию API, не поправив разбор. Входящее сообщение приходит в другой форме, бот молчит без ошибок.
• Секрет не проверяется. На публичный адрес может постучаться кто угодно.
• Тяжёлая работа до ответа ok. Результат — дубли ответов у клиента и растущая очередь.
• Сообщения или возможности ботов выключены в настройках сообщества. Ключ, адрес и подписки в порядке, а переписки нет.

Что ВКонтакте даёт сверх остальных каналов

Из четырёх каналов, в которых мы делаем ботов, ВКонтакте единственный разрешает сообществу написать человеку первым. Разрешение даётся один раз — кнопкой «Разрешить сообщения» или самим обращением в сообщество, — и не истекает. Окна в 24 часа у ВК нет.

Практический смысл в том, что напоминания, догоняющие сообщения и возврат тех, кто не дошёл до конца, технически живут именно во ВКонтакте — не «во всех мессенджерах». Правила первого шага по каждому каналу разобраны отдельно: кто может написать клиенту первым.

Обратная сторона бессрочного права — ответственность. Подписка на «Запрет на получение сообщений» здесь не техническая деталь, а способ не превратить преимущество канала в жалобы.

Когда Callback API подключать не надо

Когда нет сервера и не планируется. Callback API требует публичного адреса, сертификата и кого-то, кто следит за машиной. Для автоответа на три вопроса в небольшом сообществе дешевле взять Long Poll или конструктор.

Когда цель — рассылка по купленной базе. ВКонтакте позволяет писать только тем, кто разрешил сообщения сообществу. Список телефонов или выгрузка из чужой таблицы такого права не дают, и никакая настройка Callback API этого не изменит.

Когда обращений мало. На двух-трёх обращениях в неделю разработка вряд ли окупится: человек ответит быстрее и точнее. Своя разработка начинает иметь смысл на потоке, когда ответы повторяются.

Когда решение принимается голосом. Сложные согласования и разговор с недовольным клиентом — не сценарий. Бот здесь полезен как приёмная: принять вопрос, передать человеку, не потерять диалог.

Когда сценарий переносится из другого канала один в один. Логика переедет, а клавиатуры, вложения и права на первое сообщение у каналов разные: лимиты Instagram* API устроены совсем не так, как правила ВКонтакте. Копия сценария Instagram* во ВКонтакте не использует главное, за что ВКонтакте и берут.

На своих данных: сколько ботов ВКонтакте живёт на нашем движке

Честно о размере выборки. ВКонтакте — самый маленький канал на движке ЭТОЧАТБОТ, и техническая часть этой статьи опирается на документацию ВКонтакте для разработчиков и на общую механику вебхуков в других каналах, а не на большую статистику поломок именно в ВК.

На 16 сентября 2026 года по пяти каналам на движке создано 426 ботов, из них 258 активных, 366 сценариев, 323 кабинета, 85 905 диалогов и 445 524 сообщения с апреля 2026 года. Это боты пользователей сервиса ЭТОЧАТБОТ, созданные на движке: люди регистрируются сами и собирают сценарии сами. Заказные проекты агентства здесь не посчитаны. Сам движок доступен по адресу etochat.bot.

Все четыре бота ВКонтакте активны, но выборка слишком мала для выводов о канале.

Сколько стоит подключение и что считается отдельно

Разработка — от 20 000 ₽, поддержка — от 5 000 ₽ в месяц. Точную цифру называем после разбора задачи и всегда до начала работ. Сроков не обещаем: объём виден после разбора, а часть работы зависит от того, что уже настроено в сообществе.

Что влияет на сумму в случае ВКонтакте:

• есть ли уже сервер с доменом и сертификатом или его надо поднимать с нуля;
• сколько типов событий обрабатывается — один поток сообщений или ещё комментарии, кнопки и подписки;
• нужны ли догоняющие сообщения, ради которых канал и выбирают: их надо не только отправлять, но и останавливать по запрету;
• есть ли связка с CRM или складом на стороне заказчика.

Если внутри бота работает ИИ-агент, его работа считается отдельно — по расходу токенов, а не фиксированной ставкой за месяц. Отдельно помогаем оплачивать зарубежные ИИ-сервисы иностранными картами. Как цена складывается в целом, разобрано в статье о том, сколько стоит разработка чат-бота; ориентиры по вилке есть и на странице с ценами на разработку и поддержку.

Если бот молчит после настройки

Если подтверждение не проходит или бот молчит уже после настройки — напишите в @etoBotTeamBot. Разберём по шагам: ключ, адрес, подтверждение, события; если бота писал другой разработчик, начнём с разбора чужого кода. Другие разборы по каналам и их ограничениям собраны в разделе про каналы для ботов.

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

Как подключить бота в ВК к сообществу?

В управлении сообществом, в разделе «Работа с API», четырьмя шагами: создать ключ доступа сообщества с правами на сообщения, указать адрес сервера в Callback API, ответить на подтверждающий запрос строкой-кодом со статусом 200, выбрать типы событий. Минимум из типов — «Входящее сообщение», без него бот не увидит ни одного обращения. Сообщения сообщества включаются отдельным переключателем.

Что такое Callback API в ВКонтакте?

Callback API — механизм, которым ВКонтакте сам отправляет события сообщества на ваш адрес: новое сообщение, нажатие кнопки, разрешение или запрет на переписку, комментарий под записью. Альтернатива — Long Poll, где ваш код опрашивает ВКонтакте сам и публичный адрес не нужен. Для бота, который работает постоянно, обычно берут Callback API, для машины без домена — Long Poll.

Почему не проходит подтверждение адреса сервера в Callback API?

Чаще всего по одной из четырёх причин: сервер отдаёт код подтверждения в JSON или в кавычках вместо голой строки, отвечает не 200, стоит редирект со слеша на без слеша или с http на https, либо адрес недоступен из интернета по https с действующим сертификатом. В ответ нужна только строка кода из настроек сообщества, без обёртки и лишнего перевода строки.

Как настроить чат-бота для приветствия в ВК?

Приветствие новому подписчику требует подписки на событие «Подписка на сообщество» (group_join) — по нему бот и отправляет первое сообщение. Приветствие в ответ на обращение работает от «Входящего сообщения». ВКонтакте — единственный канал из четырёх, где сообщество вправе написать подписчику первым и бессрочно, поэтому приветствие здесь можно отправить и не в момент обращения.

Можно ли писать подписчику ВКонтакте первым?

Да, и бессрочно. Сообщество ВКонтакте пишет человеку, который разрешил ему сообщения, — кнопкой «Разрешить сообщения» или самим обращением в сообщество. Окна в 24 часа у ВК нет, это чужое ограничение. Купленная база телефонов права писать не даёт. Чтобы не писать тем, кто отказался, нужна подписка на событие «Запрет на получение сообщений».

Какие права нужны ключу доступа сообщества?

Для переписки — права на сообщения сообщества; ключ должен быть именно сообщества, а не пользователя, иначе отправка ответит ошибкой доступа. Для автоответов под записями добавляются права на стену, для работы со списком подписчиков — на участников. Лишние права не помогают, но увеличивают ущерб при утечке ключа, поэтому выдаются по задаче.

Сколько стоит разработка бота ВКонтакте?

Разработка — от 20 000 ₽, поддержка — от 5 000 ₽ в месяц. Точную цифру называем после разбора задачи и до начала работ, сроков не обещаем. На сумму влияют наличие готового сервера с доменом и сертификатом, число обрабатываемых типов событий и связки с CRM. ИИ-агент внутри бота считается отдельно — по расходу токенов.