> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lovi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Интеграция Widget WebView

> Встраиваемый веб-обёртка для внедрения чат-виджета Lovi

## Введение

Эндпоинт Widget WebView — это интерактивная HTML-обёртка, которая позволяет безопасно встраивать чат-виджет Lovi на веб-страницы или в мобильные приложения. Вместо стандартного JSON-ответа этот эндпоинт возвращает полный HTML-документ, содержащий `iframe`, указывающий на интерфейс чата.

Эта обёртка действует как безопасный мост, получая необходимые метаданные интеграции (такие как приветственное сообщение агента и настройки языка) на стороне сервера и безопасно внедряя их в веб-представление с помощью стандартной коммуникации `postMessage`.

***

## 🌐 Получить Widget WebView

> **Метод**: GET **Формат**: HTML

### Endpoint

```
GET https://cloud.lovi.ai/functions/v1/widgetWebView
```

*Альтернативный формат пути:* `GET https://cloud.lovi.ai/functions/v1/widgetWebView/{customer_id}/{widget_id}`

### Query-параметры

Если вы не используете упомянутую выше структуру пути, вы должны передать обязательные параметры в строке запроса.

| Параметр      | Обязательно | Описание                                                                                              |
| ------------- | ----------- | ----------------------------------------------------------------------------------------------------- |
| `customer_id` | Да          | Access Key вашей компании, используемый для проверки разрешений.                                      |
| `widget_id`   | Да          | Конкретный `uuid` аккаунта канала/виджета, который вы хотите загрузить.                               |
| `lang`        | Нет         | Код целевого языка (например, `es`, `en`, `pt`). При указании приветственные сообщения переводятся.   |
| `showClose`   | Нет         | Boolean в виде строки (`true` или `false`). По умолчанию `true`. Определяет, можно ли закрыть виджет. |

### Как Это Работает

1. **Аутентификация**: Сервер проверяет `customer_id` (Access Key) и владение `widget_id`.
2. **Получение Метаданных**: Получает конфигурацию виджета и при необходимости запрашивает backend перевода Lovi для перевода приветственного сообщения агента на запрошенный `lang`.
3. **Доставка HTML**: Сервер возвращает HTML-страницу, содержащую `<iframe src="https://widget.lovi.ai/?cw_id=...">`.
4. **Мост PostMessage**: Загруженный HTML содержит JavaScript, который прослушивает события `get_widget` и `get_customer`, инициированные iframe. Он безопасно отвечает данными конфигурации виджета (`widgetData`) и обрабатывает локальное хранилище (например, генерацию уникального ID пользователя).

### Распространённые Ошибки

Если виджет не загружается, вы можете получить один из следующих HTTP-статусов вместо HTML:

* **400 Bad Request**: Отсутствует `customer_id` или `widget_id`, или `widget_id` не является допустимым UUID.
* **403 Forbidden**: Неверный `customer_id` (ошибка проверки Access Key).
* **404 Not Found**: Компания или указанный виджет не найдены.
* **500 Internal Server Error**: Произошла непредвиденная ошибка при генерации обёртки.

> 🧭 **Важно**: Если виджет зависает на экране "Loading Widget...", проверьте консоль браузера. Убедитесь, что ваша среда разрешает кросс-оригин iframe и не блокирует `postMessage` коммуникацию между WebView и `widget.lovi.ai`.