Abikeskus
Chat API

Chat API

Viimati uuendatud:

Chat API ülevaade

Vidina API võimaldab teil vestlusvidinat programmiliselt juhtida ning registreerida tagasikutseid (callbacks) vestlussündmustele.

Otsite REST API-t? See artikkel käsitleb brauserisisest JavaScripti vidina API-t (window.aichatbotApi) lehtedel, kuhu on lisatud ChatLabi vidin. Serveritevahelise REST API kohta, mida kasutatakse robotitega suhtlemiseks teie taustsüsteemist või robotite programmilisest haldamisest, lugege artikleid Bot Talk API ja Management API.

Alustamine

Chatboti API ei ole kohe lehe laadimisel saadaval - skript peab esmalt laadima ja lähtestuma. API-le turvaliseks ligipääsemiseks peate alglaadimismehhanismina kasutama funktsiooni window.aichatbotCallback.onSessionActivated.

Kasutage väärtusena YOUR_API_KEY avalikku vidina võtit jaotisest Deploy (Paigalda), mitte kunagi salajast ck_- või mk_-võtit. Säilitage oma Deploy-koodijupist pärit teenusepakkuja ID ja skripti host. Lisage tagasikutse seadistus enne seda skriptisilti:

<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 käivitub siis, kui seanss muutub kättesaadavaks, sealhulgas taastatud seansside puhul. Sõltuvalt paigaldusest ja tervituskuva seadetest ei pruugi see tingimata toimuda vidina esmakordsel avamisel klikiga. See võib käivituda uuesti; registreerige tagasikutsed ühe API-objekti kohta üks kord, et vältida dubleerivaid töötlejaid. Selle sees on API-objekti olemasolu tagatud ja seanss aktiivne, seega saate turvaliselt kutsuda välja funktsioone sendMessage(), updateClientContext() ning registreerida sündmuste tagasikutseid.

Tähtis: Ärge kutsuge oma lehe skriptis funktsiooni window.aichatbotApi.getChatbotApi() välja otse ilma ootamata - API-objekti ei eksisteeri enne, kui ChatLabi skript on laadinud ja lähtestunud.

Nõuanne: Kui teil on vaja vaid vidinat juhtida (näidata/peita/lülitada) ja te ei vaja aktiivset seanssi, kuulake selle asemel DOM-i sündmust aichatbotReady:

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

Meetodid

Meetod Kirjeldus
showChat() Ava vestlusvidin
hideChat() Sule vestlusvidin
toggleChat() Lülita vidina nähtavust
sendMessage(text) Saada sõnum programmiliselt
updateClientContext(data) Uuenda kasutaja konteksti (vt allpool)
setLanguage(code) Lülita vidin teisele keelele (ainult mitmekeelsete robotite puhul, vt allpool)
getLanguage() Tagasta keel, mida vidin parasjagu kasutab
getAvailableLanguages() Tagasta roboti pakutavate keelte loend
addCallback(name, fn) Registreeri sündmuse tagasikutse

Märkus: Funktsioonid sendMessage ja updateClientContext vajavad aktiivset seanssi. Kasutage jaotises „Alustamine“ näidatud onSessionActivated lähtestamismustrit.

Tagasikutsed

Registreerige sündmuste tagasikutsed oma onSessionActivated töötlejas (vt jaotist „Alustamine“):

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

Saadaval olevad tagasikutsed

Tagasikutse Andmed Kirjeldus
onSessionActivated - Vestlusseanss on valmis
onUserMessage string Kasutaja saatis sõnumi
onChatbotMessage string Robot vastas sõnumiga
onProductClick Toote/lingi andmed kuvatud kaardilt Kasutaja klõpsas tootelinki; kontrollige oma kaarditüübi andmeid
onLeadCollectionFormSubmit {email, phone, name} Müügivihjete kogumise vorm esitati
onContactFormSubmit {email, message} Kontakti-/tugivorm esitati
onLiveChatFormSubmit {name, email} Reaalajas vestluse vorm esitati; see ei kinnita operaatori liitumist
onCustomFormSubmit {formId, values} Kohandatud vorm esitati; üleslaaditud failiandmed ei sisaldu selles tagasikutses

Vormide tagasikutsed teatavad brauseripoolsest esitamisest, mitte kinnitatud salvestamisest ega edukast kohaletoimetamisest. Taustsüsteemis kinnitatud töötlemiseks kasutage lahendust Webhooks. Tagasikutsete andmed võivad sisaldada isikuandmeid; ärge edastage neid tervikuna analüütikale ega avalikesse logidesse.

Pärandatud sündmuste tagasikutsed

Objekt window.aichatbotCallback toetab otseomadustena ka funktsioone onUserMessage ja onChatbotMessage. Modulaarsete kuulajate jaoks kasutage funktsiooni addCallback(), ilma et asendaksite globaalset objekti:

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

Märkus: window.aichatbotCallback.onSessionActivated ei ole aegunud - see on soovitatav alglaadimismehhanism Chat API lähtestamiseks (vt jaotist „Alustamine“).

Iframe-paigaldus

Kui kasutate iframe-paigaldust, kasutage chatbotiga suhtlemiseks meetodit postMessage:

Käskude saatmine

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

Tagasikutsete vastuvõtmine

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

Kliendi konteksti uuendamine

Funktsioon updateClientContext võimaldab aktiivse seansi ajal kliendi konteksti uuendada:

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

Parameetrid:

  • clientId (kohustuslik): Kliendi kordumatu identifikaator
  • clientName, clientEmail, clientPhone (valikuline): Kliendi andmed, mida kuvatakse vestlustes
  • clientSecurityToken (valikuline): Turbemärk (token), mis edastatakse kontekstina teie kohandatud integratsioonile. Teie enda API peab kontrollima selle ehtsust, aegumist ja volitusi.
  • clientHostContext (valikuline): Täiendavad kontekstiparameetrid, mis on ligipääsetavad kohandatud API toimingutes

Brauseri esitatud ID-d ja kontekst ei ole isikutõenduseks. Ärge lisage lehe JavaScripti kogu kontot hõlmavaid saladusi ning ärge andke juurdepääsu ainult seetõttu, et esitatud clientId või e-posti aadress kattub kirje andmetega.

Kasutamine API kutsetes:

Konteksti atribuute saab kasutada API funktsioonikutsetes, konfigureerides API parameetri tüübiks „Context“:

  • clientName, clientEmail, clientPhone, clientSecurityToken
  • Eesliitega client kohandatud hostikonteksti parameetrid, nt clientparam1, clientparam2

Keel

Need meetodid töötavad ainult mitmekeelsete chatbotide puhul. Ühekeelse roboti puhul puudub vidinal keelekiht, mida lülitada, seega setLanguage() ei tee midagi ja getAvailableLanguages() tagastab vaid roboti enda keele. Lülitage esmalt mitmekeelsuse tugi sisse menüüs Settings > Languages (Seaded > Keeled) - vaadake juhendit Mitmekeelsed chatbotid.

Kasutage meetodit setLanguage(), kui teie leht on saadaval mitmes keeles ja te soovite, et vestlus avaneks keeles, mida külastaja parajasti loeb, mitte keeles, millele tema brauser juhtub olema seadistatud:

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

Samuti saate lehe keele määrata enne skripti laadimist, mis väldib vale keele lühiajalist kuvamist:

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

Milline keel jääb peale. Vidin määrab keele järgmises järjekorras:

  1. Keel, mille külastaja valis ise vidina enda keelemenüüst.
  2. Lehe keel meetodist setLanguage() või muutujast window.aichatbotLanguage.
  3. Külastaja brauseri keel.
  4. Chatboti põhikeel.

Külastaja enda valik jäetakse hilisemate külastuste jaoks meelde, kuid see lakkab kehtimast kohe, kui lehe keel muutub - seega jääb teie lehe keelevalija alati peale varasema aegunud valiku ees. Koodid on standardi ISO 639-1 järgi (en, de, pl); piirkondlik kood nagu de-AT taandub koodile de. Keelt, mida robot ei paku, ignoreeritakse.

Keele vahetamine ei lõpeta vestlust ega kustuta vestluse ajalugu.

Seotud artiklid

Otsige kõigist artiklitestKüsige agendilt