Hjälpcenter
Chat API

Chat API

Senast uppdaterad:

Översikt över Chat API

Den här funktionen är endast tillgänglig i utvalda planer. Den gör att du kan styra chattwidgeten programmatiskt och registrera återanrop (callbacks) för chatthändelser.

Letar du efter REST API? Den här artikeln täcker JavaScript-widget-API:et i webbläsaren (window.aichatbotApi) för sidor där ChatLab-widgeten är inbäddad. För server-till-server REST API som används för att samtala med botar från din backend eller hantera botar programmatiskt, se artiklarna om Bot Talk API och Management API.

Komma igång

Chattbotens API är inte tillgängligt direkt när din sida läses in - skriptet måste först laddas och initieras. Du måste använda window.aichatbotCallback.onSessionActivated som startmekanism för att säkert komma åt API:et.

Placera detta före ChatLabs skript-tagg:

<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 chattsessionen skapas (dvs. när användaren öppnar widgeten). Inuti denna garanteras att API-objektet finns och att sessionen är aktiv, så att du säkert kan anropa sendMessage(), updateClientContext() och registrera återanrop för händelser.

Viktigt: Anropa inte window.aichatbotApi.getChatbotApi() direkt i ditt sidskript utan att vänta - API-objektet finns inte förrän ChatLab-skriptet har lästs in och initierats.

Tips: Om du bara behöver styra widgeten (visa/dölja/växla) och inte behöver en aktiv session kan du i stället lyssna på DOM-händelsen aichatbotReady:

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

Metoder

Metod Beskrivning
showChat() Öppna chattwidgeten
hideChat() Stäng chattwidgeten
toggleChat() Växla widgetens synlighet
sendMessage(text) Skicka ett meddelande programmatiskt
updateClientContext(data) Uppdatera användarkontext (se nedan)
setLanguage(code) Byt språk i widgeten (endast flerspråkiga botar, se nedan)
getLanguage() Returnera språket som widgeten för närvarande använder
getAvailableLanguages() Returnera listan över språk som boten erbjuder
addCallback(name, fn) Registrera ett återanrop för en händelse

Observera: sendMessage och updateClientContext kräver en aktiv session. Använd initieringsmönstret onSessionActivated som visas i avsnittet Komma igång.

Återanrop

Registrera återanrop för händelser inuti din onSessionActivated-hanterare (se Komma igång):

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

Tillgängliga återanrop

Återanrop Data Beskrivning
onSessionActivated - Chattsessionen är redo
onUserMessage string Användaren skickade ett meddelande
onChatbotMessage string Boten svarade med ett meddelande
onProductClick string (produkt-ID eller länk) Användaren klickade på en produkt (kräver att Offer Cards är aktiverat)
onLeadCollectionFormSubmit {email, phone, name} Formuläret för lead-insamling skickades
onContactFormSubmit {email, message} Kontakt-/supportformuläret skickades
onLiveChatFormSubmit {name, email} Live Chat-formuläret skickades

Äldre återanrop för händelser (föråldrade)

Objektet window.aichatbotCallback stöder även onUserMessage och onChatbotMessage som direkta egenskaper. Detta format är föråldrat - använd addCallback() i stället för att få tillgång till alla typer av återanrop:

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

Observera: window.aichatbotCallback.onSessionActivated är inte föråldrat - det är den rekommenderade startmekanismen för att initiera Chat API (se Komma igång).

Iframe-implementering

När du använder iframe-implementering använder du postMessage för att kommunicera med chattbotten:

Skicka kommandon

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

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

// Dölj chatt
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'hideChat'
}, '*');

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

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

// Byt språk (endast flerspråkiga botar)
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'setLanguage',
    payload: 'de'
}, '*');

Ta emot återanrop

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

Uppdatera klientkontext

Funktionen updateClientContext gör det möjligt att uppdatera klientkontexten under en aktiv session:

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

Parametrar:

  • clientId (obligatoriskt): Unik identifierare för klienten
  • clientName, clientEmail, clientPhone (valfritt): Klientuppgifter som visas i konversationer
  • clientSecurityToken (valfritt): Säkerhetstoken för API-auktorisering
  • clientHostContext (valfritt): Ytterligare kontextparametrar som är tillgängliga i anpassade API-åtgärder

Användning i API-anrop:

Kontextattribut kan användas i API-funktionsanrop genom att konfigurera API-parametern som typen "Context":

  • clientName, clientEmail, clientPhone, clientSecurityToken
  • Anpassade värdkontextparametrar med prefixet client, t.ex. clientparam1, clientparam2

Språk

Dessa metoder fungerar endast på flerspråkiga chattbotar. På en enspråkig bot har widgeten inget språklager att växla mellan, så setLanguage() gör ingenting och getAvailableLanguages() returnerar bara botens eget språk. Aktivera flerspråksstöd i Settings > Languages (Inställningar > Språk) först - se Flerspråkiga chattbotar.

Använd setLanguage() när din sida finns på flera språk och du vill att chatten ska öppnas på det språk besökaren läser, i stället för det som webbläsaren råkar vara inställd på:

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

    chatbot.setLanguage(document.documentElement.lang);  // t.ex. "de"

    console.log(chatbot.getLanguage());            // "de"
    console.log(chatbot.getAvailableLanguages());   // ["en", "de", "fr", ...]
});

Du kan också ange sidans språk innan skriptet läses in, vilket förhindrar att fel språk blinkar till snabbt:

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

Vilket språk som gäller. Widgeten bestämmer språket i följande ordning:

  1. Ett språk som besökaren själv har valt i widgetens egen språkmeny.
  2. Sidans språk, från setLanguage() eller window.aichatbotLanguage.
  3. Språket i besökarens webbläsare.
  4. Chattbotens grundspråk.

Besökarens eget val sparas för framtida besök, men det slutar gälla så snart sidans språk ändras - så din språkväljare vinner alltid över ett inaktuellt val. Koderna är ISO 639-1 (en, de, pl); en regional kod som de-AT faller tillbaka till de. Ett språk som boten inte erbjuder ignoreras.

Att byta språk avslutar inte konversationen och rensar inte transkriptionen.

Relaterade artiklar

Sök bland alla artiklarFråga agenten