Hvordan får jeg adgang til ChatLab Chat API?

Angiv window.aichatbotCallback.onSessionActivated, før script-tagget indlæses. Inde i dette callback skal du bruge window.aichatbotApi.getChatbotApi(apiKey) til at hente API-objektet og registrere event listeners.

Hvilke callbacks er tilgængelige i Chat API?

Tilgængelige callbacks omfatter onSessionActivated, onUserMessage, onChatbotMessage, onProductClick, onLeadCollectionFormSubmit, onContactFormSubmit og onLiveChatFormSubmit.

Hvordan bruger jeg Chat API med en iframe-implementering?

Brug postMessage til at sende kommandoer til iframen, og brug addEventListener('message') til at modtage callbacks. Kommandoerne omfatter showChat, hideChat, sendMessage og updateClientContext.

Kan jeg ændre chat-widgettens sprog fra min side?

Ja, på flersprogede chatbots. Kald setLanguage('de') på API-objektet, eller angiv window.aichatbotLanguage, før scriptet indlæses. På enkeltsprogede bots gør metoden ingenting.

Hvad bruges updateClientContext til?

updateClientContext giver dig mulighed for at videregive brugeroplysninger (ID, navn, e-mail, telefon) og brugerdefinerede parametre til chatbotted under en aktiv session, hvilket kan bruges i API-funktionskald.

Chat API - ChatLab Hjælpecenter

Oversigt over Chat API

Denne funktion er kun tilgængelig i udvalgte abonnementer. Den giver dig mulighed for at styre chat-widgetten programmatisk og registrere callbacks for chathændelser.

Leder du efter REST API'et? Denne artikel dækker JavaScript-widget-API'et i browseren (window.aichatbotApi) til sider, hvor ChatLab-widgetten er integreret. For server-til-server-REST-API'et, der bruges til at føre samtaler med botter fra dit backend-system eller administrere botter programmatisk, henvises der til artiklerne om Bot Talk API og Management API.

Kom godt i gang

Chatbot-API'et er ikke tilgængeligt med det samme, når din side indlæses - scriptet skal indlæses og initialiseres først. Du skal bruge window.aichatbotCallback.onSessionActivated som bootstrap-mekanisme for sikkert at tilgå API'et.

Placer dette før ChatLab-script-tagget:

<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 udløses, når chatsessionen oprettes (dvs. når brugeren åbner widgetten). Inde i den er API-objektet garanteret at eksistere, og sessionen er aktiv, så du sikkert kan kalde sendMessage(), updateClientContext() og registrere hændelses-callbacks.

Vigtigt: Kald ikke window.aichatbotApi.getChatbotApi() direkte i dit sidescript uden at vente - API-objektet eksisterer ikke, før ChatLab-scriptet er indlæst og initialiseret.

Tip: Hvis du kun har brug for at styre widgetten (vise/skjule/slå til eller fra) og ikke behøver en aktiv session, kan du i stedet lytte efter DOM-hændelsen aichatbotReady:

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

Metoder

Metode	Beskrivelse
`showChat()`	Åbn chat-widgetten
`hideChat()`	Luk chat-widgetten
`toggleChat()`	Slå widgettens synlighed til/fra
`sendMessage(text)`	Send en besked programmatisk
`updateClientContext(data)`	Opdater brugerkontekst (se nedenfor)
`setLanguage(code)`	Skift widgetten til et sprog (kun flersprogede botter, se nedenfor)
`getLanguage()`	Returner det sprog, widgetten aktuelt bruger
`getAvailableLanguages()`	Returner listen over sprog, som botten tilbyder
`addCallback(name, fn)`	Registrer et hændelses-callback

Bemærk: sendMessage og updateClientContext kræver en aktiv session. Brug initialiseringsmønsteret onSessionActivated, der er vist i afsnittet Kom godt i gang.

Callbacks

Registrer hændelses-callbacks inde i din onSessionActivated-handler (se Kom godt 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);
});

Tilgængelige callbacks

Callback	Data	Beskrivelse
`onSessionActivated`	-	Chatsessionen er klar
`onUserMessage`	`string`	Brugeren sendte en besked
`onChatbotMessage`	`string`	Botten svarede med en besked
`onProductClick`	`string` (produkt-id eller link)	Brugeren klikkede på et produkt (kræver, at Offer Cards er aktiveret)
`onLeadCollectionFormSubmit`	`{email, phone, name}`	Formular til indsamling af leads blev indsendt
`onContactFormSubmit`	`{email, message}`	Kontakt-/supportformular blev indsendt
`onLiveChatFormSubmit`	`{name, email}`	Live chat-formular blev indsendt

Forældede hændelses-callbacks (Deprecated)

window.aichatbotCallback-objektet understøtter også onUserMessage og onChatbotMessage som direkte egenskaber. Dette format er forældet - brug addCallback() i stedet for at få adgang til alle callback-typer:

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

Bemærk: window.aichatbotCallback.onSessionActivated er ikke forældet - det er den anbefalede bootstrap-mekanisme til initialisering af Chat API (se Kom godt i gang).

Iframe-implementering

Ved brug af iframe-implementering skal du bruge postMessage til at kommunikere med chatbotten:

Afsendelse af 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'
}, '*');

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

Opdatering af klientkontekst

Funktionen updateClientContext giver mulighed for at opdatere klientkonteksten under en aktiv session:

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

Parametre:

clientId (påkrævet): Unikt identifikationsmærke for klienten
clientName, clientEmail, clientPhone (valgfrit): Klientoplysninger, der vises i samtaler
clientSecurityToken (valgfrit): Sikkerhedstoken til API-godkendelse
clientHostContext (valgfrit): Yderligere kontekstparametre, der er tilgængelige i brugerdefinerede API-handlinger

Anvendelse i API-kald:

Kontekstattributter kan bruges i API-funktionskald ved at konfigurere API-parameteren som typen "Context":

clientName, clientEmail, clientPhone, clientSecurityToken
Brugerdefinerede vært-kontekstparametre med præfikset client, f.eks. clientparam1, clientparam2

Sprog

Disse metoder fungerer kun på flersprogede chatbotter. På en enkeltsproget bot har widgetten ikke noget sproglag at skifte imellem, så setLanguage() gør ingenting, og getAvailableLanguages() returnerer kun bottens eget sprog. Slå først understøttelse af flere sprog til under Settings > Languages (Indstillinger > Sprog) - se Flersprogede chatbotter.

Brug setLanguage(), hvis din side findes på flere sprog, og du vil have chatten til at åbne på det sprog, den besøgende læser, i stedet for det sprog, deres browser tilfældigvis er indstillet 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å angive sidens sprog, før scriptet indlæses, hvilket forhindrer et kort glimt af det forkerte sprog:

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

Hvilket sprog vinder. Widgetten finder sproget i denne rækkefølge:

Et sprog, som den besøgende selv har valgt i widgettens egen sprogmenu.
Sidens sprog, fra setLanguage() eller window.aichatbotLanguage.
Den besøgendes browsersprog.
Chatbottens grundsprog.

Den besøgendes eget valg huskes til fremtidige besøg, men det tilsidesættes, så snart sidens sprog ændres - din sidesprogvælger vinder altså altid over et forældet valg. Koderne følger ISO 639-1 (en, de, pl); en regional kode som de-AT falder tilbage til de. Et sprog, som botten ikke tilbyder, ignoreres.

Et sprogskift afslutter ikke samtalen og rydder ikke samtalehistorikken.

Chat API