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

# Integrazione Widget WebView

> Wrapper web incorporabile per iniettare il widget di chat Lovi

## Introduzione

L'endpoint Widget WebView è un wrapper HTML interattivo che ti permette di incorporare in modo sicuro il widget di chat Lovi all'interno di pagine web o applicazioni mobili. Invece di restituire una risposta JSON standard, questo endpoint serve un documento HTML completo contenente un `iframe` che punta all'interfaccia di chat.

Questo wrapper funge da ponte sicuro, recuperando i metadati di integrazione necessari (come il messaggio di benvenuto dell'agente e le impostazioni della lingua) lato server e iniettandoli in modo sicuro nella webview utilizzando la comunicazione `postMessage` standard.

***

## 🌐 Ottieni Widget WebView

> **Metodo**: GET **Formato**: HTML

### Endpoint

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

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

### Parametri Query

Se non utilizzi la struttura del percorso sopra menzionata, devi passare i parametri richiesti nella query string.

| Parametro     | Richiesto | Descrizione                                                                                                 |
| ------------- | --------- | ----------------------------------------------------------------------------------------------------------- |
| `customer_id` | Sì        | La tua Access Key aziendale usata per validare i permessi.                                                  |
| `widget_id`   | Sì        | Lo specifico `uuid` dell'account canale/widget che desideri caricare.                                       |
| `lang`        | No        | Codice lingua di destinazione (es. `es`, `en`, `pt`). Se fornito, i messaggi di benvenuto vengono tradotti. |
| `showClose`   | No        | Booleano come stringa (`true` o `false`). Predefinito `true`. Determina se il widget può essere chiuso.     |

### Come Funziona

1. **Autenticazione**: Il server valida il `customer_id` (Access Key) e verifica la proprietà del `widget_id`.
2. **Recupero Metadati**: Recupera la configurazione del widget e opzionalmente interroga il backend di traduzione Lovi per tradurre il messaggio di benvenuto dell'agente nella `lang` richiesta.
3. **Consegna HTML**: Il server restituisce una pagina HTML contenente un `<iframe src="https://widget.lovi.ai/?cw_id=...">`.
4. **Ponte PostMessage**: L'HTML caricato contiene JavaScript che ascolta gli eventi `get_widget` e `get_customer` attivati dall'iframe. Risponde in modo sicuro con la configurazione del widget (`widgetData`) e gestisce lo storage locale (come generare un ID utente univoco).

### Errori Comuni

Se il widget non riesce a caricarsi, potresti ricevere uno dei seguenti codici di stato HTTP invece del payload HTML:

* **400 Bad Request**: `customer_id` o `widget_id` mancanti, o `widget_id` non è un UUID valido.
* **403 Forbidden**: `customer_id` invalido (validazione Access Key fallita).
* **404 Not Found**: L'azienda o il widget specificato non è stato trovato.
* **500 Internal Server Error**: Si è verificato un errore imprevisto durante la generazione del wrapper.

> 🧭 **Importante**: Se il widget appare bloccato su una schermata "Loading Widget...", controlla la console del browser. Assicurati che il tuo ambiente consenta iframe cross-origin e non blocchi la comunicazione `postMessage` tra il WebView e `widget.lovi.ai`.