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.
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()
| Event | Payload | Wann es auslöst |
|---|---|---|
ready | { assistantId: string } | Der Assistant ist gemountet und vollständig interaktiv |
open | undefined | Der Assistant-Dialog öffnet sich |
close | undefined | Der 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
| Attribut | Typ | Beschreibung |
|---|---|---|
assistant-id | string | Assistant-ID (erforderlich) |
site-id | string | Legacy-Alias für assistant-id |
origin | string | Basis-URL der Olotalk-API; optional, standardmäßig die Cloud-API |
theme | "light" | "dark" | JSON | UI-Theme; ein JSON-Objekt überschreibt die Tokens vollständig |
mode | Siehe Shapes, vierzehn Werte | Welche Form gemountet wird, siehe Shapes unten |
reach | string | Zusätzliche Trigger über der gemounteten Form, kommagetrennt: "selection,commandk", siehe Formen kombinieren |
selection-answers | string | Wo 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 |
locale | string | Die 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-url | string | URL des Assistant-Stylesheets |
config | JSON-String | Vollstä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.
mode | Wo er sitzt | Wie er sich öffnet |
|---|---|---|
bubble | Ein Launcher in der Ecke, Panel schwebt über der Seite | Besucher klickt den Launcher. Der Standard |
starters | Eck-Launcher mit vorgeschlagenen Fragen beim Hover | Besucher klickt den Launcher oder einen Vorschlag |
inline | Füllt das Element, in das Sie ihn mounten, immer offen | Nichts zu öffnen, er ist Teil der Seite |
drawer | Volle Höhe, bündig am Rand; schiebt die Seite zur Seite, statt sie zu überdecken | Ihr eigener Button, data-olotalk-open oder open() |
commandk | Zentriert über einer abgedunkelten Seite | ⌘K / CtrlK |
corner | Eck-Panel, im Ruhezustand nichts auf der Seite | Ihr eigenes Steuerelement oder ein reach-Trigger |
center | Zentriert über abgedunkelter Seite, nichts im Ruhezustand | Ihr eigenes Steuerelement oder ein reach-Trigger |
expand | Eine Zeile in Ihrer Seite, die sich an Ort und Stelle entfaltet und Inhalt nach unten schiebt | Besucher drückt die Zeile |
anchored | Neben einem Element, ein Tarif, eine Spezifikationszeile | Ihre eigene Affordance, mit open({ anchor }) |
fullpage | Der Assistant ist die Seite | Immer offen; nichts zu beschwören |
sidebar | Eine feste Leiste voller Höhe am Rand | Immer offen; nichts zu beschwören |
navfield | Nichts von uns, das Suchfeld Ihrer eigenen Nav | Ihr Feld submittet, mit open({ prefill }) |
askbar | Nichts von uns, Ihre eigene Leiste am Fuß der Seite | Ihre Leiste submittet, mit open({ prefill }) |
selection | Nichts im Ruhezustand, ein Angebot erscheint, wo Text markiert wird | Besucher 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:
- antwortet der Assistant in der erkannten Sprache,
- zeigt er oberhalb des Eingabefelds einen Inline-Hinweis:
Continue in {language}? · Yes / No, - lädt er bei
Yesdie Assistant-Config in der neuen Locale neu, tauscht Dictionary und vorgeschlagene Fragen aus und speichert die Wahl inlocalStorageunterolotalk:lang:{assistantId}, - sperrt er bei
Nodie 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')