Centrum nápovědy
Chat API

Chat API

Poslední aktualizace:

Přehled Chat API

Widget API vám umožňuje programově ovládat chatovací widget a registrovat zpětná volání (callbacks) pro události chatu.

Hledáte REST API? Tento článek se věnuje JavaScript widget API v prohlížeči (window.aichatbotApi) pro stránky, kde je widget ChatLab vložen. Pro server-to-server REST API určené ke komunikaci s boty z vašeho backendu nebo k programové správě botů si přečtěte články Bot Talk API a Management API.

Začínáme

API chatbota není k dispozici okamžitě po načtení stránky - skript se musí nejprve načíst a inicializovat. Pro bezpečný přístup k API musíte jako inicializační mechanismus použít window.aichatbotCallback.onSessionActivated.

Jako YOUR_API_KEY použijte veřejný klíč widgetu ze sekce Deploy (Nasazení), nikdy ne tajný klíč ck_ nebo mk_. ID poskytovatele a hostitele skriptu ponechte ze svého vlastního fragmentu kódu z Deploy. Nastavení callbacku umístěte před tento 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 se spustí ve chvíli, kdy je relace k dispozici, a to včetně obnovených relací. V závislosti na nastavení nasazení a uvítací obrazovky to nemusí být nutně první kliknutí otevírající widget. Může se spustit znovu; zaregistrujte callbacky jednou pro každý objekt API, abyste předešli duplicitním obslužným rutinám. Uvnitř máte jistotu, že objekt API existuje a relace je aktivní, takže můžete bezpečně volat sendMessage(), updateClientContext() a registrovat callbacky událostí.

Důležité: Nevolejte window.aichatbotApi.getChatbotApi() přímo ve skriptu stránky bez čekání - objekt API neexistuje, dokud se skript ChatLab nenačte a neinicializuje.

Tip: Pokud potřebujete widget pouze ovládat (zobrazit/skrýt/přepnout) a nepotřebujete aktivní relaci, poslouchejte místo toho DOM událost aichatbotReady:

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

Metody

Metoda Popis
showChat() Otevřít widget chatu
hideChat() Zavřít widget chatu
toggleChat() Přepnout viditelnost widgetu
sendMessage(text) Odeslat zprávu programově
updateClientContext(data) Aktualizovat kontext uživatele (viz níže)
setLanguage(code) Přepnout widget do daného jazyka (pouze vícejazyční boti, viz níže)
getLanguage() Vrátit jazyk, který widget aktuálně používá
getAvailableLanguages() Vrátit seznam jazyků, které bot nabízí
addCallback(name, fn) Zaregistrovat zpětné volání události

Poznámka: Metody sendMessage a updateClientContext vyžadují aktivní relaci. Použijte inicializační vzor onSessionActivated popsaný v části Začínáme.

Zpětná volání (callbacks)

Zaregistrujte zpětná volání událostí uvnitř vašeho obslužného kódu onSessionActivated (viz Začínáme):

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á zpětná volání

Callback Data Popis
onSessionActivated - Chatová relace je připravena
onUserMessage string Uživatel odeslal zprávu
onChatbotMessage string Bot odpověděl zprávou
onProductClick Payload produktu/odkazu z vykreslené karty Uživatel kliknul na odkaz na produkt; zkontrolujte payload pro váš typ karty
onLeadCollectionFormSubmit {email, phone, name} Formulář pro sběr leadů byl odeslán
onContactFormSubmit {email, message} Kontaktní/podpůrný formulář byl odeslán
onLiveChatFormSubmit {name, email} Formulář pro live chat byl odeslán, nejde o potvrzení připojení operátora
onCustomFormSubmit {formId, values} Vlastní formulář byl odeslán; data nahraných souborů nejsou v tomto callbacku zahrnuta

Zpětná volání formulářů hlásí odeslání na straně prohlížeče, nikoli potvrzené uložení nebo úspěšné doručení. Pro zpracování potvrzené backendem použijte Webhooks. Data (payloady) zpětných volání mohou obsahovat osobní údaje; nepřeposílejte je kompletně do analytických nástrojů ani veřejných logů.

Starší zpětná volání událostí (legacy)

Objekt window.aichatbotCallback také podporuje onUserMessage a onChatbotMessage jako přímé vlastnosti. Pro modulární listenery bez nahrazování globálního objektu použijte addCallback():

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

Poznámka: window.aichatbotCallback.onSessionActivated není zastaralý - jedná se o doporučený bootstrap mechanismus pro inicializaci Chat API (viz Začínáme).

Nasazení přes iframe

Při nasazení přes iframe použijte pro komunikaci s chatbotem postMessage:

Odesílání příkazů

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

Příjem zpětných volání

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

Aktualizace kontextu klienta

Funkce updateClientContext umožňuje aktualizovat kontext klienta během aktivní relace:

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

Parametry:

  • clientId (povinné): Jedinečný identifikátor klienta
  • clientName, clientEmail, clientPhone (volitelné): Údaje o klientovi zobrazované v konverzacích
  • clientSecurityToken (volitelné): Token předávaný jako kontext pro vaši vlastní integraci. Vaše vlastní API musí ověřit jeho pravost, platnost a oprávnění.
  • clientHostContext (volitelné): Další kontextové parametry přístupné ve vlastních akcích API

Identifikátory a kontext poskytnuté prohlížečem nejsou důkazem totožnosti. Do JavaScriptu na stránce nevkládejte tajné klíče s přístupem k celému účtu a neudělujte přístup pouze na základě toho, že zadané clientId nebo e-mail odpovídají záznamu.

Použití ve voláních API:

Atributy kontextu můžete použít ve voláních funkcí API nastavením typu parametru API na "Context":

  • clientName, clientEmail, clientPhone, clientSecurityToken
  • Vlastní parametry kontextu hostitele s předponou client, např. clientparam1, clientparam2

Jazyk

Tyto metody fungují pouze u vícejazyčných chatbotů. U jednojazyčného bota widget nemá žádnou jazykovou vrstvu, kterou by bylo možné přepnout, takže setLanguage() neprovede žádnou akci a getAvailableLanguages() vrátí pouze vlastní jazyk bota. Nejprve zapněte vícejazyčnou podporu v Settings > Languages (Nastavení > Jazyky) - viz Vícejazyční chatboti.

Metodu setLanguage() použijte, pokud vaše stránka existuje v několika jazycích a chcete, aby se chat otevřel v jazyce, který návštěvník právě čte, namísto jazyka nastaveného v jeho prohlížeči:

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 také deklarovat před načtením skriptu, čímž zabráníte krátkému probliknutí nesprávného jazyka:

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

Který jazyk má přednost. Widget vyhodnocuje jazyk v tomto pořadí:

  1. Jazyk, který si návštěvník sám vybral v nabídce jazyků přímo ve widgetu.
  2. Jazyk stránky z setLanguage() nebo window.aichatbotLanguage.
  3. Jazyk prohlížeče návštěvníka.
  4. Výchozí jazyk chatbota.

Vlastní volba návštěvníka se ukládá pro pozdější návštěvy, ale přestane platit, jakmile se změní jazyk stránky - váš přepínač jazyků na stránce má tedy vždy přednost před starší volbou. Kódy odpovídají standardu ISO 639-1 (en, de, pl); regionální kód jako de-AT přechází zpět na de. Jazyk, který bot nenabízí, se ignoruje.

Přepnutí jazyka neukončí konverzaci ani nesmaže její přepis.

Související články

Prohledat všechny článkyZeptejte se agenta