Centar za pomoć
Chat API

Chat API

Poslednje ažuriranje:

Pregled Chat API-ja

Ova funkcija je dostupna samo u odabranim paketima. Omogućava vam da programski kontrolišete vidžet za ćaskanje i registrujete povratne pozive (callbacks) za događaje u ćaskanju.

Tražite REST API? Ovaj članak pokriva JavaScript widget API u pregledaču (window.aichatbotApi) za stranice na kojima je ugrađen ChatLab vidžet. Za server-to-server REST API koji se koristi za razgovor sa botovima sa vašeg bekenda ili za programsko upravljanje botovima, pogledajte članke Bot Talk API i Management API.

Početak rada

API za chatbot nije dostupan odmah čim se vaša stranica učita - skripta se prvo mora učitati i inicijalizovati. Morate koristiti window.aichatbotCallback.onSessionActivated kao mehanizam pokretanja kako biste bezbedno pristupili API-ju.

Postavite ovo pre ChatLab script taga:

<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 se aktivira kada se sesija ćaskanja kreira (tj. kada korisnik otvori vidžet). Unutar njega, postojanje API objekta je zagarantovano i sesija je aktivna, tako da možete bezbedno pozivati sendMessage(), updateClientContext() i registrovati povratne pozive za događaje.

Važno: Nemojte pozivati window.aichatbotApi.getChatbotApi() direktno u skripti vaše stranice bez čekanja - API objekat ne postoji sve dok se ChatLab skripta ne učita i ne inicijalizuje.

Savet: Ako samo treba da kontrolišete vidžet (prikaži/sakrij/promeni vidljivost) i nije vam potrebna aktivna sesija, umesto toga slušajte DOM događaj aichatbotReady:

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

Metode

Metoda Opis
showChat() Otvara vidžet za ćaskanje
hideChat() Zatvara vidžet za ćaskanje
toggleChat() Menja vidljivost vidžeta
sendMessage(text) Šalje poruku programski
updateClientContext(data) Ažurira kontekst korisnika (pogledajte ispod)
setLanguage(code) Prebacuje vidžet na određeni jezik (samo za višejezične botove, pogledajte ispod)
getLanguage() Vraća jezik koji vidžet trenutno koristi
getAvailableLanguages() Vraća listu jezika koje bot nudi
addCallback(name, fn) Registruje povratni poziv za događaj

Napomena: sendMessage i updateClientContext zahtevaju aktivnu sesiju. Koristite obrazac inicijalizacije onSessionActivated prikazan u odeljku Početak rada.

Povratni pozivi (Callbacks)

Registrujte povratne pozive za događaje unutar vašeg onSessionActivated hendlera (pogledajte Početak rada):

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

Dostupni povratni pozivi

Povratni poziv Podaci Opis
onSessionActivated - Sesija ćaskanja je spremna
onUserMessage string Korisnik je poslao poruku
onChatbotMessage string Bot je odgovorio porukom
onProductClick string (ID proizvoda ili link) Korisnik je kliknuo na proizvod (zahteva omogućenu funkciju Offer Cards)
onLeadCollectionFormSubmit {email, phone, name} Obrazac za prikupljanje lidova je poslat
onContactFormSubmit {email, message} Obrazac za kontakt/podršku je poslat
onLiveChatFormSubmit {name, email} Obrazac za Live Chat je poslat

Zastareli povratni pozivi za događaje (Deprecated)

Objekat window.aichatbotCallback takođe podržava onUserMessage i onChatbotMessage kao direktna svojstva. Ovaj format je zastareo - koristite addCallback() umesto toga za pristup svim tipovima povratnih poziva:

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

Napomena: window.aichatbotCallback.onSessionActivated nije zastareo - to je preporučeni mehanizam pokretanja za inicijalizaciju Chat API-ja (pogledajte Početak rada).

Implementacija putem iframe-a

Kada koristite implementaciju putem iframe-a, koristite postMessage za komunikaciju sa chatbotom:

Slanje komandi

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

// Prikaz ćaskanja
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'showChat'
}, '*');

// Sakrivanje ćaskanja
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'hideChat'
}, '*');

// Slanje poruke
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'sendMessage',
    payload: 'Hello!'
}, '*');

// Ažuriranje konteksta klijenta
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'updateClientContext',
    payload: { clientId: 'user123', clientName: 'John' }
}, '*');

// Promena jezika (samo za višejezične botove)
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'setLanguage',
    payload: 'de'
}, '*');

Prijem povratnih poziva

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

Ažuriranje konteksta klijenta

Funkcija updateClientContext omogućava ažuriranje konteksta klijenta tokom aktivne sesije:

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

Parametri:

  • clientId (obavezno): Jedinstveni identifikator klijenta
  • clientName, clientEmail, clientPhone (opciono): Podaci o klijentu koji se prikazuju u razgovorima
  • clientSecurityToken (opciono): Bezbednosni token za autorizaciju API-ja
  • clientHostContext (opciono): Dodatni parametri konteksta dostupni u prilagođenim API akcijama

Upotreba u API pozivima:

Atributi konteksta mogu se koristiti u pozivima API funkcija tako što se API parametar konfiguriše kao tip „Context”:

  • clientName, clientEmail, clientPhone, clientSecurityToken
  • Prilagođeni parametri host konteksta sa prefiksom client, npr. clientparam1, clientparam2

Jezik

Ove metode funkcionišu samo na višejezičnim chatbotovima. Na jednojezičnom botu vidžet nema jezički sloj za prebacivanje, pa setLanguage() ne radi ništa, a getAvailableLanguages() vraća samo primarni jezik bota. Prvo uključite višejezičnu podršku u Settings > Languages (Podešavanja > Jezici) - pogledajte Multilingual chatbots.

Koristite setLanguage() kada vaša stranica postoji na nekoliko jezika i želite da se ćaskanje otvori na onom koji posetilac čita, umesto na onom na koji je slučajno podešen njegov pregledač:

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

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

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

Takođe možete deklarisati jezik stranice pre nego što se skripta učita, čime se izbegava kratak prikaz pogrešnog jezika:

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

Koji jezik ima prioritet. Vidžet određuje jezik sledećim redosledom:

  1. Jezik koji je posetilac sam izabrao u meniju za jezik unutar vidžeta.
  2. Jezik stranice, iz setLanguage() ili window.aichatbotLanguage.
  3. Jezik pregledača posetioca.
  4. Osnovni jezik chatbota.

Izbor samog posetioca se pamti za buduće posete, ali prestaje da važi čim se promeni jezik stranice - tako da vaš birač jezika uvek ima prednost u odnosu na stari izbor. Kodovi su u formatu ISO 639-1 (en, de, pl); regionalni kod kao što je de-AT se vraća na de. Jezik koji bot ne nudi se zanemaruje.

Promena jezika ne prekida razgovor niti briše transkript.

Povezani članci

Pretražite sve člankePitajte agenta