Chat API

Oversikt over Chat API

Denne funksjonen er bare tilgjengelig i utvalgte abonnementer. Den lar deg styre chat-widgeten programmatisk og registrere callbacks for chat-hendelser.

Leter du etter REST API-et? Denne artikkelen dekker JavaScript-widget-API-et i nettleseren (window.aichatbotApi) for sider der ChatLab-widgeten er bygd inn. For server-til-server-REST-API-et som brukes til å kommunisere med boter fra backend eller administrere boter programmatisk, se artiklene om Bot Talk API og Management API.

Komme i gang

Chatbot-API-et er ikke tilgjengelig umiddelbart når siden din lastes inn - skriptet må lastes og initialiseres først. Du må bruke window.aichatbotCallback.onSessionActivated som oppstartsmekanisme for å få trygg tilgang til API-et.

Plasser dette før ChatLab-skripttaggen:

<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 utløses når chat-økten opprettes (dvs. når brukeren åpner widgeten). Inne i denne er det garantert at API-objektet eksisterer og at økten er aktiv, slik at du trygt kan kalle sendMessage(), updateClientContext() og registrere hendelses-callbacks.

Viktig: Ikke kall window.aichatbotApi.getChatbotApi() direkte i sideskriptet ditt uten å vente - API-objektet eksisterer ikke før ChatLab-skriptet er ferdig lastet og initialisert.

Tips: Hvis du bare trenger å styre widgeten (vis/skjul/veksle) og ikke trenger en aktiv økt, kan du lytte til DOM-hendelsen aichatbotReady i stedet:

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

Metoder

Metode	Beskrivelse
showChat()	Åpne chat-widgeten
hideChat()	Lukke chat-widgeten
toggleChat()	Veksle widgetens synlighet
sendMessage(text)	Sende en melding programmatisk
updateClientContext(data)	Oppdatere brukerkontekst (se nedenfor)
setLanguage(code)	Bytte språk i widgeten (kun flerspråklige boter, se nedenfor)
getLanguage()	Returnere språket widgeten bruker for øyeblikket
getAvailableLanguages()	Returnere listen over språk boten tilbyr
addCallback(name, fn)	Registrere en hendelses-callback

Merk: sendMessage og updateClientContext krever en aktiv økt. Bruk initialiseringsmønsteret onSessionActivated som er vist under Komme i gang.

Callbacks

Registrer hendelses-callbacks inne i funksjonen for onSessionActivated (se Komme i gang):

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

Tilgjengelige callbacks

Callback	Data	Beskrivelse
onSessionActivated	-	Chat-økten er klar
onUserMessage	string	Brukeren sendte en melding
onChatbotMessage	string	Boten svarte med en melding
onProductClick	string (produkt-ID eller lenke)	Brukeren klikket på et produkt (krever at Offer Cards er aktivert)
onLeadCollectionFormSubmit	{email, phone, name}	Skjema for lead-innsamling ble sendt inn
onContactFormSubmit	{email, message}	Kontakt-/brukerstøtteskjema ble sendt inn
onLiveChatFormSubmit	{name, email}	Skjema for Live Chat ble sendt inn

Eldre hendelses-callbacks (avviklet)

Objektet window.aichatbotCallback støtter også onUserMessage og onChatbotMessage som direkte egenskaper. Dette formatet er avviklet - bruk addCallback() i stedet for å få tilgang til alle callback-typer:

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

Merk: window.aichatbotCallback.onSessionActivated er ikke avviklet - det er den anbefalte oppstartsmekanismen for å initialisere Chat API (se Komme i gang).

Iframe-distribusjon

Når du bruker iframe-distribusjon, bruker du postMessage til å kommunisere med chatboten:

Sende kommandoer

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

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

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

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

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

// Switch language (multi-language bots only)
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'setLanguage',
    payload: 'de'
}, '*');

Motta callbacks

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

Oppdatere klientkontekst

Funksjonen updateClientContext gjør det mulig å oppdatere klientkonteksten under en aktiv økt:

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

Parametere:

• clientId (påkrevd): Unik identifikator for klienten
• clientName, clientEmail, clientPhone (valgfritt): Klientopplysninger som vises i samtaler
• clientSecurityToken (valgfritt): Sikkerhetstoken for API-autorisasjon
• clientHostContext (valgfritt): Ekstra kontekstparametere som er tilgjengelige i egendefinerte API-handlinger

Bruk i API-kall:

Kontekstattributter kan brukes i API-funksjonskall ved å konfigurere API-parameteren som typen "Context":

• clientName, clientEmail, clientPhone, clientSecurityToken
• Egendefinerte vertskontekst-parametere med prefikset client, f.eks. clientparam1, clientparam2

Språk

Disse metodene fungerer kun på flerspråklige chatboter. På en enkeltspråklig bot har widgeten ikke noe språklag å bytte til, så setLanguage() gjør ingenting og getAvailableLanguages() returnerer kun botens eget språk. Slå på flerspråklig støtte i Settings > Languages (Innstillinger > Språk) først - se Flerspråklige chatboter.

Bruk setLanguage() når siden din finnes på flere språk og du vil at chatten skal åpnes på språket den besøkende leser, i stedet for språket nettleseren deres tilfeldigvis er satt til:

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

Du kan også angi sidespråket før skriptet lastes inn, noe som forhindrer et kort glimt av feil språk:

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

Hvilket språk som vinner. Widgeten avgjør språket i denne rekkefølgen:

1. Et språk den besøkende valgte selv i widgetens egen språkmeny.
2. Sidespråket, fra setLanguage() eller window.aichatbotLanguage.
3. Språket i den besøkendes nettleser.
4. Chatbotens basisspråk.

Den besøkendes eget valg huskes for senere besøk, men slutter å gjelde så snart sidespråket endres - dermed vil språkvelgeren din alltid overstyre et gammelt valg. Kodene er ISO 639-1 (en, de, pl); en regional kode som de-AT faller tilbake til de. Et språk boten ikke tilbyr, blir ignorert.

Å bytte språk avslutter ikke samtalen og sletter ikke loggen.

Relaterte artikler

• Flerspråklige chatboter
• Legge til chatbot på nettstedet ditt
• Bot Talk API
• Management API