Helpcentrum
Chat API

Chat API

Laatst bijgewerkt:

Chat API - overzicht

Deze functie is alleen beschikbaar in geselecteerde abonnementen. Hiermee kun je de chatwidget programmatisch beheren en callbacks registreren voor chatgebeurtenissen.

Zoek je de REST API? Dit artikel behandelt de JavaScript widget-API in de browser (window.aichatbotApi) voor pagina's waarop de ChatLab-widget is ingesloten. Zie de artikelen over de Bot Talk API en Management API voor de server-to-server REST API om vanuit je backend gesprekken te voeren met bots 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.

Plaats dit vóór de ChatLab-scripttag:

<script>
window.aichatbotCallback = {
    onSessionActivated() {
        var chatbot = window.aichatbotApi.getChatbotApi('YOUR_API_KEY');

        chatbot.addCallback('onUserMessage', function(message) {
            console.log('User said:', message);
        });

        chatbot.addCallback('onChatbotMessage', function(message) {
            console.log('Bot replied:', message);
        });

        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 zodra de chatsessie is aangemaakt (oftewel wanneer de gebruiker de widget opent). Binnen deze functie bestaat het API-object gegarandeerd en is de sessie actief, zodat je veilig sendMessage() en updateClientContext() kunt aanroepen en callbacks voor gebeurtenissen kunt registreren.

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

Tip: Als je de widget alleen wilt bedienen (tonen/verbergen/wisselen) 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 Omschrijving
showChat() Open de chatwidget
hideChat() Sluit de chatwidget
toggleChat() Zichtbaarheid van de widget wisselen
sendMessage(text) Verstuur een bericht programmatisch
updateClientContext(data) Werk de gebruikerscontext bij (zie hieronder)
setLanguage(code) Schakel de widget over naar een taal (alleen meertalige bots, zie hieronder)
getLanguage() Retourneer de taal die de widget momenteel gebruikt
getAvailableLanguages() Retourneer de lijst met talen die de bot aanbiedt
addCallback(name, fn) Registreer een event-callback

Opmerking: sendMessage en updateClientContext vereisen een actieve sessie. Gebruik het initialisatiepatroon onSessionActivated zoals getoond onder 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 Omschrijving
onSessionActivated - Chatsessie is gereed
onUserMessage string Gebruiker heeft een bericht verstuurd
onChatbotMessage string Bot heeft geantwoord met een bericht
onProductClick string (product-ID of link) Gebruiker heeft op een product geklikt (vereist ingeschakelde Offer Cards)
onLeadCollectionFormSubmit {email, phone, name} Formulier voor leadverzameling is verzonden
onContactFormSubmit {email, message} Contact-/supportformulier is verzonden
onLiveChatFormSubmit {name, email} Live Chat-formulier is verzonden

Verouderde event-callbacks (afgeraden)

Het object window.aichatbotCallback ondersteunt ook onUserMessage en onChatbotMessage als directe eigenschappen. Dit formaat is verouderd - gebruik in plaats daarvan addCallback() voor toegang tot alle callbacktypes:

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

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

Iframe-implementatie

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

Commando's verzenden

const chatbotIframe = document.querySelector('iframe');

// Chat tonen
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'showChat'
}, '*');

// Chat verbergen
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'hideChat'
}, '*');

// Bericht versturen
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'sendMessage',
    payload: 'Hello!'
}, '*');

// Clientcontext bijwerken
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'updateClientContext',
    payload: { clientId: 'user123', clientName: 'John' }
}, '*');

// Taal wisselen (alleen meertalige bots)
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'setLanguage',
    payload: 'de'
}, '*');

Callbacks ontvangen

window.addEventListener('message', (event) => {
    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 context van de client tijdens een actieve sessie bijwerken:

chatbot.updateClientContext({
    clientId: "unique-client-identifier",     // Verplicht
    clientName: "John",                       // Optioneel
    clientEmail: "john@doe.com",              // Optioneel
    clientPhone: "555-444-333",               // Optioneel
    clientSecurityToken: "your-token",        // Optioneel
    clientHostContext: {                      // Optioneel
        param1: "value1",
        param2: "value2"
    }
});

Parameters:

  • clientId (verplicht): Unieke id voor de client
  • clientName, clientEmail, clientPhone (optioneel): Gegevens van de client die in gesprekken worden weergegeven
  • clientSecurityToken (optioneel): Beveiligingstoken voor API-autorisatie
  • clientHostContext (optioneel): Extra contextparameters die toegankelijk zijn in aangepaste API-acties

Gebruik in API-aanroepen:

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

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

Taal

Deze methoden werken alleen bij meertalige chatbots. Bij een eentalige bot heeft de widget geen taallaag om te wisselen, 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);  // bijv. "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 taalkiezer altijd voorrang op een verouderde keuze. Codes zijn volgens ISO 639-1 (en, de, pl); een regionale code zoals de-AT valt terug 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