Custom actions виджета

customActions нужны, когда ответ виджета должен содержать кнопку, которую обрабатывает ваш сайт: открыть заказ, показать тариф, запустить собственный сценарий или изменить локальное состояние интерфейса. Сначала реализуйте и защитите действие на стороне сайта, затем объявите его виджету.

Отдельной формы для customActions в кабинете нет: сайт передаёт их при SenlerWidget.init(...) или позже через SenlerWidget.updateRuntime(...). Поэтому здесь приведён пример интеграции, а внешний вид кнопки посетителя показан в статье «Интерфейс виджета».

Что происходит после ответа

Страница передаёт объект customActions. Ключ — техническое имя действия, значение — обязательный handler и необязательные title, description, payloadSchema.

Агент получает только имя, заголовок, описание и схему данных. Сам handler остаётся на странице. По умолчанию он вызывается после нажатия посетителя на кнопку custom_action и получает { name, payload, button_text }.

Объявите действие

SenlerWidget.init({
  channel_id: "xxx",
  customActionsLanguage: "ru",
  customActions: {
    "site.openOrder": {
      title: "Открыть заказ",
      description: "Открывает карточку заказа по order_id.",
      payloadSchema: {
        type: "object",
        properties: {
          order_id: { type: "string" },
        },
        required: ["order_id"],
        additionalProperties: false,
      },
      handler({ payload }) {
        const orderId = String(payload?.order_id || "");
        if (!canViewOrder(orderId)) return;
        openOrder(orderId);
      },
    },
  },
});

canViewOrder и openOrder в примере обозначают ваши функции проверки доступа и открытия карточки. Реализуйте их на стороне сайта; скрипт-загрузчик не создаёт готовых глобальных функций с такими именами.

Если title и description написаны на одном языке, укажите customActionsLanguage: "ru" или "en". Параметр не переводит текст, а сообщает AI язык описаний. Без него используется двуязычный поиск по русским и английским описаниям.

Опишите входные данные

Имя берётся из ключа объекта customActions. Оно должно начинаться с латинской буквы, быть не длиннее 120 символов и может содержать латинские буквы, цифры, _, ., : и -.

В одном контексте можно объявить до 20 действий. title ограничен 80 символами, description — 240 символами. Сам payloadSchema должен быть обычным объектом схемы. Корневое поле type можно опустить; если оно задано, поддерживается только "object". Глубина схемы — не более 8 уровней, сериализованный размер одной схемы — не более 1200 символов, а всех передаваемых описаний действий вместе — не более 6000 символов. В общий размер входят имена, заголовки, описания и схемы.

Поддерживается ограниченное подмножество JSON Schema: типы object, string, number, integer, boolean, array, null и поля properties, required, additionalProperties, items, enum, title, description, default, examples, minLength, maxLength, pattern, minimum, maximum, minItems, maxItems. Другие поля отклоняются при инициализации. Не передавайте секреты в schema, description или payload.

custom_action.name нельзя придумывать динамически: агент использует только имена, явно переданные текущей страницей. Если страница не объявила действие, виджет не должен обещать или выполнять такую кнопку.

Проверьте действие на сайте

payload формируется по ответу агента и приходит в браузер вместе с кнопкой, поэтому считайте его недоверенными входными данными. handler должен заново проверить типы, права пользователя, существование объекта и допустимость операции. Для удаления, оплаты и других значимых изменений оставляйте обычное подтверждение сайта.

Скрипт-загрузчик вызывает handler синхронно и не ожидает возвращённый Promise. Если обработка асинхронная, самостоятельно обработайте ошибку и покажите результат пользователю внутри сайта.

Обновление действий при навигации

Действия можно заменить без пересоздания виджета:

SenlerWidget.updateRuntime({
  customActions: buildActionsForCurrentPage(),
  customActionsLanguage: "ru",
});

Скрипт-загрузчик передаёт новые описания в виджет, а handler остаётся на странице сайта и заменяет предыдущий обработчик с тем же именем.

updateRuntime заменяет весь текущий набор действий. Передавайте полный набор для новой страницы, а не только добавленные имена.

Автоматическое выполнение

По умолчанию действие представляется пользователю кнопкой. autoExecuteCustomActionNames разрешает автоматически выполнить только перечисленные имена в текущем сценарии Public API. Кнопки этих действий не показываются в сообщении. Из одного ответа автоматически выполняется первое подходящее действие, поэтому проектируйте такой ответ с одной автоматической операцией; остальные перечисленные кнопки также будут скрыты.

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

Чем custom action отличается от действий по элементам

Custom action объявляет собственную бизнес-операцию сайта и вызывает ваш handler. Действия по элементам (highlight, click, fill и другие) работают с размеченным DOM по data-ai-context-id. Не используйте custom action только ради подсветки обычной кнопки.

Переходы по ссылкам

open_url обрабатывается страницей сайта: target: "self" меняет текущую страницу, без self ссылка открывается в новой вкладке.

Для внутренних переходов сайта лучше объявить custom_action: так сайт сам проверит payload и выполнит переход через свой маршрутизатор.

Что подключать дальше

Если действие должно не просто открыть страницу или изменить состояние сайта, а подготовить AI-правку конкретного поля с просмотром до применения, используйте inline-правки. Полный список runtime-параметров и событий находится в справочнике Public API.