Centro assistenza
Chat API

Chat API

Ultimo aggiornamento:

Panoramica di Chat API

L'API del widget ti consente di controllare programmaticamente il widget di chat e registrare callback per gli eventi di chat.

Cerchi la REST API? Questo articolo descrive l'API JavaScript del widget nel browser (window.aichatbotApi) per le pagine in cui è incorporato il widget ChatLab. Per la REST API server-to-server utilizzata per conversare con i bot dal tuo backend o gestire i bot a livello programmatico, consulta gli articoli su Bot Talk API e Management API.

Primi passi

L'API del chatbot non è disponibile immediatamente al caricamento della pagina - lo script deve prima caricarsi ed essere inizializzato. Devi usare window.aichatbotCallback.onSessionActivated come meccanismo di bootstrap per accedere all'API in modo sicuro.

Usa la chiave pubblica del widget presa da Deploy (Pubblica) come YOUR_API_KEY, mai una chiave segreta ck_ o mk_. Mantieni l'ID del provider e l'host dello script dal tuo snippet di Deploy. Inserisci la configurazione della callback prima di quel tag 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 si attiva quando una sessione diventa disponibile, incluse le sessioni ripristinate. A seconda delle impostazioni di pubblicazione e della schermata di benvenuto, questo non corrisponde necessariamente al primo clic di apertura del widget. Può attivarsi di nuovo; registra le callback una sola volta per ciascun oggetto API per evitare gestori duplicati. Al suo interno, l'esistenza dell'oggetto API è garantita e la sessione è attiva, quindi puoi chiamare in sicurezza sendMessage(), updateClientContext() e registrare le callback degli eventi.

Importante: non chiamare window.aichatbotApi.getChatbotApi() direttamente nello script della tua pagina senza attendere - l'oggetto API non esiste finché lo script di ChatLab non è stato caricato e inizializzato.

Suggerimento: se hai solo bisogno di controllare il widget (mostra/nascondi/attiva-disattiva) e non ti serve una sessione attiva, resta invece in ascolto dell'evento DOM aichatbotReady:

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

Metodi

Metodo Descrizione
showChat() Apre il widget di chat
hideChat() Chiude il widget di chat
toggleChat() Mostra o nasconde il widget
sendMessage(text) Invia un messaggio a livello di programmazione
updateClientContext(data) Aggiorna il contesto utente (vedi sotto)
setLanguage(code) Imposta la lingua del widget (solo bot multilingue, vedi sotto)
getLanguage() Restituisce la lingua attualmente in uso nel widget
getAvailableLanguages() Restituisce l'elenco delle lingue offerte dal bot
addCallback(name, fn) Registra una callback per un evento

Nota: sendMessage e updateClientContext richiedono una sessione attiva. Utilizza il pattern di inizializzazione onSessionActivated mostrato nella sezione Primi passi.

Callback

Registra i callback degli eventi all'interno del tuo gestore onSessionActivated (vedi Primi passi):

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 disponibili

Callback Dati Descrizione
onSessionActivated - La sessione di chat è pronta
onUserMessage string L'utente ha inviato un messaggio
onChatbotMessage string Il bot ha risposto con un messaggio
onProductClick Payload di prodotto/link dalla scheda generata L'utente ha fatto clic sul link di un prodotto; analizza il payload per il tipo di scheda
onLeadCollectionFormSubmit {email, phone, name} Il modulo di acquisizione lead è stato inviato
onContactFormSubmit {email, message} Il modulo di contatto/assistenza è stato inviato
onLiveChatFormSubmit {name, email} Il modulo di Live Chat è stato inviato, non prova che un operatore sia entrato
onCustomFormSubmit {formId, values} Il modulo personalizzato è stato inviato; i dati dei file caricati non sono inclusi in questo callback

I callback dei moduli segnalano l'invio lato browser, non una persistenza confermata o una consegna riuscita. Per un'elaborazione confermata dal backend, usa i Webhook. I payload dei callback possono contenere dati personali; non inoltrarli integralmente a strumenti di analytics o log pubblici.

Callback di eventi legacy

L'oggetto window.aichatbotCallback supporta anche onUserMessage e onChatbotMessage come proprietà dirette. Usa addCallback() per listener modulari senza sostituire l'oggetto globale:

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

Nota: window.aichatbotCallback.onSessionActivated non è deprecato - è il meccanismo di bootstrap consigliato per inizializzare la Chat API (vedi Primi passi).

Pubblicazione tramite iframe

Quando usi la pubblicazione tramite iframe, usa postMessage per comunicare con il chatbot:

Invio di comandi

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

Ricezione di callback

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

Aggiorna il contesto del client

La funzione updateClientContext consente di aggiornare il contesto del client durante una sessione attiva:

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 (obbligatorio): identificatore univoco per il client
  • clientName, clientEmail, clientPhone (facoltativo): dettagli del client visualizzati nelle conversazioni
  • clientSecurityToken (facoltativo): un token inoltrato come contesto per la tua integrazione personalizzata. La tua API deve convalidarne l'autenticità, la scadenza e l'autorizzazione.
  • clientHostContext (facoltativo): parametri di contesto aggiuntivi accessibili nelle azioni API personalizzate

Gli ID e il contesto forniti dal browser non costituiscono una prova di identità. Non inserire segreti a livello di account nel codice JavaScript della pagina e non concedere l'accesso solo perché un valore clientId o un'e-mail forniti corrispondono a un record.

Utilizzo nelle chiamate API:

Gli attributi di contesto possono essere utilizzati nelle chiamate di funzioni API configurando il parametro API come tipo "Context":

  • clientName, clientEmail, clientPhone, clientSecurityToken
  • Parametri di contesto host personalizzati preceduti dal prefisso client, ad es. clientparam1, clientparam2

Lingua

Questi metodi funzionano solo sui chatbot multilingua. Su un bot a lingua singola, il widget non ha un livello linguistico da cambiare, quindi setLanguage() non fa nulla e getAvailableLanguages() restituisce solo la lingua del bot stesso. Attiva prima il supporto multilingua in Settings > Languages (Impostazioni > Lingue) - vedi Chatbot multilingue.

Usa setLanguage() quando la tua pagina esiste in più lingue e vuoi che la chat si apra in quella che il visitatore sta leggendo, anziché in quella su cui è impostato il suo browser:

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

Puoi anche dichiarare la lingua della pagina prima del caricamento dello script, evitando così un breve flash della lingua errata:

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

Quale lingua prevale. Il widget determina la lingua in questo ordine:

  1. La lingua scelta direttamente dal visitatore nel menu delle lingue del widget.
  2. La lingua della pagina, da setLanguage() o window.aichatbotLanguage.
  3. La lingua del browser del visitatore.
  4. La lingua di base del chatbot.

La scelta personale del visitatore viene memorizzata per le visite successive, ma smette di essere applicata non appena cambia la lingua della pagina - in questo modo il selettore di lingua del tuo sito prevale sempre su una scelta precedente. I codici seguono lo standard ISO 639-1 (en, de, pl); un codice regionale come de-AT usa come fallback de. Una lingua non offerta dal bot viene ignorata.

Il cambio di lingua non interrompe la conversazione e non cancella la trascrizione.

Articoli correlati

Cerca tra tutti gli articoliChiedi all'assistente