Helpcentrum
Chat API

Chat API

Laatst bijgewerkt:

Chat API-overzicht

Met de widget-API kun je de chat-widget programmatisch bedienen en callbacks registreren voor chatgebeurtenissen.

Op zoek naar de REST API? Dit artikel behandelt de JavaScript-widget-API in de browser (window.aichatbotApi) voor pagina's waarop de ChatLab-widget is ingesloten. Raadpleeg de artikelen over de Bot Talk API en de Management API voor de server-to-server REST API die wordt gebruikt om vanuit je backend met bots te communiceren of bots programmatisch te beheren.

Aan de slag

De chatbot-API is niet direct beschikbaar zodra je pagina laadt - het script moet eerst laden en initialiseren. Je moet window.aichatbotCallback.onSessionActivated gebruiken als bootstrap-mechanisme om veilig toegang te krijgen tot de API.

Gebruik de openbare widgetcode uit Deploy (Implementeren) als YOUR_API_KEY, nooit een geheime ck_- of mk_-sleutel. Behoud de provider-ID en script-host uit je eigen Deploy-fragment. Plaats de configuratie van de callback vóór die scripttag:

<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 wordt geactiveerd wanneer een sessie beschikbaar komt, inclusief herstelde sessies. Afhankelijk van de implementatie- en welkomstscherminstellingen is dit niet noodzakelijk de eerste klik om de widget te openen. De gebeurtenis kan opnieuw worden geactiveerd; registreer callbacks eenmaal per API-object om dubbele handlers te voorkomen. Binnen deze functie bestaat het API-object gegarandeerd en is de sessie actief, zodat je veilig sendMessage() en updateClientContext() kunt aanroepen en event-callbacks kunt registreren.

Belangrijk: Roep window.aichatbotApi.getChatbotApi() niet direct aan in het script van je pagina zonder te wachten - het API-object bestaat pas nadat het script van ChatLab is geladen en geïnitialiseerd.

Tip: Als je de widget alleen wilt bedienen (weergeven/verbergen/in- of uitschakelen) en geen actieve sessie nodig hebt, luister dan naar het DOM-event aichatbotReady:

window.addEventListener('aichatbotReady', function(e) {
    var chatbot = window.aichatbotApi.getChatbotApi(e.detail.apiKey);
    chatbot.showChat();
});

Methoden

Methode Beschrijving
showChat() Open de chat-widget
hideChat() Sluit de chat-widget
toggleChat() Schakel zichtbaarheid van de widget in of uit
sendMessage(text) Verstuur programmatisch een bericht
updateClientContext(data) Werk de gebruikerscontext bij (zie hieronder)
setLanguage(code) Schakel de widget over naar een taal (alleen meertalige bots, zie hieronder)
getLanguage() Geeft de taal terug die de widget momenteel gebruikt
getAvailableLanguages() Geeft de lijst met talen terug die de bot aanbiedt
addCallback(name, fn) Registreer een event-callback

Opmerking: Voor sendMessage en updateClientContext is een actieve sessie vereist. Gebruik het initialisatiepatroon onSessionActivated zoals getoond in Aan de slag.

Callbacks

Registreer event-callbacks binnen je onSessionActivated-handler (zie Aan de slag):

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);
});

Beschikbare callbacks

Callback Gegevens Beschrijving
onSessionActivated - Chatsessie is gereed
onUserMessage string Gebruiker heeft een bericht verstuurd
onChatbotMessage string Bot heeft geantwoord met een bericht
onProductClick Product-/linkpayload van de weergegeven kaart Gebruiker heeft op een productlink geklikt; inspecteer de payload voor jouw kaarttype
onLeadCollectionFormSubmit {email, phone, name} Leadverzamelformulier is verzonden
onContactFormSubmit {email, message} Contact-/ondersteuningsformulier is verzonden
onLiveChatFormSubmit {name, email} Live chat-formulier is verzonden; dit is geen bewijs dat een medewerker heeft deelgenomen
onCustomFormSubmit {formId, values} Aangepast formulier is verzonden; geüploade bestandsgegevens zijn niet inbegrepen in deze callback

Formulier-callbacks melden een verzending aan de browserzijde, geen bevestigde opslag of succesvolle aflevering. Gebruik voor verwerking met backend-bevestiging Webhooks. Callback-payloads kunnen persoonsgegevens bevatten; stuur ze niet integraal door naar analytics of openbare logs.

Verouderde event-callbacks

Het object window.aichatbotCallback ondersteunt ook onUserMessage en onChatbotMessage als directe eigenschappen. Gebruik addCallback() voor modulaire listeners zonder het globale object te overschrijven:

window.aichatbotCallback = {
    onUserMessage(message) { ... },
    onChatbotMessage(message) { ... }
};

Opmerking: window.aichatbotCallback.onSessionActivated is niet verouderd - het is het aanbevolen bootstrap-mechanisme voor het initialiseren van de Chat API (zie Aan de slag).

Iframe-implementatie

Wanneer je gebruikmaakt van een iframe-implementatie, gebruik je postMessage om met de chatbot te communiceren:

Opdrachten verzenden

// 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 ontvangen

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;
    }
});

Clientcontext bijwerken

Met de functie updateClientContext kun je de clientcontext tijdens een actieve sessie bijwerken:

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"
    }
});

Parameters:

  • clientId (verplicht): Unieke identificatie voor de client
  • clientName, clientEmail, clientPhone (optioneel): Clientgegevens die worden weergegeven in gesprekken
  • clientSecurityToken (optioneel): Een token dat als context wordt doorgestuurd voor je aangepaste integratie. Je eigen API moet de authenticiteit, geldigheid en autorisatie hiervan verifiëren.
  • clientHostContext (optioneel): Extra contextparameters die toegankelijk zijn in aangepaste API-acties

Door de browser verstrekte ID's en context zijn geen identiteitsbewijs. Plaats geen accountbrede geheimen in de JavaScript van de pagina en verleen geen toegang louter omdat een verstrekte clientId of e-mailadres overeenkomt met een record.

Gebruik in API-aanroepen:

Contextkenmerken kunnen worden gebruikt in API-functieaanroepen door de API-parameter in te stellen op het type "Context":

  • clientName, clientEmail, clientPhone, clientSecurityToken
  • Aangepaste hostcontextparameters voorafgegaan door client, bijv. clientparam1, clientparam2

Taal

Deze methoden werken alleen op meertalige chatbots. Bij een eentalige bot heeft de widget geen taallaag om tussen te schakelen, waardoor setLanguage() niets doet en getAvailableLanguages() alleen de eigen taal van de bot retourneert. Schakel eerst ondersteuning voor meerdere talen in via Settings > Languages (Instellingen > Talen) - zie Meertalige chatbots.

Gebruik setLanguage() wanneer je pagina in meerdere talen bestaat en je wilt dat de chat opent in de taal die de bezoeker leest, in plaats van de taal waarop diens browser toevallig is ingesteld:

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", ...]
});

Je kunt de paginataal ook opgeven voordat het script laadt, wat een korte flits van de verkeerde taal voorkomt:

<script>window.aichatbotLanguage = "de";</script>

Welke taal voorrang krijgt. De widget bepaalt de taal in deze volgorde:

  1. Een taal die de bezoeker zelf heeft gekozen in het taalmenu van de widget.
  2. De paginataal, afkomstig uit setLanguage() of window.aichatbotLanguage.
  3. De browsertaal van de bezoeker.
  4. De basistaal van de chatbot.

De eigen keuze van een bezoeker wordt onthouden voor latere bezoeken, maar vervalt zodra de paginataal verandert - zo heeft jouw taalkeuze altijd voorrang op een verouderde selectie. Codes volgen ISO 639-1 (en, de, pl); bij een regionale code zoals de-AT wordt teruggevallen op de. Een taal die de bot niet aanbiedt, wordt genegeerd.

Het wisselen van taal beëindigt het gesprek niet en wist het transcript niet.

Gerelateerde artikelen

Doorzoek alle artikelenVraag het de agent