Súgóközpont
Chat API

Chat API

Utoljára frissítve:

A Chat API áttekintése

Ez a funkció csak bizonyos csomagokban érhető el. Lehetővé teszi a chat widget programozott vezérlését, valamint visszahívások (callbacks) regisztrálását a chateseményekre.

A REST API-t keresi? Ez a cikk a böngészőn belüli JavaScript widget API-ról (window.aichatbotApi) szól olyan oldalak esetén, ahová a ChatLab widget be van ágyazva. Ha a szerverek közötti REST API-ra van szüksége, amellyel a háttérrendszerből (backend) beszélgethet a robotokkal, vagy programozottan kezelheti őket, tekintse meg a Bot Talk API és a Management API cikkeinket.

Első lépések

A chatbot API nem érhető el azonnal az oldal betöltésekor - a szkriptnek először be kell töltődnie és inicializálódnia kell. Az API biztonságos eléréséhez a window.aichatbotCallback.onSessionActivated függvényt kell használnia indítási mechanizmusként.

Helyezze ezt a kódot a ChatLab script tag elé:

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

Az onSessionActivated akkor fut le, amikor a csevegési munkamenet létrejön (azaz a felhasználó megnyitja a widgetet). Ezen belül az API objektum már garantáltan létezik, és a munkamenet aktív, így biztonságosan meghívhatja a sendMessage() és az updateClientContext() metódusokat, valamint regisztrálhat esemény-visszahívásokat.

Fontos: Ne hívja meg a window.aichatbotApi.getChatbotApi() függvényt közvetlenül az oldalszkriptből várakozás nélkül - az API objektum nem létezik mindaddig, amíg a ChatLab szkript be nem töltődött és nem inicializálódott.

Tipp: Ha csak a widgetet szeretné vezérelni (megjelenítés/elrejtés/váltás), és nincs szüksége aktív munkamenetre, figyelje inkább az aichatbotReady DOM-eseményt:

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

Metódusok

Metódus Leírás
showChat() A chat widget megnyitása
hideChat() A chat widget bezárása
toggleChat() A widget láthatóságának váltása
sendMessage(text) Üzenet küldése programozottan
updateClientContext(data) Felhasználói kontextus frissítése (lásd alább)
setLanguage(code) A widget nyelvének átváltása (csak többnyelvű botoknál, lásd alább)
getLanguage() A widget által jelenleg használt nyelv visszaadása
getAvailableLanguages() A bot által kínált nyelvek listájának visszaadása
addCallback(name, fn) Esemény-visszahívás regisztrálása

Megjegyzés: A sendMessage és az updateClientContext metódusokhoz aktív munkamenet szükséges. Használja az Első lépések részben bemutatott onSessionActivated inicializálási mintát.

Visszahívások (callbacks)

Regisztrálja az esemény-visszahívásokat az onSessionActivated kezelőn belül (lásd: Első lépések):

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

Elérhető visszahívások

Visszahívás Adat Leírás
onSessionActivated - A csevegési munkamenet készen áll
onUserMessage string A felhasználó üzenetet küldött
onChatbotMessage string A bot üzenettel válaszolt
onProductClick string (termékazonosító vagy link) A felhasználó egy termékre kattintott (az Offer Cards funkció engedélyezése szükséges)
onLeadCollectionFormSubmit {email, phone, name} Elküldték a leadgyűjtő űrlapot
onContactFormSubmit {email, message} Elküldték a kapcsolatfelvételi/ügyfélszolgálati űrlapot
onLiveChatFormSubmit {name, email} Elküldték a Live Chat űrlapot

Korábbi esemény-visszahívások (elavult)

A window.aichatbotCallback objektum közvetlen tulajdonságként is támogatja az onUserMessage és az onChatbotMessage elemeket. Ez a formátum elavult - az összes visszahívási típus eléréséhez használja inkább az addCallback() metódust:

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

Megjegyzés: A window.aichatbotCallback.onSessionActivated nem elavult - ez az ajánlott indítási mechanizmus a Chat API inicializálásához (lásd: Első lépések).

Beágyazás iframe-ben

Ha iframe-es beágyazást használ, a postMessage segítségével kommunikálhat a chatbottal:

Parancsok küldése

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

Visszahívások fogadása

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

Ügyfélkontextus frissítése

Az updateClientContext függvény lehetővé teszi az ügyfélkontextus frissítését egy aktív munkamenet során:

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

Paraméterek:

  • clientId (kötelező): Az ügyfél egyedi azonosítója
  • clientName, clientEmail, clientPhone (opcionális): A beszélgetésekben megjelenített ügyféladatok
  • clientSecurityToken (opcionális): Biztonsági token az API-hitelesítéshez
  • clientHostContext (opcionális): További kontextusparaméterek, amelyek elérhetők az egyéni API-műveletekben

Használat az API-hívásokban:

A kontextusattribútumok az API-függvényhívásokban úgy használhatók fel, ha az API-paraméter típusát „Context”-re állítja:

  • clientName, clientEmail, clientPhone, clientSecurityToken
  • Egyéni hosztkontextus-paraméterek client előtaggal, például clientparam1, clientparam2

Nyelv

Ezek a metódusok kizárólag többnyelvű chatbotok esetén működnek. Egy egyetlen nyelvet használó botnál a widget nem rendelkezik váltható nyelvi réteggel, így a setLanguage() semmit sem csinál, a getAvailableLanguages() pedig csak a bot saját nyelvét adja vissza. Először kapcsolja be a többnyelvű támogatást a Settings > Languages (Beállítások > Nyelvek) menüpontban - lásd: Többnyelvű chatbotok.

Használja a setLanguage() metódust, ha az oldala több nyelven is elérhető, és azt szeretné, hogy a chat azon a nyelven nyíljon meg, amelyet a látogató éppen olvas, nem pedig azon, amelyre a böngészője be van állítva:

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

Az oldal nyelvét még a szkript betöltése előtt is megadhatja, amellyel elkerülhető a nem megfelelő nyelv rövid felvillanása:

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

Melyik nyelv élvez elsőbbséget. A widget a következő sorrendben határozza meg a nyelvet:

  1. A látogató által a widget saját nyelvválasztó menüjében kiválasztott nyelv.
  2. Az oldal nyelve a setLanguage() metódusból vagy a window.aichatbotLanguage változóból.
  3. A látogató böngészőjének nyelve.
  4. A chatbot alapértelmezett nyelve.

A látogató saját választását a rendszer megjegyzi a későbbi látogatásokra, de a beállítás érvényét veszti, amint az oldal nyelve megváltozik - így az Ön nyelvváltója mindig felülírja a korábbi választást. A kódok ISO 639-1 formátumúak (en, de, pl); a regionális kódok, mint például a de-AT, visszaesnek az alapkódra (de). Ha a megadott nyelv nem érhető el a botban, a rendszer figyelmen kívül hagyja.

A nyelvváltás nem szakítja meg a beszélgetést, és nem törli a csevegési előzményeket sem.

Kapcsolódó cikkek

Keresés az összes cikkbenKérdezze az agenst