Кнопки с действиями

Сначала объявите custom action и его входные данные.

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

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

Агент получает имя, заголовок, описание, схему данных и признак возврата результата. Сам 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 язык описаний. Без него используется двуязычный поиск по русским и английским описаниям.

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

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

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

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

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

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

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

open_url — встроенный тип действия для кнопки-ссылки в ответе агента. Например, агент предлагает кнопку «Открыть тарифы», а посетитель нажимает её и переходит на страницу с ценами.

Чтобы агент мог добавлять такие кнопки, включите кнопки в ответах. Объявлять open_url в customActions или писать для него handler не нужно: переход выполняет сам виджет.

В описании действия кнопки поле url содержит адрес, а target определяет, где его открыть:

target: "blank" или отсутствие target — в новой вкладке;
target: "self" — вместо текущей страницы сайта, а не внутри окна чата.

Это параметры действия кнопки, а не настройки SenlerWidget.init.

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