Hur får jag åtkomst till ChatLab Chat API?

Ställ in window.aichatbotCallback.onSessionActivated innan skripttaggen laddas. Inuti den callbacken använder du window.aichatbotApi.getChatbotApi(apiKey) för att hämta API-objektet och registrera händelselyssnare.

Vilka callbacks finns tillgängliga i Chat API?

Tillgängliga callbacks inkluderar onSessionActivated, onUserMessage, onChatbotMessage, onProductClick, onLeadCollectionFormSubmit, onContactFormSubmit och onLiveChatFormSubmit.

Hur använder jag Chat API med iframe-distribution?

Använd postMessage för att skicka kommandon till iframen och addEventListener('message') för att ta emot callbacks. Kommandon inkluderar showChat, hideChat, sendMessage och updateClientContext.

Kan jag ändra chat widget-språket från min sida?

Ja, på flerspråkiga chattbotar. Anropa setLanguage('de') på API-objektet, eller ställ in window.aichatbotLanguage innan skriptet laddas. På enspråkiga botar gör metoden ingenting.

Vad används updateClientContext till?

Med updateClientContext kan du skicka användarinformation (ID, namn, e-postadress, telefon) och anpassade parametrar till chattbotten under en aktiv session, vilket kan användas i API-funktionsanrop.

Chat API - ChatLab Hjälpcenter

Översikt över Chat API

Widget-API:et låter dig styra chattwidgeten programmatiskt och registrera callbacks för chatthändelser.

Letar du efter REST-API:et? 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:et 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 omedelbart när din sida läses in - skriptet måste läsas in och initieras först. Du måste använda window.aichatbotCallback.onSessionActivated som startmekanism för att säkert komma åt API:et.

Använd den publika widgetnyckeln från Deploy (Driftsättning) som YOUR_API_KEY, aldrig en hemlig ck_- eller mk_-nyckel. Behåll leverantörs-ID och skripthost från din egen Deploy-kodsnutt. Placera konfigurationen av callback före den skripttaggen:

<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 utlöses när en session blir tillgänglig, inklusive återställda sessioner. Beroende på inställningar för driftsättning och välkomstskärm är detta inte nödvändigtvis det första klicket som öppnar widgeten. Den kan utlösas igen; registrera callbacks en gång per API-objekt för att undvika dubblerade hanterare. Inuti den är API-objektet garanterat att existera och sessionen är aktiv, så du kan säkert anropa sendMessage(), updateClientContext() och registrera callbacks för händelser.

Viktigt: Anropa inte window.aichatbotApi.getChatbotApi() direkt i ditt sidskript utan att vänta - API-objektet existerar 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, lyssna på DOM-händelsen aichatbotReady istället:

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)`	Växla widgeten till ett språk (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 en händelse-callback

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

Callbacks

Registrera händelse-callbacks 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 callbacks

Callback	Data	Beskrivning
`onSessionActivated`	-	Chattsessionen är redo
`onUserMessage`	`string`	Användaren skickade ett meddelande
`onChatbotMessage`	`string`	Boten svarade med ett meddelande
`onProductClick`	Produkt-/länkpayload från det renderade kortet	Användaren klickade på en produktlänk; granska nyttolasten för din korttyp
`onLeadCollectionFormSubmit`	`{email, phone, name}`	Formulär för insamling av leads skickades in
`onContactFormSubmit`	`{email, message}`	Kontakt-/supportformulär skickades in
`onLiveChatFormSubmit`	`{name, email}`	Livechatt-formulär skickades in, inte bevis på att en operatör har anslutit
`onCustomFormSubmit`	`{formId, values}`	Anpassat formulär skickades in; uppladdad fildata ingår inte i denna callback

Formulär-callbacks rapporterar en inskickning på webbläsarsidan, inte bekräftad lagring eller framgångsrik leverans. För backend-bekräftad bearbetning, använd Webhooks. Callback-nyttolaster kan innehålla personuppgifter; vidarebefordra dem inte rakt av till analysverktyg eller publika loggar.

Äldre händelse-callbacks

Objektet window.aichatbotCallback stöder även onUserMessage och onChatbotMessage som direkta egenskaper. Använd addCallback() för modulära lyssnare utan att ersätta det globala objektet:

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

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

Iframe-driftsättning

När du använder iframe-driftsättning, använd postMessage för att kommunicera med chattbotten:

Skicka kommandon

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

Ta emot callbacks

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

Uppdatera klientkontext

Funktionen updateClientContext gör det möjligt att uppdatera klientkontext 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"
    }
});

Parametrar:

clientId (obligatorisk): Unik identifierare för klienten
clientName, clientEmail, clientPhone (valfria): Klientuppgifter som visas i konversationer
clientSecurityToken (valfri): En token som vidarebefordras som kontext för din anpassade integration. Ditt eget API måste validera dess äkthet, giltighetstid och auktorisering.
clientHostContext (valfri): Ytterligare kontextparametrar tillgängliga i anpassade API-åtgärder

Identifierare och kontext från webbläsaren är inte identitetsbevis. Lägg inte kontoomfattande hemligheter i sidans JavaScript, och bevilja inte åtkomst enbart för att ett angivet clientId eller en e-postadress matchar en post.

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, så setLanguage() gör ingenting och getAvailableLanguages() returnerar bara botens eget språk. Aktivera stöd för flera språk under 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, istället för det deras webbläsare råkar vara inställd på:

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 också deklarera sidans språk innan skriptet läses in, vilket förhindrar en kort blinkning av fel språk:

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

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

Ett språk som besökaren själv har valt i widgetens egen språkmeny.
Sidans språk, från setLanguage() eller window.aichatbotLanguage.
Besökarens webbläsarspråk.
Chattbotens basspråk.

En besökares eget val sparas för senare 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 på de. Ett språk som boten inte erbjuder ignoreras.

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

Chat API