> ## 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.

# Integração WebView do Widget

> Wrapper web incorporável para injetar o widget de chat Lovi

## Introdução

O endpoint Widget WebView é um wrapper HTML interativo que permite incorporar o widget de chat Lovi de forma segura em páginas web ou aplicativos móveis. Em vez de retornar uma resposta JSON padrão, este endpoint serve um documento HTML completo contendo um `iframe` apontando para a interface de chat.

Este wrapper atua como uma ponte segura, buscando os metadados de integração necessários (como a mensagem de boas-vindas do agente e configurações de idioma) no lado do servidor e injetando-os com segurança na webview usando comunicação `postMessage` padrão.

***

## 🌐 Obter WebView do Widget

> **Método**: GET **Formato**: HTML

### Endpoint

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

*Formato de caminho alternativo:* `GET https://cloud.lovi.ai/functions/v1/widgetWebView/{customer_id}/{widget_id}`

### Parâmetros de Consulta

Se você não estiver usando a estrutura de caminho mencionada acima, deve passar os parâmetros obrigatórios na string de consulta.

| Parâmetro     | Obrigatório | Descrição                                                                                                      |
| ------------- | ----------- | -------------------------------------------------------------------------------------------------------------- |
| `customer_id` | Sim         | A Access Key da sua empresa usada para validar permissões.                                                     |
| `widget_id`   | Sim         | O `uuid` específico da conta do canal/widget que você deseja carregar.                                         |
| `lang`        | Não         | Código de idioma de destino (ex.: `es`, `en`, `pt`). Se fornecido, as mensagens de boas-vindas são traduzidas. |
| `showClose`   | Não         | Booleano como string (`true` ou `false`). Padrão `true`. Determina se o widget pode ser fechado.               |

### Como Funciona

1. **Autenticação**: O servidor valida o `customer_id` (Access Key) e verifica a propriedade do `widget_id`.
2. **Busca de Metadados**: Recupera a configuração do widget e opcionalmente consulta o backend de tradução Lovi para traduzir a mensagem de boas-vindas do agente para o `lang` solicitado.
3. **Entrega de HTML**: O servidor retorna uma página HTML contendo um `<iframe src="https://widget.lovi.ai/?cw_id=...">`.
4. **Ponte PostMessage**: O HTML carregado contém JavaScript que escuta os eventos `get_widget` e `get_customer` disparados pelo iframe. Responde com segurança com a configuração do widget (`widgetData`) e lida com armazenamento local (como gerar um ID de usuário único).

### Erros Comuns

Se o widget falhar ao carregar, você pode receber um dos seguintes códigos de status HTTP em vez do payload HTML:

* **400 Bad Request**: Faltam `customer_id` ou `widget_id`, ou o `widget_id` não é um UUID válido.
* **403 Forbidden**: `customer_id` inválido (falha na validação da Access Key).
* **404 Not Found**: A empresa ou o widget especificado não pôde ser encontrado.
* **500 Internal Server Error**: Ocorreu um erro inesperado ao gerar o wrapper.

> 🧭 **Importante**: Se o widget aparecer travado na tela "Loading Widget...", verifique o console do navegador. Certifique-se de que seu ambiente permita iframes de origem cruzada e não bloqueie a comunicação `postMessage` entre o WebView e `widget.lovi.ai`.