🧰 UI-виджеты: справочник разработчика

Эта страница описывает формат хранения виджета, то, как его функции обращаются к вашему API, и контракт ошибок. Пользовательское руководство — в разделе UI-виджеты.

📦 Определение виджета

Файл .widget и объект в API имеют одинаковую структуру:

{
  "uuid": "…",
  "name": "Order status",
  "description": "Показывает статус заказа",
  "category": "ecommerce",
  "tree": { "type": "Card", "children": [] },
  "schema": { "type": "object", "properties": {} },
  "defaultState": {},
  "examples": [{ "name": "Example 1", "state": {} }],
  "states": [],
  "functions": []
}

• category: booking | ecommerce | forms | analytics | other.
• tree — один корневой узел; представление JSX печатается из него.
• schema — подмножество JSON Schema: type, properties, items, required, enum, default, format, description.

🌲 Дерево узлов

Каждый узел — объект с полем type; дочерние элементы в children:

{
  "type": "Card",
  "gap": 3,
  "children": [
    { "type": "Title", "value": "{{order.title}}", "size": "lg" },
    { "type": "Badge", "label": "{{order.status}}", "color": "info" },
    {
      "type": "Repeat",
      "each": "{{order.items}}",
      "as": "item",
      "children": [{ "type": "Text", "value": "{{item.name}}" }]
    }
  ]
}

• Привязка — путь в двойных фигурных скобках. Если свойство состоит только из привязки, сохраняется тип значения.
• Repeat перебирает массив (each, as); индекс элемента доступен как <as>Index.
• State связывается с правилом видимости по name.

⚙️ Объекты функций

{ "name": "confirm", "type": "call_api",
  "url": "https://api.example.com/book",
  "method": "POST",
  "headers": { "Authorization": "Bearer …" },
  "inputs": { "id": "{{order.id}}", "note": "{{note}}" },
  "additionalInputs": ["note"],
  "onSuccess": { "type": "set_variables", "variables": { "booked": true } },
  "onFailure": { "type": "set_variables", "variables": { "error": "…" } } }

Другие типы: set_variables (variables), send_message (message, hidden), open_link (url), dismiss.

🔐 Как выполняется call_api

• При доставке виджета в диалог функция call_api теряет url, method, headers и inputs и помечается как проксируемая.
• Браузер отправляет только имя функции и входы; запрос к вашему эндпоинту выполняет сервер.
• Сервер вычисляет токены по состоянию, сохранённому вместе с сообщением, поверх которого накладываются принятые входы.
• inputs — белый список: ключи, не объявленные в additionalInputs, отбрасываются.

🌐 Вызов со стороны посетителя

POST /api/v1/widget/ui-widget/{widget_uuid}/functions/execute

{
  "message_uuid": "…",
  "function_name": "confirm",
  "inputs": { "note": "hi" },
  "tool_call_id": "call_1"
}

• Авторизация — собственный токен чат-виджета.
• message_uuid обязателен: он подтверждает, что виджет был показан посетителю. Состояние и сессия читаются на сервере и не принимаются из браузера.
• tool_call_id нужен, если одно сообщение отрисовало один и тот же виджет дважды.

🚨 Ошибки

{ "success": false, "error": { "code": "…", "message": "…" } }

• WIDGET_FUNCTION_NOT_CALLABLE — посетителю нельзя вызывать эту функцию.
• WIDGET_INVALID_TOKEN, NOT_A_WIDGET_VISITOR — проблемы с токеном.
• WIDGET_NOT_IN_MESSAGE — сообщение с этим виджетом не найдено.
• WIDGET_FUNCTION_NOT_FOUND, WIDGET_FUNCTION_FAILED, WIDGET_FUNCTION_UNAVAILABLE.
• 429 — ограничение частоты (60 запросов в минуту на IP).
• 200 с ok: false означает, что ваш API отклонил запрос.

📤 Что должен возвращать ваш эндпоинт

• JSON-объект. При waitForResponse ответ добавляется в данные виджета, и привязки перерисовываются.
• Возвращайте имена полей из схемы либо используйте действие Вызов API + виджет с сопоставлением ответа: { "orders": "data.items" }.
• Ключа идемпотентности нет — защищайтесь от повторов на своей стороне. Браузер блокирует параллельный вызов той же функции, но сетевые повторы возможны.

🧾 Ограничения

• В дереве допустимы только разрешённые компоненты; остальное отклоняется.
• Виджеты привязаны к проекту: виджет другого проекта не будет найден.
• Компонент Map и client-функция на основе iframe пока не поддерживаются.