Pagalbos centras
Chat API

Chat API

Paskutinį kartą atnaujinta:

Chat API apžvalga

Valdiklio API leidžia programiškai valdyti pokalbių valdiklį ir registruoti atgalinius iškvietimus (angl. callbacks) pokalbių įvykiams.

Ieškote REST API? Šiame straipsnyje aptariama naršyklės „JavaScript“ valdiklio API (window.aichatbotApi), skirta puslapiams, kuriuose integruotas „ChatLab“ valdiklis. Informacijos apie tiesioginę serverių REST API, naudojamą bendrauti su robotais iš jūsų vidinės sistemos (angl. backend) arba valdyti juos programiškai, ieškokite straipsniuose apie Bot Talk API ir Management API.

Darbo pradžia

Pokalbių roboto API nėra pasiekiamas iš karto, kai tik užsikrauna Jūsų puslapis - pirmiausia scenarijus turi būti įkeltas ir inicializuotas. Norėdami saugiai pasiekti API, kaip paleidimo mechanizmą privalote naudoti window.aichatbotCallback.onSessionActivated.

Naudokite viešąjį valdiklio raktą iš skilties „Test & Deploy“ (testavimas ir diegimas) kaip YOUR_API_KEY, bet niekada nenaudokite slapto ck_ ar mk_ rakto. Teikėjo ID ir scenarijaus pagrindinį kompiuterį (host) paimkite iš to paties įterpimo kodo fragmento. Atgalinio iškvietimo (callback) sąranką įdėkite prieš šią scenarijaus žymą:

<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 suveikia tada, kai sesija tampa pasiekiama, įskaitant atkurtas sesijas. Priklausomai nuo diegimo ir pasveikinimo ekrano nustatymų, tai nebūtinai yra pats pirmas valdiklio atidarymo paspaudimas. Įvykis gali suveikti pakartotinai; užregistruokite atgalinius iškvietimus vieną kartą vienam API objektui, kad išvengtumėte pasikartojančių doroklių. Šio iškvietimo viduje garantuojama, kad API objektas egzistuoja, o sesija yra aktyvi, todėl galite saugiai iškviesti sendMessage(), updateClientContext() ir registruoti įvykių atgalinius iškvietimus.

Svarbu: nekvieskite window.aichatbotApi.getChatbotApi() tiesiogiai savo puslapio scenarijuje nelaukdami - API objektas neegzistuoja tol, kol ChatLab scenarijus nėra visiškai įkeltas ir inicializuotas.

Patarimas: jei Jums tereikia valdyti valdiklį (rodyti / slėpti / perjungti) ir nereikia aktyvios sesijos, verčiau klausykitės aichatbotReady DOM įvykio:

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

Metodai

Metodas Aprašymas
showChat() Atidaryti pokalbių valdiklį
hideChat() Uždaryti pokalbių valdiklį
toggleChat() Perjungti valdiklio matomumą
sendMessage(text) Išsiųsti žinutę programiškai
updateClientContext(data) Atnaujinti naudotojo kontekstą (žr. toliau)
setLanguage(code) Perjungti valdiklį į konkrečią kalbą (tik daugiakalbiams robotams, žr. toliau)
getLanguage() Grąžinti kalbą, kurią valdiklis šiuo metu naudoja
getAvailableLanguages() Grąžinti roboto siūlomų kalbų sąrašą
addCallback(name, fn) Užregistruoti įvykio atgalinį iškvietimą

Pastaba: sendMessage ir updateClientContext reikalauja aktyvios sesijos. Naudokite onSessionActivated inicializavimo šabloną, parodytą skiltyje „Darbo pradžia“.

Atgaliniai iškvietimai (callbacks)

Registruokite įvykių atgalinius iškvietimus savo onSessionActivated apdorojimo funkcijoje (žr. „Darbo pradžia“):

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

Galimi atgaliniai iškvietimai

Atgalinis iškvietimas Duomenys Aprašymas
onSessionActivated - Pokalbio sesija paruošta
onUserMessage string Naudotojas išsiuntė žinutę
onChatbotMessage string Robotas atsakė žinute
onProductClick Produkto / nuorodos duomenys iš atvaizduotos kortelės Naudotojas paspaudė produkto nuorodą; patikrinkite savo kortelės tipo duomenų paketą
onLeadCollectionFormSubmit {email, phone, name} Pateikta potencialių klientų rinkimo forma
onContactFormSubmit {email, message} Pateikta kontaktų / pagalbos forma
onLiveChatFormSubmit {name, email} Pateikta tiesioginio pokalbio (Live Chat) forma, tai nėra įrodymas, kad prisijungė operatorius
onCustomFormSubmit {formId, values} Pateikta pasirinktinė forma; įkeltų failų duomenys į šį atgalinį iškvietimą neįtraukiami

Formų atgaliniai iškvietimai praneša apie pateikimą naršyklės pusėje, o ne apie patvirtintą išsaugojimą ar sėkmingą pristatymą. Norėdami gauti serverio patvirtintą apdorojimą, naudokite Webhooks (saityno kibirkštis). Atgalinių iškvietimų duomenyse gali būti asmens duomenų; nepersiųskite jų visų į analitikos sistemas ar viešus žurnalus.

Pasenę įvykių atgaliniai iškvietimai

Objektas window.aichatbotCallback taip pat palaiko onUserMessage ir onChatbotMessage kaip tiesiogines savybes. Naudokite addCallback(), jei norite pridėti modulinių klausytojų nepakeisdami visuotinio objekto:

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

Pastaba: window.aichatbotCallback.onSessionActivated nėra pasenęs - tai rekomenduojamas paleidimo mechanizmas Chat API inicializavimui (žr. „Darbo pradžia“).

Iframe diegimas

Naudodami iframe diegimą, bendravimui su chatbot naudokite postMessage:

Komandų siuntimas

// Give the ChatLab iframe from Test & 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);

Grįžtamųjų iškvietimų (angl. callbacks) gavimas

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

Kliento konteksto atnaujinimas

Funkcija updateClientContext leidžia atnaujinti kliento kontekstą aktyvios sesijos metu:

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

Parametrai:

  • clientId (privalomas): unikalus kliento identifikatorius
  • clientName, clientEmail, clientPhone (neprivalomi): kliento duomenys, rodomi pokalbiuose
  • clientSecurityToken (neprivalomas): prieigos raktas, persiunčiamas kaip kontekstas jūsų pasirinktinei integracijai. Jūsų pačių API privalo patikrinti jo autentiškumą, galiojimo laiką ir autorizaciją.
  • clientHostContext (neprivalomas): papildomi konteksto parametrai, pasiekiami atliekant pasirinktinius API veiksmus

Naršyklės pateikti ID ir kontekstas nėra tapatybės įrodymas. Niekada nedėkite visos paskyros paslapčių į puslapio „JavaScript“ ir nesuteikite prieigos vien todėl, kad pateiktas clientId ar el. pašto adresas sutampa su įrašu sistemoje.

Naudojimas API iškvietimuose:

Konteksto atributai gali būti naudojami API funkcijų iškvietimuose, sukonfigūravus API parametrą kaip tipo „Context“:

  • clientName, clientEmail, clientPhone, clientSecurityToken
  • Pasirinktiniai pagrindinio kompiuterio konteksto (angl. host context) parametrai su priešdėliu client, pvz., clientparam1, clientparam2

Kalba

Šie metodai veikia tik daugiakalbiuose pokalbių robotuose. Vienakalbiame robote valdiklis neturi kalbos sluoksnio, kurį būtų galima perjungti, todėl setLanguage() nieko nedaro, o getAvailableLanguages() grąžina tik paties roboto kalbą. Pirmiausia įjunkite kelių kalbų palaikymą skiltyje Settings > Languages (Nustatymai > Kalbos) - žr. Daugiakalbiai pokalbių robotai.

Naudokite setLanguage(), kai jūsų puslapis veikia keliomis kalbomis ir norite, kad pokalbių langas atsidarytų ta kalba, kuria lankytojas skaito puslapį, o ne ta, kuri nustatyta jo naršyklėje:

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

Taip pat puslapio kalbą galite nurodyti prieš įkeliant scenarijų - taip išvengsite trumpo netinkamos kalbos mirktelėjimo:

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

Kuri kalba turi pirmenybę. Valdiklis kalbą nustato šia tvarka:

  1. Kalba, kurią lankytojas pasirinko pats valdiklio kalbų meniu.
  2. Puslapio kalba, nurodyta per setLanguage() arba window.aichatbotLanguage.
  3. Lankytojo naršyklės kalba.
  4. Pagrindinė pokalbių roboto kalba.

Paties lankytojo pasirinkimas įsimenamas vėlesniems apsilankymams, tačiau jis nustoja galioti, kai pasikeičia puslapio kalba - taigi jūsų kalbos perjungiklis visada turi pirmenybę prieš nebeaktualų ankstesnį pasirinkimą. Kodai atitinka ISO 639-1 standartą (en, de, pl); regioninis kodas, pavyzdžiui, de-AT, pagal numatytuosius nustatymus perjungiamas į de. Kalba, kurios robotas nesiūlo, yra ignoruojama.

Kalbos perjungimas neužbaigia pokalbio ir neišvalo susirašinėjimo istorijos.

Susiję straipsniai