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

# Widget & Playground

Diese Seite erklärt, wie du deinen Agent auf deiner Website einbettest, wie du ihn vor dem Go-Live testest, und wie du einen eigenständigen Chat-Link teilst.

***

## Embed-Code holen

Dein Embed-Code befindet sich auf dem **Dashboard**. Klick auf den **Agent teilen**-Button (oben rechts) - es öffnet sich ein Dialog mit zwei Tabs: **Widget einbetten** und **Öffentlicher Link**.

> **Nur für Owner:** Der Agent-Teilen-Button ist nur für Workspace Owner sichtbar.

<Frame>
  <img src="https://mintcdn.com/tstgdev/1jTEEgvJDfcb_O5Q/images/embed-widget-de.png?fit=max&auto=format&n=1jTEEgvJDfcb_O5Q&q=85&s=237e8ff70edf56002f0e538630765e4f" alt="Widget Einbetten" width="3024" height="1492" data-path="images/embed-widget-de.png" />
</Frame>

***

## Widget einbetten

Füge das Script-Tag in den HTML-Code deiner Seite ein, direkt vor dem schliessenden `</body>`-Tag. Ein minimales Embed sieht so aus:

```html theme={null}
<script 
  src="https://www.klaroai.ch/widget.min.js" 
  data-agent-id="[agent-id]"
></script>
```

`data-agent-id` ist das einzige Pflichtattribut. Deine Agent-ID ist die UUID, die im Share-Dialog angezeigt wird (und in der URL sichtbar ist, wenn du dich in deinem Agent in der App befindest).

Das Script lädt asynchron und injiziert einen schwebenden Chat-Button auf deiner Seite. Es blockiert das Seiten-Rendering nicht.

### Optionale Attribute

| Attribut        | Werte                                                  | Standard       | Was es tut                                                                                                               |
| --------------- | ------------------------------------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `data-position` | `bottom-right`, `bottom-left`, `top-right`, `top-left` | `bottom-right` | Bestimmt, wo der Toggle-Button auf dem Bildschirm erscheint                                                              |
| `data-lang`     | `en`, `de`                                             | Auto-Erkennung | Fixiert die Widget-Sprache. Wenn weggelassen, nutzt Klaro die Browsersprache des Besuchers und fällt auf Englisch zurück |

Im Share-Dialog kannst du Position und Sprache visuell auswählen, bevor du kopierst - der Snippet aktualisiert sich automatisch.

### JavaScript API

Nach dem Laden stellt das Widget eine kleine API unter `window.KlaroAIWidget` bereit, falls du programmatische Kontrolle brauchst:

```js theme={null}
window.KlaroAIWidget.open()    // Chat öffnen
window.KlaroAIWidget.close()   // Chat schliessen
window.KlaroAIWidget.toggle()  // Öffnen/Schliessen umschalten
window.KlaroAIWidget.destroy() // Widget von der Seite entfernen
```

***

## CSP (Content Security Policy)

Wenn deine Seite eine Content Security Policy verwendet, musst du Klaros Domain in zwei Direktiven aufnehmen, damit das Script laden und der Chat-Iframe rendern kann:

```text theme={null}
script-src  https://www.klaroai.ch;
frame-src  https://www.klaroai.ch;
```

Füge diese zu deiner bestehenden CSP hinzu - ersetze nicht, was bereits dort steht. Der Share-Dialog zeigt die exakten Werte zum Kopieren an.

***

## Der Playground

Der **Playground** ist eine integrierte Testumgebung innerhalb der App. Du findest ihn in der Sidebar unter **Playground**.

Er zeigt dasselbe Chat-Interface, das deine Besucher sehen — aber innerhalb deines Klaro-Dashboards, ohne Embed. Nutze ihn, um:

* Die Antworten deines Agents nach dem Hinzufügen neuer Knowledge Sources zu testen
* Zu prüfen, wie der System Prompt das Verhalten beeinflusst
* Tool-Verhalten (Eskalation, Lead Capture) zu verifizieren, bevor du sie auf deiner Live-Seite aktivierst

<Frame>
  <img src="https://mintcdn.com/tstgdev/1jTEEgvJDfcb_O5Q/images/playground-de.png?fit=max&auto=format&n=1jTEEgvJDfcb_O5Q&q=85&s=719aa574744b58b5feeab12897fcc059" alt="Playground" width="3024" height="1492" data-path="images/playground-de.png" />
</Frame>

### Playground-Konversationen in der Inbox

Jede Konversation aus dem Playground erscheint in deiner Inbox - genau wie echte Besucher-Konversationen. Sie sind mit einem kleinen Kolben-Icon (🧪) in der Konversationsliste markiert, damit du deine eigenen Tests von echtem Traffic unterscheiden kannst.

Du kannst Playground-Konversationen in der Inbox genauso schliessen oder löschen wie jede andere Konversation.

***

## Öffentlicher Chat-Link

Der **Public Link**-Tab im Share-Dialog gibt dir eine eigenständige URL, die deinen Agent in einem Vollbild-Chat öffnet - kein Embed nötig. Sie sieht so aus:

```text theme={null}
https://www.klaroai.ch/public/[agent-id]
```

Jeder mit diesem Link kann mit deinem Agent chatten. Praktisch für:

* Den Agent per E-Mail oder Support-Ticket teilen
* Internes Testen, ohne auf einer Seite einzubetten
* Eine schnelle Demo mit einem Interessenten

Die öffentliche Seite nutzt dieselbe Sprach-Fallback-Logik wie das Widget - Browsersprache des Besuchers, mit Englisch als Standard, wenn die Sprache nicht unterstützt wird.

<Frame>
  <img src="https://mintcdn.com/tstgdev/1jTEEgvJDfcb_O5Q/images/share-agent-de.png?fit=max&auto=format&n=1jTEEgvJDfcb_O5Q&q=85&s=7fd1d07bdcac9314fa63b9dc1e0a6c67" alt="Agent Teilen" width="3024" height="1492" data-path="images/share-agent-de.png" />
</Frame>

> Die öffentliche Chat-Seite und das eingebettete Widget sind separate Oberflächen, betreiben aber denselben Agent. Konversationen von beiden erscheinen in deiner Inbox - Public-Link-Konversationen werden wie reguläre Widget-Konversationen angezeigt (kein spezielles Badge).

***

**Geschafft.** Damit hast du alles in diesem Guide abgedeckt — vom Einrichten deines Agents über das Einbetten bis hin zum Verwalten von Konversationen. Falls etwas nicht abgedeckt ist, [melde dich bei unserem Team](mailto:titian@klaroai.ch).