Schnellstart

Widget-Übersicht

Die Widget-App wird unter widget.companin.tech gehostet und bietet eine einfache Möglichkeit, einen KI-Agenten für den Kundensupport in Ihre Website einzubetten. Um loszulegen, müssen Sie einen Agenten und eine OAuth-Anwendung erstellen.

Das Widget ist eine leichte, eigenständige Anwendung, die in einem isolierten Iframe auf Ihrer Website ausgeführt wird. Diese Architektur stellt sicher, dass das Widget nicht mit Ihrem vorhandenen CSS oder JavaScript in Konflikt gerät und gleichzeitig eine hervorragende Leistung und Sicherheit gewährleistet.

1. Einen Agenten erstellen

Zuerst erstellen Sie einen Kundenservice-KI-Agenten in Ihrem Dashboard:

Ihr Agent ist das KI-Gehirn hinter dem Widget. Es verarbeitet Benutzernachrichten, verwaltet den Konversationskontext und generiert intelligente Antworten. Jeder Agent kann mit spezifischen Anweisungen, Persönlichkeitsmerkmalen und Wissensdatenbanken individuell an Ihren Anwendungsfall angepasst werden.

1. Gehe zu deinem Dashboard und navigiere zur Seite "Datenquellen"
2. Klicke auf die Schaltfläche "Hinzufügen" im Abschnitt Agenten
3. Fülle die Agentendetails aus (Name, Beschreibung, Ton usw.)
4. Speichere den Agenten und notiere seine ID

Tipp: Geben Sie Ihrem Agenten klare und spezifische Anweisungen zu seiner Rolle und seinen Einschränkungen. Zum Beispiel: „Sie sind ein hilfreicher Kundendienstagent für ein SaaS-Produkt. Sie können Fragen zu Funktionen, Preisen und Kontoverwaltung beantworten. Bei technischen Problemen weisen Sie Benutzer an, ein Support-Ticket zu erstellen.“

2. Erstellen Sie eine OAuth-Anwendung

Erstellen Sie eine OAuth-Anwendung, um Ihr Widget zu authentifizieren:

1. Gehe zur "OAuth"-Seite in deinem Dashboard
2. Klicke auf "Anwendung erstellen"
3. Fülle den Anwendungsnamen und die Beschreibung aus
4. Kopiere die client_id aus der erstellten Anwendung

3. Betten Sie das Widget über Iframe ein

Der einfachste Weg, das Widget zu integrieren, besteht darin, es direkt mit einem iframe einzubetten. Diese Methode erfordert keine JavaScript-Initialisierung und funktioniert sofort. Bei mehreren iframes auf einer Seite sollte jede Einbettung auf ihren eigenen Container und ihre Parameter beschränkt werden.

<iframe src="https://widget.companin.tech/embed/session?key=YOUR_WIDGET_KEY&locale=en" style="border:none; width:100%; height:600px; border-radius:8px;" title="Customer Support AI Agent Widget"></iframe>

Ersetzen Sie YOUR_WIDGET_KEY durch den Installationsschlüssel Ihres Widgets (den wgt_…-Wert — kopieren Sie ihn von der Widget- oder Installationsseite im Dashboard). Der locale-Parameter kann so eingestellt werden, dass er der Sprache Ihrer Website entspricht.

Erweitert: JavaScript-Initialisierung

Die empfohlene Integrationsmethode ist die Verwendung unseres JavaScript-Widget-Loaders, der automatische Größenanpassung, Konfigurationsverwaltung und Reaktionsverhalten bietet.

Skriptintegration

Fügen Sie Ihrer HTML-Seite das folgende Skript-Tag hinzu:

<script  src="https://widget.companin.tech/widget.js"  data-widget-key="YOUR_WIDGET_KEY"  data-instance-id="support-widget"  data-locale="en"  async></script>

Skriptattribute

Jedes Attribut dient einem bestimmten Zweck bei der Konfiguration Ihres Widgets:

• data-widget-key: Die Widget-ID Ihres Widgets - Der einzelne Wert, den die meisten Installationen benötigen. Er löst Ihren Client, Agenten und Konfigurationsserver auf der Serverseite auf, sodass Sie sie nicht separat einfügen müssen.

Die drei unten stehenden Attribute sind eine fortgeschrittene Alternative zu data-widget-key - verwenden Sie sie für Multi-Instanz-Setups, bei denen Sie explizit einen bestimmten Client, Agenten oder eine Konfiguration anvisieren müssen:

• data-client-id: Ihre OAuth-Client-ID – Dies authentifiziert Ihre Anwendung mit unserer API. Betrachten Sie es als das Passwort Ihrer App.
• data-agent-id: Die UUID Ihres Agenten – Dies gibt an, welcher KI-Agent des Kundensupports die Gespräche abwickelt.
• data-config-id: Die UUID Ihrer Widget-Konfiguration – Dies bestimmt, wie Ihr Widget aussieht und sich verhält (Farben, Größe, Position usw.).
• data-instance-id: Eindeutige Instanz-ID pro Widget – Erforderlich beim Einbetten mehrerer Widgets auf derselben Seite, um Kollisionen zu vermeiden und das API-Targeting pro Instanz zu ermöglichen.
• data-custom-css: Veraltet. Das Festlegen dieses Attributs protokolliert eine Konsolenwarnung und hat keine Auswirkung. Legen Sie stattdessen custom_css für Ihre Widget-Konfiguration im Dashboard fest – es wird aus der Konfiguration geladen und automatisch in den Iframe eingefügt.
• data-locale: Sprachcode (z. B. „en“, „es“, „fr“) – Legt die Anzeigesprache des Widgets fest. Der Agent antwortet weiterhin in jeder Sprache, in der Benutzer schreiben.
• data-dev: Für den Entwicklungsmodus (localhost) auf „true“ setzen – Verwenden Sie dies beim lokalen Testen. Für die Produktion entfernen oder auf „false“ setzen.

Das Widget wird automatisch:

• Rufen Sie die Konfiguration von der Konfigurations-ID ab
• Passt die Größe entsprechend den Widget-Abmessungen in der Konfiguration an
• Positionieren Sie die minimierte Schaltfläche basierend auf den Konfigurationseinstellungen
• Öffnen oder schließen Sie den Start basierend auf der start_open-Einstellung der Konfiguration

Notizen

• Das Widget verwaltet seine eigene Größe automatisch basierend auf Ihren Konfigurationseinstellungen
• Die Position der minimierten Schaltfläche kann über die Widget-Konfiguration angepasst werden
• Das Widget berücksichtigt die Einstellung start_open aus Ihrer Konfiguration
• Der gesamte Stil (Farben, Schriftarten, Abmessungen) wird über die Widget-Konfiguration gesteuert
• Das Widget nutzt die PostMessage-Kommunikation für Reaktionsverhalten
• Der Entwicklungsmodus kann mit data-dev="true" für Localhost-Tests aktiviert werden
• Verwenden Sie für den serverseitigen Token-Austausch /api/v1/auth/widget-token und bewahren Sie das Client-Geheimnis nur auf Ihrem Server auf.
• Stellen Sie sicher, dass Ihr Host-Ursprung (z. B. http://localhost:3000)) in OAuthallowed_origins enthalten ist, wenn Sie das Widget in einen Iframe einbetten.