Centrum pomoci
Chat API

Chat API

Posledná aktualizácia:

Prehľad Chat API

Widget API vám umožňuje programovo ovládať chat widget a registrovať spätné volania (callbacks) pre udalosti chatu.

Hľadáte REST API? Tento článok sa venuje JavaScript widget API v prehliadači (window.aichatbotApi) pre stránky, na ktorých je vložený widget ChatLab. Ak hľadáte REST API typu server-to-server na konverzáciu s botmi z vášho backendu alebo na programovú správu botov, pozrite si články o Bot Talk API a Management API.

Začíname

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

Použite verejný kľúč widgetu zo sekcie Deploy (Nasadenie) ako YOUR_API_KEY, nikdy nie tajný kľúč ck_ ani mk_. Ponechajte ID poskytovateľa a hostiteľa skriptu z vlastného fragmentu v sekcii Deploy. Nastavenie spätného volania (callback) umiestnite pred daný tag skriptu:

<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 sa spustí vo chvíli, keď je relácia k dispozícii, vrátane obnovených relácií. V závislosti od nastavení nasadenia a uvítacej obrazovky to nemusí byť nevyhnutne prvé kliknutie na otvorenie widgetu. Môže sa spustiť znova; spätné volania registrujte iba raz pre každý objekt API, aby ste predišli duplicitným obslužným rutinám. Vnútri neho máte 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() priamo v skripte vašej stránky 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 radšej 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í vo svojom handleri onSessionActivated (pozrite si 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 Dáta Popis
onSessionActivated - Relácia chatu je pripravená
onUserMessage string Používateľ odoslal správu
onChatbotMessage string Bot odpovedal správou
onProductClick Dátový obsah produktu/odkazu z vykreslenej karty Používateľ klikol na odkaz na produkt; skontrolujte dátový obsah pre daný typ karty
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 pre Live Chat bol odoslaný, nie je to však potvrdenie, že sa pripojil operátor
onCustomFormSubmit {formId, values} Vlastný formulár bol odoslaný; dáta z nahraných súborov nie sú súčasťou tohto spätného volania

Spätné volania formulárov hlásia odoslanie na strane prehliadača, nie potvrdené uloženie do databázy alebo úspešné doručenie. Na spracovanie potvrdené na strane backendu použite Webhooky. Dátové obsahy spätných volaní môžu obsahovať osobné údaje; nepreposielajte ich v plnom rozsahu do analytických nástrojov ani do verejných logov.

Zastarané spätné volania udalostí

Objekt window.aichatbotCallback podporuje aj onUserMessage a onChatbotMessage ako priame vlastnosti. Použite addCallback() pre modulárne listenery bez nutnosti nahradenia globálneho objektu:

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

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

Nasadenie cez iframe

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

Odosielanie príkazov

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

Prijímanie spätných volaní (callbacks)

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

Aktualizácia kontextu klienta

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

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

Parametre:

  • clientId (povinné): Jedinečný identifikátor klienta
  • clientName, clientEmail, clientPhone (voliteľné): Údaje o klientovi zobrazené v konverzáciách
  • clientSecurityToken (voliteľné): Token odovzdaný ako kontext pre vašu vlastnú integráciu. Vaše vlastné API musí overiť jeho pravosť, čas vypršania platnosti a autorizáciu.
  • clientHostContext (voliteľné): Ďalšie parametre kontextu dostupné vo vlastných akciách API

Identifikátory a kontext poskytnuté prehliadačom nie sú dôkazom identity. Neumiestňujte tajné kľúče s rozsahom pre celý účet do JavaScriptu na stránke a neudeľujte prístup len preto, že zadané clientId alebo e-mail zodpovedajú záznamu.

Použitie vo volaniach API:

Atribúty kontextu môžete použiť vo volaniach funkcií API tak, že parameter API nakonfigurujete ako typ "Context" (Kontext):

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

Jazyk

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

Použite setLanguage(), ak vaša stránka existuje vo viacerých jazykoch a chcete, aby sa chat otvoril v tom jazyku, ktorý si návštevník práve číta, a nie v tom, na ktorý má náhodou nastavený prehliadač:

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

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 určuje jazyk v tomto poradí:

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

Vlastný výber návštevníka sa zapamätá aj pre ďalšie návštevy, no prestane platiť v momente, keď sa zmení jazyk stránky - prepínač jazykov na vašom webe má teda vždy prednosť pred starou voľbou. Kódy zodpovedajú štandardu ISO 639-1 (en, de, pl); regionálny kód ako napríklad 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