Assistant-JS-API

Steuern Sie den Olotalk-Assistant programmatisch aus Ihrem eigenen JavaScript.

Die globale Funktion Olotalk() ist auf jeder Seite verfügbar, auf der das Loader-Snippet eingebunden ist. Sobald das Loader-Script ausgeführt wurde, werden Aufrufe, die vor dem vollständigen Boot des Assistant-Bundles erfolgen, automatisch in eine Queue gestellt und später wieder abgespielt.

initautomatisch beim Laden
ready
open ⇄ closebleibt gemountet
destroydemontiert
↺ nach destroy mountet init() eine neue Instanz
`init` läuft automatisch bei `DOMContentLoaded`. `open` und `close` schalten den Dialog um, während die Instanz gemountet bleibt. `destroy()` demontiert sie und entfernt ihr DOM, danach mountet `init()` eine neue Instanz.

Command API

Olotalk(command: string, payload?: any): void | Promise<void>

Olotalk('open')

Öffnet den Assistant-Dialog.

Olotalk('open')

Wenn der Assistant bereits geöffnet ist, passiert nichts.


Olotalk('close')

Schließt den Assistant-Dialog. Die Instanz bleibt gemountet; der nächste Aufruf von open() stellt sie einfach wieder her.

Olotalk('close')

Olotalk('destroy')

Unmountet den Assistant vollständig und entfernt alle DOM-Knoten, die er erzeugt hat. Verwenden Sie das, wenn Sie ihn von einer einzelnen Seite entfernen möchten, ohne eine komplette Navigation auszulösen.

await Olotalk('destroy')

Gibt eine Promise zurück, die aufgelöst wird, sobald das Unmounting abgeschlossen ist. Nach destroy() können Sie mit Olotalk('init') erneut initialisieren.


Olotalk('init', config?)

Startet die Initialisierung des Assistants manuell. Optional können Sie eine partielle Config übergeben, um Werte aus dem Embed-Snippet zu überschreiben.

// Mit der Config aus dem Snippet initialisieren
Olotalk('init')

// Mit explizitem Locale-Override initialisieren
Olotalk('init', { locale: 'de' })

init wird vom Loader automatisch bei DOMContentLoaded aufgerufen. Sie müssen es nur manuell aufrufen, wenn Sie:

  • window.OlotalkConfig = { ... } erst setzen, nachdem der Loader bereits gebootet hat, oder
  • nach einem destroy() neu initialisieren möchten.

Low-Level-API der Assistant-Instanz

Wenn Sie @olotalk/assistant direkt importieren statt den Loader zu verwenden, gibt createAssistant() eine Assistant-Instanz mit Methoden und Events zurück.

import { createAssistant } from '@olotalk/assistant'

const assistant = createAssistant(document.body, {
  assistantId: 'ast_oltk_7Kd2mQxRv9TbNhLpW3Zsy',
  origin: 'https://api.olotalk.com',
  config: assistantConfig,
  cssUrl: 'https://cdn.jsdelivr.net/npm/@olotalk/assistant@0/dist/olotalk-assistant.css',
})

Instanzmethoden

assistant.open()
assistant.open({ prefill: 'Unterstützen Sie SSO?' })          // stellt die Frage
assistant.open({ prefill: passage, send: false })             // hält sie zum Bearbeiten
assistant.close()
assistant.isOpen()                                            // true, solange das Panel zu sehen ist
assistant.setTheme('dark')
await assistant.setLocale('de')                               // erhält die Konversation
assistant.destroy({ outro: true })

setLocale liefert ein Promise, das angibt, ob die Sprache gewechselt hat. Greifen Sie immer dann dazu, wenn Ihr eigener Umschalter die Seite nicht neu lädt, siehe Die Sprache selbst steuern.

Ein Assistant pro Seite

createAssistant() gibt den bereits gemounteten Assistant für diese assistantId zurück, statt einen zweiten zu mounten. So teilen sich mehrere Affordances, etwa ein Corner Bubble und Ihr eigener „Ask AI“-Button, ein Panel und eine Konversation, statt zwei zu öffnen.

Nutzen Sie getAssistant(), um den bestehenden zu steuern:

import { getAssistant } from '@olotalk/assistant'

document.querySelector('#ask-about-pricing').addEventListener('click', () => {
  getAssistant('ast_oltk_7Kd2mQxRv9TbNhLpW3Zsy')
    ?.open({ prefill: 'What is included in the Growth plan?' })
})

Es gibt undefined zurück, wenn für diese ID nichts gemountet ist, es mountet nie einen als Nebenwirkung.

Instanz-Events

const unsubscribe = assistant.on('open', () => {
  console.log('Assistant geöffnet')
})

assistant.on('ready', ({ assistantId }) => {
  console.log('Bereit', assistantId)
})

assistant.on('send', ({ text }) => {
  console.log('Gesendet', text)
})

unsubscribe()
EventPayloadWann es auslöst
ready{ assistantId: string }Der Assistant ist gemountet und vollständig interaktiv
openundefinedDer Assistant-Dialog öffnet sich
closeundefinedDer Assistant-Dialog schließt sich
send{ text: string }Der Nutzer sendet eine Nachricht
cta_click{ id: string; action: ActionType; intent: string }Der Besucher klickt auf einen vom Assistant vorgeschlagenen CTA
lead_submit{ leadId: string; status: string; score: number }Der Besucher sendet ein Lead-Capture-Formular ab

ActionType ist "lead_form" | "link" | "escalate_to_human" | "trigger_webhook" | "book_meeting" | "hubspot_create_contact_deal".

Das loader-basierte Embed legt die interne Assistant-Instanz nicht als öffentliche globale API offen. Für Script-Tag-Integrationen verwenden Sie die Olotalk()-Command-Schnittstelle oben.


Custom Element (<olotalk-assistant>)

Der ESM-Build exportiert OlotalkAssistantElement, ein standardkonformes Custom Element, das Sie registrieren und deklarativ in jedem HTML- oder Framework-Template verwenden können.

Registrieren

import { defineOlotalkAssistantElement } from '@olotalk/assistant'

defineOlotalkAssistantElement() // registriert <olotalk-assistant>

Rufen Sie das einmal beim App-Start auf, zum Beispiel in main.ts. Mehrfaches Aufrufen ist unproblematisch; eine erneute Registrierung ist ein No-op.

Verwenden

<olotalk-assistant
  assistant-id="ast_oltk_7Kd2mQxRv9TbNhLpW3Zsy"
  origin="https://api.olotalk.com"
  theme="light"
  mode="inline"
  css-url="https://cdn.jsdelivr.net/npm/@olotalk/assistant@0/dist/olotalk-assistant.css"
></olotalk-assistant>

Attribute

AttributTypBeschreibung
assistant-idstringAssistant-ID (erforderlich)
site-idstringLegacy-Alias für assistant-id
originstringBasis-URL der Olotalk-API; optional, standardmäßig die Cloud-API
theme"light" | "dark" | JSONUI-Theme; ein JSON-Objekt überschreibt die Tokens vollständig
modeSiehe Shapes, vierzehn WerteWelche Form gemountet wird, siehe Shapes unten
reachstringZusätzliche Trigger über der gemounteten Form, kommagetrennt: "selection,commandk", siehe Formen kombinieren
selection-answersstringWo eine Markierung das Panel öffnet: "beside" (Standard) neben den Wörtern, "in-place" dort, wo der Assistant lebt, siehe Formen kombinieren
placement"floating" | "embedded"Veraltet, nutzen Sie mode. floating entspricht bubble, embedded entspricht inline
localestringDie Anzeigesprache. Sie nach dem Mount zu ändern tauscht die Texte des Assistant an Ort und Stelle und erhält die Konversation, siehe Die Sprache selbst steuern
css-urlstringURL des Assistant-Stylesheets
configJSON-StringVollständiges AssistantConfig-Objekt als serialisiertes JSON

Shapes

Ein Assistant, an verschiedenen Stellen gemountet. Jede Form fährt dieselbe Konversation, dieselbe Verankerung und dieselben Quellenangaben, nur der Mount unterscheidet sich.

Jede Zeile entscheidet drei Dinge auf einmal: wo das Panel sitzt, was es öffnet, und was auf der Seite steht, bevor irgendetwas passiert. Was eine Form entscheidet erklärt die Regel hinter der Tabelle, auch, welche Formen gar keinen Button auf die Seite setzen.

modeWo er sitztWie er sich öffnet
bubbleEin Launcher in der Ecke, Panel schwebt über der SeiteBesucher klickt den Launcher. Der Standard
startersEck-Launcher mit vorgeschlagenen Fragen beim HoverBesucher klickt den Launcher oder einen Vorschlag
inlineFüllt das Element, in das Sie ihn mounten, immer offenNichts zu öffnen, er ist Teil der Seite
drawerVolle Höhe, bündig am Rand; schiebt die Seite zur Seite, statt sie zu überdeckenIhr eigener Button, data-olotalk-open oder open()
commandkZentriert über einer abgedunkelten Seite⌘K / CtrlK
cornerEck-Panel, im Ruhezustand nichts auf der SeiteIhr eigenes Steuerelement oder ein reach-Trigger
centerZentriert über abgedunkelter Seite, nichts im RuhezustandIhr eigenes Steuerelement oder ein reach-Trigger
expandEine Zeile in Ihrer Seite, die sich an Ort und Stelle entfaltet und Inhalt nach unten schiebtBesucher drückt die Zeile
anchoredNeben einem Element, ein Tarif, eine SpezifikationszeileIhre eigene Affordance, mit open({ anchor })
fullpageDer Assistant ist die SeiteImmer offen; nichts zu beschwören
sidebarEine feste Leiste voller Höhe am RandImmer offen; nichts zu beschwören
navfieldNichts von uns, das Suchfeld Ihrer eigenen NavIhr Feld submittet, mit open({ prefill })
askbarNichts von uns, Ihre eigene Leiste am Fuß der SeiteIhre Leiste submittet, mit open({ prefill })
selectionNichts im Ruhezustand, ein Angebot erscheint, wo Text markiert wirdBesucher markiert eine Passage und nimmt das Angebot an

Die meisten Formen zeichnen keinen eigenen Launcher, die Spalte Wie er sich öffnet oben sagt, was jede einzelne öffnet. Überall dort, wo sie Ihren eigenen Button, Ihr Feld oder Ihre Leiste nennt, ist das Ihr Code, der open() aufruft. Ein Drawer nimmt Ihren:

import { getAssistant } from '@olotalk/assistant'

document.querySelector('#ask-ai').addEventListener('click', () => {
  getAssistant('ast_oltk_7Kd2mQxRv9TbNhLpW3Zsy')?.open()
})

Mit dem eingefügten Snippet installiert? Sie brauchen weder Imports noch einen Build-Schritt, das globale Olotalk nimmt dieselben Aufrufe entgegen und reiht sie ein, bis der Assistant bereit ist:

<button onclick="Olotalk('open')">Ask AI</button>

Jedes open(...)-Payload auf dieser Seite reist auf demselben Weg durch das Global, Olotalk('open', { anchor, context, prefill, send }), jedes Snippet unten hat also einen Loader-Zwilling: Ersetzen Sie getAssistant(id)?.open(…) durch Olotalk('open', …).

commandk bindet das Tastenkürzel selbst, und nur, wenn es als diese Form gemountet ist, kein anderer Modus fasst diese Taste an. Weil sein Ruhezustand schlicht nichts ist, bleibt er unauffindbar, wenn Sie ihn nicht ankündigen: Kombinieren Sie ihn mit einem Hinweis in Ihrer Navigation.

drawer und commandk dunkeln die Seite dahinter ab, sperren ihr Scrollen solange sie offen sind, halten den Fokus im Panel, schließen auf Esc oder einen Klick auf die Abdunklung und geben den Fokus an das zurück, was sie geöffnet hat.

An ein Element verankert

anchored öffnet sich neben dem, worum es geht, und verdeckt es nie, bevorzugt darunter, darüber, wenn der Platz fehlt, und folgt dem Element beim Scrollen:

document.querySelector('#growth-tier .ask').addEventListener('click', () => {
  getAssistant(id)?.open({
    anchor: document.querySelector('#growth-tier'),
    context: 'Growth plan',
    prefill: 'What is included in the Growth plan?',
    send: false,
  })
})

Auf einem Telefon ist neben nichts Platz, er wird zum Bottom-Sheet. Und weil der Anker nicht mehr sichtbar ist, sagt das Sheet, worum es geht. context ist dieses Etikett; ohne es greifen wir auf das data-olotalk-context des Elements zurück, sein aria-label oder seine eigene Überschrift.

Aus einer markierten Passage

selection hat gar keinen Ruhezustand. Markiert ein Besucher eine Passage auf Ihrer Seite, erscheint darüber ein kleines Angebot; es anzunehmen öffnet den Assistant mit dieser Passage im Composer, ungesendet, eine markierte Passage ist keine Frage, und sie wörtlich zu stellen würde ihm Worte in den Mund legen.

<olotalk-assistant assistant-id="ast_oltk_…" mode="selection"></olotalk-assistant>

Mehr ist nicht zu verdrahten. Markierungen in Inputs, Textareas und contenteditable-Bereichen werden ignoriert, wer editiert, fragt nicht, das Seeding ist auf ein Wort bis einen Absatz begrenzt, und einem Rechtsklick geht es aus dem Weg.

Auf einem Touch-Gerät bietet es bewusst nichts an. Text markieren öffnet dort das systemeigene Kopieren-/Nachschlagen-Menü, das sich weder stylen noch verschieben noch unterdrücken lässt, ohne die Auswahl, und damit Kopieren, ganz abzuschalten. Dagegen anzutreten wäre schlechter als nichts anzubieten: Auf dem Telefon bleibt diese Form still, und jeder andere Mount funktioniert normal weiter.

Felder, die Sie schon haben

navfield und askbar rendern nichts Eigenes. Das Feld ist Ihres, in Ihrer Navigation oder als Leiste am Fuß einer Doku, und sein Submit öffnet den Assistant mit der bereits gestellten Frage:

form.addEventListener('submit', (e) => {
  e.preventDefault()
  getAssistant(id)?.open({ prefill: input.value })
})

Das ist die gesamte Integration. Sie funktioniert mit jedem Markup, das Sie schon haben, und genau das ist der Punkt: Die Form ist Ihr Feld, nicht unser Rendering eines Feldes.

Formen kombinieren

Eine Seite mountet eine Form, dort lebt die Konversation, aber sie lässt sich auf mehr als einem Weg herbeirufen:

  • Aus Ihrer eigenen Oberfläche. Jeder Button, jedes Feld und jeder Link kann getAssistant(id).open({ prefill }) aufrufen, ganz gleich welche Form gemountet ist. Ein Nav-Feld neben einer Corner-Bubble sind zwei Zeilen Ihres Codes.
  • Aus unserer, mit reach. Sie benennen zusätzliche Trigger über der gemounteten Form:
<script
  src="https://cdn.jsdelivr.net/npm/@olotalk/assistant-loader@0/dist/loader.iife.js"
  data-olotalk-assistant-id="ast_oltk_7Kd2mQxRv9TbNhLpW3Zsy"
  data-olotalk-mode="bubble"
  data-olotalk-reach="selection,commandk"
  async
></script>

Das ist eine Corner-Bubble, die sich zusätzlich öffnet, wenn ein Besucher eine Passage markiert, neben der Markierung, mit der Passage als Zitat über einem leeren Composer, und wenn er ⌘K drückt. reach akzeptiert selection und commandk; unbekannte Ids werden mit einer Konsolenwarnung ignoriert. Wie viele Wege hinein Sie auch hinzufügen: Es gibt weiterhin genau ein Panel, eine Konversation und eine Session, reach fügt Türen hinzu, keine Räume.

mode="selection" und reach="selection" sind nicht dasselbe

Das Wort hat zwei Bedeutungen, und hier wird es am ehesten falsch gelesen:

  • data-olotalk-mode="selection", Markieren-und-fragen ist der Assistant. Im Ruhezustand steht nichts auf der Seite, es gibt nirgends einen Button, und Text zu markieren ist der einzige Weg hinein.
  • data-olotalk-mode="bubble" data-olotalk-reach="selection", die Corner-Bubble ist der Assistant, und das Markieren ist ein zusätzlicher Weg zu ihr. Der Launcher bleibt, denn genau das ist eine Bubble.

Wenn Sie Markieren-und-fragen ohne jeden Button auf der Seite wollen, ist es die erste Variante, für sich allein.

Das Panel dort lassen, wo es lebt

Standardmäßig holt eine Markierung das Panel zu den Wörtern: Die Antwort kommt dort an, wo die Frage gestellt wurde, auch bei einer Corner-Bubble. Wenn Ihr Assistant ein fester Punkt ist, den Ihre Besucher bereits gefunden haben, möchten Sie vielleicht, dass er sich nicht bewegt:

data-olotalk-mode="bubble"
data-olotalk-reach="selection"
data-olotalk-selection-answers="in-place"

Das Panel öffnet sich dann dort, wo der Assistant lebt, weiterhin mit der Passage als Zitat über einem leeren Composer. beside ist der Standard; jeder andere Wert wird mit einer Konsolenwarnung ignoriert. Betroffen ist nur der Selection-Trigger: Ihre eigenen open({ anchor })-Aufrufe bleiben unberührt.

Auf Telefonen

Eine Mobil-Form wählen Sie nicht. Bei Telefonbreite werden Eck-, Rand-, zentrierte und verankerte Mounts zum selben Bottom-Sheet, und inline bleibt im Fluss, wo Sie es platziert haben. Ein Embed, beide Präsentationen.

Methoden und Properties

const el = document.querySelector('olotalk-assistant')

el.open()
el.close()
await el.destroy()

// Config/Theme programmgesteuert setzen (löst einen Rebuild aus)
el.config = { ...assistantConfig }
el.theme = 'dark'

Das Element baut sich automatisch neu auf, wenn sich beobachtete Attribute ändern.


Adaptive Sprache (nach dem ersten Turn)

Wenn die erste Nachricht eines Besuchers in einer anderen unterstützten Sprache geschrieben ist als die aktuelle UI, dann:

  1. antwortet der Assistant in der erkannten Sprache,
  2. zeigt er oberhalb des Eingabefelds einen Inline-Hinweis: Continue in {language}? · Yes / No,
  3. lädt er bei Yes die Assistant-Config in der neuen Locale neu, tauscht Dictionary und vorgeschlagene Fragen aus und speichert die Wahl in localStorage unter olotalk:lang:{assistantId},
  4. sperrt er bei No die aktuelle Locale für diese Session, damit der Hinweis nicht erneut erscheint.

Wiederkehrende Besucher landen direkt in der Sprache, die sie zuvor akzeptiert haben. Es gibt keine API, um diesen Hinweis aktiv zu steuern; das Verhalten ist bewusst passiv und wird durch die serverseitige Spracherkennung ausgelöst.

Wenn Sie den Hinweis komplett vermeiden möchten, pinnen Sie die Locale mit data-olotalk-locale. Ein expliziter Override schlägt alle Auto-Detection-Signale: Der Hinweis erscheint nicht, und die UI bleibt in der gewählten Sprache.

Die Sprache selbst steuern

Wenn Ihre Website einen eigenen Sprachumschalter hat, sagen Sie es dem Assistant, sobald der Besucher ihn benutzt:

Olotalk('locale', 'de')                    // Einbindung per Script-Tag
getAssistant(id).setLocale('de')           // direkter Import
el.setAttribute('locale', 'de')            // Custom Element

Das tauscht die UI, die Textrichtung und die vorgeschlagenen Fragen an Ort und Stelle, die offene Konversation bleibt erhalten, und sagt es dem Server, sodass auch die Antworten die Sprache wechseln, nicht nur das Panel darum herum. Greifen Sie immer dann dazu, wenn Ihr Umschalter die Seite nicht neu lädt, also in jeder Single-Page-App: Der Assistant löst seine Sprache genau einmal auf, beim Mount, aus data-olotalk-locale, dann der zuvor vom Besucher akzeptierten Wahl, dann <html lang>, dann dem Browser. Danach liest nichts diese Signale erneut, und ohne diesen Aufruf antwortet das Panel weiter in der Sprache, die der Besucher gerade verlassen hat.

Nutzen Sie dafür nicht Olotalk('init', { locale }): init baut den Assistant neu auf und wirft dabei weg, was der Besucher gerade fragen wollte.

Ein Trade-off, den man kennen sollte: Eine Sprache zu pinnen, beim Mount mit data-olotalk-locale ebenso wie nachträglich mit diesem Aufruf, ist eine explizite Anweisung und schlägt damit die Signale des Besuchers. Der adaptive Hinweis oben erscheint nicht, solange eine Sprache gesetzt ist, denn Sie haben die Frage, die er stellt, bereits beantwortet. Wenn Sie Besucher lieber selbst wählen lassen, pinnen Sie keine Locale: Der Assistant folgt dann bei jedem Seitenaufruf <html lang> und bietet den Wechsel an, sobald jemand in einer anderen Sprache schreibt.

Die Menge der unterstützten Sprachen wird pro Assistant im Source-Schritt des Builders konfiguriert. Öffnen Sie Ihren Assistant über Assistants und klappen Sie Ingestion status, coverage & languages auf. Auto-Detection ist auf dieses Set begrenzt: Eine Sprache außerhalb dieser Liste wird sowohl bei der initialen Locale-Auflösung als auch beim adaptiven Prompt ignoriert.


Den Assistant über einen eigenen Button öffnen

Ein häufiges Muster ist, einen eigenen Button statt des Standard-Launchers zu verwenden. Mounten Sie mode="corner": Das ist dasselbe Corner-Panel wie bubble, aber ohne sichtbares Element im Ruhezustand. Danach macht data-olotalk-open jeden Button zur Tür.

<button data-olotalk-open>Mit uns chatten</button>

<script
  src="https://cdn.jsdelivr.net/npm/@olotalk/assistant-loader@0/dist/loader.iife.js"
  data-olotalk-assistant-id="ast_oltk_7Kd2mQxRv9TbNhLpW3Zsy"
  data-olotalk-mode="corner"
  async
></script>

Wenn Sie den Standardmodus bubble behalten, ist Ihr Button ein zusätzlicher Einstieg; er entfernt den eingebauten Launcher nicht. Der Launcher lebt im Shadow Root des Assistants und sollte nicht per Seiten-CSS versteckt werden.


TypeScript-Typen

Wenn Sie TypeScript verwenden, deklarieren Sie die globale Variable, damit Sie Type-Checking erhalten:

// global.d.ts
declare global {
  interface Window {
    Olotalk?: (command: 'open' | 'close' | 'destroy' | 'init' | 'locale', payload?: any) => void | Promise<void>
    OlotalkConfig?: {
      assistantId?: string
      siteId?: string
      origin?: string
      locale?: string
      theme?: 'light' | 'dark' | Record<string, string>
      mode?: string                  // which shape — see Shapes above
      reach?: string                 // extra triggers, e.g. 'selection,commandk'
      selectionAnswers?: 'beside' | 'in-place'
      placement?: 'floating' | 'embedded'   // deprecated — use mode
      mount?: string
      cdnBase?: string
      version?: string
      cssUrl?: string
    }
    // Hinweis: Conversion-/Lead-Capture-/CTA-Regeln werden serverseitig
    // konfiguriert (Action policy im Dashboard), NICHT über dieses Objekt.
  }
}
export {}

Bevor der Assistant bootet

Rufen Sie Olotalk() nicht aus einem Script auf, das vor dem Loader-Script selbst ausgeführt wird. Sobald der Loader auf der Seite vorhanden ist, werden Commands automatisch gequeued, bis der Assistant bereit ist; Click-Handler und spätere Seitenscripts sind deshalb sicher:

// Sicher, sobald das Loader-Script ausgeführt wurde
Olotalk('open')