Fehlerbehebung

Zuerst auf Fehler lauschen

Bevor Sie spezifische Probleme debuggen, stellen Sie sicher, dass Sie einen error-Listener angehängt haben, damit SDK-Fehler in Ihrer Konsole angezeigt werden:

widget.on("error", (error) => {
  console.error("Widget error:", error.message);
});

Initialisierungsfehler

`WidgetSDK can only be used in a browser environment`

widget.init() wurde außerhalb eines Browser-Kontexts aufgerufen, typischerweise während des serverseitigen Renderings. Der Konstruktor ist SSR-sicher und kann überall aufgerufen werden, aber init() muss im Browser ausgeführt werden. Verschieben Sie widget.init() in einen useEffect-Aufruf oder einen anderen Codepfad, der nur im Browser ausgeführt wird. Siehe den React-Integrationsleitfaden für Muster.

`widgetKey is required`

Die Option widgetKey wurde nicht an den Konstruktor übergeben. Überprüfen Sie, ob Ihre Umgebungsvariable gesetzt ist und dass ihr Wert gelesen wird, bevor WidgetClient erstellt wird.

`Widget already initialized`

widget.init() wurde zweimal auf derselben Instanz aufgerufen. Schützen Sie den Aufruf mit einer Ref oder einem Flag oder erstellen Sie eine neue WidgetClient-Instanz pro Sitzung.

`Widget not initialized. Call init() first.`

Eine Methode wie joinQueue() wurde aufgerufen, bevor widget.init() abgeschlossen wurde. Warten Sie auf das ready-Event oder bis das init()-Promise erfüllt ist, bevor Sie andere Methoden aufrufen:

await widget.init(); // wait for this to resolve
await widget.joinQueue({ terms: true });

HTTP-Fehler

Status	Bedeutung	Behebung
`400`	Fehlerhafte Anfrage – fehlende oder fehlerhafte Parameter	Überprüfen Sie den `widgetKey`-Wert und stellen Sie sicher, dass `page_url` eine gültige URL ist
`403`	Verboten – Ursprung nicht auf Allowlist oder Domain nicht verifiziert	Fügen Sie Ihre Domain unter Einstellungen → Widgets → Domains hinzu und verifizieren Sie sie
`404`	Widget nicht gefunden	Bestätigen Sie, dass der `widgetKey` mit einem vorhandenen, aktiven Widget übereinstimmt
`423`	Widget inaktiv	Reaktivieren Sie das Widget im Dashboard
`429`	Rate-Limit überschritten	Siehe Rate-Limiting unten

`401 Unauthorized` bei init

Ihr Widget-Schlüssel fehlt oder ist falsch. Überprüfen Sie den Wert und stellen Sie sicher, dass die Domain, von der aus Sie aufrufen, unter Einstellungen → Widgets → Domains auf der Allowlist steht.

`403 Forbidden` — Ursprung stimmt nicht überein

Der Anforderungsursprung stimmt mit keiner erlaubten Domain überein. Öffnen Sie Einstellungen → Widgets, wählen Sie Ihr Widget aus und fügen Sie Ihren vollständigen Ursprung einschließlich Protokoll hinzu (z.B. https://example.com). Die Domain-Verifizierung ist erforderlich, bevor der Ursprung akzeptiert wird.

Warteschlangen-Fehler

`Already in queue`

joinQueue() wurde aufgerufen, während der Besucher bereits in der Warteschlange ist. Überprüfen Sie widget.getState(), bevor Sie joinQueue() aufrufen, und rufen Sie es nur im ready-Status auf.

`Cannot join queue while in call or assigned to agent`

Eine Sitzung ist bereits im Gange. Lauschen Sie auf call:ended, bevor Sie dem Besucher erlauben, erneut in eine Warteschlange einzutreten.

Warteschlangenposition aktualisiert sich nicht mehr

Die Echtzeit-Verbindung wurde möglicherweise unterbrochen. Dies ist nicht fatal – das SDK fällt auf Polling zurück. Wenn die Updates vollständig aufhören, rufen Sie widget.destroy() auf und initialisieren Sie neu.

Rate-Limit-Fehler (`429`)

Der öffentliche init-Endpunkt ist auf 10 Anfragen pro Minute pro IP begrenzt. Dies wird fast immer dadurch verursacht, dass widget.init() bei jedem Render aufgerufen wird.

Videoanruf-Fehler

Anruf-UI erscheint nicht nach `call:started`

Das Videokonferenz-Script wurde möglicherweise nicht geladen. Überprüfen Sie den Netzwerk-Tab Ihres Browsers auf blockierte Anfragen. Wenn Sie eine strenge Content Security Policy (CSP) haben, müssen Sie möglicherweise die Domain des Konferenzanbieters auf die Allowlist setzen.

`Failed to load video call API`

Ein Netzwerkfehler hat verhindert, dass das Konferenz-Script geladen wurde. Überprüfen Sie Ihre Verbindung und alle Firewall- oder Proxy-Regeln, die externe Scripts blockieren könnten.

`Parent node not found for video conference after timeout`

Das DOM-Element, in das die Anruf-UI gemountet werden sollte, wurde innerhalb von 5 Sekunden nicht gefunden. Wenn Sie einen benutzerdefinierten container verwenden, stellen Sie sicher, dass das Element im DOM vorhanden ist, bevor Sie widget.init() aufrufen.

Cobrowsing-Fehler

Agent fordert Cobrowsing an, aber es passiert nichts

Stellen Sie sicher, dass Sie das cobrowse:consent:required-Event behandeln. Ohne Handler wird die Zustimmungsaufforderung niemals angezeigt und Cobrowsing kann nicht starten:

widget.on("cobrowse:consent:required", ({ accept, decline }) => {
  // You must call accept() or decline() — without this, cobrowsing will not start
});

Token-Ablauf

Sitzungs-Tokens laufen nach 30 Minuten ab und Auth-Tokens nach 15 Minuten. Das SDK erneuert Tokens automatisch vor dem Ablauf, sodass dies unter normalen Bedingungen keine Auswirkungen auf Besucher haben sollte.

Wenn die Erneuerung selbst fehlschlägt (z.B. durch Netzwerkausfall), gibt das SDK ein token:expired-Event aus. Rufen Sie in diesem Fall widget.destroy() auf und erstellen Sie eine neue Instanz, um neu zu initialisieren.

Client SDK Übersicht Zurück zur Client SDK Übersicht und Schnellstart.

Fehlerbehebung

Zuerst auf Fehler lauschen

Initialisierungsfehler

WidgetSDK can only be used in a browser environment

widgetKey is required

Widget already initialized

Widget not initialized. Call init() first.