Übersicht über die Chat API
Über die Widget-API können Sie das Chat-Widget programmatisch steuern und Callbacks für Chat-Ereignisse registrieren.
Suchen Sie nach der REST-API? Dieser Artikel behandelt die JavaScript-Widget-API (window.aichatbotApi) im Browser für Seiten, auf denen das ChatLab-Widget eingebunden ist. Informationen zur Server-to-Server-REST-API, mit der Sie von Ihrem Backend aus Unterhaltungen mit Bots führen oder Bots programmatisch verwalten können, finden Sie in den Artikeln zur Bot Talk API und Management API.
Erste Schritte
Die Chatbot-API ist nicht sofort verfügbar, wenn Ihre Seite geladen wird - das Skript muss zuerst geladen und initialisiert werden. Sie müssen window.aichatbotCallback.onSessionActivated als Bootstrap-Mechanismus verwenden, um sicher auf die API zuzugreifen.
Verwenden Sie den öffentlichen Widget-Schlüssel aus Deploy (Bereitstellen) als YOUR_API_KEY, niemals einen geheimen ck_- oder mk_-Schlüssel. Behalten Sie die Provider-ID und den Skript-Host aus Ihrem eigenen Deploy-Snippet bei. Platzieren Sie das Callback-Setup vor diesem Skript-Tag:
<script>
let registeredChatbot;
window.aichatbotCallback = {
onSessionActivated() {
var chatbot = window.aichatbotApi.getChatbotApi('YOUR_API_KEY');
if (registeredChatbot === chatbot) return;
registeredChatbot = chatbot;
chatbot.addCallback('onUserMessage', function(message) {
console.log('User said:', message);
});
chatbot.addCallback('onChatbotMessage', function(message) {
console.log('Bot replied:', message);
});
// Send only when your application intends to start a real chat:
// chatbot.sendMessage('Hello from the API!');
}
};
</script>
<script>window.aichatbotApiKey="YOUR_API_KEY";</script>
<script src="https://script.chatlab.com/aichatbot.js" defer></script>
onSessionActivated wird ausgelöst, sobald eine Sitzung verfügbar ist, einschließlich wiederhergestellter Sitzungen. Abhängig von den Bereitstellungs- und Startbildschirm-Einstellungen ist dies nicht zwingend der erste Klick zum Öffnen des Widgets. Das Ereignis kann erneut ausgelöst werden; registrieren Sie Callbacks einmal pro API-Objekt, um doppelte Handler zu vermeiden. Innerhalb dieses Callbacks existiert das API-Objekt garantiert und die Sitzung ist aktiv, sodass Sie sendMessage() sowie updateClientContext() sicher aufrufen und Ereignis-Callbacks registrieren können.
Wichtig: Rufen Sie window.aichatbotApi.getChatbotApi() nicht direkt in Ihrem Seitenskript auf, ohne zu warten - das API-Objekt existiert erst, wenn das ChatLab-Skript vollständig geladen und initialisiert wurde.
Tipp: Wenn Sie das Widget nur steuern möchten (einblenden/ausblenden/umschalten) und keine aktive Sitzung benötigen, hören Sie stattdessen auf das DOM-Ereignis aichatbotReady:
window.addEventListener('aichatbotReady', function(e) {
var chatbot = window.aichatbotApi.getChatbotApi(e.detail.apiKey);
chatbot.showChat();
});
Methoden
| Methode | Beschreibung |
|---|---|
showChat() |
Chat-Widget öffnen |
hideChat() |
Chat-Widget schließen |
toggleChat() |
Sichtbarkeit des Widgets umschalten |
sendMessage(text) |
Nachricht programmatisch senden |
updateClientContext(data) |
Nutzerkontext aktualisieren (siehe unten) |
setLanguage(code) |
Widget auf eine Sprache umstellen (nur bei mehrsprachigen Bots, siehe unten) |
getLanguage() |
Sprache zurückgeben, die das Widget aktuell verwendet |
getAvailableLanguages() |
Liste der Sprachen zurückgeben, die der Bot anbietet |
addCallback(name, fn) |
Ereignis-Callback registrieren |
Hinweis: sendMessage und updateClientContext erfordern eine aktive Sitzung. Verwenden Sie das in Erste Schritte gezeigte Initialisierungsmuster onSessionActivated.
Callbacks
Registrieren Sie Event-Callbacks innerhalb Ihres onSessionActivated-Handlers (siehe Erste Schritte):
chatbot.addCallback('onUserMessage', function(message) {
console.log('User said:', message);
});
chatbot.addCallback('onChatbotMessage', function(message) {
console.log('Bot replied:', message);
});
chatbot.addCallback('onProductClick', function(productIdOrLink) {
console.log('Product clicked:', productIdOrLink);
});
chatbot.addCallback('onLeadCollectionFormSubmit', function(data) {
console.log('Lead captured:', data.email);
});
chatbot.addCallback('onContactFormSubmit', function(data) {
console.log('Support request from:', data.email);
});
chatbot.addCallback('onLiveChatFormSubmit', function(data) {
console.log('Live chat started:', data.name);
});
Verfügbare Callbacks
| Callback | Daten | Beschreibung |
|---|---|---|
onSessionActivated |
- | Chat-Sitzung ist bereit |
onUserMessage |
string |
Benutzer hat eine Nachricht gesendet |
onChatbotMessage |
string |
Bot hat mit einer Nachricht geantwortet |
onProductClick |
Produkt-/Link-Payload aus der gerenderten Karte | Benutzer hat auf einen Produktlink geklickt; prüfen Sie den Payload für Ihren Kartentyp |
onLeadCollectionFormSubmit |
{email, phone, name} |
Lead-Erfassungsformular wurde abgeschickt |
onContactFormSubmit |
{email, message} |
Kontakt-/Support-Formular wurde abgeschickt |
onLiveChatFormSubmit |
{name, email} |
Live-Chat-Formular wurde abgeschickt, kein Nachweis über den Beitritt eines Mitarbeiters |
onCustomFormSubmit |
{formId, values} |
Benutzerdefiniertes Formular wurde abgeschickt; Daten hochgeladener Dateien sind in diesem Callback nicht enthalten |
Formular-Callbacks melden das Absenden im Browser, keine bestätigte Speicherung oder erfolgreiche Zustellung. Verwenden Sie für eine im Backend bestätigte Verarbeitung Webhooks. Callback-Payloads können personenbezogene Daten enthalten; leiten Sie diese nicht in ihrer Gesamtheit an Analysedienste oder öffentliche Protokolle weiter.
Veraltete Event-Callbacks
Das window.aichatbotCallback-Objekt unterstützt auch onUserMessage und onChatbotMessage als direkte Eigenschaften. Verwenden Sie addCallback() für modulare Listener, ohne das globale Objekt zu ersetzen:
window.aichatbotCallback = {
onUserMessage(message) { ... },
onChatbotMessage(message) { ... }
};
Hinweis: window.aichatbotCallback.onSessionActivated ist nicht veraltet - es ist der empfohlene Bootstrap-Mechanismus zur Initialisierung der Chat API (siehe Erste Schritte).
Iframe-Bereitstellung
Wenn Sie die Iframe-Bereitstellung verwenden, nutzen Sie postMessage für die Kommunikation mit dem Chatbot:
Befehle senden
// Give the ChatLab iframe from Deploy this unique id.
const chatbotIframe = document.getElementById('chatlab-frame');
const chatbotOrigin = new URL(chatbotIframe.src, window.location.href).origin;
// Run show/hide/language commands after the iframe loads.
// Wait for onSessionActivated before sendMessage or updateClientContext.
// Show chat
chatbotIframe.contentWindow.postMessage({
type: 'aichatbot',
action: 'showChat'
}, chatbotOrigin);
// Hide chat
chatbotIframe.contentWindow.postMessage({
type: 'aichatbot',
action: 'hideChat'
}, chatbotOrigin);
// Send message
chatbotIframe.contentWindow.postMessage({
type: 'aichatbot',
action: 'sendMessage',
payload: 'Hello!'
}, chatbotOrigin);
// Update client context
chatbotIframe.contentWindow.postMessage({
type: 'aichatbot',
action: 'updateClientContext',
payload: { clientId: 'user123', clientName: 'John' }
}, chatbotOrigin);
// Switch language (multi-language bots only)
chatbotIframe.contentWindow.postMessage({
type: 'aichatbot',
action: 'setLanguage',
payload: 'de'
}, chatbotOrigin);
Callbacks empfangen
window.addEventListener('message', (event) => {
if (event.origin !== chatbotOrigin || event.source !== chatbotIframe.contentWindow) return;
if (event.data?.type !== 'aichatbot-callback') return;
const { apiKey, callback, data } = event.data;
switch (callback) {
case 'onSessionActivated':
console.log('Session ready');
break;
case 'onUserMessage':
console.log('User said:', data);
break;
case 'onChatbotMessage':
console.log('Bot replied:', data);
break;
case 'onProductClick':
console.log('Product clicked:', data);
break;
case 'onLeadCollectionFormSubmit':
console.log('Lead captured:', data);
break;
case 'onContactFormSubmit':
console.log('Contact form:', data);
break;
case 'onLiveChatFormSubmit':
console.log('Live chat started:', data);
break;
}
});
Client-Kontext aktualisieren
Mit der Funktion updateClientContext können Sie den Client-Kontext während einer aktiven Sitzung aktualisieren:
chatbot.updateClientContext({
clientId: "unique-client-identifier", // Required
clientName: "John", // Optional
clientEmail: "john@doe.com", // Optional
clientPhone: "555-444-333", // Optional
clientSecurityToken: "your-token", // Optional
clientHostContext: { // Optional
param1: "value1",
param2: "value2"
}
});
Parameter:
- clientId (erforderlich): Eindeutige Kennung für den Client
- clientName, clientEmail, clientPhone (optional): Client-Details, die in Unterhaltungen angezeigt werden
- clientSecurityToken (optional): Ein Token, das als Kontext für Ihre benutzerdefinierte Integration weitergeleitet wird. Ihre eigene API muss dessen Authentizität, Gültigkeitsdauer und Autorisierung validieren.
- clientHostContext (optional): Zusätzliche Kontextparameter, die in benutzerdefinierten API-Aktionen zugänglich sind
Vom Browser bereitgestellte IDs und Kontextdaten sind kein Identitätsnachweis. Hinterlegen Sie keine kontoweiten Geheimnisse im JavaScript der Seite und gewähren Sie Zugriff niemals allein deshalb, weil eine übergebene clientId oder E-Mail-Adresse mit einem Datensatz übereinstimmt.
Verwendung in API-Aufrufen:
Kontextattribute können in API-Funktionsaufrufen verwendet werden, indem der API-Parameter als Typ "Context" konfiguriert wird:
clientName,clientEmail,clientPhone,clientSecurityToken- Benutzerdefinierte Host-Kontextparameter mit dem Präfix
client, z. B.clientparam1,clientparam2
Sprache
Diese Methoden funktionieren nur bei mehrsprachigen Chatbots. Bei einem einsprachigen Bot verfügt das Widget über keine Sprachebene zum Umschalten, sodass setLanguage() nichts bewirkt und getAvailableLanguages() lediglich die eigene Sprache des Bots zurückgibt. Aktivieren Sie die Mehrsprachigkeit zuerst unter Einstellungen > Sprachen (Settings > Languages) - siehe Mehrsprachige Chatbots.
Verwenden Sie setLanguage(), wenn Ihre Seite in mehreren Sprachen verfügbar ist und der Chat in der Sprache geöffnet werden soll, die der Besucher gerade liest, anstatt in der Sprache, auf die sein Browser zufällig eingestellt ist:
window.addEventListener('aichatbotReady', function(e) {
var chatbot = window.aichatbotApi.getChatbotApi(e.detail.apiKey);
chatbot.setLanguage(document.documentElement.lang); // e.g. "de"
console.log(chatbot.getLanguage()); // "de"
console.log(chatbot.getAvailableLanguages()); // ["en", "de", "fr", ...]
});
Sie können die Seitensprache auch deklarieren, bevor das Skript geladen wird, wodurch ein kurzes Aufblitzen der falschen Sprache vermieden wird:
<script>window.aichatbotLanguage = "de";</script>
Welche Sprache Vorrang hat. Das Widget bestimmt die Sprache in dieser Reihenfolge:
- Eine Sprache, die der Besucher selbst im Sprachmenü des Widgets ausgewählt hat.
- Die Seitensprache aus
setLanguage()oderwindow.aichatbotLanguage. - Die Browsersprache des Besuchers.
- Die Basissprache des Chatbots.
Die eigene Auswahl eines Besuchers wird für spätere Besuche gespeichert, gilt jedoch nicht mehr, sobald sich die Seitensprache ändert - Ihr Sprachumschalter hat somit immer Vorrang vor einer veralteten Auswahl. Codes entsprechen ISO 639-1 (en, de, pl); bei einem regionalen Code wie de-AT wird auf de zurückgegriffen. Eine Sprache, die der Bot nicht anbietet, wird ignoriert.
Das Umschalten der Sprache beendet weder die Unterhaltung noch löscht es den Chatverlauf.