Ohjekeskus
Chat API

Chat API

Viimeksi päivitetty:

Chat API - yleiskatsaus

Widget API:n avulla voit ohjata chat-widgetiä ohjelmallisesti ja rekisteröidä takaisinkutsuja (callbacks) chatin tapahtumille.

Etsitkö REST APIa? Tässä artikkelissa käsitellään selaimessa toimivaa JavaScript-widget-rajapintaa (window.aichatbotApi) sivuille, joihin ChatLab-widget on upotettu. Jos etsit palvelimien välistä REST APIa, jolla keskustellaan bottien kanssa taustajärjestelmästäsi tai hallitaan botteja ohjelmallisesti, tutustu artikkeleihin Bot Talk API ja Management API.

Aloittaminen

Chatbot API ei ole käytettävissä välittömästi sivun latautuessa - skriptin on ensin latauduttava ja alustuttava. Sinun on käytettävä window.aichatbotCallback.onSessionActivated -mekanismia päästäksesi turvallisesti käsiksi API:in.

Käytä julkista widget-avainta kohdasta Deploy (Julkaise) arvona YOUR_API_KEY, älä koskaan salaista ck_- tai mk_-avainta. Pidä palveluntarjoajan tunniste (provider ID) ja skriptin isäntäosoite omasta Deploy-koodinpätkästäsi. Sijoita takaisinkutsun määritys ennen kyseistä script-tagia:

<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 laukeaa, kun istunto tulee saataville, mukaan lukien palautetut istunnot. Julkaisu- ja aloitusnäyttöasetuksista riippuen tämä ei välttämättä ole ensimmäinen widgetin avaava klikkaus. Se voi laueta uudelleen; rekisteröi takaisinkutsut kerran API-objektia kohden välttääksesi päällekkäisiä käsittelijöitä. 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 metodia window.aichatbotApi.getChatbotApi() suoraan sivusi skriptissä 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äkonteksti (katso alla)
setLanguage(code) Vaihda widgetin kieli (vain monikieliset botit, katso alla)
getLanguage() Palauta kieli, jota widget parhaillaan käyttää
getAvailableLanguages() Palauta luettelo kielistä, joita botti tarjoaa
addCallback(name, fn) Rekisteröi tapahtuman takaisinkutsu

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

Takaisinkutsut (Callbacks)

Rekisteröi tapahtumien takaisinkutsut onSessionActivated-käsittelijän 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 Data Kuvaus
onSessionActivated - Chat-istunto on valmis
onUserMessage string Käyttäjä lähetti viestin
onChatbotMessage string Botti vastasi viestillä
onProductClick Tuotteen/linkin hyötykuorma renderöidystä kortista Käyttäjä klikkasi tuotelinkkiä; tarkista korttityyppisi hyötykuorma
onLeadCollectionFormSubmit {email, phone, name} Liidien keruulomake lähetettiin
onContactFormSubmit {email, message} Yhteydenotto-/tukilomake lähetettiin
onLiveChatFormSubmit {name, email} Live chat -lomake lähetettiin, ei vahvistus asiakaspalvelijan liittymisestä
onCustomFormSubmit {formId, values} Mukautettu lomake lähetettiin; ladatun tiedoston tietoja ei sisällytetä tähän takaisinkutsuun

Lomakkeiden takaisinkutsut ilmoittavat selaimen puolella tapahtuneesta lähetyksestä, eivät vahvistetusta tallentumisesta tai onnistuneesta toimituksesta. Jos tarvitset taustajärjestelmän vahvistamaa käsittelyä, käytä Webhooks -toimintoa. Takaisinkutsujen hyötykuormat voivat sisältää henkilötietoja; älä välitä niitä sellaisenaan analytiikkaan tai julkisiin lokeihin.

Aiemmat tapahtumien takaisinkutsut (Legacy)

Objekti window.aichatbotCallback tukee myös funktioita onUserMessage ja onChatbotMessage suorina ominaisuuksina. Käytä metodia addCallback() modulaarisiin kuuntelijoihin korvaamatta globaalia objektia:

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

Huomautus: window.aichatbotCallback.onSessionActivated ei ole vanhentunut - se on suositeltu alustusmekanismi Chat API:n käyttöönottoon (katso Aloittaminen).

Iframe-julkaisu

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

Komentojen lähettäminen

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

Takaisinkutsujen vastaanottaminen

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

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): Token, joka välitetään kontekstina mukautetulle integraatiollesi. Oman API:si on vahvistettava sen aitous, vanheneminen ja valtuutus.
  • clientHostContext (valinnainen): Lisäkontekstiparametrit, jotka ovat käytettävissä mukautetuissa API-toiminnoissa

Selaimen toimittamat tunnisteet ja kontekstitiedot eivät ole todiste henkilöllisyydestä. Älä sijoita koko tilin laajuisia salaisuuksia sivun JavaScriptiin, äläkä myönnä pääsyä vain siksi, että annettu clientId tai sähköpostiosoite vastaa tietuetta.

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 parametrit, joiden etuliitteenä on 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ä, joka sattuu olemaan valittuna hänen selaimessaan:

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. 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 muuttujasta window.aichatbotLanguage.
  3. Vierailijan selaimen kieli.
  4. Chatbotin peruskieli.

Vierailijan oma valinta muistetaan myöhempiä käyntejä varten, mutta se lakkaa pätemästä heti, kun sivun kieli vaihtuu - joten sivustosi kielivalitsin ohittaa aina vanhentuneen valinnan. Koodit ovat ISO 639-1 -muodossa (en, de, pl); alueellinen koodi, kuten de-AT, palautuu muotoon de. Kieli, jota botti ei tarjoa, ohitetaan.

Kielen vaihtaminen ei päätä keskustelua eikä tyhjennä keskusteluhistoriaa.

Aiheeseen liittyvät artikkelit

Hae kaikista artikkeleistaKysy agentilta