Hjælpecenter
Chat API

Chat API

Sidst opdateret:

Oversigt over Chat API

Widget-API'et giver dig mulighed for at styre chat-widgetten programmatisk og registrere callbacks for chat-hæ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 indlejret. For server-til-server REST API'et, der bruges til at føre samtaler med botter fra din backend eller administrere botter programmatisk, se 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 at få sikker adgang til API'et.

Brug den offentlige widget-nøgle fra Deploy (Udrulning) som YOUR_API_KEY, aldrig en hemmelig ck_- eller mk_-nøgle. Behold udbyder-id'et og script-værten fra dit eget Deploy-kodestykke. Placer opsætningen af callback før dette script-tag:

<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 udløses, når en session bliver tilgængelig, herunder gendannede sessioner. Afhængigt af indstillingerne for udrulning og velkomstskærm er dette ikke nødvendigvis det første klik, der åbner widgetten. Den kan udløses igen; registrer callbacks én gang pr. API-objekt for at undgå duplikerede handlere. Indeni 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 (vis/skjul/slå til eller fra) og ikke behøver en aktiv session, kan du lytte efter DOM-hændelsen aichatbotReady i stedet:

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å widget-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, botten tilbyder
addCallback(name, fn) Registrer et hændelses-callback

Bemærk: sendMessage og updateClientContext kræver en aktiv session. Brug initialiseringsmønsteret med onSessionActivated, der er vist under 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 - Chatsession er klar
onUserMessage string Brugeren sendte en besked
onChatbotMessage string Botten svarede med en besked
onProductClick Produkt-/link-payload fra det viste kort Brugeren klikkede på et produktlink; inspicer payloaden for din korttype
onLeadCollectionFormSubmit {email, phone, name} Formular til lead-indsamling blev indsendt
onContactFormSubmit {email, message} Kontakt-/supportformular blev indsendt
onLiveChatFormSubmit {name, email} Live chat-formular blev indsendt, ikke bevis for, at en operatør deltog
onCustomFormSubmit {formId, values} Brugerdefineret formular blev indsendt; uploadede fildata er ikke inkluderet i dette callback

Formular-callbacks rapporterer en indsendelse på browsersiden, ikke bekræftet lagring eller vellykket levering. Til backend-bekræftet behandling skal du bruge Webhooks. Callback-payloads kan indeholde personoplysninger; videresend dem ikke ufiltreret til analyseværktøjer eller offentlige logs.

Ældre hændelses-callbacks

Objektet window.aichatbotCallback understøtter også onUserMessage og onChatbotMessage som direkte egenskaber. Brug addCallback() til modulære lyttere uden at erstatte det globale objekt:

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-udrulning

Når du bruger iframe-udrulning, skal du bruge postMessage til at kommunikere med chatbommen:

Afsendelse af kommandoer

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

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

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 id for klienten
  • clientName, clientEmail, clientPhone (valgfrit): Klientoplysninger, der vises i samtaler
  • clientSecurityToken (valgfrit): En token, der videresendes som kontekst til din brugerdefinerede integration. Dit eget API skal validere dets ægthed, udløb og autorisation.
  • clientHostContext (valgfrit): Yderligere kontekstparametre, der er tilgængelige i brugerdefinerede API-handlinger

Id'er og kontekst leveret af browseren er ikke bevis på identitet. Placer ikke hemmeligheder for hele kontoen i sidens JavaScript, og giv ikke adgang udelukkende på baggrund af, at et angivet clientId eller en e-mail matcher en post.

Anvendelse i API-kald:

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

  • clientName, clientEmail, clientPhone, clientSecurityToken
  • Brugerdefinerede værtsparametre med præfikset client, f.eks. clientparam1, clientparam2

Sprog

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

Brug setLanguage(), når 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, 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 der vinder. Widgetten bestemmer sproget i denne rækkefølge:

  1. Et sprog, den besøgende selv har valgt i widgettens egen sprogmenu.
  2. Sidens sprog, fra setLanguage() eller window.aichatbotLanguage.
  3. Den besøgendes browsersprog.
  4. Chatbottens standardsprog.

En besøgendes eget valg huskes til senere besøg, men det ophører med at gælde, når sidens sprog ændres - så din sprogvælger vinder altid over et forældet valg. Koder er ISO 639-1 (en, de, pl); en regional kode som de-AT falder tilbage på de. Et sprog, botten ikke tilbyder, ignoreres.

Sprogskift afslutter ikke samtalen og rydder ikke chathistorikken.

Relaterede artikler

Søg i alle artiklerSpørg agenten