Widget-Einbettung

Binden Sie das HelpStack-Web-Chat-Widget mit einem einzigen Script-Tag auf jeder beliebigen Website ein.

Kurzüberblick#

Der Loader leitet seine baseUrl vom Ursprung seines eigenen <script src> ab, sodass das von helpstack.eu ausgelieferte widget.js automatisch mit HelpStack kommuniziert — es ist keine weitere Konfiguration erforderlich.

Einbettungs-Snippet#

<script src="https://helpstack.eu/widget.js?id=CHANNEL_ID" async></script>

CHANNEL_ID ist die ID Ihres WEBSITE_CHAT-Kanals. Der Loader wird automatisch über den ?id=-Query-Parameter initialisiert — es ist kein zusätzliches JavaScript erforderlich.

Wo Sie die CHANNEL_ID finden#

Gehen Sie im Dashboard zu Einstellungen → Kanäle, öffnen (oder erstellen) Sie einen Website-Chat-Kanal und kopieren Sie dessen ID über die Schaltfläche zum Kopieren neben dem Kanal. Diese ID übergeben Sie als ?id=CHANNEL_ID.

Wie der Loader funktioniert#

1. Das Script liest seinen eigenen <script src>, um Folgendes zu ermitteln:
   • baseUrl — den Ursprung des Scripts (z. B. https://helpstack.eu)
   • channelId — den ?id=-Query-Parameter
2. Es fügt eine schwebende Chat-Blase und ein <iframe> ein, das auf Folgendes verweist:

   {baseUrl}/widget/{channelId}?visitorId={visitorId}
   

3. Das iframe öffnet eine Socket.IO-Verbindung für Echtzeit-Messaging, mit einem HTTP-Fallback, wenn WebSocket nicht verfügbar ist.

Besucheridentität#

Der Loader generiert eine persistente Besucher-ID, die in localStorage gespeichert wird:

Dieselbe visitorId wird über Seitenladevorgänge und Sitzungen in diesem Browser hinweg wiederverwendet, sodass ein wiederkehrender Besucher wieder mit seinem bestehenden Gespräch verbunden wird. Das Leeren von localStorage (oder ein anderer Browser/ein anderes Gerät) erzeugt einen neuen Besucher und einen neuen Gesprächs-Thread.

Programmatische API#

Der Loader stellt ein globales window.ChatWidget-Objekt bereit:

window.ChatWidget.init('CHANNEL_ID'); // manuell initialisieren (wenn nicht ?id= verwendet wird)
window.ChatWidget.open();             // Chat-Panel öffnen
window.ChatWidget.close();            // Chat-Panel schließen
window.ChatWidget.toggle();           // zwischen geöffnet/geschlossen umschalten

Für die verzögerte Form im Snippet-Kommentar steht auch ein Befehls-Queue-Helfer zur Verfügung:

window.chat('init', 'CHANNEL_ID');

Es gibt keine clientseitige Tool-Registrierungs-API. Der Loader stellt keine registerTool()- oder clientseitige Tool-Handler-Funktion bereit. Clientseitige Agent-Tools werden durch den Server über den iframe-Socket vermittelt (siehe Benutzerdefinierte Agent-Tools) und nicht über das JavaScript Ihrer Seite registriert.

Erscheinungsbild-Konfiguration#

Das Erscheinungsbild wird im Dashboard konfiguriert, nicht über den Einbettungs-Snippet. Das Widget ruft die Konfiguration vom Server ab (GET /api/widget/[channelId]/config) und wendet sie über CSS-Variablen an. Verifizierte konfigurierbare Felder:

Öffentliche Widget-Endpunkte#

Alle Endpunkte sind öffentlich (keine Authentifizierung) und per IP/Besucher rate-limitiert.

Upload-Antwort (POST /api/widget/[channelId]/upload):

{
  "storagePath": "...",
  "publicUrl": "...",
  "fileName": "...",
  "fileSize": 12345,
  "contentType": "image/png",
  "width": 800,
  "height": 600
}

width und height sind nur bei Bildern vorhanden.

Nachrichten-Fallback (POST /api/widget/message) — Anfrage-Body:

{
  "channelId": "CHANNEL_ID",
  "visitorId": "visitor_<uuid>",
  "content": "Hello, I need help",
  "visitorInfo": {
    "userAgent": "...",
    "currentUrl": "https://example.com/pricing",
    "referrer": "https://google.com"
  }
}

visitorInfo ist optional. Der Kanal muss vom Typ WEBSITE_CHAT sein, sonst wird die Anfrage abgelehnt. Bei Erfolg enthält das data-Feld des Antwort-Envelopes { messageId, conversationId, createdAt }.

Echtzeit-Ereignisse (Socket.IO)#

Das iframe kommuniziert mit dem Server über Socket.IO.

Widget → Server

Server → Widget

Domain-Allowlist#

Ein Kanal kann einschränken, welche Ursprünge das Widget laden dürfen. Wenn eine Allowlist konfiguriert ist und der anfragende Ursprung nicht darauf steht, antwortet der Server mit 403. Konfigurieren Sie die Allowlist in den Kanaleinstellungen im Dashboard. Lassen Sie sie leer, um jeden Ursprung zuzulassen.

Minimale Beispielseite#

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>HelpStack Widget Demo</title>
  </head>
  <body>
    <h1>My website</h1>
    <button onclick="window.ChatWidget.open()">Need help?</button>

    <!-- HelpStack widget -->
    <script
      src="https://helpstack.eu/widget.js?id=CHANNEL_ID"
      async
    ></script>
  </body>
</html>

Verwandte Themen#

• API-Referenz
• Benutzerdefinierte Agent-Tools
• Kanäle-Leitfaden
• Glossar