# ADR-0024. Сообщество ВКонтакте мерчанта

- Статус: принято; реализовано на этапе 7 — 7j-1 (сообщество мерчанта, его события, подключение ВКонтакте к карте из
  кабинета покупателя, SMS «Не вы?»), 7j-2 (сообщения во ВКонтакте, согласие «Реклама во ВКонтакте»)
- Дата: 2026-11-07

## Контекст

Часть 7j плана была «агрегаторы мессенджеров». WhatsApp, Telegram и Viber в России заблокированы или ограничены, а
агрегаторы дают их только через автоматизацию личного номера или официальный WhatsApp Business для тех, кто ходит
через VPN. Владелец продукта выбрал вместо них ВКонтакте (2026-11-07).

Сообщество ВКонтакте может писать только тем, кто сам ему написал или разрешил его сообщения; писать по номеру
телефона нельзя. Сообщество работает по ключу доступа, который его администратор создаёт в «Управление» → «Работа с
API» → «Ключи доступа» с правами «Сообщения сообщества» и «Управление сообществом»; ключ не истекает. Свои события
сообщество присылает на серверы Callback API (до 10 на сообщество): сервер подтверждает адрес кодом, который выдаёт
`groups.getCallbackConfirmationCode`, в каждом событии — секрет сервера, ответ — строка `ok`, событие без ответа
ВКонтакте присылает ещё раз. Ссылка `vk.me/<короткое имя>?ref=<метка>` открывает чат сообщества, и метка приходит в
событии `message_new` вместе с id написавшего.

Мини-приложение (карта внутри ВКонтакте) — позже: ему нужно одно приложение платформы во ВКонтакте, модерация не
меньше трёх дней, пользовательское соглашение и политика конфиденциальности и согласие поддержки ВКонтакте на вход по
коду из SMS внутри приложения (правила платформы, п. 4.3.2). `VKWebAppGetPhoneNumber` не доказывает, что номер —
человека: годится только подставить номер в форму.

Решения владельца продукта (2026-11-07): сначала только сообщения сообщества; порядок — MAX, потом ВКонтакте, потом SMS
или письмо; реклама во ВКонтакте — с отдельным согласием «Реклама во ВКонтакте», кнопкой «Не присылать рекламу» и
словом «стоп».

## Решение

### Сообщество мерчанта

- Одно сообщество на мерчанта — строка `communication_channels` провайдера `vk` рядом с SMS-каналами, почтой и ботом
  MAX. Ключ запечатан, как пароль SMS-аккаунта (`CredentialBox`); в `settings` — id сообщества, его название и
  короткое имя (из него сделана ссылка на чат), программа, код подтверждения сервера, id сервера платформы и SHA-256
  секрета событий. Списки SMS-каналов, порядок кодов, «Почта» и «MAX» сообщества не видят.
- Подключение (`Contracts\VkCommunity::connect`): сначала ВКонтакте отвечает, чьё это сообщество и что может ключ
  (`groups.getById`, `groups.getTokenPermissions`), — ключ, который он не принял, не хранится; без прав на сообщения и
  управление (`field: token`) и сообщество без короткого имени (`field: community`) не подключаются. Код подтверждения
  берётся до того, как ВКонтакте узнаёт о сервере: он спрашивает код сразу. Потом сообщество сохраняется с новым
  секретом, и сервер платформы `<APP_URL>/hooks/vk/<канал>` («Loyalty») настраивается: найден по пути адреса (на любом
  хосте: APP_URL мог смениться) и изменён или добавлен, его двойники удалены, где ВКонтакте позволяет, — затем отдельно
  включены события `message_new`, `message_allow`, `message_deny`, `message_event` (`groups.setCallbackSettings`,
  версия 5.199). Чужие серверы сообщества (CRM, рассылки) остаются. Что ответил ВКонтакте, записывается, только если
  ключ всё ещё тот, о котором спрашивали, и секрет — тот, что ему дали. Другое сообщество на месте прежнего удаляет
  сервер прежнего (если ВКонтакте отвечает) и забывает привязки; переход к другой программе забывает привязки.
- Секрет меняется в два шага, как у MAX: новый становится тем, с которым принимаются события, как только сервер
  ВКонтакте его получил, — даже если события включить не удалось (тогда сообщество «не работает», и проверка включает их
  снова); до тех пор события принимаются и со старым, и с новым, а новый секрет в пути оставляет принятым и предыдущий
  в пути (`webhook_stale_sha256`): ВКонтакте мог его принять, а ответ — потеряться. Всё, что говорит с ВКонтакте о
  сообществе одного мерчанта, идёт по очереди (блокировка сессии БД вне транзакции).
- Проверка — снова те же вопросы, код и сервер с новым секретом; отказ — состояние сообщества, а не ошибка; урезанные
  права ключа — `access_refused`. Выключенное сообщество не подключает покупателей; привязки остаются. Удаление удаляет
  сервер платформы (если ВКонтакте отвечает), забывает ключ и привязки. Подключения и проверки считаются в часовом
  лимите мерчанта вместе с другими каналами, а ключи, которые ВКонтакте отклонил, останавливают их на время —
  сначала у мерчанта, потом у всех (`RequestLimits`, сервер `vk`).
- Запросы к ВКонтакте — только через `Gateway` (`VkApi`: форма POST на `api.vk.ru/method/<метод>`, ключ в теле,
  никогда в адресе; отказ — по `error_code`: 5 и 28 — ключ не принят, 7, 15 и 27 — нет права, 900–902 у сообщения —
  человек запретил сообщения или его настройки их не пускают, 6, 9, 10 и 29 — ВКонтакте занят). Свой текст
  ВКонтакте не хранится: в нём может быть то, что отправляли; отказ 7 или 15 у сообщения закрывает маршрут этого
  сообщения, а не сообщество. В песочнице — двойник: любой ключ — сообщество с обоими правами и коротким именем
  `sandbox-<id>` — с дефисом, которого ВКонтакте не даёт: ссылка песочницы не ведёт в чужое сообщество.

### События сообщества

- ВКонтакте присылает события на `POST /hooks/vk/<канал>` — вне группы web и API. Арендатор находится до RLS функцией
  SECURITY DEFINER `vk_channel_tenant()`. `confirmation` своего сообщества получает код (секрет, если он прислан,
  должен быть своим); остальное — только со своим секретом и своим `group_id` (иначе 401), канал не сообщества — 404,
  ответ — `ok`.
- Повтор события ничего не делает второй раз: его `event_id` хранится сутки (`vk_events`) в той же транзакции, что и
  работа, — событие, работа которого упала на миг (конфликт сессий, потерянное соединение), при повторе выполняется. Сбой,
  который повторился бы при каждом повторе, записывается в журнал ошибок, а событие принимается: сервер, который раз за
  разом отвечает ошибкой, ВКонтакте на время перестаёт кормить событиями — и подключения всех покупателей встали бы.
- `message_new` в личном чате с меткой `link-<метка канала>-<токен>` — подключение ВКонтакте к карте и ответ: «Готово:
  ВКонтакте подключён к карте программы … с номером …» (номер замаскирован: пересланная ссылка — не секрет того, кто по
  ней написал), «Ссылка устарела…» или «Сейчас подключить ВКонтакте к карте … не получится…» — с адресом кабинета
  покупателя, пока он работает; не чаще раза в 30 секунд одному человеку и до ответа ВКонтакте (3 секунды на ответ). Тот,
  чей ВКонтакте уже подключён, по использованной ссылке ответа не получает. Метка канала (6 знаков из его id) отличает
  ссылки платформы от `ref` самого мерчанта и от ссылок другого сервера платформы в том же сообществе: чужие метки не
  разбираются.
- QR-код у кассы — `vk.me/<короткое имя>?ref=card-<метка>`: написавшему по нему сообщество раз в сутки отвечает, что
  ВКонтакте подключают в профиле кабинета покупателя, с его адресом (или что кабинет закрыт). Всё остальное, что пишут
  сообществу, платформа не отвечает: сообщения сообщества — канал мерчанта, их читают его люди.
- `message_allow` и `message_deny` снимают и ставят отметку `stopped_at` привязки — и у выключенного сообщества.
  У закрытого мерчанта события не принимаются. `message_event` — нажатия кнопок согласия и отказа от рекламы (7j-2,
  ниже).

### Подключение ВКонтакте к карте

- Только из профиля кабинета покупателя: `POST /p/<имя>/vk/link` даёт одноразовую ссылку
  `https://vk.me/<короткое имя>?ref=link-<метка канала>-<токен>` (15 минут; хранится SHA-256 токена, `vk_link_tokens`;
  отказ в подключении тоже тратит токен: его `ref` видели все серверы сообщества; заблокированной карте ссылка ничего
  не подключает). Человек
  отправляет в чате любое сообщение — ВКонтакте говорит, кто написал (`from_id`), — и этот аккаунт подключается к
  карте (`vk_links`: id ВКонтакте запечатан ключом персональных данных под контекстом привязки и найден по слепому
  индексу `communications.vk_user`; один аккаунт на участника и один участник на аккаунт в сообществе). Написав
  сообществу, человек разрешает его сообщения.
- Не по номеру телефона и не по входу через VK ID. Привязка ничего не открывает: ни входа в кабинет, ни кодов кассы
  (коды кассы во ВКонтакте не уходят).
- О каждом новом аккаунте на номер карты сразу уходит SMS «К карте подключён ВК. Не вы? <ссылка>» (тема `vk_linked`,
  только по SMS, не выключается в «Автосообщениях»): ссылку на карту из профиля мог получить любой, у кого в браузере
  остался открытым чужой кабинет. Уведомления ВКонтакте живут в той же таблице, что и уведомления MAX
  (`max_link_notices.messenger` = `vk`), со страницей `/m/<токен>`: «Это не я — отключить ВКонтакте» забывает аккаунт
  ВКонтакте и MAX — кто подключил один, сидел во входе участника и мог подключить и другой, а MAX входит без кода, — и
  завершает все входы в кабинет покупателя и сеансы плоскости участника; «Не вы?» уведомления о MAX так же отключает и
  ВКонтакте. «ВК», а не «ВКонтакте»: с ссылкой до 40 знаков это одно SMS, как у MAX. Если уведомление не записать,
  ВКонтакте не подключается; без работающего SMS-канала с деньгами — тоже; после трёх подключений MAX и ВКонтакте за
  сутки (любых, и по коду) новые без кода не принимаются — счёт идёт под одной блокировкой участника, последней, которую
  берёт подключение (`Internal\UnprovenLinks`, отказы — те же `max_link_unavailable` и `max_links_throttled`).
- Порядок блокировок — как у MAX: строка участника, его привязки MAX, его привязки ВКонтакте (блокировки транзакции),
  строка сообщества (`for key share`), токены.
- Всё, что завершает входы участника ради защиты, забывает и ВКонтакте с его неиспользованными ссылками: блокировка
  карты, новый номер, обезличивание, «Выйти на всех устройствах» в кабинете покупателя и у сотрудников, «Не вы?» о
  списании и о подключении MAX или ВКонтакте. Объединение дублей передаёт привязку выжившему, если у него её нет;
  покупатель отключает ВКонтакте сам кнопкой «Отключить ВКонтакте» в профиле.
- Доверие к людям сообщества. Секрет сервера событий видят администраторы сообщества и сервисы с ключом «Управление
  сообществом» (ВКонтакте показывает его в настройках «Callback API» и отдаёт `groups.getCallbackServers`), а `ref`
  ссылки покупателя получают все серверы сообщества: такой человек может подделать событие и подключить свой
  ВКонтакте к чужой карте. Мерчант сам доверяет им данные покупателей; страница «ВКонтакте» предупреждает. Закрыть это
  может только второй код, который сообщество присылает в чат ВКонтакте и который набирают во входе, просившем ссылку
  (как в 7i-4), — отложено: лишний шаг для каждого покупателя. О согласии на рекламу — ниже, в 7j-2.

### Сообщения во ВКонтакте (7j-2)

- Тем, кто подключил ВКонтакте, служебные сообщения, автосообщения и реклама уходят в чат сообщества — после MAX
  (решение владельца продукта: сначала MAX, потом ВКонтакте, потом письмо или SMS в порядке мерчанта) и бесплатно, с
  кнопкой «Моя карта», пока работает кабинет покупателя. Не принял ВКонтакте — сообщение сразу уходит следующим
  маршрутом. Уведомление о списании «Не вы?» — сначала по SMS, затем письмом, MAX и ВКонтакте последними: аккаунт,
  который подключил кто-то другой, не должен забрать новость о списании у хозяина номера. Уведомления о подключении MAX
  и ВКонтакте — только по SMS; коды кассы во ВКонтакте не уходят никогда. Маршрут `vk` в журнале сообщений; номер
  участника — как у SMS, для поиска.
- `random_id` сообщения — из id сообщения участнику, 31 бит (ВКонтакте берёт int32): повтор того же сообщения
  ВКонтакте не примет дважды. Отказ ВКонтакте человеку (900–902, а у сообщения и 7, 15) закрывает маршрут только этого
  сообщения — запрет сообщений отмечает только `message_deny`; ВКонтакте не ответил — попытка позже, в этом проходе его
  больше не спрашивают; ключ не принят — сообщество «не работает». Сообщения уходят на `peer_ids`: так ВКонтакте
  называет id сообщения в диалоге (`conversation_message_id`), с которым потом присылает нажатие его кнопки.
- Кнопки — встроенная клавиатура; ВКонтакте принимает её, только когда в сообществе включены «Возможности ботов»
  («Управление» → «Сообщения» → «Настройки для бота»). Иначе ВКонтакте отказывает с ошибкой 912: сообщество
  помечается (`settings.keyboards_refused`, кабинет просит включить их; «Проверить» снимает отметку, а следующий отказ
  ставит снова), сообщение без рекламы сразу уходит ещё раз без кнопок, реклама во ВКонтакте не уходит (без кнопки
  «Не присылать рекламу» нельзя), ответ «Готово» подключившему уходит без кнопок — с адресом кабинета покупателя
  отдельной строкой — и без вопроса о рекламе.
- Реклама — только с согласием «Реклама во ВКонтакте» (`marketing_vk`, отдельный документ, как «Реклама в MAX»), пока
  ВКонтакте присылает события сообщества (по ним приходят отказы) и принимает кнопки, с кнопкой «Не присылать рекламу»,
  помеченной для участника, которому ушла.
- Вопрос о рекламе: подключившего ВКонтакте сообщество сразу спрашивает, присылать ли ему рекламу, — если работает
  кабинет покупателя (отказ и устаревшие кнопки отправляют в его профиль), программа опубликовала согласие, участник на
  него ещё не отвечал и текст согласия не длиннее 2000 знаков, — с текстом документа и кнопками «Да, присылать» и
  «Нет». «Готово» о подключении уходит всегда, без ограничения частоты ответов. Кнопки несут метку канала (`ch`: на
  нажатия кнопок другого сервера сообщества и собственного бота мерчанта платформа не отвечает), версию и метку
  участника.
- Согласие из нажатия. `messages.sendMessageEventAnswer` принимает только `event_id`, `user_id` и `peer_id`: принятый
  ответ доказывает, что человек нажал какую-то кнопку в этом чате, но не какую. Поэтому «Да» засчитывается, только
  если нажата кнопка под тем самым вопросом: id сообщения вопроса и его версия хранятся с привязкой
  (`vk_links.question_message`, `question_version`), «Да» с другого сообщения (например, кнопки с той же нагрузкой,
  которую прислал кто-то с ключом сообщества) — «Кнопка устарела». Каждое нажатие учитывается один раз, чьей бы ни была
  кнопка (`vk_events` с префиксом `p:`): нажатие, пришедшее повторно под другим id события (так может только тот, у
  кого секрет), отказывать может, давать согласие — нет. Согласие пишется, только когда ВКонтакте принял ответ, — уже
  удерживая участника, если аккаунт всё ещё его, состояние согласия не менялось с нажатия (отказ, пришедший за эти
  секунды, остаётся в силе) и вопрос ещё не использован (берётся сейчас: одно «Да» — одно согласие). Отказ («Нет»,
  кнопка под рекламой, слово «стоп» в чате — и в сообщении со ссылкой) записывается сразу, тому, к кому аккаунт
  подключён сейчас, какой бы ни была метка кнопки (после объединения дублей — выжившему), и выключенным сообществом
  тоже (38-ФЗ: требование прекратить исполняется сразу). Согласие и отказ — через `Members::changeConsent`, канал `bot`,
  с идентификатором сообщества, слепым индексом аккаунта, id нажатия и id сообщения.
- Что остаётся. Тот, у кого секрет сервера, может подделать нажатие «Да» под вопросом, взяв id настоящего нажатия
  покупателем другой кнопки в том же чате, если его подделка придёт раньше настоящего события, — то есть перехватить
  нажатие. Это люди, которым мерчант доверил сообщество; страница «ВКонтакте» предупреждает.
- «Не вы?» о подключении MAX или ВКонтакте отзывает согласия на рекламу, данные онлайн — через бота, сообщество или в
  кабинете покупателя, где MAX входит без кода, — после подключения первого аккаунта, о котором ещё предупреждают
  уведомления участника: их мог давать тот, кто подключал. Данные на кассе и раньше остаются.
- Проверка «Баллы скоро сгорят» учитывает ВКонтакте как MAX: тех, кого достаёт только мессенджер, предупреждает, а день
  держит открытым для остальных, пока не сможет уйти SMS или письмо.

### Кабинет мерчанта

- Страница «ВКонтакте» в разделе каналов: подключение по ключу и программе, проверка, выключение, включение и
  удаление — с правом `channels.manage`, в журнале аудита `vk-community.*` (ключ — никогда); ссылка-приглашение и QR-код
  для кассы; предупреждение, кому видно секрет сервера событий. В карточке участника видно, подключён ли ВКонтакте.

## Последствия

- Покупателю не нужно ничего, кроме ВКонтакте: одна кнопка в профиле и одно сообщение сообществу. Сообщения
  ВКонтакте для мерчанта бесплатны: кто подключил ВКонтакте, тому SMS почти не нужны.
- Платформа отвечает в сообществе только на сообщения по своим ссылкам; другой бот сообщества (рассылки, CRM) может
  ответить тому же человеку и сам.
- Если мерчант удалит сервер «Loyalty» в настройках сообщества или отзовёт ключ, подключения не проходят, пока он не
  нажмёт «Проверить» или не подключит сообщество заново.
- Вживую не проверено: нужен сервер, доступный ВКонтакте из интернета, и настоящее сообщество. Формы запросов и ответов
  — по документации API ВКонтакте 5.199; проверка вживую на тестовом стенде с тестовым сообществом — до production. Там же
  проверить: подтверждает ли ВКонтакте сервер, добавленный через API, сразу (иначе читать его `status` в
  `groups.getCallbackServers` и показывать в кабинете); приходит ли `ref` только с первым сообщением после перехода по
  ссылке; как узнать, что «Сообщения сообщества» выключены (сейчас не проверяется: ссылка на такой чат ведёт в никуда);
  открывает ли `vk.me` ссылка из мини-приложения MAX; бывают ли ошибки 7 и 15 у `messages.send` из-за одного человека.
  Для 7j-2: как долго и в каких пределах ВКонтакте помнит `random_id` (за всю историю или около часа: повторы идут
  через 5, 30 и 120 минут); отвечает ли `messages.send` с `peer_ids` списком с `conversation_message_id` и приходит ли он
  в `message_event`; принимает ли ВКонтакте второй ответ на то же нажатие и ответ с чужими `user_id`/`peer_id`; ошибка
  ли 912 при выключенных «Возможностях ботов» и можно ли включить их ключом (`groups.setSettings`, `bots_capabilities`).
