Centrum nápovědy
Chat API

Chat API

Poslední aktualizace:

Přehled Chat API

Tato funkce je dostupná pouze ve vybraných plánech. Umožňuje vám programově ovládat widget chatu a registrovat zpětná volání (callbacks) pro události chatu.

Hledáte REST API? Tento článek se věnuje JavaScript API widgetu v prohlížeči (window.aichatbotApi) pro stránky, kde je vložen widget ChatLab. Informace o REST API mezi servery (server-to-server), které slouží ke konverzaci s boty z vašeho backendu nebo k programové správě botů, najdete v článcích Bot Talk API a Management API.

Začínáme

API chatbota není k dispozici ihned po načtení stránky - skript se musí nejprve načíst a inicializovat. Jako zaváděcí mechanismus pro bezpečný přístup k API musíte použít window.aichatbotCallback.onSessionActivated.

Umístěte tento kód před 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>

Událost onSessionActivated se spustí při vytvoření relace chatu (tj. když uživatel otevře widget). Uvnitř této funkce je existence objektu API zaručena a relace je aktivní, takže můžete bezpečně volat sendMessage(), updateClientContext() a registrovat zpětná volání 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 událost DOM 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ř obslužné rutiny onSessionActivated (viz část 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í

Zpětné volání Data Popis
onSessionActivated - Relace chatu je připravena
onUserMessage string Uživatel odeslal zprávu
onChatbotMessage string Bot odpověděl zprávou
onProductClick string (ID produktu nebo odkaz) Uživatel kliknul na produkt (vyžaduje povolenou funkci Offer Cards)
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

Zastaralá zpětná volání událostí (Deprecated)

Objekt window.aichatbotCallback podporuje také onUserMessage a onChatbotMessage jako přímé vlastnosti. Tento formát je zastaralý - pro přístup ke všem typům zpětných volání použijte raději addCallback():

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

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

Nasazení přes iframe

Při nasazení pomocí iframe použijte ke komunikaci s chatbotem postMessage:

Odesílání příkazů

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

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

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

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 zobrazené v konverzacích
  • clientSecurityToken (volitelné): Bezpečnostní token pro autorizaci API
  • clientHostContext (volitelné): Další parametry kontextu přístupné ve vlastních akcích API

Použití při voláních API:

Atributy kontextu lze použít při volání funkcí API konfigurací parametru API jako typu „Context":

  • clientName, clientEmail, clientPhone, clientSecurityToken
  • Vlastní parametry hostitelského kontextu 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 (Nastavení) > Languages (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