---
name: vk-bridge
description: "Интеграция ВКонтакте (сообщество) через Bots Long Poll API: слушать message_new, извлекать текст/метаданные, проксировать запрос в локальный AI-обработчик и отправлять ответ в VK через messages.send. Использовать, когда нужно подключить входящие сообщения VK к ассистенту и отвечать пользователям автоматически."
---

# VK Bridge

Подключай сообщество VK к локальному обработчику ответов через Long Poll.

## Что входит

- `scripts/vk-longpoll-bridge.mjs` — раннер Long Poll + отправка ответов в VK.
- `scripts/vk-openclaw-endpoint.mjs` — локальный HTTP endpoint `/vk/inbound`, который проксирует сообщения в OpenClaw `/v1/responses`.
- `references/.env.example` — пример конфигурации.

## Быстрый запуск

1. Скопируй конфиг:
   - `cp skills/vk-bridge/references/.env.example .env.vk`
2. Заполни `VK_TOKEN` и `OPENCLAW_GATEWAY_TOKEN`.
3. Запусти локальный endpoint:
   - `node skills/vk-bridge/scripts/vk-openclaw-endpoint.mjs --env .env.vk`
4. В отдельном процессе запусти Long Poll worker:
   - `node skills/vk-bridge/scripts/vk-longpoll-bridge.mjs --env .env.vk`

## Требования

- Токен сообщества VK с правами `messages`.
- Включённые сообщения сообщества в настройках группы.
- Long Poll API включён для сообщества.
- Локальный HTTP-обработчик, который принимает входящее сообщение и возвращает текст ответа.
- В Gateway включён HTTP endpoint `POST /v1/responses` и известен токен доступа.

## Протокол AI-обработчика

Bridge делает POST на `OPENCLAW_BRIDGE_URL` с JSON:

- `source`: `vk`
- `group_id`
- `user_id`
- `peer_id`
- `text`
- `payload`
- `attachments`
- `raw`

Ожидает JSON-ответ:

- `reply` (string) — текст для отправки в VK.
- `silent` (boolean, optional) — если `true`, не отправлять ответ.

## Дополнительные настройки

- `VK_ALLOWED_EVENTS` — список типов событий через запятую (по умолчанию `message_new`).
- `VK_SYNC_LONGPOLL_SETTINGS=1` — при старте проверяй `groups.getLongPollSettings` и включай нужные события через `groups.setLongPollSettings`.
- `VK_API_VERSION=5.199` — рекомендуемая версия (раннер предупреждает, если другая).

## Надёжность

- При `failed=1` обновляй `ts`.
- При `failed=2|3` запрашивай новый `server/key/ts` через `groups.getLongPollServer`.
- Игнорируй пустые/служебные сообщения и события вне списка `VK_ALLOWED_EVENTS`.
- Не отвечай на исходящие (`out=1`).