Öffentliche JavaScript-API¶

Alles, was eine Host-Seite verwenden kann, um das eingebettete Chat-Widget über eigene Skripte zu steuern.

Das Widget wird im Shadow DOM innerhalb des Host-Dokuments gemountet — es gibt kein iframe, daher sind alle Aufrufe gewöhnliches JavaScript im selben Realm. Zwei globale Objekte bilden den Vertrag:

Global	Eigentümer	Zweck
`window.daktelaAiChatConfig`	Host-Seite	woher das Widget geladen werden soll
`window.daktelaAiChat`	Widget	die unten beschriebene API

Installation¶

Fügen Sie beide Skripte in der unten gezeigten Reihenfolge in die Seite ein.

<script>
  // Befehlswarteschlange: erlaubt der Seite, die API aufzurufen, bevor das Widget geladen ist.
  (function () {
    if (window.daktelaAiChat && window.daktelaAiChat.__isProxy) return;
    var q = [];
    window.daktelaAiChat = new Proxy(
      { queue: q, __isProxy: true },
      {
        get: function (t, p) {
          if (p in t) return t[p];
          return function () {
            q.push({ m: p, a: [].slice.call(arguments), t: Date.now() });
          };
        },
      },
    );
  })();
</script>

<script>
  window.daktelaAiChatConfig = {
    url: 'https://my-instance.bot.coworkers.ai',
    daktelaAiChatId: 'abc123',
  };
</script>

<script
  defer
  crossorigin="anonymous"
  src="https://my-instance.bot.coworkers.ai/chat-window-public-api/loader/dai-loader.js"
></script>

url und der Host in src müssen auf dieselbe Instanz verweisen.

So funktioniert das Laden¶

Das Widget selbst wird lazy geladen — zum Beispiel bei open() oder einem Klick auf den Launcher. Alles, was Sie vorher aufrufen, landet in einer Warteschlange und wird ausgeführt, sobald das Widget geladen ist — und zwar genau in der Reihenfolge, in der Sie es aufgerufen haben. Es geht nichts verloren.

Fensterkontrolle¶

`open()`¶

Öffnet das Chat-Fenster. Löst beim ersten Aufruf den lazy Download aus. Kann problemlos mehrfach aufgerufen werden — es passiert dann einfach nichts zusätzlich.

`close()`¶

Schließt das Fenster und beendet standardmäßig die Konversation: Bei der Standardeinstellung true für configuration.identity.closeResetsSession wird die Session zurückgesetzt, und das nächste Öffnen startet eine neue Diskussion. Setzen Sie diese Option auf false, damit close() das Fenster nur ausblendet.

`restart(options?)` / `restartAndOpen(options?)`¶

Verwirft die aktuelle Konversation und startet eine neue. restartAndOpen öffnet zusätzlich das Fenster.

window.daktelaAiChat.restart({ retainContextKeys: ['$orderId'] });

Option	Typ	Wirkung
`retainContextKeys`	`string[]`	Kontextschlüssel, die in die neue Konversation kopiert werden. Alles andere wird verworfen. Unbekannte Schlüssel werden ignoriert.

Ohne Optionen wird der gesamte Kontext gelöscht.

`restartAndClose()`¶

Schließt das Fenster. Entgegen dem Namen wird die Konversation nicht neu gestartet — ob die Session endet, entscheidet closeResetsSession, genau wie bei close().

`destroy()`¶

Trennt die Verbindung, entfernt das Widget, löscht registrierte Tools und Analytics und entfernt window.daktelaAiChat. Verwenden Sie dies, wenn die Host-Seite den Chat abbaut (z. B. bei einem SPA-Routenwechsel). Danach erfolgte Aufrufe haben keine Wirkung.

Sprache¶

`setLanguage(languageCode)`¶

Wechselt die Sprache der Benutzeroberfläche.

Der Code muss in configuration.languages.enabledLanguages aufgeführt sein — andernfalls wird der Aufruf mit einer Konsolenfehlermeldung abgelehnt und nichts ändert sich. Sprachen aktivieren Sie in der Administration (Detail des Chat-Fensters → Languages) und veröffentlichen sie anschließend; das Widget liest immer nur die veröffentlichte Konfiguration.

`resetLanguage()`¶

Verwirft die Überschreibung und kehrt zur konfigurierten Erkennung zurück.

Konversationskontext¶

Kontext ist eine Menge von Schlüssel/Wert-Paaren, die der Bot lesen kann — Bestellnummer, Tarif, Warenkorbgröße.

Schlüssel müssen so geschrieben werden, wie die Bot-Plattform ihre Variablen benennt: ein führendes $, gefolgt von einem einzelnen Wort ohne Leerzeichen — $orderId, nicht orderId oder $order id. Ein Schlüssel, der nicht passt, wird mit einer Konsolenfehlermeldung verworfen, da der Bot ihn ohnehin nie auflösen könnte.

Der Options-Tab in der Administration kann Kontextpaare voreinstellen. Diese setzen jede Diskussion, die das Widget startet, einschließlich der nach einem Neustart, und wirken so als Standardwerte; ein addContext()- / setContext()-Aufruf von der Host-Seite überschreibt denselben Schlüssel für die aktuelle Diskussion.

`addContext(context)`¶

window.daktelaAiChat.addContext({
  $orderId: 'A-1234',
  $plan: 'premium',
  $note: { value: 'expires soon', lifespan: 3 },
});

Akzeptiert ein einfaches Objekt. Skalare werden automatisch umschlossen; übergeben Sie { value, lifespan }, um zu begrenzen, wie viele Bot-Runden ein Eintrag überlebt. Schlüssel werden zusammengeführt, nicht ersetzt. Wird sofort gesendet, wenn eine Konversation aktiv ist, andernfalls der nächsten zugeordnet. Schlüssel, die die $name-Regel verletzen, werden übersprungen; der Rest des Objekts wird trotzdem angewendet.

`setContext(key, value)`¶

Die Einzeleintrag-Form von addContext. Es gilt dieselbe $name-Schlüsselregel.

Erscheinungsbild¶

`setCustomCss(cssText)` / `resetCustomCss()`¶

Fügt rohes CSS in den Shadow DOM des Widgets ein. Wirkt sich erst aus, sobald das Bundle geladen ist.

window.daktelaAiChat.setCustomCss('.daktela-ai-window { border-radius: 37px !important; }');

Zwei Dinge, die Sie wissen sollten — beide sind häufige Ursachen für "es passiert nichts":

Eigenes CSS wird vor dem eigenen Stylesheet des Widgets eingefügt, sodass Regeln fast immer !important benötigen.
Selektoren müssen zu echten Klassen passen. Die nützlichen sind .daktela-ai-window, .daktela-ai-header, .daktela-ai-launcher-button, .daktela-ai-message-button und .daktela-ai-home-screen.

Das Widget protokolliert eine Warnung, sobald eigenes CSS angewendet wird. Das ist beabsichtigt — Klassennamen sind kein stabiler Vertrag, testen Sie eigenes CSS daher nach Widget-Updates erneut.

Seiten-Aktions-Tools¶

Das Agent-Modul — das LLM, das Ihre Dialoge steuert — kann neben dem Prompt auch Tools nutzen. Ein Typ davon sind API-Integrationen, die Ihre Backend-Endpunkte aufrufen. Seiten-Aktions-Tools sind der zweite Typ: eine JavaScript-Funktion, die direkt auf Ihrer Seite läuft und die Sie mit registerTool() registrieren — so kann der Agent in Ihre Seite zurückrufen (eine Bestellung nachschlagen, ein Element hervorheben, ein Ticket öffnen), ohne dass Daten den Browser des Besuchers verlassen.

`registerTool(tool)`¶

window.daktelaAiChat.registerTool({
  name: 'openTicket',
  description: 'Opens a support ticket and returns its id.',
  parameters: {
    type: 'object',
    properties: { subject: { type: 'string' } },
    required: ['subject'],
  },
  confirm: true,
  handler: (args) => ({ ticketId: createTicket(args.subject) }),
});

Feld	Typ	Hinweise
`name`	`string`	Eindeutig; eine erneute Registrierung desselben Namens ersetzt das Tool.
`description`	`string`	Was der Assistent liest, um zu entscheiden, wann er es aufruft.
`parameters`	JSON Schema	Objektschema. Nur `required` auf oberster Ebene und primitive Typen werden validiert.
`handler`	`(args) => unknown`	Synchron oder asynchron. Verlässt nie den Browser.
`confirm`	`boolean`	Optional. Zeigt vor der Ausführung eine Bestätigungs-/Ablehnungsaufforderung.

Ein Handler kann jeden JSON-serialisierbaren Wert zurückgeben; dieser wird an den Assistenten zurückgegeben. Fehler werden als handler_error gemeldet, ein Handler, der 30 Sekunden überschreitet, als timeout, eine abgelehnte Aufforderung als user_declined.

Timing: Die registrierte Menge wird jeder ausgehenden Besuchernachricht angehängt, nicht dem initialen Handshake. Registrieren Sie Tools, bevor der Besucher seine erste Nachricht sendet — der erste Zug des Bots sieht sie nicht.

Info

Ein Tool zu registrieren macht es für den Agent verfügbar, sagt ihm aber noch nicht, wann er es einsetzen soll. Genau wie bei API-Integrationen müssen Sie das Tool (anhand seines name) direkt in den Agent-Instruktionen erwähnen — z. B. „Nutze das Tool openTicket, wenn der Kunde ein Support-Ticket öffnen möchte."

`unregisterTool(name)` / `getRegisteredTools()`¶

getRegisteredTools() gibt die aktuell geltenden Schemas zurück (ohne Handler), also das, was eine ausgehende Nachricht mitführt.

Alte `ew-*`-Custom-Events¶

Diese existieren aus einem einzigen Grund: damit eine bereits mit dem alten Chat-Fenster integrierte Seite nach dem Upgrade weiter funktioniert, ohne ihren Code anzufassen. Event-Namen, Payloads und Effekte entsprechen dem alten Widget.

Für alles Neue verwenden Sie die obige JavaScript-API — sie ist die unterstützte Oberfläche, deckt mehr ab und meldet Fehler. Die Events werden nur aus Kompatibilitätsgründen gepflegt.

Lösen Sie sie auf window aus:

window.dispatchEvent(new CustomEvent('ew-open-window'));

Event	Wirkung	API-Äquivalent
`ew-open-window`	Öffnet das Fenster	`open()`
`ew-hide-window`	Blendet das Fenster aus, ohne die Konversation zu beenden	—
`ew-toggle-window`	Öffnet oder blendet aus	—
`ew-end-discussion`	Beendet die Konversation auf dem Server, sodass sich der Assistent verabschieden und um eine Bewertung bitten kann; das Fenster bleibt geöffnet. Erneutes Auslösen nach Ende der Konversation schließt sie und startet neu.	—
`ew-reset-chat`	Startet eine neue Konversation, Fensterstatus unverändert	`restart()`
`ew-close-and-reset-chat`	Schließt das Fenster und startet eine neue Konversation	`restartAndClose()`
`add-context`	Ein Kontexteintrag, `detail: { key, value }`	`setContext(key, value)`
`chatbot-ew-context-set`	Gesamtes Kontextobjekt in `detail`	`addContext(object)`
`ew-set-dark-mode`	Erzwingt das dunkle Theme	—
`ew-set-light-mode`	Erzwingt das helle Theme	—
`ew-set-system-theme-mode`	Folgt dem Theme des Betriebssystems	—
`ew-enable-ga` / `ew-disable-ga`	Schaltet die Google-Analytics-Berichterstattung um. `ew-disable-ga` stoppt nur Google Analytics — Google Tag Manager erhält weiterhin Events, wie beim alten Widget.	—

Öffentliche JavaScript-API¶

Installation¶

So funktioniert das Laden¶

Fensterkontrolle¶

open()¶

close()¶

restart(options?) / restartAndOpen(options?)¶

restartAndClose()¶

destroy()¶

Sprache¶

setLanguage(languageCode)¶

resetLanguage()¶