Pagalbos centras
Chat API

Chat API

Paskutinį kartą atnaujinta:

Chat API apžvalga

Ši funkcija pasiekiama tik pasirinktuose planuose. Ji leidžia programiškai valdyti pokalbių valdiklį ir registruoti atgalinio ryšio iškvietas (angl. callbacks) pokalbių įvykiams.

Ieškote REST API? Šiame straipsnyje aptariama naršyklėje veikianti JavaScript valdiklio API (window.aichatbotApi), skirta puslapiams, kuriuose įterptas ChatLab valdiklis. Norėdami sužinoti apie serveris-serveris REST API, naudojamą bendrauti su robotais iš Jūsų vidinių sistemų (angl. backend) arba programiškai valdyti robotus, skaitykite straipsnius Bot Talk API ir Management API.

Darbo pradžia

Pokalbių roboto API nėra pasiekiama iš karto įkėlus puslapį - pirmiausia turi užsikrauti ir inicializuotis scenarijus. Privalote naudoti window.aichatbotCallback.onSessionActivated kaip pradinio paleidimo mechanizmą, kad saugiai pasiektumėte API.

Įterpkite šį kodą prieš ChatLab scenarijaus žymą:

<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 suveikia, kai sukuriama pokalbio sesija (t. y. naudotojas atidaro valdiklį). Jos viduje užtikrinama, kad API objektas egzistuoja ir sesija yra aktyvi, todėl galite saugiai kviesti sendMessage(), updateClientContext() ir registruoti įvykių atgalinio ryšio iškvietas.

Svarbu: nekvieskite window.aichatbotApi.getChatbotApi() tiesiogiai savo puslapio scenarijuje nelaukdami - 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 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 valdiklio 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 atgalinio ryšio iškvietą

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

Atgalinio ryšio iškvietos (callbacks)

Registruokite įvykių atgalinio ryšio iškvietas savo onSessionActivated doroklyje (ž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);
});

Galimos atgalinio ryšio iškvietos

Atgalinio ryšio iškvieta Duomenys Aprašymas
onSessionActivated - Pokalbio sesija paruošta
onUserMessage string Naudotojas išsiuntė žinutę
onChatbotMessage string Robotas atsakė žinute
onProductClick string (produkto ID arba nuoroda) Naudotojas paspaudė ant produkto (reikalingos įjungtos Offer Cards)
onLeadCollectionFormSubmit {email, phone, name} Pateikta potencialių klientų rinkimo forma
onContactFormSubmit {email, message} Pateikta kontakto / pagalbos forma
onLiveChatFormSubmit {name, email} Pateikta Live Chat forma

Pasenusios įvykių atgalinio ryšio iškvietos (nebenaudotinos)

Objektas window.aichatbotCallback taip pat palaiko onUserMessage ir onChatbotMessage kaip tiesiogines savybes. Šis formatas yra pasenęs - naudokite addCallback(), kad pasiektumėte visų tipų atgalinio ryšio iškvietas:

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

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

Įterpimas per iframe

Naudojant įterpimą per iframe, bendravimui su pokalbių robotu naudokite postMessage:

Komandų siuntimas

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

Atgalinio ryšio iškvietų gavimas

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

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): saugos raktas (angl. token), skirtas API autorizacijai
  • clientHostContext (neprivalomas): papildomi konteksto parametrai, pasiekiami pasirinktiniuose API veiksmuose

Naudojimas API iškvietose:

Konteksto atributus galima naudoti API funkcijų iškvietose, sukonfigūravus API parametrą kaip „Context“ tipo:

  • clientName, clientEmail, clientPhone, clientSecurityToken
  • Pasirinktiniai priimančiosios sistemos konteksto parametrai su priešdėliu client, pvz., clientparam1, clientparam2

Kalba

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

Naudokite setLanguage(), kai Jūsų puslapis veikia keliomis kalbomis ir norite, kad pokalbis atsidarytų ta kalba, kuria lankytojas skaito, 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", ...]
});

Puslapio kalbą taip pat galite nurodyti prieš įkeliant scenarijų, taip išvengsite trumpo netinkamos kalbos blykstelėjimo:

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

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

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

Paties lankytojo pasirinkimas įsimenamas vėlesniems apsilankymams, tačiau nustoja galioti, kai pasikeičia puslapio kalba - todėl Jūsų kalbų perjungiklis visada turi pirmenybę prieš pasenusį pasirinkimą. Kodai atitinka ISO 639-1 standartą (en, de, pl); regioninis kodas, pavyzdžiui, de-AT, grįžta prie de. Kalba, kurios robotas nesiūlo, yra ignoruojama.

Kalbos perjungimas nenutraukia pokalbio ir neišvalo susirašinėjimo teksto.

Susiję straipsniai

Ieškoti visuose straipsniuoseKlauskite asistento