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 pasiekiama iš karto, kai puslapis įkeliamas - pirmiausia scenarijus turi būti įkeltas ir inicializuotas. Norėdami saugiai pasiekti API, kaip paleidimo mechanizmą privalote naudoti window.aichatbotCallback.onSessionActivated.

Kaip YOUR_API_KEY naudokite viešąjį valdiklio raktą iš skilties Deploy (Diegimas), niekada nenaudokite slaptojo ck_ ar mk_ rakto. Išsaugokite teikėjo ID ir scenarijaus prieglobos adresą (angl. script host) iš savo „Deploy“ kodo fragmento. Atgalinio iškvietimo konfigūraciją įterpkite 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, kai sesija tampa pasiekiama, įskaitant atkurtas sesijas. Priklausomai nuo diegimo ir pasveikinimo ekrano nustatymų, tai nebūtinai yra pats pirmasis paspaudimas, atidarantis valdiklį. Šis įvykis gali suveikti pakartotinai; registruokite atgalinius iškvietimus vieną kartą kiekvienam API objektui, kad išvengtumėte pasikartojančių apdorojimo funkcijų. Jos viduje garantuojama, kad API objektas egzistuoja, o sesija yra aktyvi, todėl galite saugiai kviesti sendMessage(), updateClientContext() ir registruoti įvykių atgalinius iškvietimus.

Svarbu: nekvieskite window.aichatbotApi.getChatbotApi() tiesiogiai puslapio scenarijuje nepalaukę - API objektas neegzistuoja, kol „ChatLab“ scenarijus nėra įkeltas ir inicializuotas.

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

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“).

Diegimas naudojant Iframe

Naudodami diegimą per iframe, bendravimui su pokalbių robotu naudokite postMessage:

Komandų siuntimas

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

Atgalinių iškvietimų 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. Multilingual chatbots.

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

Ieškoti visuose straipsniuoseKlauskite asistento