Интеграция на сайте

Для чего нужен этот тип

Выбирайте «Интеграцию на сайте», когда основной интерфейс и бизнес-логика находятся во внешнем сервисе, а пользователь должен подключить к нему проект Senler AI или разрешить работу от имени своего аккаунта. Например, это может быть CRM, платёжный сервис, аналитика или личный кабинет на сайте разработчика.

Подключение начинается на внешнем сайте. Пользователь подтверждает запрошенные права в Senler AI, после чего сервер интеграции получает OAuth-токены. При проектном доступе токен относится к одному выбранному проекту. При пользовательском доступе интеграция может обращаться к разрешённым проектам и developer-приложениям от имени пользователя, но каждый вызов ограничен его актуальными правами.

Как пользователь подключает интеграцию

Пользователь начинает подключение на сайте разработчика.
Senler AI открывает страницу авторизации с названием приложения и точным перечнем запрашиваемых разрешений. Для проектного доступа пользователь также выбирает проект; для пользовательского доступа подтверждает работу от имени своего аккаунта.
После подтверждения Senler AI возвращает пользователя на разрешённый Redirect URI, а сервер интеграции обменивает полученный код на токены.

У опубликованного приложения может быть карточка в каталоге плагинов с переходом на сайт разработчика и ссылка на документацию приложения.

События для агентов

«Интеграция на сайте» не добавляет агенту вызываемые инструменты и не встраивает интерфейс приложения в кабинет. При этом приложение с проектным OAuth-доступом может отправлять объявленные события для агентов: например, сообщить об успешной оплате и запустить агента в связанном диалоге.

Сначала разработчик объявляет тип события и схему его данных. После установки приложения пользователь включает это событие у нужного агента. Затем интеграция вызывает POST /api/app-agent-events и передаёт уникальный external_event_id, тип события, данные, а также target.dialog_id и target.agent_id. Пример запроса и правила повторной отправки приведены в статье о событиях. Senler AI проверяет установку, схему, подписку и назначение агента на диалог. Если проверка пройдена, событие запускает выбранного агента; без подписки оно принимается со статусом ignored и не запускает ответ.

При OAuth-доступе от имени аккаунта пользователя отправка событий агентам недоступна: для неё нужна установка приложения в конкретный проект. Если агент должен сам вызывать функции приложения, используйте тип «Плагин». Если нужно установить готовый набор ресурсов в проект, используйте «Готовое решение».

Что настраивает разработчик

При создании выбирает тип «Интеграция на сайте», затем указывает название, описание, аватар и сайт в настройках приложения и добавляет публичную документацию.
В OAuth-настройках отдельно задаёт права проектного и пользовательского сценариев, сохраняет Redirect URI и безопасно хранит Client Secret.
На сервере обменивает authorization_code на access token, обновляет его через refresh_token и не передаёт Client Secret в браузер.
При необходимости объявляет события для агентов, добавляет вебхуки и документацию своего сервиса.

OAuth-доступ

Создание приложения и знание Client ID или Client Secret не дают доступа к данным. Доступ появляется только после явного OAuth-подтверждения пользователя и ограничивается выбранными разрешениями. Каждый запрос авторизации выбирает проектный или пользовательский сценарий параметром subject; одно приложение может использовать оба. Отзыв авторизации прекращает доступ внешнего сервиса.

Перед публикацией

Проверьте сайт разработчика, рабочий HTTPS Redirect URI, тексты на русском и английском языках, минимальный набор разрешений, сценарий отзыва доступа и пользовательскую документацию. После этого отправьте приложение на модерацию из раздела публикации.