Súgóközpont
Chat API

Chat API

Utoljára frissítve:

Chat API áttekintés

A widget API lehetővé teszi a chat widget programozott vezérlését és visszahívások (callbackek) 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-t (window.aichatbotApi) mutatja be azon oldalak esetében, ahová be van ágyazva a ChatLab widget. A szerverek közötti REST API-val kapcsolatban, amellyel a háttérrendszeréből (backend) folytathat beszélgetést a botokkal, 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őbb be kell töltődnie és inicializálódnia kell. Az API biztonságos eléréséhez a betöltési mechanizmusként a window.aichatbotCallback.onSessionActivated függvényt kell használnia.

A Deploy (Telepítés) menüpontból származó nyilvános widgetkulcsot használja YOUR_API_KEY értékként, soha ne titkos ck_ vagy mk_ kulcsot. A szolgáltatói azonosítót (provider ID) és a szkriptkiszolgálót (script host) a saját Deploy kódrészletéből vegye át. A visszahívás beállítását az adott script címke elé helyezze:

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

Az onSessionActivated akkor fut le, amikor egy munkamenet elérhetővé válik, ideértve a visszaállított munkameneteket is. A telepítési és az üdvözlőképernyő-beállításoktól függően ez nem feltétlenül a widget legelső megnyitására történő kattintáskor történik meg. Újra lefuthat; az API-objektumonként egyszer regisztrálja a visszahívásokat a duplikált kezelők elkerülése érdekében. Ezen belül garantált az API-objektum megléte és a munkamenet aktív állapota, így biztonságosan hívhatja meg a sendMessage(), updateClientContext() metódusokat, és regisztrálhat esemény-visszahívásokat.

Fontos: Ne hívja meg a window.aichatbotApi.getChatbotApi() metódust közvetlenül az oldalszkriptben várakozás nélkül - az API-objektum mindaddig nem létezik, amíg a ChatLab szkript be nem fejezte a betöltést és az inicializálást.

Tipp: Ha csak a widget vezérlésére van szüksége (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() Megnyitja a chat widgetet
hideChat() Bezárja a chat widgetet
toggleChat() Váltja a widget láthatóságát
sendMessage(text) Üzenetet küld programozottan
updateClientContext(data) Frissíti a felhasználói kontextust (lásd alább)
setLanguage(code) Átváltja a widgetet a megadott nyelvre (csak többnyelvű botoknál, lásd alább)
getLanguage() Visszaadja a widget által jelenleg használt nyelvet
getAvailableLanguages() Visszaadja a bot által kínált nyelvek listáját
addCallback(name, fn) Regisztrál egy esemény-visszahívást

Megjegyzés: A sendMessage és az updateClientContext aktív munkamenetet igényel. Használja az Első lépések szakaszban 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 az Első lépések szakaszt):

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 chat munkamenet készen áll
onUserMessage string A felhasználó üzenetet küldött
onChatbotMessage string A bot válaszüzenetet küldött
onProductClick Termék/link adatcsomag a megjelenített kártyából A felhasználó rákattintott egy termékhivatkozásra; ellenőrizze az adatcsomagot az adott kártyatípushoz
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; nem igazolja, hogy operátor csatlakozott
onCustomFormSubmit {formId, values} Elküldték az egyéni űrlapot; a feltöltött fájlok adatai nem szerepelnek ebben a visszahívásban

Az űrlap-visszahívások böngészőoldali beküldést jelentenek, nem pedig megerősített adatbázisba mentést vagy sikeres kézbesítést. A háttérrendszer által megerősített feldolgozáshoz használja a Webhooks (Webhooks) funkciót. A visszahívások adatcsomagjai személyes adatokat tartalmazhatnak; ne továbbítsa őket teljes egészében analitikai rendszerekbe vagy nyilvános naplófájlokba.

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

A window.aichatbotCallback objektum közvetlen tulajdonságként is támogatja az onUserMessage és onChatbotMessage értékeket. Használja az addCallback() metódust moduláris figyelőkhöz anélkül, hogy felülírná a globális objektumot:

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

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

Iframe telepítés

Iframe használatával történő telepítés esetén használja a postMessage metódust a chatbotal való kommunikációhoz:

Parancsok küldése

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

Visszahívások fogadása

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

Ügyfélkontextus frissítése (Update Client Context)

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ő ügyféladatok
  • clientSecurityToken (opcionális): Egyéni integrációhoz kontextusként továbbított token. Saját API-jának kell ellenőriznie annak hitelességét, érvényességét és a jogosultságot.
  • clientHostContext (opcionális): További kontextusparaméterek, amelyek elérhetők az egyéni API-műveletekben

A böngésző által megadott azonosítók és kontextusadatok nem jelentik a személyazonosság igazolását. Ne helyezzen fiókszintű titkos kulcsokat az oldal JavaScriptjébe, és ne biztosítson hozzáférést pusztán azért, mert a megadott clientId vagy e-mail-cím egyezik egy rekorddal.

Használat API-hívásokban:

A kontextusattribútumok felhasználhatók API-függvényhívásokban, ha az API-paraméter típusát "Context" (Kontextus) értékre állítja be:

  • clientName, clientEmail, clientPhone, clientSecurityToken
  • Egyéni hosztkontextus-paraméterek client előtaggal, pl. 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 a Többnyelvű chatbotok cikket.

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, ahelyett, amire 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, amivel elkerülhető a nem megfelelő nyelv rövid idejű 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 nyelv, amelyet a látogató maga választott ki a widget saját nyelvválasztó menüjében.
  2. Az oldal nyelve a setLanguage() metódusból vagy a window.aichatbotLanguage beállításból.
  3. A látogató böngészőjének nyelve.
  4. A chatbot alapértelmezett nyelve.

A rendszer megjegyzi a látogató saját választását a későbbi látogatásokhoz, de amint az oldal nyelve megváltozik, ez a választás érvényét veszti - így az Ön oldalán található nyelvváltó mindig felülírja a korábbi választást. A kódok ISO 639-1 szabványúak (en, de, pl); a területi kódok, mint például a de-AT, visszalépnek az alapkódra (de). Ha olyan nyelvet ad meg, amelyet a bot nem kínál fel, a rendszer figyelmen kívül hagyja azt.

A nyelv átváltása nem zárja le a beszélgetést, és nem törli a csevegési előzményeket.

Kapcsolódó cikkek

Keresés az összes cikkbenKérdezze az agenst