Troubleshooting
Der Assistant lädt auf jeder Plattform nach demselben Prinzip. Deshalb lassen sich fast alle Installationsprobleme auf wenige Ursachen zurückführen. Arbeiten Sie diese Liste der Reihe nach ab. Die Punkte 1 und 3 decken den Großteil aller Fälle ab.
Testen Sie zuerst auf einer Preview-Seite
Der schnellste Weg, fast alle Probleme unten zu vermeiden, ist ein Test vor dem Go-live auf einer Staging- oder Plattform-Preview-Seite, die Sie kontrollieren:
- Tragen Sie in den Einstellungen Ihres Assistants die Build-/Preview-Domain Ihrer Plattform ein (
*.webflow.io,*.myshopify.comusw. siehe Tabelle unten), zusätzlich Ihre eigene Staging-Domain oderlocalhost. - Fügen Sie dort das Snippet ein und öffnen Sie die Seite. Stellen Sie einige Fragen, prüfen Sie, ob die Antworten auf Ihren Inhalten basieren, und kontrollieren Sie, ob der Launcher angezeigt wird.
- Wenn alles passt, fügen Sie das Snippet auch auf Ihrer Produktions-Domain ein und erlauben Sie diese ebenfalls.
Unterhaltungen auf einer Preview-Seite zählen genau wie anderer Traffic zu Ihrem Plan. Eine nicht abgerechnete Developer Sandbox, testen Sie mit einem Preview-Token sogar einen noch nicht live geschalteten Assistant kostenlos, ist ein Preview-Feature: Zeigt Ihr Schritt Installation eine Karte Testen Sie Ihren Assistant, ist sie für Ihren Arbeitsbereich aktiviert. Siehe Im Sandbox-Modus testen.
Der Launcher erscheint nicht
1. Ihre Domain ist nicht auf der Allowlist
Der Loader ruft die Config Ihres Assistants ab, bevor er irgendetwas rendert. Wenn der Hostname der Seite nicht in Ihrer Liste Installationsdomains steht, wird die Request mit 403 abgelehnt und kein Launcher erscheint.
Prüfen Sie zuerst das Dashboard, ganz ohne Konsole. Der Schritt Installation Ihres Assistants zeigt eine Karte Installationsstatus, die jeden Hostnamen auflistet, auf dem das Snippet geladen wurde, plattformunabhängig. Ein blockierter Hostname erscheint dort mit einem Erlauben-Button; der Klick fügt genau den angezeigten Host hinzu (Wildcards wie *.myshopify.com aus der Tabelle unten bleiben ein manueller Eintrag unter Installationsdomains).
Der Loader schreibt außerdem eine konkrete Fehlermeldung in die Browser-Konsole, inklusive des exakten abgelehnten Hostnamens.
Lösung: Öffnen Sie im Dashboard Ihren Assistant und fügen Sie unter Installationsdomains genau den Hostnamen hinzu, auf dem das Snippet läuft. Wenn Sie www. nutzen, tragen Sie ihn ebenfalls ein. Wildcards wie *.example.com werden unterstützt.
Vergessen Sie außerdem nicht die Preview-Domain Ihrer Plattform. Das ist der häufigste übersehene Schritt:
| Plattform | Ebenfalls erlauben |
|---|---|
| Shopify | *.myshopify.com |
| BigCommerce | *.mybigcommerce.com |
| Squarespace | *.squarespace.com |
| Webflow | *.webflow.io |
| Framer | *.framer.app |
| Carrd | *.carrd.co |
| Bubble | *.bubbleapps.io |
| Ghost | *.ghost.io |
| HubSpot | *.hs-sites.com |
| WordPress.com | *.wordpress.com, *.wpcomstaging.com |
| Wix | Ihre verbundene Custom Domain (Custom Code läuft nicht auf *.wixsite.com) |
| Drupal / Joomla | Ihre Produktions- und Staging-Hostnamen |
2. Die Plattform hat die Script-Attribute entfernt
Einige CMS oder Editoren sanitizen Markup und entfernen unbekannte Attribute. Schauen Sie in den Seitenquelltext: Wenn das <script> vorhanden ist, aber data-olotalk-assistant-id fehlt, ist das das Problem.
Lösung: Nutzen Sie die attributfreie Variante. Setzen Sie zuerst window.OlotalkConfig und laden Sie dann den nackten Loader:
<script>
window.OlotalkConfig = { assistantId: 'YOUR_ASSISTANT_ID' };
</script>
<script
src="https://cdn.jsdelivr.net/npm/@olotalk/assistant-loader@0/dist/loader.iife.js"
async
></script>
Oder injizieren Sie das Snippet über einen Weg, der rohes HTML unverändert erhält, etwa ein Header/Footer-Plugin, Drupals Full HTML oder eine Editor-Codeansicht.
3. Ihr Snippet steckt in einem Iframe fest
Wenn Sie nur eine kleine leere Box im Seiteninhalt sehen oder der Chat nur in einem einzelnen Abschnitt auftaucht, wurde das Snippet in ein Embed HTML-Element pro Abschnitt eingefügt. Diese Elemente rendern in einem Iframe, und ein schwebender Launcher kann daraus nicht ausbrechen.
Lösung: Verschieben Sie das Snippet in die site-weite Custom-Code-/Footer-Integration der Plattform. Das betrifft typischerweise Wix (Custom Code statt Embed-Element), Squarespace (Code Injection statt Code Block) und Carrd (Embed Type: Code, nicht IFRAME).
4. Sie schauen auf den Editor statt auf die veröffentlichte Site
Webflow, Framer, Wix, Squarespace, Carrd und BigCommerce führen Custom Code nur auf der veröffentlichten Site aus, nicht im Editor oder in der Preview. Veröffentlichen Sie also zuerst und öffnen Sie dann die Live-URL.
Der Launcher erscheint, antwortet aber nicht
- Sie sehen eine Fallback-Nachricht wie „Ich habe dazu noch keine Informationen.“ Dann wurden Ihre Inhalte noch nicht ingestiert. Fügen Sie im Schritt Source Ihres Assistants eine URL hinzu und starten Sie die Ingestion. Siehe Schnellstart.
- Beim Senden einer Nachricht passiert nichts oder Sie sehen Fehler in der Konsole. Prüfen Sie Ihre Content Security Policy und die Config-Request mit den Debug-Schritten unten.
- Er antwortet in der falschen Sprache. Die Sprache wird pro Besucher gewählt und ist durch das unterstützte Sprachset Ihres Assistants begrenzt, die genaue Prioritätskette und das Festpinnen einer Locale stehen unter Mehrsprachig.
- Das Eingabefeld ist ausgegraut und es wird nichts gesendet. Auf der Policy-Seite Ihres Assistants ist ein Einwilligungsbanner aktiviert. Dieses Banner ist eine Sperre, kein bloßer Hinweis: Solange der Besucher es nicht bestätigt, wird keine Sitzung angelegt und keine Nachricht gesendet. Das ist Absicht, ein Einwilligungshinweis, der das Gespräch trotzdem zulässt, würde eine Einwilligung behaupten, die er nie eingeholt hat. Deaktivieren Sie es unter Policy → Einwilligungs-Tracking, oder rechnen Sie damit, dass der erste Klick die Bestätigung ist.
Content Security Policy (CSP)
Wenn Ihre Site eine strenge CSP setzt, blockiert der Browser eventuell den Loader oder dessen API-Requests. Erlauben Sie die Hosts von Olotalk:
script-src 'self' https://cdn.jsdelivr.net;
style-src 'self' https://cdn.jsdelivr.net;
connect-src 'self' https://api.olotalk.com https://cdn.jsdelivr.net;
Passen Sie die Hosts an, wenn Sie das Assistant-Bundle selbst hosten. Die vollständige Policy finden Sie unter Embed-Referenz → Sicherheit.
Wenn Sie die attributfreie Fallback-Variante oben nutzen, also ein Inline-<script> mit window.OlotalkConfig, blockiert eine strenge script-src ohne 'unsafe-inline' auch dieses Inline-Script. Verwenden Sie dann einen CSP-Nonce oder Hash oder bevorzugen Sie das attributbasierte Snippet.
In unter einer Minute debuggen
- Öffnen Sie DevTools → Network und laden Sie die Seite neu.
- Suchen Sie die Request auf
…/public/v1/assistants/<your-assistant-id>/config:- 403 → Ihre Domain ist nicht erlaubt (Punkt 1). Im Sandbox-Test kann das auch ein fehlender oder abgelaufener Preview-Token sein.
- 429 → Sie werden rate-limited. Warten Sie eine Minute und versuchen Sie es erneut.
- 404 auf
loader.iife.js→ Diesrc-URL des Snippets ist falsch. - gar keine Request → Das Script wurde nie ausgeführt. Es wurde entfernt, durch CSP blockiert oder die Site ist nicht veröffentlicht (Punkte 2–4).
- Prüfen Sie die Console auf
Olotalk-Warnungen. - Notieren Sie den Response-Header
x-request-id. Wenn Sie Support kontaktieren, hilft dieser Header bei der Zuordnung in den Server-Logs.
Datenschutz: was das Embed speichert und sendet
Das vollständige Inventar, für die Person, die Ihre Datenschutzerklärung und Ihren Consent-Banner pflegt:
- Im Browser des Besuchers: zwei
localStorage-Schlüssel,olotalk_visitor_id(eine anonyme Besucherkennung) undolotalk:lang:<assistantId>(eine vom Besucher akzeptierte Sprachwahl). Keine Werbe-Cookies, keine Dritt-Pixel. - Über das Netzwerk: Der Loader sendet beim Laden einen Seitenaufruf-Beacon (Seiten-URL, Referrer, UTM-Tags), und Konversationen gehen zur Beantwortung an die Olotalk-API. In die Datenbank Ihrer eigenen Website wird nichts geschrieben.
Ob davon etwas in Ihren Cookie-Banner gehört, ist eine Rechtsfrage Ihrer Jurisdiktion, diese Docs können Ihnen das Inventar geben, nicht die Antwort. Siehe Olotalks Datenschutzerklärung; und wenn Sie das Snippet über einen Tag-Manager laden, zeigt der Google-Tag-Manager-Guide, wie es hinter dem Consent feuert.
Entfernen, pausieren oder umziehen
- Entfernen: Löschen Sie das Snippet (oder deaktivieren Sie das Plugin). Sonst lebt nichts auf Ihrer Website; die beiden
localStorage-Schlüssel oben sind ohne das Script wirkungslose Überbleibsel. - Pausieren: Nehmen Sie den Assistant im Dashboard offline, das Snippet kann bleiben, der Assistant rendert einfach nicht mehr (der Loader erklärt in der Browser-Konsole, warum).
- Auf eine neue Domain umziehen: Neue Domain unter Installationsdomains eintragen, Snippet dort einfügen, die alte bei Gelegenheit entfernen. Assistant, Inhalte und Konversationshistorie bleiben unberührt, die Karte Installationsstatus zeigt die neue Domain beim ersten Laden.
- Archivierter oder gelöschter Assistant: Ein zurückgelassenes Embed rendert nichts und loggt „no longer available, remove this embed snippet“.
Immer noch fest?
Kontaktieren Sie den Support mit Ihrer Assistant-ID, der Plattform, auf der Sie installieren, und der x-request-id der fehlgeschlagenen Request. Prüfen Sie vorher noch einmal besonders Punkt 1 (Domain-Allowlist) und Punkt 3 (Iframe). Dort liegt das Problem am häufigsten.