Introduzione Imposta info visitatore Ottieni info visitatore Imposta lingua widget Imposta aspetto widget Imposta dimensione widget Modifica testi del widget Imposta colori widget Imposta info pagina Ottieni stato widget Stato connessione Stato aperto/chiuso ID del dialogo Invia messaggio Imposta dipartimento Callback

API JavaScript per la live chat

Usa l'API JavaScript di onWebChat per personalizzare il widget di chat e automatizzare i flussi. Puoi passare dati del visitatore, impostare la lingua del widget, massimizzare o nascondere il widget e altro.

Ad esempio, puoi inviare i dettagli del visitatore alla chat, impostare la lingua in base alla pagina o aprire il widget in modo programmatico quando un utente clicca un pulsante.

Aggiungi il tuo codice API subito sotto lo script del widget di chat, come mostrato a destra.




    <script type='text/javascript'>
        /* Incolla qui lo snippet di installazione del widget onWebChat che trovi nella dashboard. */
    </script>
    <script type='text/javascript'>
        /* Aggiungi qui sotto le tue chiamate all'API JavaScript, ad esempio onWebChat.set() o onWebChat.get() */
    </script>

Impostare le informazioni del visitatore

Puoi impostare i dettagli del visitatore prima o durante una sessione di chat. Ad esempio, impostare il nome aiuta il team a identificare i contatti nell'elenco dei visitatori.

Usa queste chiamate API per impostare nome, email, telefono e note del visitatore:



    onWebChat.set("name","Sarah Chen");
    onWebChat.set("email","sarah.chen@example.com");
    onWebChat.set("phone","+1 555 010 0142");
    onWebChat.set("notes","Returning visitor, requested an Enterprise trial");

Ottenere le informazioni del visitatore

Puoi leggere il nome, l'email, il telefono e le note del visitatore ogni volta che questi valori sono stati forniti tramite questa API JavaScript, raccolti nel modulo pre-chat o aggiornati dagli agenti nella dashboard.

Chiama queste funzioni dopo il caricamento completo del widget. Esempio:
onWebChat.set("onWebChatLoaded", function() { console.log("visitor name: " + onWebChat.get("name")); });



    onWebChat.get("name");
    onWebChat.get("email");
    onWebChat.get("phone");
    onWebChat.get("notes");

Impostare la lingua del widget

Puoi impostare la lingua del widget usando il codice di qualsiasi lingua attivata nella tua dashboard.

Ad esempio, "it" per l'italiano, "en" per l'inglese e "es" per lo spagnolo. Se il codice indicato non è attivato, il widget usa la lingua predefinita. Senza questa chiamata, il widget usa la lingua del browser del visitatore, se l'hai attivata. Puoi gestire le lingue attive e quella predefinita in Impostazioni > Widget > Lingue.

Codici lingua disponibili:

am ar az be bg bn bs ca cs da de dv dz el en es et fa fi fil fo fr he hi hr ht hu hy id is it ja ka kk kl km ko ky la lb lo lt lv mg mk mn ms mt my ne nl no pl ps pt ro ru rw si sk sl sm so sq sr sv sw tg th ti tk to tr uk ur uz vi zh zh-TW





    onWebChat.set("language","es");

Impostare l'aspetto del widget

Puoi controllare la visibilità del widget e il suo stato aperto o chiuso:

Usa il parametro max con 0 per minimizzare o 1 per massimizzare il widget.

Per nascondere completamente il widget, usa il parametro show con valore 0. Usa 1 per renderlo di nuovo visibile.





    onWebChat.set("max",1);

    onWebChat.set("show",0);

Impostare la dimensione del widget

In una pagina specifica puoi mostrare il widget in una qualsiasi delle tre dimensioni di Impostazioni > Widget > Impostazioni widget, senza cambiare la dimensione salvata nel tuo account.

Usa il parametro size con il valore "standard" (la dimensione Piccolo nella dashboard), "large" o "xlarge" (Extra grande). È utile nelle pagine con poco spazio libero o in una landing page dove vuoi un widget più grande.

Importante: inserisci questa chiamata subito sotto lo script del widget, prima che il widget venga caricato. Il widget viene costruito una sola volta, al caricamento, quindi una dimensione impostata dopo viene ignorata.





    onWebChat.set("size","standard");

    onWebChat.set("size","large");

    onWebChat.set("size","xlarge");

Modificare i testi del widget

Puoi sostituire i testi del widget in una pagina specifica, ad esempio un saluto diverso nella pagina dei prezzi. I nuovi testi valgono solo per quella pagina e non vengono salvati nella tua dashboard.

Usa il parametro texts con un oggetto contenente i campi da cambiare, come max_title, max_subtitle, min_online, min_offline, off_title, off_subtitle, off_msg o prechat_msg.

Un testo indicato come stringa viene usato in tutte le lingue del widget. Per cambiare una sola lingua, passa un oggetto con i codici lingua, come nel secondo esempio.

Puoi chiamarla sotto lo script del widget, prima che venga caricato, o in qualsiasi momento successivo: il widget viene ridisegnato con i nuovi testi.




    onWebChat.set("texts",{
        max_title: "Need help?",
        max_subtitle: "We usually reply in a minute"
    });

    onWebChat.set("texts",{
        min_online: { en: "Chat with us", es: "Chatea con nosotros" }
    });

Impostare i colori del widget

In una pagina specifica puoi dare all'intestazione del widget un colore quando la chat è online e un altro quando è offline. Usa i parametri onlineColor e offlineColor con qualsiasi colore CSS, ad esempio "#2e7d32".

I colori valgono solo per quella pagina e non cambiano il colore salvato in Impostazioni > Widget > Impostazioni widget. Puoi impostarli prima che il widget venga caricato o in qualsiasi momento successivo. Il colore offline viene usato anche per il pulsante Invia del modulo offline.





    onWebChat.set("onlineColor","#2e7d32");

    onWebChat.set("offlineColor","#757575");

Impostare le informazioni della pagina

Puoi sovrascrivere l'URL e il titolo della pagina corrente inviati alla dashboard di onWebChat:

Usa il parametro pageUrl per impostare un URL personalizzato. È particolarmente utile per le single-page application (SPA) o il routing personalizzato, dove l'URL del browser non cambia.

Usa il parametro pageTitle per impostare un titolo personalizzato che gli agenti vedranno invece del titolo della pagina del browser.





    onWebChat.set("pageUrl","https://www.example.com/checkout/step-2");

    onWebChat.set("pageTitle","Checkout: shipping details");

Ottenere lo stato del widget

Restituisce "online" o "offline" in base alla disponibilità attuale della chat.

Assicurati di chiamarla dopo il caricamento completo del widget. Ad esempio:
onWebChat.set("onWebChatLoaded", function() { console.log("chat status: " + onWebChat.get("status")); });




    onWebChat.get("status");

Ottenere lo stato della connessione

Restituisce true se il widget di chat ha una connessione socket attiva con il server, o false in caso contrario.




    onWebChat.get("isConnected");

Ottenere lo stato aperto/chiuso del widget

Restituisce true se il widget di chat è attualmente massimizzato (aperto), o false se è minimizzato (chiuso).




    onWebChat.get("isMaximized");

Ottenere l'ID del dialogo

Restituisce l'ID del dialogo attivo corrente, o 0 se non c'è una sessione di chat attiva. È lo stesso ID di chat_id nei payload dei webhook, quindi è utile per le integrazioni che devono collegare una sessione di chat a un CRM o a un sistema di ticketing.




    onWebChat.get("dialogId");

Inviare un messaggio

Puoi inviare un messaggio di chat per conto del visitatore in modo programmatico. Utile per creare flussi di aiuto contestuali, come inviare automaticamente «Ho bisogno di aiuto con il mio ordine» quando il visitatore clicca un pulsante specifico.

Il messaggio compare nella chat esattamente come se il visitatore lo avesse digitato, e la finestra della chat si apre. Il widget deve essere completamente caricato e connesso prima di poter inviare un messaggio. Per evitare abusi, in questo modo il widget invia al massimo 3 messaggi al secondo, 8 al minuto e 30 all'ora.




    onWebChat.set("sendMessage","I need help with my order");

Impostare il dipartimento

Puoi preselezionare un dipartimento per il visitatore in base al contesto della pagina. Ad esempio, puoi indirizzare automaticamente i visitatori della pagina dei prezzi al dipartimento «Vendite» e quelli della pagina di aiuto a «Supporto».

Puoi passare il nome del dipartimento (come stringa) o il suo ID (come numero). Se usi il nome, deve corrispondere esattamente a uno dei dipartimenti configurati nella tua dashboard.

Puoi trovare l'ID del dipartimento nella tua dashboard: vai su Impostazioni > Team > Dipartimenti e clicca su un dipartimento. L'ID viene mostrato accanto al nome del dipartimento.

Non è necessario attivare l'opzione dipartimenti nel modulo pre-chat: l'impostazione del dipartimento tramite l'API JavaScript funziona anche senza.

Se nessun agente del dipartimento selezionato è online, il messaggio viene consegnato a tutti gli agenti connessi. Se il chatbot IA è attivo, non risponde finché un agente del dipartimento è online e risponde al visitatore quando non c'è nessuno.

Per maggiori informazioni sui dipartimenti, consulta la nostra guida ai dipartimenti.




    onWebChat.set("department","Sales");

    onWebChat.set("department",1333);

Funzioni di callback

Puoi eseguire funzioni di callback quando si verificano specifici eventi della chat:

onClick viene eseguito quando il visitatore clicca sul widget di chat.

onMaximize viene eseguito quando il widget viene massimizzato (aperto).

onMinimize viene eseguito quando il widget viene minimizzato (chiuso).

onTrigger viene eseguito quando si attiva un trigger di coinvolgimento o di uscita, anche mentre il widget è nascosto con show impostato a 0.

onStartWriting viene eseguito quando il visitatore inizia a scrivere un messaggio (una volta per sessione del browser).

onNewMessage viene eseguito quando un nuovo messaggio viene inviato o ricevuto. Il callback riceve due argomenti: il testo del messaggio e chi lo ha inviato ("visitor", "agent" o "bot").

onEndChat viene eseguito quando la chat viene terminata. Il callback riceve un argomento: chi l'ha terminata ("visitor", "agent" o "bot").

onChatStatusChange viene eseguito quando lo stato del widget di chat cambia. Il callback riceve un argomento: il nuovo stato ("online" o "offline").

onWebChatLoaded viene eseguito non appena il widget di chat completa il caricamento.




    onWebChat.set("onClick",function(){ alert('chat widget is clicked'); });

    onWebChat.set("onMaximize",function(){ alert('chat maximized'); });

    onWebChat.set("onMinimize",function(){ alert('chat minimized'); });

    onWebChat.set("onTrigger",function(){ alert('trigger activated'); });

    onWebChat.set("onStartWriting",function(){ alert('visitor is writing'); });

    onWebChat.set("onNewMessage",function(msg, by){
        console.log('new message by ' + by + ': ' + msg);
    });

    onWebChat.set("onEndChat",function(endedBy){
        console.log('chat ended by ' + endedBy);
    });

    onWebChat.set("onChatStatusChange",function(status){
        console.log('agents are now ' + status);
    });

    onWebChat.set("onWebChatLoaded",function(){ alert('chat widget is loaded'); });