Das Chat-Widget installieren

Bevor du beginnst

Du brauchst ein Konto, ein Organisationswidget in SupportWhale und Zugriff auf den Code deiner Website. Eigentümer und Admins können Widget-Einstellungen ändern. Der Website-Schlüssel im Skript ist öffentlich; der Signierschlüssel für verifizierte Kundenidentitäten bleibt geheim und gehört niemals in Browsercode.

Widget einbinden

1. Melde dich an und wähle in der Seitenleiste die richtige Organisation.
2. Öffne Widget → Installation und kopiere das erzeugte Skript. Verwende Loader-URL, Website-Schlüssel und API-Adresse zusammen.
3. Füge das Skript direkt vor </body> deiner Website ein und veröffentliche die Änderung.
4. Öffne die Website in einem privaten Browserfenster. Sende eine Nachricht, öffne den SupportWhale-Posteingang und antworte. Lade die Kundenseite neu und prüfe, ob der Verlauf erhalten bleibt.

Erlaubte Domains

Öffne Widget → Erlaubte Domains. Standardmäßig wird eine Domainliste verwendet. Trage alle Produktions-, Staging- oder Entwicklungshosts ein, die das Widget benötigen. example.com und www.example.com sind unterschiedliche Einträge. *.example.com erlaubt Subdomains, aber nicht die Hauptdomain example.com. Ein abweichender Port muss exakt passen, etwa localhost:5173. Internationale Domainnamen normalisiert der Server.

Alle Domains erlauben ermöglicht die Einbindung dieses Widgets auf jeder Website. Aktiviere dies nur bewusst. Private Gespräche und Team-Zugangsdaten werden dadurch nicht freigegeben. Domainänderungen gelten auch beim erneuten Verbinden; berücksichtige benötigte Vorschau- und Staging-Hosts.

Sprache des Widgets

Das Widget folgt der Browsersprache des Besuchers (Deutsch, Englisch oder Niederländisch). Mit dem optionalen Attribut data-locale="de" im Installationsskript wählst du eine Sprache ausdrücklich; auch en und nl werden unterstützt. Nach dem Laden ändert window.SupportWhale.setLocale("nl") die Sprache, ohne einen Nachrichtenentwurf oder eine eingegebene E-Mail-Adresse zu löschen.

HTML

Nutze das Skript aus Installation. Dieses Beispiel zeigt den Aufbau; ersetze YOUR_WEBSITE_KEY durch deinen öffentlichen Schlüssel.

<script src="https://cdn.supportwhale.com/loader.js"
  data-website-id="YOUR_WEBSITE_KEY"
  data-api="https://api.supportwhale.com/v1" defer></script>

Nuxt

Füge das Skript einmal in der useHead-Konfiguration deiner App ein, nicht in jeder Seitenkomponente. Verwende die Werte aus deinem erzeugten Skript.

useHead({ script: [{
  src: 'https://cdn.supportwhale.com/loader.js',
  'data-website-id': 'YOUR_WEBSITE_KEY',
  'data-api': 'https://api.supportwhale.com/v1',
  defer: true
}] })

React

Am einfachsten fügst du das erzeugte Skript im HTML-Dokument deiner App vor </body> ein. Falls das nicht möglich ist, lade es einmal in einem Effect der Hauptkomponente. Lass es bei clientseitiger Navigation bestehen; lade nicht für jede Route eine neue Kopie.

useEffect(() => {
  if (document.getElementById('supportwhale-loader')) return;
  const script = document.createElement('script');
  script.id = 'supportwhale-loader';
  script.src = 'https://cdn.supportwhale.com/loader.js';
  script.dataset.websiteId = 'YOUR_WEBSITE_KEY';
  script.dataset.api = 'https://api.supportwhale.com/v1';
  script.defer = true;
  document.head.appendChild(script);
}, []);

Chat über einen eigenen Button öffnen

Füge diesen Button an beliebiger Stelle neben dem installierten Widget-Skript ein:

<button type="button" data-supportwhale-action="open">Support kontaktieren</button>

Mit close schließt du den Chat; toggle wechselt zwischen geöffnet und geschlossen. Bei clientseitiger Navigation neu eingefügte Buttons funktionieren automatisch. Klicks während des Ladens werden gespeichert; die Seite springt nicht und die URL bleibt gleich. Verwende einen Button statt eines leeren href="#"-Links.

In JavaScript stehen nach dem Ausführen des Loaders window.SupportWhale.open(), window.SupportWhale.close() und window.SupportWhale.toggle() bereit. Binde das Skript einmal in deiner App ein. Rufe beim Abmelden oder Kontowechsel window.SupportWhale.reset() auf, bevor du die Identität des nächsten Kunden setzt.

Wenn das Widget nicht erscheint

Prüfe die Erreichbarkeit der Loader-URL, den Website-Schlüssel sowie Hostname und Port in der Domainliste. Eine Content-Security-Policy muss das CDN-Skript und API-/WebSocket-Verbindungen erlauben. Browsererweiterungen können Chatskripte blockieren. Lade das Skript nicht doppelt. Die eingebaute Vorschau prüft die Einstellungen; teste zusätzlich die tatsächliche Kundenseite.

Für angemeldete Kunden erstellt dein eigener Server kurzlebige JWTs. Nutze dafür die Integration für Kundenidentitäten unter Installation. Gib den Signierschlüssel niemals an den Browser weiter. Kontaktiere den Support mit dem betroffenen Host und der sichtbaren Fehlermeldung, ohne Passwörter oder private Tokens mitzuschicken.