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

# Chatbot Einrichtung

> Widget anlegen, Domain-Whitelist und erste Konversation

## Chatbot Einrichtung

Diese Anleitung beschreibt, wie du einen Chatbot in Northline Echo anlegst, das Widget freischaltest und die erste Konversation testest.

***

# Voraussetzungen

* Zugang zur Northline-Echo-Organisation mit Berechtigung zur Chatbot-/Widget-Konfiguration
* Eine oder mehrere Domains, auf denen das Widget eingebunden werden soll

***

# Chatbot anlegen

1. Im Dashboard zu **Chatbot** (bzw. **Einstellungen** → Grundeinstellungen → Widget) wechseln.
2. Einen neuen Chatbot anlegen oder den bestehenden auswählen.
3. **Widget-Key** notieren – er wird für die Einbettung benötigt und ist eindeutig pro Organisation/Widget.

<Warning>
  Den Widget-Key nicht öffentlich in Repositories oder Client-Code committen. Die Einbettung erfolgt über ein Snippet, das den Key enthält; die Domain-Whitelist begrenzt den gültigen Einsatz.
</Warning>

***

# Domain-Whitelist

Das Chat-Widget antwortet nur auf Anfragen von **whitelisteten Domains**.

* **Einstellung:** Unter Chatbot-/Widget-Konfiguration die erlaubten Domains eintragen (z. B. `https://meine-firma.de`, `https://www.meine-firma.de`).
* **Lokal/Test:** `localhost` und `127.0.0.1` sind für Entwicklung oft voreingetragen oder können ergänzt werden.
* **Produktion:** Nur die tatsächlich genutzten Domains eintragen – keine Platzhalter oder Wildcards.

Ungültige oder nicht freigegebene Domains erhalten eine klare Fehlermeldung; das Widget lädt dann nicht oder blockiert die Konversation.

***

# Einbettungs-Snippet

Nach dem Speichern der Konfiguration erhältst du ein **Einbettungs-Snippet** für deine Website.

Typischer Aufbau:

```html theme={null}
<script
  src="https://[APP-URL]/widget.js"
  data-widget-key="wk_xxxxxxxx"
  defer
></script>
```

* **APP-URL** – Basis-URL der Northline-Echo-Instanz
* **data-widget-key** – dein Widget-Key
* **defer** – empfohlen, damit das Laden der Seite nicht blockiert wird

Das Script bindet das Chat-Widget ein (z. B. als Bubble und Panel). Details zu Position und Optik siehe [Branding & Einbindung](/chatbot/branding-einbindung).

***

# Erste Konversation testen

1. Seite mit eingebettetem Widget in einem erlaubten Origin aufrufen.
2. Chat öffnen und eine Testnachricht senden.
3. Prüfen, ob Antworten kommen und ob ggf. ein Lead erfasst wird (siehe [Lead Capture](/chatbot/lead-capture)).

<Tip>
  Bei Problemen: Domain-Whitelist prüfen, Widget-Key vergleichen, Browser-Konsole auf Fehler prüfen. Bei CORS- oder 403-Meldungen zuerst die Whitelist-Konfiguration prüfen.
</Tip>

***

# Sicherheit

* **API-Anfragen** werden mit dem Widget-Key und optional Origin-Header validiert.
* **Kein org\_id im Frontend** – die Zuordnung erfolgt serverseitig über den Widget-Key.
* Konversationsdaten unterliegen der gleichen Zugriffskontrolle wie andere Organisationsdaten (RLS, Rollen).

More coming soon.