Справочник

Интеграции

Интеграция — это подключённый источник: мессенджер, соцсеть или способ входа на сайт. Через интеграции система узнаёт о событиях (пришло сообщение, человек вступил в группу) и отвечает пользователю. Раздел — /cabinet/integrations.

Обзор

Что умеют интеграции

Интеграция решает три задачи: авторизация (человек входит на сайт через знакомый сервис), приём сигналов (события из источника попадают в систему и запускают программы по триггерам) и отправка (бот пишет пользователю — из программы или рассылки).

Что поддерживается

Как подключить

Нажмите «Добавить интеграцию», выберите тип из каталога и заполните настройки: название, домен и токен доступа. После подключения у интеграции появляются две вкладки — «Настройки» и «Журнал сигналов». Чтобы события начали приходить, у источника настраивается приём (вебхук) — см. разделы ниже.

ВКонтакте

Источник — сообщество ВКонтакте. Бот отвечает от имени сообщества и реагирует на события в нём.

Подключение

В настройках интеграции укажите токен сообщества с правами на сообщения и управление. Адрес приложения (webapp), если он требуется в настройках сообщества, — https://АДРЕС_САЙТА/cabinet.

Приём событий (Callback API)

Чтобы сообщения доходили до системы, в сообществе включается Callback API (Управление → Работа с API → Callback API): туда добавляется адрес нашего сервера, и его нужно «Подтвердить» в интерфейсе сообщества — без подтверждения сервер остаётся в статусе «не подтверждён» и события не идут. Затем включаются подписки на нужные типы событий (например, «Входящее сообщение»).

Диагностика

Кнопка «Диагностика» на странице интеграции проверяет всю цепочку: валиден ли токен и хватает ли прав, добавлен ли и подтверждён ли наш Callback-сервер, включены ли подписки на нужные события. Многие проблемы она чинит сама. Если бот «молчит», хотя всё выглядит зелёным, — диагностика обычно показывает, где разрыв.

Что доступно после подключения

События сообщества запускают ваши программы. Из программ можно отправлять сообщения и делать произвольные вызовы VK API блоком «Запрос к API ВКонтакте».

Telegram

Интеграция с Telegram в разработке. Тип есть в каталоге, но приём и отправка пока недоступны.

MAX

Источник — бот в мессенджере MAX.

Подключение

В настройках интеграции укажите токен бота MAX. Приём событий настраивается на стороне мессенджера; после подключения события бота запускают программы.

Что доступно после подключения

Бот принимает события и отправляет сообщения. Из программ доступны произвольные вызовы Bot API MAX блоком «Запрос к API MAX» — метод, query-параметры и, при необходимости, тело запроса.

Веб-сайт и VKID

Пользователи входят в веб-кабинет по адресу https://АДРЕС_САЙТА/cabinet. Для входа используется авторизация через VK ID: в разделе интеграций добавляется приложение VK ID со своими параметрами (идентификатор и секрет приложения). Помимо VK ID система предусматривает и другие способы входа (например, через Яндекс) — набор зависит от настроек.

Журнал сигналов

У каждой интеграции есть вкладка «Журнал сигналов» — он показывает весь её трафик, чтобы ничего не терялось и было видно, что происходит.

Входящие и исходящие

Входящие — события, пришедшие от источника (они фиксируются ещё до проверки, поэтому видно и отклонённые). Исходящие — отправленные сообщения и обращения к API. Новые записи сверху, тело раскрывается по клику; есть фильтр «Все / Входящие / Исходящие».

Включение логирования

Журнал — диагностический инструмент, по умолчанию он выключен. На вкладке два переключателя: отдельно для входящих и для исходящих. Включайте их, когда разбираетесь с проблемой, и выключайте потом. Хранятся примерно последние 1000 записей на интеграцию.

Повтор сигнала

Кнопка «Повторить» в строке проигрывает сигнал заново: входящий — заново запустит программы (и может отправить сообщения), исходящий — повторно отправит запрос в сеть. Действие с подтверждением — удобно, чтобы воспроизвести ситуацию при отладке.

Журнал авторизаций

Отдельная вкладка «Авторизации» отвечает на вопрос «кто и когда заходил в приложение через эту интеграцию». Она есть у ВК-приложения, сообщества ВКонтакте, MAX и Telegram.

Что записывается

Только успешные события: вход уже зарегистрированного человека и регистрация нового (когда он первый раз зашёл через приложение). Видно время, пользователя, его ID в сети, IP-адрес и проект, в который он вошёл. Отказы и неудачные попытки не сохраняются.

Включение

По умолчанию журнал выключен. Включается переключателем «Вести журнал авторизаций» на той же вкладке; рядом выбирается срок хранения — по умолчанию 30 дней. Старше срока записи удаляются автоматически раз в сутки.

Это персональные данные: кто, когда и с какого адреса заходил. Включайте, если они вам действительно нужны, и сообщите участникам в своих правилах.

Работа с журналом

Записи идут новыми сверху. Есть фильтр «Все / Входы / Регистрации» и поиск по ID в сети, IP-адресу и имени. Кнопка «Показать ещё» подгружает следующую порцию, «Очистить журнал» удаляет все записи этой интеграции (с подтверждением, необратимо).

Не путайте с «Журналом вызовов» выше: там трафик интеграции (вебхуки и запросы к API), здесь — только входы людей.

UTM-метки

UTM-метки показывают, откуда пришёл человек: из какой рекламы, кампании, по какой ссылке. Система принимает их в мини-приложениях и складывает в раздел «UTM-метки» кабинета.

Зачем это нужно

Вы запускаете рекламу в трёх местах — объявление во ВКонтакте, пост в Telegram, рассылку в MAX. Все ведут в одно и то же мини-приложение. По UTM-меткам видно, какая ссылка привела человека, а не просто «пришёл кто-то».

Как это работает

Ссылка с метками ведёт не напрямую в приложение, а через наш адрес:

https://АДРЕС_САЙТА/wparams/14?utm_source=vk_ads&utm_medium=cpc&utm_campaign=sale

Разберём по частям:

Часть Что значит
/wparams/14 14 — id интеграции (не проекта и не бота). Система по нему понимает, в какое приложение вести человека
utm_source источник: vk, telegram, max или название площадки
utm_medium тип трафика: cpc, email, social
utm_campaign название кампании — удобно задавать своё для каждой
utm_content, utm_term необязательные: какой баннер, какое ключевое слово

Дополнительно можно указать r=miniapps — на какую страницу кабинета перевести человека после входа.

Готовые примеры

В кабинете откройте Проект → Ссылки (/cabinet/projects/{id}/links). У каждой интеграции будет блок «Ссылка с UTM-метками» с готовым примером и кнопкой «Скопировать пример».

Замените значения после = на свои — остальное трогать не нужно.

Что видит человек

Он нажимает вашу ссылку, попадает в приложение, входит — и всё как обычно. Метки на его experience не влияют.

Где смотреть результат

Раздел «UTM-метки» в кабинете (/cabinet/utm) показывает таблицу: когда пришёл, кто, источник, канал, кампания. Данные группируются по пользователям — видно первое касание каждого человека.

Особенности платформ

Каждая платформа передаёт метки по-своему, но для вас это неважно — ссылка из кабинета уже готова:

Платформа Что подставляется в ссылку
MAX ?startapp=… — метки едут целиком
Telegram ?startapp=… — короткий код, потому что у Telegram лимит на длину
ВКонтакте #utm_… — через фрагмент адреса

У ВКонтакте есть нюанс: метки работают, когда человек приходит по вашей прямой ссылке вида vk.ru/app1234#utm_source=…. Если он открывает приложение из каталога или сообщества, меток не будет — там их просто неоткуда взять.

Дубли не создаются

Метки записываются один раз на человека: повторные заходы с теми же метками не плодят записи. Если человек придёт позже по другой ссылке с другими метками — появится новая запись, и это правильно: видно, что он откликнулся на другую кампанию.

Требуется настроить

Чтобы ссылка заработала, интеграция должна быть подключена в проекте (раздел «Интеграции») и относиться к этому проекту либо быть общей для кабинета. Ссылка на неподключённую интеграцию приведёт к ошибке «Интеграция не найдена».