Referenz der Widget-JavaScript-API

Für: Entwickler·Voraussetzung: Das Widget-Skript auf der Seite·Screenshots zeigen Beispieldaten

Das StrikeUp-Widget-Skript gibt Ihrer Seite zwei Einstiegspunkte: window.initStrikeUpChatWidget(config), das das Widget für eine Person startet, und window.StrikeUpChat, ein kleines Objekt, mit dem Ihr Code den Chat öffnet und schließt, auf seine Bereitschaft wartet, ihn entfernt und dem Assistenten versteckten Seitenkontext übergibt. Alles andere, etwa Farben, Position und URL-Regeln, stammt aus den gespeicherten Einstellungen des Widgets in StrikeUp und ist nicht Teil der API. Diese Seite listet jede Option und jede Methode mit Typ, Standardwert, Rückgabewert und den Konsolenmeldungen, die sie erzeugen kann.

So funktioniert es

Das Skript legt seine Globals an, wenn es läuft. Ihre Seite ruft initStrikeUpChatWidget auf, sobald die Person bekannt ist; das Widget holt mit dem Anwendungs-Token seine gespeicherten Einstellungen, zeichnet sich und lädt den Chat in einem Frame. window.StrikeUpChat spricht dann für Sie mit diesem Chat.

Globals, die das Skript anlegt

Global	Typ	Hinweise
window.initStrikeUpChatWidget(config)	(config: object) => void	Startet das Widget. Liefert nichts (kein Promise). Aufrufe laufen nacheinander; ein Aufruf ohne applicationToken wird ignoriert
window.StrikeUpChat	Objekt	Existiert erst, nachdem das Skript gelaufen ist
window.destroyStrikeUpChatWidget()	() => void	Dasselbe wie StrikeUpChat.destroy()
window._strikeupChatWidgetQueue	Array von Konfigurationen	Aufrufe, die vor dem Laden des Skripts eingereiht wurden; das Skript spielt sie ab
strikeupChatWidgetLoaded	Ereignis auf window	Wird einmal ausgelöst, wenn das Skript fertig gelaufen ist, nicht wenn der Chat bereit ist
window.chatWidgetConfig.loginTicket	Zeichenkette	Der einzige Wert, den das Skript aus diesem Global liest, als Ersatz für loginTicket

Optionen von initStrikeUpChatWidget

Option	Typ	Standard	Wirkung
applicationToken	Zeichenkette, Pflicht	keiner	Erkennt das Widget; seine Einstellungen werden damit geladen
userId	Zeichenkette, höchstens 255 Zeichen	keiner	Die ID des Kunden; Schlüssel für Verlauf, Erinnerungen, Zugangsdaten und Anmeldung. Ein anderer Wert in einem späteren Aufruf startet das Widget neu
userDisplayName	Zeichenkette	keiner	Der Name des Kunden, nur gefüllt, wenn leer
userEmail	Zeichenkette	keiner	Die E-Mail des Kunden, nur gefüllt, wenn leer
userCompanyId	Zeichenkette	keiner	Verbindet den Kunden mit dem Kundenunternehmen mit dieser Unternehmens-ID, wenn er noch keines hat
userCompanyName	Zeichenkette	keiner	Der Name zum Abgleichen oder Anlegen des Unternehmens
handoffUserId	Zeichenkette	userId	Die ID der Person in Ihrem Helpdesk für die Übergabe an Menschen
loginTicket	Zeichenkette	window.chatWidgetConfig.loginTicket, dann ein Parameter loginTicket in der Adresse der Seite	Meldet den Kunden ohne Abfrage an; 60 Sekunden gültig, einmalig. Ein neues Ticket in einem späteren Aufruf startet das Widget neu
serverAuthorizations	Array<{ serverId: string; authData: Record<string, string> }>	keiner	Werden per Nachricht an den Chat-Frame übergeben, nie in seiner Adresse, und beim Verbinden des Chats als Toolkit-Zugangsdaten des Kunden gespeichert
getServerAuthorizations	() => Array<…> | null | Promise<Array<…> | null>	keiner	Liefert frische Zugangsdaten in derselben Form. Das Widget ruft es vor jeder Nachricht und Tool-Freigabe auf und wenn gespeicherte Zugangsdaten abgelehnt werden; es wartet höchstens 5 Sekunden. null behält die aktuellen
openTarget	string	aus strikeup_open in der Adresse der Seite	chat:<id> oder run:<id>; das Widget öffnet diesen Chat oder Lauf, sobald der Kunde angemeldet ist. Wird von Öffnen-Links in Benachrichtigungen automatisch gesetzt
displayType	"popup" | "modal" | "sidebar" | "panel" | "custom-trigger" | "custom-trigger-panel" | "inline"	Die gespeicherte Darstellungsart des Widgets	Überschreibt auf dieser Seite die gespeicherte Darstellungsart
container	CSS-Selektor | HTMLElement	keiner	Pflicht für "inline"; das Element, das der Chat füllt. Wird nirgendwohin gesendet
portalDisplayType	"inline"	keiner	Nur Inline: Das Kundenportal öffnet sich im selben Container
theme	"light" | "dark" | "system"	Die letzte Wahl der Person im Widget, sonst "system"	Der Farbmodus des Chats
showToolArgs	Boolean (nur true zählt)	false	Zeigt die Argumente jedes Tool-Aufrufs in den Fortschrittsschritten, die Besucher sehen

Nicht aufgeführte Optionen werden ignoriert. Auch die alte Option headers wird ignoriert, mit einer Warnung in der Browserkonsole; übergeben Sie Zugangsdaten in serverAuthorizations. Das Aussehen des Widgets stammt aus seinen gespeicherten Einstellungen, nicht aus Optionen: Position, Farben und Größe der Schaltfläche, Breite und Höhe, Display behaviour, Modal-Hintergrund, Symbol der Startschaltfläche und URL-Regeln werden unter Konfigurieren › User Interface eingestellt oder sind fest. Nur displayType lässt sich aus Ihrem Code überschreiben.

initStrikeUpChatWidget erneut aufrufen

Zweiter Aufruf	Ergebnis
Dieselbe userId und kein neues loginTicket	Der offene Chat bleibt unberührt; nur die gespeicherten Einstellungen werden aufgefrischt. Neue serverAuthorizations werden weitergegeben und erneut gespeichert
Andere userId oder ein neues loginTicket	Das Widget wird entfernt und für die neue Identität neu gestartet
Nach StrikeUpChat.destroy()	Ein frisches Widget startet

Methoden von window.StrikeUpChat

Member	Signatur	Liefert	Verhalten
open	open(options?: { message?: string; openContext?: string; autoSend?: boolean | 1 | "1" | "true" })	void	Öffnet den Bereich einer Darstellungsart mit eigenem Auslöser. Tut nichts, bevor das Widget bereit ist. message allein erscheint als Eröffnungszeile des Assistenten; mit autoSend wird es als erste Frage der Person in einem neuen Chat gesendet. openContext ist versteckter Kontext für die erste Antwort (auf 8192 Zeichen gekürzt)
close	close()	void	Klappt einen Bereich mit eigenem Auslöser ein. Keine Wirkung auf das Panel. Bei Popup, Modal und Seitenleiste vermeiden
destroy	destroy()	void	Entfernt Startschaltfläche, Bereich und Chat-Frame, beendet die Live-Verbindung und stellt das Padding Ihrer Seite wieder her. Sicher, auch wenn nichts angezeigt wird. Meldet den Kunden nicht ab
getDisplayType	getDisplayType()	string | null	Die verwendete Darstellungsart; null vor dem Start und nach destroy()
isReady	isReady()	boolean	true, sobald der Chat seine Bereitschaft gemeldet hat, nach einem Ersatz-Timeout von 8 Sekunden oder sofort, wenn nichts gezeichnet wird (durch URL-Regeln ausgeblendet, Start gescheitert, Popup noch nicht geöffnet)
isOpen	isOpen()	boolean	true, solange der Chat sichtbar ist; bei Panel und Inline immer true, solange sie auf der Seite sind; false vor dem Start, nach destroy() und auf ausgeblendeten Pfaden. Kein Änderungsereignis
onReady	onReady(cb: (displayType: string | null) => void)	() => void, zum Abmelden	Ruft cb auf, wenn das Widget bereit ist. null bedeutet: Token falsch oder Einstellungen nicht ladbar. Ist es schon bereit, läuft cb direkt nach der Rückkehr des Aufrufs
context.set	set(value: string | object)	boolean	Ersetzt den bereitgestellten Seitenkontext. Objekte werden zu JSON. false über 8192 Zeichen, und nichts wird bereitgestellt
context.add	add(value: string | object)	boolean	Hängt in einer neuen Zeile an; false, wenn das Ergebnis länger als 8192 Zeichen wäre
context.clear	clear()	void	Leert den bereitgestellten Seitenkontext
context.get	get()	string | null	Der bereitgestellte Wert; null, sobald er mit einer Nachricht gesendet wurde
setServerAuthorizations	setServerAuthorizations(authorizations: Array<{ serverId; authData }>)	boolean	Übergibt dem Chat neue Zugangsdaten, etwa nachdem Ihr Token erneuert wurde. Ersetzt die beim Start übergebenen; nur die genannten Toolkits sind betroffen. false mit Konsolenwarnung, wenn der Wert kein Array ist

Der ältere Optionsname developerContext für openContext funktioniert weiter und schreibt eine Veraltet-Warnung in die Konsole.

Konsolenmeldungen

Meldung	Ursache
[StrikeUpChat] displayType "inline" requires a valid container (CSS selector or Element). Widget not mounted.	displayType: "inline" ohne container, der ein Element trifft
[StrikeUpChat] context.set rejected: N chars exceeds the 8192-char limit.	context.set() mit mehr als 8192 Zeichen
[StrikeUpChat] context.add rejected: result N chars exceeds the 8192-char limit.	context.add() würde den Kontext länger als 8192 Zeichen machen
[StrikeUpChat] open({ developerContext }) is deprecated — use open({ openContext }).	Der alte Optionsname
[StrikeUpChat] onReady callback threw:	Ihr onReady-Callback hat einen Fehler geworfen; das Widget hat ihn abgefangen
[StrikeUpChat] Widget initialisation failed:	Ein unerwarteter Fehler beim Start
[StrikeUpChat] setServerAuthorizations rejected: expected an array of { serverId, authData }.	setServerAuthorizations() mit etwas anderem als einem Array
[StrikeUpChat] serverAuthorizations ignored: expected an array of { serverId, authData }.	Die Option serverAuthorizations ist kein Array
[StrikeUpChat] getServerAuthorizations returned an invalid value; keeping the previous credentials.	Ihr Callback lieferte etwas anderes als ein Array oder null
[StrikeUpChat] getServerAuthorizations failed; keeping the previous credentials.	Ihr Callback warf einen Fehler oder sein Promise wurde abgelehnt
[Widget] Failed to parse includeUrls: oder excludeUrls:	Die gespeicherten URL-Regeln des Widgets sind ungültig
Gar nichts	Falsches Anwendungs-Token oder nicht erreichbare API: Nichts wird gezeichnet, und onReady meldet null

Öffnen-Links aus Benachrichtigungen

Die Öffnen-Schaltfläche in einer Benachrichtigung per E-Mail, Slack, Telegram oder Teams führt zur App-Seiten-URL, die unter Konfigurieren › User Interface eingetragen ist, ergänzt um ?strikeup_open=chat:<id> oder run:<id>. Das Skript liest diesen Parameter, sobald es lädt, entfernt ihn aus der Adressleiste, damit ein Neuladen ihn nicht erneut öffnet, und gibt ihn als openTarget weiter. Ein Chat öffnet sich nur, wenn er in der eigenen Liste des angemeldeten Kunden steht; ein Lauf öffnet sich im Kundenportal, nur solange das Portal eingeschaltet ist. Alles andere lässt den Kunden auf dem Startbildschirm. Behalten Sie den Parameter, wenn Ihre Seite umleitet, bevor das Widget startet. Siehe Auftragsbenachrichtigungen und Chat-Apps.

Ladereihenfolge

window.StrikeUpChat und das echte initStrikeUpChatWidget existieren erst, nachdem das Skript gelaufen ist. Mit dem schlichten Script-Tag vor Ihrem Inline-Aufruf am Ende des <body> ist das immer der Fall. Lädt das Skript asynchron, starten Sie das Widget aus dem Ereignis strikeupChatWidgetLoaded oder legen vor allem anderen window._strikeupChatWidgetQueue und ein einreihendes initStrikeUpChatWidget an; das Skript übernimmt die Warteschlange und spielt sie ab. Laden Sie das Skript nicht im <head>: Dort scheitert es teilweise, die URL-Regeln werden bei Routenwechseln nicht mehr neu geprüft, und das Lade-Ereignis wird nie ausgelöst.

Beispiel

Eine Seite mit eigener Schaltfläche „Assistent ein/aus“ an einem Widget mit der Darstellungsart Eigener Auslöser — Panel. Die Schaltfläche bleibt deaktiviert, bis das Widget bereit ist, und öffnet oder schließt dann den Bereich.

<button id="ask-ai" disabled>Assistent ein/aus</button>

<script src="https://<your widget script URL>" data-api-url="https://api.strikeup.io"></script>
<script>
  window.initStrikeUpChatWidget({
    applicationToken: "<your widget's application token>",
    userId: "cus_48210",
    userDisplayName: "Rosie Kendall",
    userCompanyId: "SAP-5531"
  });

  const button = document.getElementById("ask-ai");

  window.StrikeUpChat.onReady(function (type) {
    if (type === null) return;                     // Token falsch oder API nicht erreichbar
    button.disabled = false;
  });

  button.onclick = function () {
    window.StrikeUpChat.isOpen() ? window.StrikeUpChat.close() : window.StrikeUpChat.open();
  };
</script>

Ihre Seite steuert das Widget über window.StrikeUpChat; hier schaltet eine Schaltfläche es mit isOpen(), open() und close() um.

Was dieser Screenshot zeigt

Ansicht

(host page (https://app.example.com/))

Hervorgehoben

button “”, host-header, pane open. calls StrikeUpChat.isOpen() ? close() : open()

Außerdem sichtbar

Host page with its own toggle button; Full-height pane on the right with welcome text, cards and message box

Zweck

the JavaScript API at work

Weitere Aufrufe, die darauf aufbauen:

// Sofort fragen, mit einem Hinweis für die erste Antwort
window.StrikeUpChat.open({
  message: "Fasse die Rechnung INV-2026-0418 zusammen",
  autoSend: true,
  openContext: "Geöffnet aus der Detailseite der Rechnung INV-2026-0418."
});

// Die Seite bei jedem Routenwechsel beschreiben (Grenze 8192 Zeichen)
const ok = window.StrikeUpChat.context.set(
  "User: Rosie Kendall (cus_48210)\nPage: Invoice details (/invoices/inv_2026_0418)"
);
if (!ok) console.warn("Seitenkontext zu groß");

// Eine andere Person meldet sich ohne Neuladen an: für sie neu starten
window.initStrikeUpChatWidget({ applicationToken: TOKEN, userId: "cus_48284", loginTicket: freshTicket });

// Die Person meldet sich von Ihrer App ab: Widget entfernen und beim nächsten Laden die userId der nächsten Person übergeben
window.StrikeUpChat.destroy();

Was es nicht tut

• Kein Promise und keine Ereignisse außer der Bereitschaft. initStrikeUpChatWidget liefert nichts; verwenden Sie onReady. Es gibt kein Ereignis, wenn die Person den Chat öffnet oder schließt; fragen Sie isOpen() ab, zum Beispiel alle 200 Millisekunden.
• Keine Abmeldung. destroy() entfernt das Widget, lässt die Sitzung des Endkunden in diesem Browser aber bestehen. Kunden melden sich mit „Abmelden“ im Kundenportal ab.
• Kein Senden in einen bestehenden Chat. Der einzige Weg, aus Ihrem Code eine Nachricht zu senden, ist open({ message, autoSend: true }), das immer ein neues Gespräch beginnt.
• Keine Sprachoption. Der Chat folgt der Browsersprache der Person (Englisch, Deutsch oder Spanisch).
• Keine Optionen für das Aussehen. Farben, Position und Symbol der Startschaltfläche, Größen und URL-Regeln stammen aus den Einstellungen des Widgets.
• Kein Zugriff aus anderen Frames. Nur das Fenster, das das Skript geladen hat, besitzt window.StrikeUpChat.
• Kein öffentliches Nachrichtenprotokoll. Die Nachrichten, die die Seite mit dem Chat-Frame austauscht, und die Parameter in der Adresse des Frames sind intern und ändern sich ohne Ankündigung; verwenden Sie nur die Methoden auf dieser Seite.
• Ein Widget pro Seite. Ein zweiter Aufruf von initStrikeUpChatWidget mit einer anderen Person ersetzt das erste Widget.

Wo Sie es sehen

• Der Code, mit dem Ihre Seite startet, wird unter Konfigurieren › Embed erzeugt: der Einbettungscode, die Inline-Variante, Custom Trigger Button Snippets für open(), close() und isOpen() sowie Gib der KI verborgenen Kontext zu deiner Seite für openContext und context.set().
• Skript und Init-Aufruf einbauen: Das Widget in Ihr Produkt einbauen.
• displayType, container, open(), close() und isOpen() im Zusammenhang: Darstellungsarten und eigene Auslöser.
• Identitätsoptionen, openContext und context.* im Detail: Nutzer identifizieren und Kontext übergeben.
• loginTicket: Anmeldung von Endkunden.
• serverAuthorizations: Den Assistenten Ihre API im Namen des Nutzers aufrufen lassen.

Verwandte Seiten

• Das StrikeUp-Widget
• Das Widget in Ihr Produkt einbauen
• Darstellungsarten und eigene Auslöser
• Nutzer identifizieren und Kontext übergeben
• Embed