VK (ВКонтакте)

OPORA поддерживает VK messenger через Callback API (группа → сервис-аккаунт → OPORA webhook). Подходит для сообществ: отвечать клиентам из сообщения сообщества, рассылать уведомления подписчикам чата сообщества.

1. Сообщество VK + group token

У вас должна быть группа VK (паблик / бизнес-страница / мероприятие):

1. Перейдите в сообщество → Управление → Настройки
2. «Сообщения» → включите «Сообщения сообщества» (если выключены)
3. «Работа с API» → «Создать ключ»
4. Скопируйте access_token группы

2. Сохраните в OPORA

Settings → Secrets:

• vk-group-token: group access_token
• vk-group-id: id сообщества (число, отображается в URL: vk.com/club<id>)
• vk-callback-secret: произвольная строка, openssl rand -hex 16, для валидации webhook’а

3. Настройте Callback API

В сообществе VK:

1. Настройки → Работа с API → Callback API
2. Адрес: URL OPORA webhook’а (после publish’а workflow’а с vk.webhook.trigger)
3. Секретный ключ: значение вашего vk-callback-secret secret’а
4. Строка подтверждения: VK покажет 7-значный код — нужен для first-time-handshake’а

Confirmation handshake

VK Callback API при первой регистрации шлёт GET / POST с "type": "confirmation" и ждёт в ответ plain-text confirmation code (не JSON). OPORA этот handshake не автоматизирует в v1 — confirmation нужно один раз сделать вручную:

1. В OPORA отключите vk.webhook.trigger на секунду
2. Временно поставьте на тот же URL простой Node / nginx который отвечает нужной строкой
3. VK Callback API → «Подтвердить» — handshake прошёл
4. Верните OPORA-trigger обратно

Альтернатива: создайте static-route в Caddy который на "type":"confirmation" возвращает строку, а все остальные шлёт proxy’им на OPORA. Пример в backlog’е (docs/ops/ vk-confirmation.md TODO).

5. Типы событий: отметьте нужные (чаще всего message_new, message_reply, group_join, wall_post_new)

4. Ноды

Нода	Что делает
vk.webhook.trigger	Incoming events с body.secret validation
vk.message.send	Отправка сообщения (peerId / userId / chatId routing)

5. Пример: автоответчик

vk.webhook.trigger (event: message_new)
    ↓
ai.chat
  system = "Ты помощник магазина. Отвечай коротко."
  input = "{{trigger.object.message.text}}"
  memory_key = "vk:{{trigger.object.message.from_id}}"
    ↓
vk.message.send
  peer_id = {{trigger.object.message.peer_id}}
  message = {{chat.output}}

Peer ID conventions

VK использует разные типы peer_id:

• user_id (положительное число < 2e9) — ЛС с пользователем
• chat_id как 2e9 + chatId (например, 2000000001 для chatId = 1) — беседа в сообществе
• group_id (отрицательное) — ЛС от имени группы

OPORA автоматически normalize’ит — в node можно передавать либо peer_id напрямую, либо user_id / chat_id отдельно (тогда node соберёт peer_id по конвенции VK).

Что не реализовано

• Attachments (photos, docs, stickers) в outbound’е — через API можно, но отдельная iteration’а
• Keyboards / inline buttons
• Pinning сообщений
• Group events beyond messages (wall_post_new и т.д. работают как trigger, но dedicated-ноды для response’а нет)

Добавим по demand’у.

Связанное

• VK WorkSpace / VK Teams — enterprise-мессенджер VK (отдельный API, нода vkteams.message.send; dedicated guide в подготовке, см. providers matrix)
• Telegram — для B2C аудитории часто лучше Telegram
• MAX — новый российский мессенджер, aналогичная структура