⚡️ Функции виджета

Функция — это то, что выполняется, когда посетитель взаимодействует с виджетом. Функции объявляются на вкладке Functions редактора и вызываются из элементов по functionName.

Важное различие: функции агента (Конструктор → Функции) показывают виджет, а функции виджета запускает пользователь.

🧰 Пять типов

1. call_api

Отправляет запрос на ваш эндпоинт.

• url, method (GET … DELETE), headers, inputs.
• waitForResponse — дождаться ответа и добавить его в данные.

2. set_variables

Меняет данные виджета без внешнего вызова. Самый простой способ переключать состояния: { "booked": true }.

3. send_message

Отправляет сообщение в диалог. В message можно использовать {{токены}}.

4. open_link

Открывает url в новой вкладке; в адресе тоже работают токены.

5. dismiss

Закрывает виджет. Закрытие запоминается — после перезагрузки страницы виджет не возвращается.

🔑 Токены

В любом текстовом поле функции (url, заголовки, inputs, message) можно писать {{путь}}. Он вычисляется по данным виджета вместе с дополнительными входами:

url:    https://api.example.com/orders/{{orderId}}
inputs: { "note": "{{note}}", "total": "{{order.total}}" }

➕ Дополнительные входы

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

функция: track_order → дополнительные входы: orderId, note

<Button label="Отследить"
  onClickAction={{ functionName: 'track_order',
                   additionalInputs: { orderId: "{{order.id}}" } }} />

Правило безопасности: сервер принимает только объявленные имена. Чтобы значение формы дошло до вашего API, имя поля должно быть в этом списке, иначе оно придёт пустым. Редактор помечает токены, которые не находятся ни в данных, ни среди объявленных входов.

⏳ Индикатор загрузки

• none — без индикатора.
• self — спиннер на нажатом элементе.
• container — оверлей на всём виджете.

🔁 Последующие действия

После завершения функция может выполнить ещё одно действие:

• у call_api — onSuccess и onFailure;
• у остальных — одно действие после выполнения;
• последующее действие — это set_variables или dismiss.

call_api: confirm_booking
  onSuccess → set_variables { booked: true }
  onFailure → set_variables { error: "Бронирование не прошло" }

🔐 Безопасность call_api

• При доставке виджета в чат его поля url, headers и inputs удаляются — браузер их не видит.
• Браузер отправляет только имя функции и объявленные входы; сам вызов выполняет сервер.
• Поэтому API-ключи в заголовках хранить безопасно.

🪜 Многошаговые виджеты

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

🧱 Как выглядит вкладка Functions

Каждая функция — сворачиваемая строка с именем и однострочным описанием (тип). В развёрнутом виде поля идут во всю ширину, повторяющиеся значения (переменные, входы API) показаны таблицей с заголовком, а внизу расположена кнопка удаления.