Centru de ajutor
Chat API

Chat API

Ultima actualizare:

Prezentare generală a Chat API

API-ul pentru widget 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 din browser (window.aichatbotApi) pentru paginile î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 dumneavoastră - 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ță.

Utilizați cheia publică a widgetului din secțiunea Deploy (Implementare) ca YOUR_API_KEY, niciodată o cheie secretă de tip ck_ sau mk_. Păstrați ID-ul furnizorului și gazda scriptului din propriul snippet Deploy. Plasați configurarea callback-ului înainte de acel tag de script:

<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 declanșează atunci când o sesiune devine disponibilă, inclusiv pentru sesiunile restaurate. În funcție de setările de implementare și de ecranul de întâmpinare, acest moment nu este neapărat primul clic de deschidere a widgetului. Acesta se poate declanșa din nou; înregistrați callback-urile o singură dată per obiect API pentru a evita gestionarii duplicați. În interiorul său, existența obiectului API este garantată, iar sesiunea este activă, astfel încât puteți apela în siguranță sendMessage(), updateClientContext() și puteți înregistra callback-uri pentru evenimente.

Important: Nu apelați direct window.aichatbotApi.getChatbotApi() î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 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 (vezi mai jos)
setLanguage(code) Comută widgetul pe o limbă (doar pentru boți multilingvi, vezi mai jos)
getLanguage() Returnează limba pe care o utilizează 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 cadrul gestionarul dumneavoastră onSessionActivated (consultaț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 Date despre produs/link din cardul randat Utilizatorul a dat clic pe un link de produs; inspectați datele pentru tipul dumneavoastră de card
onLeadCollectionFormSubmit {email, phone, name} Formularul de colectare a lead-urilor a fost trimis
onContactFormSubmit {email, message} Formularul de contact/asistență a fost trimis
onLiveChatFormSubmit {name, email} Formularul de chat live a fost trimis, nu dovedește că un operator s-a alăturat
onCustomFormSubmit {formId, values} Formularul personalizat a fost trimis; fișierele încărcate nu sunt incluse în acest callback

Callback-urile de formular raportează o trimitere la nivelul browserului, nu o salvare confirmată sau o livrare reușită. Pentru procesarea confirmată în backend, utilizați Webhooks. Datele trimise prin callback pot conține date cu caracter personal; nu le redirecționați în masă către servicii de analiză sau jurnale publice.

Callback-uri pentru evenimente de tip legacy

Obiectul window.aichatbotCallback acceptă, de asemenea, onUserMessage și onChatbotMessage ca proprietăți directe. Utilizați addCallback() pentru ascultători modulari, fără a înlocui obiectul global:

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

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

Implementarea prin iframe

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

Trimiterea comenzilor

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

Recepționarea callback-urilor

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

Actualizarea contextului clientului

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): Un token transmis drept context pentru integrarea dumneavoastră personalizată. Propriul dumneavoastră API trebuie să îi valideze autenticitatea, valabilitatea și autorizarea.
  • clientHostContext (opțional): Parametri suplimentari de context accesibili în acțiuni API personalizate

ID-urile și contextul furnizate de browser nu reprezintă o dovadă a identității. Nu introduceți secrete la nivel de cont în codul JavaScript al paginii și nu acordați acces doar pentru că o valoare clientId sau un e-mail furnizat corespunde unei înregistrări.

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 host context prefixați cu client, de exemplu clientparam1, clientparam2

Limbă

Aceste metode funcționează numai pe chatboturile multilingve. Pe un bot monolingv, widgetul nu are un strat de limbă de comutat, astfel încât setLanguage() nu face nimic, iar getAvailableLanguages() returnează doar limba proprie a botului. Activați mai întâi suportul multilingv în Settings > Languages (Setări > Limbi) - consultați Multilingual chatbots.

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

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 limbii 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 selectat-o el însuși din meniul propriu de limbi al widgetului.
  2. Limba paginii, preluată din setLanguage() sau window.aichatbotLanguage.
  3. Limba browserului vizitatorului.
  4. Limba de bază a chatbotului.

Alegerea făcută de vizitator este reținută pentru vizitele ulterioare, dar încetează să se aplice odată ce limba paginii se modifică - astfel, selectorul dumneavoastră de limbă are întotdeauna prioritate în fața unei alegeri vechi. Codurile sunt conforme ISO 639-1 (en, de, pl); un cod regional precum de-AT utilizează ca rezervă de. O limbă care nu este oferită de bot este ignorată.

Schimbarea limbii nu încheie conversația și nu șterge transcrierea.

Articole conexe

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