Chat-Widget einbetten (Entwicklerhandbuch)

Widget Embed Guide

Das Widget ist eine Web Component (<web-chat-agent>), die asynchron lädt und auf jeder Website läuft, ganz ohne Framework oder Build-Schritt. Das Skript rendert einen schwebenden Chat-Button; Besucher klicken darauf, um das Chat-Fenster zu öffnen.

Embed Code

Fügen Sie dies direkt vor dem schließenden </body>-Tag ein:

<script src="https://webchatagent.com/widget/web-chat-agent.js" async></script>
<web-chat-agent
  chatbot-id="YOUR_CHATBOT_ID"
></web-chat-agent>

Ersetzen Sie YOUR_CHATBOT_ID durch Ihre Chatbot-ID. Sie finden den vorausgefüllten Embed Code unter Dashboard → Ihr Assistent → Kanäle → Chat-Widget → Installationsdetails anzeigen und können ihn dort kopieren, um Tippfehler zu vermeiden.

Das Widget ruft die API über dieselbe Origin auf, von der es geladen wurde. Wenn Sie das Skript von webchatagent.com laden, gehen die Chat-Anfragen automatisch an webchatagent.com/api/..., Sie müssen keine API-URL manuell konfigurieren.

So funktioniert's

1. Das async-Skript lädt im Hintergrund und blockiert das Rendern der Seite nicht.
2. Das <web-chat-agent>-Element rendert einen schwebenden Chat-Button.
3. Das Widget ruft Ihre Dashboard-Einstellungen ab (Farben, Texte, Tools, Begrüßungsnachricht) und wendet sie an. Keine zusätzlichen Attribute erforderlich.
4. Ein Besucher klickt auf den Button, das Chat-Fenster öffnet sich und die Nachrichten werden an Ihren KI-Chatbot gesendet.

HTML Attributes

Jede visuelle Einstellung aus Kanäle → Chat-Widget wird automatisch angewendet. HTML-Attribute auf dem Element sind optionale Überschreibungen, nutzen Sie diese nur für Anpassungen pro Seite (z. B. eine andere Position auf einer bestimmten Landingpage). Attributnamen sind in Kebab-Case gehalten (das Widget mappt theme-color intern auf den themeColor-Prop).

Die folgenden Standardwerte sind die integrierten Fallbacks des Widgets. In der Praxis bleiben die meisten Attribute ungesetzt und übernehmen den Wert, den Sie im Dashboard konfiguriert haben.

Grundeinstellungen

Farben

Alle Farbattribute akzeptieren jede gültige CSS-Farbe (Hex wie #2563eb, rgb(), hsl()). Wenn nicht gesetzt, verwendet das Widget Ihren Dashboard-Wert oder seinen integrierten Fallback (der Standardwert der Marke ist Blau, #2563eb).

Bilder

Positionierung

Inhalt & Verhalten

Einwilligung zur Laufzeit aktualisieren

window.dispatchEvent(
  new CustomEvent('webchatagent:consent', {
    detail: { tracking: 'granted' }
  })
)

Senden Sie denied, wenn die Einwilligung abgelehnt oder widerrufen wird. Anonyme lokale Trigger bleiben verfügbar. Die Trigger-Matrix und CMP-Adapter finden Sie im Cookie Consent guide.

Prompt-Buttons

Schnellaktionen, die unter der Nachrichtenliste gerendert werden. Jeder Button hat einen sichtbaren title und eine action (der Text, der beim Klicken als Nachricht des Nutzers gesendet wird). Übergeben Sie ein JSON-Array als Attributwert:

<web-chat-agent
  chatbot-id="YOUR_CHATBOT_ID"
  prompt-buttons='[{"title":"Talk to support","action":"I need help with my order"},{"title":"Pricing","action":"What does it cost?"}]'
></web-chat-agent>

Session Context Data

Wenn das Widget innerhalb eines Systems läuft, das den Besucher bereits kennt, etwa in einem CRM, einem Kundenportal oder einem eingeloggten Bereich, kann die einbettende Seite dieses Wissen an den Chatbot übergeben. Die KI sieht die Werte, bezieht sich in ihren Antworten darauf und nutzt sie, um passende Argumente von API Connector- und MCP Tool-Aufrufen auszufüllen. Ein Besucher, dessen Vorgangsnummer bereits auf dem Bildschirm zu sehen ist, muss diese kein zweites Mal eingeben.

Kontextdaten werden mit jedem Chat-Request der Sitzung gesendet, werden ausschließlich für diesen Request in den KI-Prompt eingefügt und werden nicht als eigener Datensatz gespeichert.

Kontext über das HTML-Attribut übergeben

Es werden zwei Formate unterstützt. Das einfache Format erfordert keine JSON-Kenntnisse, sondern durch Semikolon getrennte Key=Value-Paare:

<web-chat-agent
  chatbot-id="YOUR_CHATBOT_ID"
  context-data="Customer=Jane Doe;Company=Acme GmbH;OrderID=A-1023"
></web-chat-agent>

Nur das erste = in jedem Paar trennt Schlüssel und Wert, sodass Werte mit einem = (z. B. Base64-Tokens) intakt bleiben. Ein Wert darf in diesem Format kein Semikolon enthalten, verwenden Sie dafür JSON:

<web-chat-agent
  chatbot-id="YOUR_CHATBOT_ID"
  context-data='{"Customer":"Jane Doe","Note":"VIP; priority support","OrderID":"A-1023"}'
></web-chat-agent>

Umschließen Sie bei JSON den Attributwert mit einfachen Anführungszeichen, damit die doppelten Anführungszeichen darin erhalten bleiben.

Kontext über JavaScript übergeben

Wenn Sie JavaScript gegenüber dem Attribut bevorzugen (oder es benötigen, z. B. bei WordPress), setzen Sie die globale Variable window.webchatagentContext. Sie kann problemlos gesetzt werden, bevor das Widget-Skript geladen wurde. Das Widget liest sie bei der Initialisierung aus, die Ladereihenfolge der Skripte spielt daher keine Rolle:

<script>
  window.webchatagentContext = {
    Customer: 'Jane Doe',
    OrderID: 'A-1023',
    userToken: 'opaque-token-validated-by-your-backend'
  }
</script>
<script src="https://webchatagent.com/widget/web-chat-agent.js" async></script>

Kontext zur Laufzeit aktualisieren

Wenn sich die Daten ändern, während das Widget bereits läuft (Login, Wechsel zu einem anderen Vorgang), lösen Sie das Event webchatagent:context mit einem einfachen Objekt aus:

window.dispatchEvent(
  new CustomEvent('webchatagent:context', {
    detail: {
      Topic: 'billing',
      OrderID: 'A-1023'
    }
  })
)

Jedes Event ersetzt den gesamten Kontext; detail: null oder {} leert ihn. Priorität beim Laden: Zuerst wird das Attribut context-data angewendet, dann window.webchatagentContext (falls gesetzt), danach eventuelle Events. Der Kontext existiert innerhalb der Seite, setzen Sie ihn nach einem Neuladen erneut.

White-Label-Deployments: Die markenneutralen Aliase window.chatWidgetContext (global) und chat-widget:context (Event) funktionieren identisch, sodass einbettende Seiten den Plattform-Namen nicht referenzieren müssen.

Limits

Maximal 20 Schlüssel, Schlüsselnamen bis zu 64 Zeichen, Werte bis zu 500 Zeichen (Zahlen und boolesche Werte werden in Zeichenketten umgewandelt), 4.000 Zeichen gesamt. Zeilenumbrüche sowie die Zeichen < und > werden aus Schlüsseln und Werten entfernt. Antworten auf Requests mit Kontextdaten werden niemals aus dem Antwort-Cache bereitgestellt.

Sicherheit: Kontextdaten sind keine Authentifizierung

Die Werte stammen aus dem Browser des Besuchers. Jeder kann die DevTools öffnen und beliebigen Kontext senden. Die KI ist daher angewiesen, diese Daten als unbestätigte Hintergrundinformationen zu behandeln, bauen Sie darauf niemals Autorisierungen auf.

Zwei Regeln für den Produktivbetrieb:

1. allowedDomains einschränken: Konfigurieren Sie dies für Ihren Chatbot im Dashboard. Andernfalls kann jede beliebige Seite Ihren Bot einbetten und mit Kontext füttern.
2. Für Abfragen personenbezogener Daten opake Tokens statt Klartext-Identitäten übergeben: Generieren Sie serverseitig ein kurzlebiges Token für den angemeldeten Benutzer, übergeben Sie es als Kontextwert (z. B. userToken=...) und lassen Sie Ihren API Connector-Endpunkt das Token validieren, bevor Benutzerdaten zurückgegeben werden. Die KI leitet das Token im API-Aufruf weiter; Ihr Backend entscheidet, was damit freigegeben wird. Ein manipuliertes Token liefert dann keine Daten zurück.

WordPress

Das WordPress-Plugin unterstützt (ab dem nächsten Release) Kontextdaten serverseitig: Der Filter webchatagent_context_data liefert sie für das Floating-Widget (und als Standard für Inline-Einbettungen), und der Inline-Shortcode akzeptiert ein context-data-Attribut:

add_filter('webchatagent_context_data', function () {
    $user = wp_get_current_user();
    return $user->exists() ? 'Customer=' . $user->display_name : '';
});

[webchatagent_inline context-data="Topic=Support;OrderID=A-1023"]

Setzen Sie bei älteren Plugin-Versionen stattdessen window.webchatagentContext oder lösen Sie das Event webchatagent:context aus, beides funktioniert auf jeder Plattform.

Beispiel: Vollständige Anpassung

<script src="https://webchatagent.com/widget/web-chat-agent.js" async></script>
<web-chat-agent
  chatbot-id="abc-123-def"
  theme="modern"
  title="Support Chat"
  theme-color="#4f46e5"
  theme-text-color="#ffffff"
  user-message-color="#4f46e5"
  bubble-color="#4f46e5"
  font-family="Inter"
  initially-open="false"
  offset-x="30"
  offset-y="30"
></web-chat-agent>

Dashboard vs. HTML-Attribute

Dashboard-Einstellungen werden serverseitig gespeichert und beim Initialisieren des Widgets geladen. HTML-Attribute überschreiben diese Einstellungen ausschließlich für die jeweilige Seite.

Empfehlung: Nehmen Sie alle visuellen Anpassungen im Dashboard vor. Nutzen Sie HTML-Attribute nur dann, wenn eine einzelne Seite abweichen soll, etwa durch eine andere Positionierung, ein fest vorgegebenes Theme oder seitenspezifische Prompt-Buttons.

Eigenes CSS

Für Änderungen, die über die oben genannten Attribute hinausgehen, können Sie die internen Elemente des Widgets mit eigenem CSS ansprechen. Jedes anpassbare Element besitzt eine feste .wca-*-Klasse (zum Beispiel .wca-header, .wca-message, .wca-bubble), sodass Ihre Selektoren auch nach Widget-Updates funktionieren und kein !important benötigen. Sie hinterlegen das CSS im Dashboard, und es wird in das Shadow DOM des Widgets eingefügt. Siehe Eigenes CSS.

Inline-Chat

Um den Chat direkt in Ihr Seitenlayout statt als schwebenden Button einzubinden, verwenden Sie die Inline-Variante. Sie lädt ein anderes Skript und ein anderes Element (<web-chat-agent-inline>):

<script src="https://webchatagent.com/widget/chat-widget-inline.js" async></script>
<web-chat-agent-inline chatbot-id="YOUR_CHATBOT_ID"></web-chat-agent-inline>

Das Inline-Element akzeptiert chatbot-id, optional container-height sowie tracking-consent und context-data (siehe Session Context Data, Attribut und Laufzeit-Event funktionieren hier identisch); alle weiteren Einstellungen stammen aus Kanäle → Inline-Chat. Platzieren Sie das Element an der Stelle, an der der Chat erscheinen soll, und steuern Sie die Größe über den umschließenden Container. Details finden Sie unter Inline-Chat.

WordPress

Verwenden Sie unter WordPress das offizielle WebChatAgent WordPress Plugin, anstatt das Skript manuell einzufügen. Es übernimmt die Einbettung und Aktualisierungen für Sie. Siehe WordPress Plugin.

Single Page Applications (SPA)

Das Widget funktioniert direkt mit React, Vue, Angular und anderen SPAs. Fügen Sie das Script-Tag in die index.html ein und platzieren Sie das <web-chat-agent>-Element in Ihrer App-Shell (z. B. im Root-Layout). Das Widget bleibt über clientseitige Routenwechsel hinweg bestehen, ein erneutes Mounten bei der Navigation ist nicht erforderlich.