Abikeskus
Chat API

Chat API

Viimati uuendatud:

Chat API ülevaade

See funktsioon on saadaval ainult valitud pakettides. See võimaldab teil vestlusvidinat programmiliselt juhtida ja registreerida tagasikutseid (callbacks) vestlussündmuste jaoks.

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

Alustamine

Chatboti API ei ole kohe pärast lehe laadimist saadaval - skript peab esmalt laadima ja initsialiseeruma. API turvaliseks kasutamiseks peate alglaadimismehhanismina kasutama funktsiooni window.aichatbotCallback.onSessionActivated.

Asetage see enne ChatLabi skriptisilti:

<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 käivitub vestlusseansi loomisel (st kui kasutaja avab vidina). 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 funktsiooni window.aichatbotApi.getChatbotApi() otse oma lehe skriptis välja ilma ootamata - API-objekti ei eksisteeri enne, kui ChatLabi skript on laaditud ja initsialiseeritud.

Nõuanne: kui teil on vaja vidinat ainult juhtida (näita/peida/lülita) 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() Avab vestlusvidina
hideChat() Sulgeb vestlusvidina
toggleChat() Lülitab vidina nähtavust
sendMessage(text) Saadab sõnumi programmiliselt
updateClientContext(data) Uuendab kasutaja konteksti (vt allpool)
setLanguage(code) Lülitab vidina kindlale keelele (ainult mitmekeelsetel robotitel, vt allpool)
getLanguage() Tagastab keele, mida vidin hetkel kasutab
getAvailableLanguages() Tagastab keelte loendi, mida robot pakub
addCallback(name, fn) Registreerib sündmuse tagasikutse

Märkus: sendMessage ja updateClientContext nõuavad aktiivset seanssi. Kasutage jaotises „Alustamine“ näidatud initsialiseerimismustrit onSessionActivated.

Tagasikutsed (Callbacks)

Registreerige sündmuste tagasikutsed oma onSessionActivated töötleja sees (vt 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);
});

Saadaolevad tagasikutsed

Tagasikutse Andmed Kirjeldus
onSessionActivated - Vestlusseanss on valmis
onUserMessage string Kasutaja saatis sõnumi
onChatbotMessage string Robot vastas sõnumiga
onProductClick string (toote ID või link) Kasutaja klõpsas tootel (vajab Offer Cards funktsiooni lubamist)
onLeadCollectionFormSubmit {email, phone, name} Müügivihjete kogumise vorm esitati
onContactFormSubmit {email, message} Kontakti-/klienditoevorm esitati
onLiveChatFormSubmit {name, email} Live Chat vorm esitati

Pärandversiooni sündmuste tagasikutsed (iganenud)

Objekt window.aichatbotCallback toetab omadustena otseselt ka väärtusi onUserMessage ja onChatbotMessage. See vorming on iganenud - kõigile tagasikutsetüüpidele juurdepääsuks kasutage selle asemel meetodit addCallback():

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

Märkus: window.aichatbotCallback.onSessionActivated ei ole iganenud - see on soovitatav alglaadimismehhanism Chat API initsialiseerimiseks (vt Alustamine).

Manustamine iframe'i abil

Kui kasutate manustamist iframe'i kaudu, kasutage chatbotiga suhtlemiseks meetodit postMessage:

Käskude saatmine

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

Tagasikutsete vastuvõtmine

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

Kliendi konteksti uuendamine

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

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 (nõutud): Kliendi kordumatu identifikaator
  • clientName, clientEmail, clientPhone (valikuline): Kliendi andmed, mida kuvatakse vestlustes
  • clientSecurityToken (valikuline): Turvatõend API autoriseerimiseks
  • clientHostContext (valikuline): Täiendavad kontekstiparameetrid, mis on kättesaadavad kohandatud API tegevustes

Kasutamine API kutsetes:

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

  • clientName, clientEmail, clientPhone, clientSecurityToken
  • Kohandatud hostikonteksti parameetrid eesliitega client, nt clientparam1, clientparam2

Keel

Need meetodid töötavad ainult mitmekeelsetel chatbotidel. Ühekeelsel robotil pole vidinal keelekihti, mida vahetada, mistõttu setLanguage() ei tee midagi ja getAvailableLanguages() tagastab ainult roboti enda baaskeele. Lülitage esmalt sisse mitmekeelsuse tugi asukohas Settings > Languages (Seaded > Keeled) - vaadake juhendit Mitmekeelsed chatbotid.

Kasutage funktsiooni setLanguage(), kui teie leht on saadaval mitmes keeles ja soovite, et vestlus avaneks keeles, mida külastaja parajasti loeb, mitte selles, mis juhtub olema tema brauseri seadistuses:

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 deklareerida 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 keelemenüüst.
  2. Lehe keel meetodist setLanguage() või muutujast window.aichatbotLanguage.
  3. Külastaja brauseri keel.
  4. Chatboti baaskeel.

Külastaja enda valik jäetakse hilisemateks külastusteks meelde, kuid see lakkab kehtimast niipea, kui lehe keel muutub - seega on teie lehe keelevahetaja alati vananenud valiku suhtes eesõigusega. Koodid vastavad standardile ISO 639-1 (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