Hjelpesenter
Chat API

Chat API

Sist oppdatert:

Oversikt over Chat API

Widget-API-et 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 å føre samtaler med boter fra baksystemet ditt 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 - skriptet må lastes inn og initialiseres først. Du må bruke window.aichatbotCallback.onSessionActivated som oppstartsmekanisme for å få trygg tilgang til API-et.

Bruk den offentlige widget-nøkkelen fra Deploy (Publiser) som YOUR_API_KEY, aldri en hemmelig ck_- eller mk_-nøkkel. Behold leverandør-ID-en og skriptverten fra din egen Deploy-kodebit. Plasser callback-oppsettet før den aktuelle script-taggen:

<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 økt blir tilgjengelig, inkludert gjenopprettede økter. Avhengig av innstillinger for publisering og velkomstskjerm er dette ikke nødvendigvis det første klikket som åpner widgeten. Den kan utløses igjen; registrer callbacks én gang per API-objekt for å unngå dupliserte håndterere. Inne i denne funksjonen er API-objektet garantert å eksistere og ø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 lastet inn og initialisert.

Tips: Hvis du bare trenger å styre widgeten (vise/skjule/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 widgetens språk (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 med onSessionActivated som vist i Komme i gang.

Callbacks

Registrer hendelses-callbacks inne i din onSessionActivated-håndterer (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 Produkt-/lenkedata fra det viste kortet Brukeren klikket på en produktlenke; undersøk nyttelasten for din korttype
onLeadCollectionFormSubmit {email, phone, name} Skjema for lead-innsamling ble sendt inn
onContactFormSubmit {email, message} Kontakt-/brukerstøtteskjema ble sendt inn
onLiveChatFormSubmit {name, email} Live chat-skjema ble sendt inn, ikke et bevis på at en operatør ble med
onCustomFormSubmit {formId, values} Egendefinert skjema ble sendt inn; opplastede fildata er ikke inkludert i denne callbacken

Skjema-callbacks rapporterer en innsending på nettlesersiden, ikke bekreftet lagring eller vellykket levering. For behandling bekreftet av baksystemet, bruk Webhooks. Callback-nyttelaster kan inneholde personopplysninger; ikke videresend dem ukritisk til analyseverktøy eller offentlige logger.

Foreldede hendelses-callbacks

Objektet window.aichatbotCallback støtter også onUserMessage og onChatbotMessage som direkte egenskaper. Bruk addCallback() for modulære lyttere uten å erstatte det globale objektet:

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

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

Iframe-distribusjon

Ved bruk av iframe-distribusjon bruker du postMessage til å kommunisere med chatbotten:

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

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

Oppdatere klientkontekst

Funksjonen updateClientContext lar deg oppdatere klientkontekst 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): Klientdetaljer som vises i samtaler
  • clientSecurityToken (valgfritt): Et token videresendt som kontekst for din egendefinerte integrasjon. Ditt eget API må validere ektheten, utløpstiden og autorisasjonen for dette.
  • clientHostContext (valgfritt): Ekstra kontekstparametere som er tilgjengelige i egendefinerte API-handlinger

ID-er og kontekst levert av nettleseren er ikke et bevis på identitet. Ikke legg hemmeligheter for hele kontoen i nettsidens JavaScript, og ikke gi tilgang utelukkende fordi en oppgitt clientId eller e-postadresse samsvarer med en oppføring.

Bruk i API-kall:

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

  • clientName, clientEmail, clientPhone, clientSecurityToken
  • Egendefinerte vertskontekstparametere med prefikset client, f.eks. clientparam1, clientparam2

Språk

Disse metodene fungerer kun på flerspråklige chatboter. På en enspråklig bot har widgeten ikke noe språklag å bytte, så setLanguage() gjør ingenting og getAvailableLanguages() returnerer bare 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 åpne seg 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å deklarere 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 til senere besøk, men det slutter å gjelde så snart sidespråket endres - dermed vil språkvelgeren din alltid overstyre et utdatert 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 transkripsjonen.

Relaterte artikler

Søk i alle artiklerSpør agenten