Centru de ajutor
Chat API

Chat API

Ultima actualizare:

Prezentare generală Chat API

Această funcționalitate este disponibilă doar în planurile selectate. Vă permite să controlați widgetul de chat în mod programatic și să înregistrați callback-uri pentru evenimentele de chat.

Căutați API-ul REST? Acest articol acoperă API-ul JavaScript pentru widget în browser (window.aichatbotApi), destinat paginilor în care este integrat widgetul ChatLab. Pentru API-ul REST server-to-server utilizat pentru a purta conversații cu boții din backend-ul dumneavoastră sau pentru a gestiona boții în mod programatic, consultați articolele Bot Talk API și Management API.

Primii pași

API-ul chatbotului nu este disponibil imediat la încărcarea paginii - scriptul trebuie mai întâi să se încarce și să se inițializeze. Trebuie să utilizați window.aichatbotCallback.onSessionActivated ca mecanism de bootstrap pentru a accesa API-ul în siguranță.

Plasați acest cod înainte de tagul de script 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>

onSessionActivated se declanșează atunci când sesiunea de chat este creată (de exemplu, când utilizatorul deschide widgetul). În interiorul acestuia, este garantat că obiectul API există și că sesiunea este activă, astfel încât puteți apela în siguranță sendMessage(), updateClientContext() și puteți înregistra callback-uri de evenimente.

Important: Nu apelați window.aichatbotApi.getChatbotApi() direct în scriptul paginii dumneavoastră fără a aștepta - obiectul API nu există până când scriptul ChatLab nu s-a încărcat și nu s-a inițializat.

Sfat: Dacă doriți doar să controlați widgetul (afișare/ascundere/comutare) și nu aveți nevoie de o sesiune activă, ascultați în schimb evenimentul DOM aichatbotReady:

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

Metode

Metodă Descriere
showChat() Deschide widgetul de chat
hideChat() Închide widgetul de chat
toggleChat() Comută vizibilitatea widgetului
sendMessage(text) Trimite un mesaj în mod programatic
updateClientContext(data) Actualizează contextul utilizatorului (vedeți mai jos)
setLanguage(code) Schimbă limba widgetului (doar pentru boți multilingvi, vedeți mai jos)
getLanguage() Returnează limba pe care o folosește widgetul în prezent
getAvailableLanguages() Returnează lista de limbi oferite de bot
addCallback(name, fn) Înregistrează un callback pentru eveniment

Notă: sendMessage și updateClientContext necesită o sesiune activă. Utilizați modelul de inițializare onSessionActivated prezentat în secțiunea Primii pași.

Callback-uri

Înregistrați callback-urile pentru evenimente în interiorul funcției de tratare onSessionActivated (vedeți Primii pași):

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

Callback-uri disponibile

Callback Date Descriere
onSessionActivated - Sesiunea de chat este pregătită
onUserMessage string Utilizatorul a trimis un mesaj
onChatbotMessage string Botul a răspuns cu un mesaj
onProductClick string (ID produs sau link) Utilizatorul a dat clic pe un produs (necesită funcția Offer Cards activată)
onLeadCollectionFormSubmit {email, phone, name} Formularul de colectare a leadurilor a fost trimis
onContactFormSubmit {email, message} Formularul de contact/suport a fost trimis
onLiveChatFormSubmit {name, email} Formularul de live chat a fost trimis

Callback-uri vechi pentru evenimente (învechite)

Obiectul window.aichatbotCallback acceptă, de asemenea, onUserMessage și onChatbotMessage ca proprietăți directe. Acest format este depreciat - utilizați în schimb addCallback() pentru a avea acces la toate tipurile de callback-uri:

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

Notă: window.aichatbotCallback.onSessionActivated nu este depreciat - este mecanismul de bootstrap recomandat pentru inițializarea Chat API (vedeți Primii pași).

Implementare prin iframe

Atunci când utilizați implementarea prin iframe, folosiți postMessage pentru a comunica cu chatbotul:

Trimiterea comenzilor

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

Recepționarea callback-urilor

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

Actualizarea contextului clientului (Update Client Context)

Funcția updateClientContext permite actualizarea contextului clientului în timpul unei sesiuni active:

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 (obligatoriu): Identificator unic pentru client
  • clientName, clientEmail, clientPhone (opțional): Detalii despre client afișate în conversații
  • clientSecurityToken (opțional): Token de securitate pentru autorizarea API
  • clientHostContext (opțional): Parametri suplimentari de context accesibili în acțiunile API personalizate

Utilizarea în apeluri API:

Atributele de context pot fi utilizate în apelurile de funcții API prin configurarea parametrului API cu tipul „Context”:

  • clientName, clientEmail, clientPhone, clientSecurityToken
  • Parametri personalizați de context gazdă prefixați cu client, de exemplu clientparam1, clientparam2

Limbă

Aceste metode funcționează doar pe chatboturi multilingve. Pe un bot monolingv, widgetul nu are un strat lingvistic pe care să îl schimbe, astfel încât setLanguage() nu are niciun efect, iar getAvailableLanguages() returnează doar limba de bază a botului. Activați mai întâi suportul multilingv în Settings > Languages (Setări > Limbi) - consultați Chatboturi multilingve.

Utilizați setLanguage() atunci când pagina dumneavoastră există în mai multe limbi și doriți ca chatul să se deschidă în limba pe care o citește vizitatorul, în loc de cea setată în browserul său:

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

De asemenea, puteți declara limba paginii înainte de încărcarea scriptului, ceea ce previne afișarea scurtă a unei limbi greșite:

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

Ce limbă are prioritate. Widgetul stabilește limba în următoarea ordine:

  1. O limbă pe care vizitatorul a ales-o el însuși din meniul de limbi al widgetului.
  2. Limba paginii, furnizată prin setLanguage() sau window.aichatbotLanguage.
  3. Limba browserului vizitatorului.
  4. Limba de bază a chatbotului.

Alegerea făcută de vizitator este reținută pentru vizitele viitoare, dar încetează să se mai aplice de îndată ce limba paginii se modifică - astfel, selectorul dumneavoastră de limbă va avea întotdeauna prioritate față de o opțiune învechită. Codurile sunt conforme cu ISO 639-1 (en, de, pl); un cod regional precum de-AT revine automat la de. O limbă care nu este oferită de bot este ignorată.

Schimbarea limbii nu întrerupe conversația și nu șterge istoricul acesteia.

Articole asociate

Căutați în toate articoleleÎntrebați agentul