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

> Einbettbarer Web-Wrapper zum Injizieren des Lovi-Chat-Widgets

## Einführung

Der Widget WebView-Endpunkt ist ein interaktiver HTML-Wrapper, der es Ihnen ermöglicht, das Lovi-Chat-Widget sicher in Webseiten oder mobile Anwendungen einzubetten. Anstatt eine Standard-JSON-Antwort zurückzugeben, liefert dieser Endpunkt ein vollständiges HTML-Dokument, das einen `iframe` enthält, der auf die Chat-Oberfläche zeigt.

Dieser Wrapper fungiert als sichere Brücke, die die notwendigen Integrationsmetadaten (wie die Willkommensnachricht des Agenten und Spracheinstellungen) serverseitig abruft und sie sicher in die Webview über standardmäßige `postMessage`-Kommunikation injiziert.

***

## 🌐 Widget WebView Abrufen

> **Methode**: GET **Format**: HTML

### Endpoint

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

*Alternatives Pfadformat:* `GET https://cloud.lovi.ai/functions/v1/widgetWebView/{customer_id}/{widget_id}`

### Query-Parameter

Wenn Sie nicht das oben erwähnte Pfadformat verwenden, müssen Sie die erforderlichen Parameter im Query-String übergeben.

| Parameter     | Erforderlich | Beschreibung                                                                                                |
| ------------- | ------------ | ----------------------------------------------------------------------------------------------------------- |
| `customer_id` | Ja           | Ihr firmeneigener Access Key zur Validierung von Berechtigungen.                                            |
| `widget_id`   | Ja           | Die spezifische `uuid` des Kanal-Accounts/Widgets, das Sie laden möchten.                                   |
| `lang`        | Nein         | Zielsprachcode (z. B. `es`, `en`, `pt`). Bei Angabe werden Willkommensnachrichten übersetzt.                |
| `showClose`   | Nein         | Boolean als String (`true` oder `false`). Standard `true`. Bestimmt, ob das Widget geschlossen werden kann. |

### Wie es funktioniert

1. **Authentifizierung**: Der Server validiert den `customer_id` (Access Key) und überprüft den Besitz des `widget_id`.
2. **Metadaten-Abruf**: Er ruft die Widget-Konfiguration ab und fragt optional das Lovi-Übersetzungs-Backend ab, um die Willkommensnachricht des Agenten in die angeforderte `lang` zu übersetzen.
3. **HTML-Auslieferung**: Der Server gibt eine HTML-Seite mit einem `<iframe src="https://widget.lovi.ai/?cw_id=...">` zurück.
4. **PostMessage-Brücke**: Das geladene HTML enthält JavaScript, das auf `get_widget` und `get_customer` Events lauscht, die vom Iframe ausgelöst werden. Es antwortet sicher mit der Widget-Konfiguration (`widgetData`) und handhabt lokalen Speicher (z. B. Generierung einer eindeutigen Benutzer-ID).

### Häufige Fehler

Wenn das Widget nicht geladen werden kann, erhalten Sie möglicherweise einen der folgenden HTTP-Statuscodes anstelle des HTML-Payloads:

* **400 Bad Request**: Fehlender `customer_id` oder `widget_id`, oder `widget_id` ist keine gültige UUID.
* **403 Forbidden**: Ungültiger `customer_id` (Access Key-Validierung fehlgeschlagen).
* **404 Not Found**: Das Unternehmen oder das angegebene Widget konnte nicht gefunden werden.
* **500 Internal Server Error**: Ein unerwarteter Fehler beim Generieren des Wrappers ist aufgetreten.

> 🧭 **Wichtig**: Wenn das Widget auf einem "Loading Widget..."-Bildschirm hängen bleibt, überprüfen Sie die Browser-Konsole. Stellen Sie sicher, dass Ihre Umgebung Cross-Origin-Iframes erlaubt und die `postMessage`-Kommunikation zwischen dem WebView und `widget.lovi.ai` nicht blockiert.