Действия с результатом

Укажите действие в customActions. Проверяйте входные данные и права пользователя в обработчике и на сервере; для значимых изменений оставляйте подтверждение сайта.

Объявите обработчик

Чтобы агент получил результат handler и использовал его в ответе, укажите returnsResult: true. Например, так можно ответить на вопрос «Сколько подписчиков у бота 15?»:

SenlerWidget.init({
  channel_id: "xxx",
  customActionsLanguage: "ru",
  customActions: {
    "site.getSubscriberCount": {
      title: "Число подписчиков",
      description: "Возвращает текущее число подписчиков бота по bot_id.",
      returnsResult: true,
      payloadSchema: {
        type: "object",
        properties: { bot_id: { type: "integer", minimum: 1 } },
        required: ["bot_id"],
        additionalProperties: false,
      },
      async handler({ payload, signal }) {
        const subscribers = await getSubscriberCount(payload.bot_id, { signal });
        return { bot_id: payload.bot_id, subscribers };
      },
    },
  },
});

getSubscriberCount — ваша функция чтения данных с проверкой прав текущего пользователя. Реализуйте её на сайте и передавайте signal сетевому запросу, чтобы поддержать отмену ожидания.

Вызов и результат

В этом режиме агент сам вызывает действие через инструмент execute_widget_custom_action. Кнопка и autoExecuteCustomActionNames не нужны; действие с этим флагом нельзя использовать как кнопку. Обработчик получает { name, payload, signal }. Можно вернуть обычное значение или Promise: виджет дождётся результата и передаст его модели как ответ инструмента. Данные сохраняются в истории диалога, поэтому возвращайте только то, что требуется для ответа, без токенов доступа и секретов.

Возвращайте JSON: объект, массив, строку, конечное число, boolean или явный null. Значения 0 и false сохраняются. undefined, функции, DOM-элементы, циклические структуры и другие значения вне JSON считаются ошибкой. Максимальный размер — 16 KiB UTF-8, глубина — 8 уровней, общее число значений — 2048. Ошибка throw или отклонённый Promise передаётся агенту как ошибка инструмента.

Ожидание и отмена

Ожидание handler ограничено 20 секундами, а общий срок вызова с доставкой — 30 секундами. При таймауте или уничтожении виджета signal отменяется; прекращение самой операции зависит от того, поддерживает ли его ваш код. Поздний результат не заменяет завершённый вызов. Тяжёлый синхронный код по-прежнему может блокировать страницу — таймер не прерывает JavaScript.

Вызов привязан к экземпляру обработчика на странице, которая объявила действие. Другая вкладка, перезагрузка страницы или замена определения действия не перехватывают старый вызов. Если исходная страница больше недоступна, агент получит таймаут. Повторная доставка запроса или результата не запускает handler заново. Ошибка или таймаут не доказывают, что операция на сайте не выполнилась.

Ожидание добавляется только для действий с returnsResult: true: время handler, доставка результата и следующий шаг модели. Сам Promise не блокирует интерфейс. Возвращайте короткие данные, чтобы не увеличивать контекст и время обработки ответа.