64 lines
3.3 KiB
Markdown
64 lines
3.3 KiB
Markdown
---
|
||
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`).
|