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 - il componente script deve prima caricarsi e inizializzarsi. Devi usare window.aichatbotCallback.onSessionActivated come meccanismo di avvio (bootstrap) per accedere all'API in modo sicuro.
Usa la chiave pubblica del widget da Test & Deploy (Testa e pubblica) come YOUR_API_KEY, mai una chiave segreta ck_ o mk_. Mantieni l'ID del provider e l'host dello script dallo stesso snippet di incorporamento (embed). Posiziona la configurazione del callback prima del 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 della configurazione di pubblicazione e della schermata di benvenuto, questo non corrisponde necessariamente al primo clic di apertura del widget. Può attivarsi di nuovo; registra i callback una sola volta per 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 i callback degli eventi.
Importante: non chiamare window.aichatbotApi.getChatbotApi() direttamente nello script della 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 necessiti di una sessione attiva, ascolta invece l'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 Test & 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:
- La lingua scelta direttamente dal visitatore nel menu delle lingue del widget.
- La lingua della pagina, da
setLanguage()owindow.aichatbotLanguage. - La lingua del browser del visitatore.
- 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.