Centar za pomoć
Chat API

Chat API

Poslednje ažuriranje:

Pregled Chat API-ja

Widget API Vam omogućava da programski kontrolišete chat widget 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 widget. Za server-to-server REST API koji se koristi za komunikaciju sa botovima iz Vašeg backend-a ili programsko upravljanje botovima, pogledajte članke za Bot Talk API i Management API.

Početak rada

API za chatbot nije dostupan odmah nakon učitavanja Vaše stranice - skripta se prvo mora učitati i inicijalizovati. Morate koristiti window.aichatbotCallback.onSessionActivated kao mehanizam za pokretanje (bootstrap) kako biste bezbedno pristupili API-ju.

Koristite javni ključ vidžeta iz odeljka Deploy (Implementacija) kao YOUR_API_KEY, nikada tajni ck_ ili mk_ ključ. Zadržite ID provajdera i host skripte iz svog Deploy isečka koda. Postavite podešavanje povratnog poziva (callback) pre te oznake skripte:

<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 pokreće kada sesija postane dostupna, uključujući i obnovljene sesije. U zavisnosti od podešavanja implementacije i ekrana dobrodošlice, ovo nije nužno prvi klik za otvaranje vidžeta. Može se okinuti ponovo; registrujte povratne pozive jednom po API objektu da biste izbegli duplirane rukovaoce (handlers). 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 svoje stranice bez čekanja - API objekat ne postoji sve dok se ChatLab skripta ne učita i inicijalizuje.

Savet: Ako samo treba da kontrolišete vidžet (prikaz/sakrivanje/prebacivanje) i nije Vam potrebna aktivna sesija, umesto toga pratite aichatbotReady DOM događaj:

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.

Callback funkcije

Registrujte callback funkcije događaja 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);
});

Dostupne callback funkcije

Callback Podaci Opis
onSessionActivated - Sesija ćaskanja je spremna
onUserMessage string Korisnik je poslao poruku
onChatbotMessage string Bot je odgovorio porukom
onProductClick Podaci o proizvodu/linku sa prikazane kartice Korisnik je kliknuo na link proizvoda; pregledajte podatke za Vaš tip kartice
onLeadCollectionFormSubmit {email, phone, name} Obrazac za prikupljanje leadova je poslat
onContactFormSubmit {email, message} Obrazac za kontakt/podršku je poslat
onLiveChatFormSubmit {name, email} Obrazac za Live Chat je poslat, nije dokaz da se operater pridružio
onCustomFormSubmit {formId, values} Prilagođeni obrazac je poslat; podaci o otpremljenoj datoteci nisu uključeni u ovu callback funkciju

Callback funkcije obrazaca prijavljuju slanje na strani veb-pregledača, a ne potvrđeno čuvanje u bazi ili uspešnu isporuku. Za obradu potvrđenu na backendu, koristite Webhooks. Podaci iz callback funkcija mogu sadržati lične podatke; nemojte ih u celosti prosleđivati analitici ili javnim logovima.

Zastarele callback funkcije događaja

Objekat window.aichatbotCallback takođe podržava onUserMessage i onChatbotMessage kao direktna svojstva. Koristite addCallback() za modularne slušaoce (listeners) bez zamene globalnog objekta:

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).

Iframe implementacija

Kada koristite iframe implementaciju, koristite postMessage za komunikaciju sa chatbotom:

Slanje komandi

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

Prijem povratnih poziva (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;
    }
});

Ažuriranje konteksta klijenta

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

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

Parametri:

  • clientId (obavezno): Jedinstveni identifikator klijenta
  • clientName, clientEmail, clientPhone (opciono): Podaci o klijentu koji se prikazuju u razgovorima
  • clientSecurityToken (opciono): Token koji se prosleđuje kao kontekst za Vašu prilagođenu integraciju. Vaš sopstveni API mora da verifikuje njegovu autentičnost, istek i autorizaciju.
  • clientHostContext (opciono): Dodatni parametri konteksta dostupni u prilagođenim API radnjama

Identifikatori i kontekst koje prosleđuje pregledač nisu dokaz identiteta. Nemojte stavljati tajne na nivou naloga u JavaScript stranice i nemojte odobravati pristup samo zato što se navedeni clientId ili imejl poklapaju sa zapisom.

Upotreba u API pozivima:

Atributi konteksta mogu se koristiti u pozivima API funkcija tako što ćete konfigurisati API parametar kao tip "Context":

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

Jezik

Ove metode rade samo na višejezičnim chatbotovima. Na jednojezičnom botu widget nema jezički sloj za prebacivanje, pa setLanguage() ne radi ništa, a getAvailableLanguages() vraća samo osnovni jezik samog bota. Prvo uključite višejezičnu podršku u Settings > Languages (Podešavanja > Jezici) - pogledajte Višejezični chatbotovi.

Koristite setLanguage() kada Vaša stranica postoji na više jezika i želite da se chat otvori na onom koji posetilac trenutno čita, umesto na onom na koji mu je pregledač podešen:

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

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

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

Koji jezik ima prednost. Widget određuje jezik sledećim redosledom:

  1. Jezik koji je posetilac sam izabrao u meniju jezika unutar widgeta.
  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 jezik stranice promeni - tako da Vaš selektor jezika uvek ima prednost nad zastarelim izborom. Kodovi su u standardu ISO 639-1 (en, de, pl); regionalni kod kao što je de-AT preusmerava se na de. Jezik koji bot ne nudi se ignoriše.

Promena jezika ne prekida razgovor niti briše transkript.

Povezani članci

Pretražite sve člankePitajte agenta