Centrum pomoci
Chat API

Chat API

Posledná aktualizácia:

Prehľad Chat API

Táto funkcia je dostupná iba vo vybraných balíkoch. Umožňuje vám programovo ovládať widget chatu a registrovať spätné volania (callbacks) pre udalosti chatu.

Hľadáte REST API? Tento článok sa venuje JavaScript API widgetu v prehliadači (window.aichatbotApi) pre stránky, na ktorých je vložený widget ChatLab. Informácie o server-to-server REST API používanom na komunikáciu s botmi z vášho backendu alebo na ich programovú správu nájdete v článkoch Bot Talk API a Management API.

Začíname

Chatbot API nie je dostupné okamžite po načítaní stránky - skript sa musí najprv načítať a inicializovať. Na bezpečný prístup k API musíte použiť window.aichatbotCallback.onSessionActivated ako zavádzací (bootstrap) mechanizmus.

Umiestnite tento kód pred značku skriptu ChatLab:

<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 sa spustí pri vytvorení relácie chatu (t. j. keď používateľ otvorí widget). Vnútri tejto funkcie je zaručené, že objekt API existuje a relácia je aktívna, takže môžete bezpečne volať sendMessage(), updateClientContext() a registrovať spätné volania udalostí.

Dôležité: Nevolajte window.aichatbotApi.getChatbotApi() vo svojom skripte na stránke priamo bez čakania - objekt API neexistuje, kým sa skript ChatLab nenačíta a neinicializuje.

Tip: Ak potrebujete widget iba ovládať (zobraziť/skryť/prepnúť) a nepotrebujete aktívnu reláciu, počúvajte namiesto toho na udalosť DOM aichatbotReady:

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

Metódy

Metóda Popis
showChat() Otvoriť widget chatu
hideChat() Zavrieť widget chatu
toggleChat() Prepnúť viditeľnosť widgetu
sendMessage(text) Odoslať správu programovo
updateClientContext(data) Aktualizovať kontext používateľa (pozrite nižšie)
setLanguage(code) Prepnúť widget do jazyka (iba viacjazyčné boty, pozrite nižšie)
getLanguage() Vrátiť jazyk, ktorý widget aktuálne používa
getAvailableLanguages() Vrátiť zoznam jazykov, ktoré bot ponúka
addCallback(name, fn) Zaregistrovať spätné volanie udalosti

Poznámka: sendMessage a updateClientContext vyžadujú aktívnu reláciu. Použite inicializačný vzor onSessionActivated uvedený v časti Začíname.

Spätné volania (callbacks)

Zaregistrujte spätné volania udalostí vnútri vášho obslužného programu onSessionActivated (pozrite Začíname):

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

Dostupné spätné volania

Spätné volanie Údaje Popis
onSessionActivated - Relácia chatu je pripravená
onUserMessage string Používateľ odoslal správu
onChatbotMessage string Bot odpovedal správou
onProductClick string (ID produktu alebo odkaz) Používateľ klikol na produkt (vyžaduje povolené Offer Cards)
onLeadCollectionFormSubmit {email, phone, name} Formulár na zber leadov bol odoslaný
onContactFormSubmit {email, message} Kontaktný/podporný formulár bol odoslaný
onLiveChatFormSubmit {name, email} Formulár Live Chat bol odoslaný

Pôvodné spätné volania udalostí (zastarané)

Objekt window.aichatbotCallback podporuje aj onUserMessage a onChatbotMessage ako priame vlastnosti. Tento formát je zastaraný - na prístup ku všetkým typom spätných volaní použite namiesto toho addCallback():

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

Poznámka: window.aichatbotCallback.onSessionActivated nie je zastarané - je to odporúčaný bootstrap mechanizmus na inicializáciu Chat API (pozrite Začíname).

Nasadenie cez Iframe

Pri použití nasadenia cez iframe použite na komunikáciu s chatbotom postMessage:

Odosielanie príkazov

const chatbotIframe = document.querySelector('iframe');

// Zobraziť chat
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'showChat'
}, '*');

// Skryť chat
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'hideChat'
}, '*');

// Odoslať správu
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'sendMessage',
    payload: 'Hello!'
}, '*');

// Aktualizovať kontext klienta
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'updateClientContext',
    payload: { clientId: 'user123', clientName: 'John' }
}, '*');

// Prepnúť jazyk (iba viacjazyčné boty)
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'setLanguage',
    payload: 'de'
}, '*');

Prijímanie spätných volaní

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

Aktualizácia kontextu klienta

Funkcia updateClientContext umožňuje aktualizovať kontext klienta počas aktívnej relácie:

chatbot.updateClientContext({
    clientId: "unique-client-identifier",     // Povinné
    clientName: "John",                       // Voliteľné
    clientEmail: "john@doe.com",              // Voliteľné
    clientPhone: "555-444-333",               // Voliteľné
    clientSecurityToken: "your-token",        // Voliteľné
    clientHostContext: {                      // Voliteľné
        param1: "value1",
        param2: "value2"
    }
});

Parametre:

  • clientId (povinné): Jedinečný identifikátor klienta
  • clientName, clientEmail, clientPhone (voliteľné): Údaje o klientovi zobrazené v konverzáciách
  • clientSecurityToken (voliteľné): Bezpečnostný token na autorizáciu API
  • clientHostContext (voliteľné): Dodatočné parametre kontextu prístupné vo vlastných akciách API

Použitie vo volaniach API:

Atribúty kontextu je možné použiť vo volaniach funkcií API konfiguráciou parametra API ako typ "Context":

  • clientName, clientEmail, clientPhone, clientSecurityToken
  • Vlastné parametre hostiteľského kontextu s predponou client, napr. clientparam1, clientparam2

Jazyk

Tieto metódy fungujú iba na viacjazyčných robotoch. Pri jednojazyčnom botovi nemá widget žiadnu jazykovú vrstvu na prepínanie, takže setLanguage() nerobí nič a getAvailableLanguages() vráti iba vlastný jazyk bota. Najprv zapnite viacjazyčnú podporu v Settings > Languages (Nastavenia > Jazyky) - pozrite Viacjazyčné chatboty.

Použite setLanguage(), keď vaša stránka existuje vo viacerých jazykoch a chcete, aby sa chat otvoril v jazyku, ktorý návštevník práve číta, namiesto jazyka, ktorý má náhodou nastavený vo svojom prehliadači:

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

    chatbot.setLanguage(document.documentElement.lang);  // napr. "de"

    console.log(chatbot.getLanguage());            // "de"
    console.log(chatbot.getAvailableLanguages());   // ["en", "de", "fr", ...]
});

Jazyk stránky môžete deklarovať aj pred načítaním skriptu, čím predídete krátkemu prebliknutiu nesprávneho jazyka:

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

Ktorý jazyk má prednosť. Widget vyhodnocuje jazyk v tomto poradí:

  1. Jazyk, ktorý si návštevník sám vybral v ponuke jazykov samotného widgetu.
  2. Jazyk stránky z setLanguage() alebo window.aichatbotLanguage.
  3. Jazyk prehliadača návštevníka.
  4. Predvolený jazyk chatbota.

Vlastný výber návštevníka sa zapamätá aj pre ďalšie návštevy, no prestane platiť, len čo sa zmení jazyk stránky - takže váš prepínač jazykov má vždy prednosť pred neaktuálnou voľbou. Kódy sú v štandarde ISO 639-1 (en, de, pl); regionálny kód ako de-AT sa automaticky prepne na de. Jazyk, ktorý bot neponúka, sa ignoruje.

Prepnutie jazyka neukončí konverzáciu ani nevymaže prepis chatu.

Súvisiace články

Prehľadávať všetky článkySpýtajte sa agenta