💬 VK Community Integration

1Создайте сообщество VK

1. Перейдите на vk.com
2. Создайте сообщество (тип: "Бизнес" или "Тематическое сообщество")
3. Настройте название, описание, аватар
4. Включите сообщения: Управление → Сообщения → Включить
5. 💡 Совет: Для бизнеса рекомендуется тип "Бизнес" с включёнными товарами

2Получите Access Token

1. Откройте Управление → Работа с API
2. Нажмите "Создать ключ"
3. Выберите права доступа:
   • ✅ Управление сообществом
   • ✅ Сообщения
4. Скопируйте токен (начинается на vk1.a....)
5. ⚠️ Важно: Сохраните токен в надёжном месте! Повторно показать не смогут

3Узнайте Group ID

Есть несколько способов узнать ID сообщества:

1. Посмотрите на URL сообщества:
   • vk.com/public123456789 → Group ID: 123456789
   • vk.com/club123456789 → Group ID: 123456789
   • vk.com/mycommunity → Нужно открыть страницу и посмотреть в источнике
2. Используйте онлайн-сервисы:
   • Whois VK
   • VK API Groups

4Настройте в личном кабинете

1. В личном кабинете откройте страницу агента → вкладка Интеграции
2. Найдите секцию "VK Сообщество"
3. Заполните поля:
   • Group ID - ID сообщества (только цифры)
   • Access Token - токен из Шага 2
   • Callback Secret Key - придумайте секретный ключ (минимум 10 символов)
4. Нажмите Проверить подключение для проверки credentials
5. Нажмите Сохранить интеграции
6. Скопируйте Webhook URL (появится после сохранения)

5Настройте Callback API

1. Перейдите в Управление → Работа с API → Callback API
2. Нажмите "Добавить сервер"
3. Заполните поля:
   • Server URL - Webhook URL из личного кабинета
     https://gonka-backend.onrender.com/api/v1/vk/webhook/<agent-id>
   • Secret key - Secret Key из личного кабинета
4. Нажмите "Сохранить"
5. Скопируйте Confirmation Code (код подтверждения)
6. Вернитесь в личный кабинет и вставьте код в поле "Код подтверждения"
7. Нажмите "Подтвердить" в настройках VK (или обновите страницу агента)
8. ✅ Статус сервера изменится на "OK"

6Включите события

1. В настройках Callback API нажмите "Настройки событий"
2. Включите обязательные события:
   • ✅ Входящие сообщения (message_new)
   • ✅ Разрешение на отправку сообщений (message_allow)
   • ✅ События кнопок (message_event)
3. Опционально (для расширенной функциональности):
   • ⚪ Запрет на отправку сообщений (message_deny)
4. Нажмите "Сохранить"

Текстовые команды

VK не поддерживает slash-команды (/start, /help). Вместо этого используются текстовые триггеры:

Кнопки главного меню

VK поддерживает callback-кнопки (аналог Inline Keyboard в Telegram):

📨 message_new

Новое входящее сообщение от пользователя

{
  "type": "message_new",
  "object": {
    "peer_id": 123456,
    "text": "Привет!",
    "from_id": 789012,
    "conversation_message_id": 1
  }
}

🔘 message_event

Нажатие на callback-кнопку

{
  "type": "message_event",
  "object": {
    "peer_id": 123456,
    "event_id": "abc123",
    "payload": {"action": "menu"},
    "conversation_message_id": 1
  }
}

✅ message_allow

Пользователь разрешил сообщения от сообщества

{
  "type": "message_allow",
  "object": {
    "user_id": 789012,
    "peer_id": 123456
  }
}

Webhook не подтверждается

Проблема: VK не принимает webhook URL

Решение: Убедитесь что сервер доступен из интернета (не localhost). Проверьте BASE_URL в настройках. Для локальной разработки используйте ngrok или подобный сервис.

Сообщения не приходят

Проблема: Бот не получает сообщения

Решение: Проверьте что включены события message_new в настройках Callback API. Убедитесь что Confirmation Code подтверждён.

Кнопки не работают

Проблема: Нажатие на кнопки не обрабатывается

Решение: Убедитесь что используется type: "callback" и обрабатывается message_event. Проверьте что событие message_event включено в настройках Callback API.

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

Проблема: Не проходит проверка Group ID + Access Token

Решение: Проверьте что токен действителен и имеет права "Управление сообществом" и "Сообщения". Убедитесь что Group ID соответствует сообществу.

Токены не расшифровываются

Проблема: Ошибка расшифровки токенов

Решение: Проверьте что ENCRYPTION_KEY установлен в переменных окружения и совпадает с тем что использовался при шифровании.