Интеграции
Интеграция — это подключённый источник: мессенджер, соцсеть или способ входа на сайт. Через интеграции система узнаёт о событиях (пришло сообщение, человек вступил в группу) и отвечает пользователю. Раздел — /cabinet/integrations.
Обзор
Что умеют интеграции
Интеграция решает три задачи: авторизация (человек входит на сайт через знакомый сервис), приём сигналов (события из источника попадают в систему и запускают программы по триггерам) и отправка (бот пишет пользователю — из программы или рассылки).
Что поддерживается
- ВКонтакте (сообщество) и MAX — полноценные источники: принимают события и отправляют сообщения, из программ доступны произвольные вызовы их API.
- VK ID и другие способы входа — для авторизации пользователей на сайте.
- Telegram — в разработке.
- ИИ — подключение нейросети для чата-помощника в кабинете (только творец). См. «ИИ-помощник».
Как подключить
Нажмите «Добавить интеграцию», выберите тип из каталога и заполните настройки: название, домен и токен доступа. После подключения у интеграции появляются две вкладки — «Настройки» и «Журнал сигналов». Чтобы события начали приходить, у источника настраивается приём (вебхук) — см. разделы ниже.
ВКонтакте
Источник — сообщество ВКонтакте. Бот отвечает от имени сообщества и реагирует на события в нём.
Подключение
В настройках интеграции укажите токен сообщества с правами на сообщения и управление. Адрес приложения (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=…. Если он открывает приложение из каталога или сообщества, меток не будет — там их просто неоткуда взять.
Дубли не создаются
Метки записываются один раз на человека: повторные заходы с теми же метками не плодят записи. Если человек придёт позже по другой ссылке с другими метками — появится новая запись, и это правильно: видно, что он откликнулся на другую кампанию.
Требуется настроить
Чтобы ссылка заработала, интеграция должна быть подключена в проекте (раздел «Интеграции») и относиться к этому проекту либо быть общей для кабинета. Ссылка на неподключённую интеграцию приведёт к ошибке «Интеграция не найдена».