Ohjekeskus
Chat API

Chat API

Viimeksi päivitetty:

Chat API:n yleiskatsaus

Tämä ominaisuus on käytettävissä vain valituissa tilauksissa. Sen avulla voit ohjata chat-widgetiä ohjelmallisesti ja rekisteröidä takaisinkutsuja (callback) chatin tapahtumille.

Etsitkö REST API:a? Tässä artikkelissa käsitellään selaimessa toimivaa JavaScript-widget-API:a (window.aichatbotApi) sivuille, joihin ChatLab-widget on upotettu. Jos etsit palvelimien välistä REST API:a keskustellaksesi bottien kanssa taustajärjestelmästäsi tai hallitaksesi botteja ohjelmallisesti, katso artikkelit Bot Talk API ja Management API.

Aloittaminen

Chatbotin API ei ole käytettävissä välittömästi sivun latautuessa - komentosarjan on ensin latauduttava ja alustuttava. Sinun on käytettävä window.aichatbotCallback.onSessionActivated -toimintoa käynnistysmekanismina, jotta voit käyttää API:a turvallisesti.

Sijoita tämä ennen ChatLab-skriptitagia:

<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 laukeaa, kun chat-istunto luodaan (eli kun käyttäjä avaa widgetin). Sen sisällä API-objektin olemassaolo on taattu ja istunto on aktiivinen, joten voit turvallisesti kutsua metodeja sendMessage(), updateClientContext() ja rekisteröidä tapahtumien takaisinkutsuja.

Tärkeää: Älä kutsu window.aichatbotApi.getChatbotApi() -metodia suoraan sivusi koodissa odottamatta - API-objektia ei ole olemassa ennen kuin ChatLab-skripti on latautunut ja alustettu.

Vinkki: Jos sinun tarvitsee vain ohjata widgetiä (näytä/piilota/vaihda näkyvyyttä) etkä tarvitse aktiivista istuntoa, kuuntele sen sijaan aichatbotReady DOM -tapahtumaa:

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

Metodit

Metodi Kuvaus
showChat() Avaa chat-widget
hideChat() Sulje chat-widget
toggleChat() Vaihda widgetin näkyvyyttä
sendMessage(text) Lähetä viesti ohjelmallisesti
updateClientContext(data) Päivitä käyttäjän konteksti (katso alla)
setLanguage(code) Vaihda widget tietylle kielelle (vain monikieliset botit, katso alla)
getLanguage() Palauta widgetin tällä hetkellä käyttämä kieli
getAvailableLanguages() Palauta luettelo botin tarjoamista kielistä
addCallback(name, fn) Rekisteröi tapahtuman takaisinkutsu

Huomautus: sendMessage ja updateClientContext vaativat aktiivisen istunnon. Käytä Aloittaminen-osiossa esitettyä onSessionActivated-alustusmallia.

Takaisinkutsut (Callbacks)

Rekisteröi tapahtumien takaisinkutsut onSessionActivated-käsittelijäsi sisällä (katso Aloittaminen):

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

Käytettävissä olevat takaisinkutsut

Takaisinkutsu Tiedot Kuvaus
onSessionActivated - Chat-istunto on valmis
onUserMessage string Käyttäjä lähetti viestin
onChatbotMessage string Botti vastasi viestillä
onProductClick string (tuotetunniste tai linkki) Käyttäjä klikkasi tuotetta (vaatii, että Offer Cards on käytössä)
onLeadCollectionFormSubmit {email, phone, name} Liidien keräyslomake lähetettiin
onContactFormSubmit {email, message} Yhteydenotto-/tukipyyntölomake lähetettiin
onLiveChatFormSubmit {name, email} Live Chat -lomake lähetettiin

Vanhat tapahtumien takaisinkutsut (Vanhentunut)

window.aichatbotCallback -objekti tukee myös funktioita onUserMessage ja onChatbotMessage suorina ominaisuuksina. Tämä muoto on vanhentunut - käytä sen sijaan metodia addCallback(), jotta pääset käsiksi kaikkiin takaisinkutsutyyppeihin:

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

Huomautus: window.aichatbotCallback.onSessionActivated ei ole vanhentunut - se on suositeltu käynnistysmekanismi Chat API:n alustamiseen (katso Aloittaminen).

Iframe-asennus

Kun käytät iframe-asennusta, käytä postMessage-toimintoa viestiäksesi chatbotin kanssa:

Komentojen lähettäminen

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

Takaisinkutsujen vastaanottaminen

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

Asiakaskontekstin päivittäminen (Update Client Context)

Funktio updateClientContext mahdollistaa asiakaskontekstin päivittämisen aktiivisen istunnon aikana:

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

Parametrit:

  • clientId (pakollinen): Asiakkaan yksilöllinen tunniste
  • clientName, clientEmail, clientPhone (valinnainen): Keskusteluissa näytettävät asiakkaan tiedot
  • clientSecurityToken (valinnainen): Turvatunniste (security token) API-valtuutusta varten
  • clientHostContext (valinnainen): Lisäkontekstiparametrit, jotka ovat käytettävissä mukautetuissa API-toiminnoissa

Käyttö API-kutsuissa:

Kontekstiattribuutteja voidaan käyttää API-funktiokutsuissa määrittämällä API-parametrin tyypiksi "Context":

  • clientName, clientEmail, clientPhone, clientSecurityToken
  • Mukautetut isäntäkontekstin (host context) parametrit etuliitteellä client, esim. clientparam1, clientparam2

Kieli

Nämä metodit toimivat vain monikielisissä chatboteissa. Yksikielisessä botissa widgetillä ei ole vaihdettavaa kielikerrosta, joten setLanguage() ei tee mitään ja getAvailableLanguages() palauttaa vain botin oman kielen. Ota monikielisyystuki ensin käyttöön kohdassa Settings > Languages (Asetukset > Kielet) - katso Monikieliset chatbotit.

Käytä metodia setLanguage(), kun sivustosi on saatavilla useilla kielillä ja haluat chatin avautuvan sillä kielellä, jota vierailija parhaillaan lukee, sen sijaan että käytettäisiin kieltä, joksi hänen selaimensa sattuu olemaan asetettu:

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

Voit myös määrittää sivun kielen ennen skriptin latautumista, mikä estää väärän kielen lyhyen välähdyksen:

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

Mikä kieli valitaan ensisijaisesti. Widget määrittää kielen seuraavassa järjestyksessä:

  1. Kieli, jonka vierailija on itse valinnut widgetin omasta kielivalikosta.
  2. Sivun kieli, joka on saatu metodista setLanguage() tai arvosta window.aichatbotLanguage.
  3. Vierailijan selaimen kieli.
  4. Chatbotin peruskieli.

Vierailijan oma valinta muistetaan myöhempiä käyntejä varten, mutta se lakkaa olemasta voimassa heti, kun sivun kieli vaihtuu - joten kielivalintasi sivulla syrjäyttää aina vanhentuneen valinnan. Koodit ovat ISO 639-1 -muotoa (en, de, pl); alueellinen koodi, kuten de-AT, palautuu kieleen de. Kieli, jota botti ei tarjoa, jätetään huomiotta.

Kielen vaihtaminen ei lopeta keskustelua eikä tyhjennä keskusteluhistoriaa.

Aiheeseen liittyvät artikkelit

Hae kaikista artikkeleistaKysy agentilta