Действия на странице

Зарегистрируйте действие сайта#

Действия открывают интерфейс самого сайта или разрешённую страницу. Установите текущий виджет и регистрируйте действия после загрузки скрипта. Обработчики остаются в приложении; агент получает только названия, описания и определения параметров, без кода обработчика.

MakeAgentFast.registerAction("show_details", {
  description: "Показать раздел с подробностями на этой странице",
  params: { section: { type: "string", description: "Используйте delivery или returns" } },
  confirm: true
}, async ({ section }) => {
  const sections = {
    delivery: document.getElementById("delivery-details"),
    returns: document.getElementById("returns-details")
  };
  if (!Object.hasOwn(sections, section) || !sections[section]) {
    throw new Error("Неизвестный раздел");
  }
  sections[section].scrollIntoView({ block: "start" });
  return { shown: section };
});

// Выполните при размонтировании компонента страницы:
// MakeAgentFast.unregisterAction("show_details");

Оба метода возвращают boolean: принята ли регистрация или отмена регистрации. Имя начинается со строчной латинской буквы, содержит 2–40 строчных букв, цифр или подчёркиваний. Доступны девять своих действий и встроенное open_page. На действие допускается пять обязательных строковых параметров со значениями до 200 символов. Описания — до 200 символов. Обработчик должен вернуть строку или сериализуемое в JSON значение до 2 КБ за 10 секунд.

Разрешите действия в панели#

Откройте сайт с установленным виджетом, чтобы он сообщил имена и описания, затем Агент → Действия → Действия на странице. Включите функцию и разрешите нужные действия. Описания — недоверенные метаданные сайта; обнаружение не означает разрешение. Настройки сохраняются автоматически.

Агент предлагает только одновременно зарегистрированные и разрешённые действия. Перед выполнением клиент видит карточку. Подтверждение обязательно, если владелец не отметил действие безопасным; confirm: true в коде сайта всегда требует нажатия. Одно лишь confirm: false не обходит политику владельца. Безопасный режим подходит для безвредных изменений интерфейса.

Для встроенного open_page обработчик не нужен. Разрешите его в панели: он принимает относительный путь или HTTP(S) URL на разрешённых источниках сайта агента. Для относительного пути текущий источник сайта также должен быть разрешён. Переход на произвольный внешний адрес запрещён.

Передавайте события через track#

MakeAgentFast.track("form_error", { formId: "contact" });
MakeAgentFast.track("checkout_help", { step: "delivery" });

Вызывайте после загрузки виджета, когда соответствующее событие действительно произошло. Настройте такое же имя в Последующих уведомлениях. Формат имени тот же, 2–40 символов; необязательные данные — JSON-объект до 1 КБ. Не передавайте значения полей, секреты и платёжные данные. Правила учитывают событие/путь/задержку; метаданные не сохраняются, не передаются модели и не подтверждают конверсию. true означает приём загрузчиком, а не показ сообщения.

Безопасность и проверка#

Действия работают в живом виджете сайта, но не в каналах сообщений, репетиции владельца или голосовом звонке. Загрузчик и фрейм проверяют источник, origin, slug и ID ожидающего запроса. Результаты возвращаются в чат как недоверенные данные браузера, а не подтверждение изменения серверной записи. Сохраняйте проверку аутентификации и прав в обработчиках/backend; для значимых изменений используйте Действия изменения.

Тайм-аут не отменяет обработчик и не доказывает, что ничего не произошло. Не повторяйте неопределённое действие автоматически. Снимайте регистрацию при уходе компонента со страницы. Для этого API старым кэшированным установкам нужна версия загрузчика 20261014-page-actions.

API не обрабатывает платежи и не предоставляет коннектор Shopify.