Controllare il widget di MagicAI Chat con JavaScript

In questo articolo imparerai a controllare con JavaScript il widget di MagicAI Chat sul tuo sito web, quali opzioni sono disponibili, come interagiscono con la configurazione della chat e quali limiti valgono.

Contenuti

• Guida rapida
• Prerequisiti
• Esempio introduttivo
• Opzioni di configurazione
• Come interagiscono le tue impostazioni con la configurazione della chat
• Limiti da tenere presenti
• Esempi pratici
• Articoli correlati

Guida rapida

1. Incorpora il widget della chat nel tuo sito web con il codice della scheda informativa Frammento di codice.
2. Nel tuo script richiama window.SpaChatWidget?.configure({ ... }) solo con le opzioni che vuoi modificare.
3. Controlla il valore restituito: true significa che i valori sono stati accettati, false significa che non è stato applicato nulla.
4. Usa window.SpaChatWidget?.open() e window.SpaChatWidget?.close() per aprire o chiudere la chat.

Prerequisiti

• Configurazione della chat pubblicata: una configurazione in modalità bozza non fornisce il codice di incorporamento.
• Widget incorporato: il codice della scheda informativa Frammento di codice è presente sul tuo sito web. Carica lo script del widget con l'identificativo della tua configurazione della chat. Come incorporarlo e quali requisiti tecnici valgono è descritto in Configurare MagicAI Chat.
• Il tuo script viene eseguito dopo il widget: i metodi seguenti sono disponibili solo dopo il caricamento dello script del widget. Se il tuo codice viene eseguito prima, la chiamata viene saltata e non cambia nulla.

Esempio introduttivo

Dopo il caricamento dello script del widget, la tua pagina può usare l'oggetto window.SpaChatWidget. Offre tre metodi: configure(), open() e close().

window.SpaChatWidget?.configure({
  teaserMessage: 'Come possiamo aiutarti?',
  teaserVisible: true,
  suggestions: [
    { buttonText: 'Scopri gli abbonamenti', message: 'Quali abbonamenti sono disponibili?' }
  ]
});

window.SpaChatWidget?.open();  // Apri la chat
window.SpaChatWidget?.close(); // Chiudi la chat

L'operatore ?. rende sicura la chiamata: se il widget non è ancora stato caricato, la chiamata viene saltata invece di causare un errore dello script.

configure() restituisce true quando i valori vengono accettati e false quando non sono validi. Puoi usare il valore restituito per verificare la tua chiamata:

const accepted = window.SpaChatWidget?.configure({ teaserVisible: false });

if (accepted === false) {
  console.warn('Il widget della chat ha rifiutato le impostazioni.');
}

Se il widget non è ancora stato caricato, la chiamata viene saltata e il valore restituito è undefined anziché true o false.

Opzioni di configurazione

Tutte le opzioni sono facoltative. Passa solo quelle che vuoi modificare.

Quando un visitatore fa clic su un suggerimento, la chat si avvia con il testo di message come primo messaggio del visitatore. Se una voce non ha message, viene inviato invece buttonText.

Come interagiscono le tue impostazioni con la configurazione della chat

Senza impostazioni dal tuo sito web, il widget usa il teaser e i suggerimenti della configurazione della chat. Puoi gestirli senza codice nella configurazione della chat, in Impostazioni / MagicAI / Chatbot, scheda informativa Informazioni di base.

• Il contenuto viene sostituito: teaserMessage sostituisce il testo del teaser configurato, suggestions sostituisce l'intero elenco di suggerimenti configurato.
• La visibilità è controllata separatamente: visible, teaserVisible, suggestionsVisible e startscreenSuggestionsVisible funzionano indipendentemente dal contenuto. Se non passi alcuna opzione di visibilità, il widget mostra ciò che fornisce la configurazione della chat.
• Per essere visibile serve un contenuto: impostare un'opzione di visibilità su true non crea un testo del teaser né suggerimenti. Se né il tuo sito web né la configurazione della chat ne forniscono, non viene mostrato nulla.
• Le chiamate vengono unite: una chiamata successiva mantiene le opzioni delle chiamate precedenti e modifica solo quelle che contiene. Ad esempio, una chiamata con solo teaserVisible: false lascia invariato un teaserMessage impostato in precedenza.
• Ritardo: testo del teaser e suggerimenti compaiono accanto al pulsante della chat circa tre secondi dopo il caricamento del widget.
• Teaser chiuso: se un visitatore chiude il teaser, teaser e suggerimenti restano nascosti per il resto di quella sessione del browser. Una chiamata con visible: true, teaserVisible: true o suggestionsVisible: true annulla questo stato e li mostra di nuovo, quindi sovrascrive anche la scelta del visitatore.

Limiti da tenere presenti

• Testo del teaser: max. 500 caratteri.
• Suggerimenti: max. 3, ogni testo del pulsante max. 40 caratteri e non può essere vuoto, ogni messaggio max. 500 caratteri.
• Chiamata non valida: configure() restituisce false se un valore ha il tipo sbagliato, se un limite è superato o se l'argomento non è un semplice oggetto. In tal caso non viene applicato nessuno dei valori della chiamata.
• Accettato non significa caricato: un valore restituito true conferma solo che i valori sono validi. Non significa che la chat abbia finito di caricarsi o che sia iniziata una conversazione.
• Nascondere non chiude: visible: false nasconde il pulsante della chat ma non chiude una chat già aperta. Per chiuderla usa close() oppure isOpen: false.

Esempi pratici

I frammenti seguenti sono esempi. Adatta testi e ID degli elementi al tuo sito web ed esegui il codice dopo il caricamento dello script del widget.

Esempio: aprire la chat da un pulsante personalizzato

<button type="button" id="open-chat">Scrivici in chat</button>

<script>
  document.getElementById('open-chat').addEventListener('click', function () {
    window.SpaChatWidget?.open();
  });
</script>

Esempio: mostrare un teaser specifico per una pagina

Su una pagina dedicata ai corsi, ad esempio, puoi sostituire il testo del teaser configurato con uno adatto:

window.SpaChatWidget?.configure({
  teaserMessage: 'Domande sui nostri corsi? Chiedici pure.',
  teaserVisible: true
});

Esempio: nascondere il pulsante della chat in una pagina

In una pagina in cui il pulsante della chat non deve comparire, ad esempio una pagina di checkout:

window.SpaChatWidget?.configure({ visible: false });

Esegui la chiamata in ogni pagina in cui l'impostazione deve valere.

Articoli correlati

• Configurare MagicAI Chat

Avviso: Questo articolo è stato creato con l'aiuto dell'intelligenza artificiale e tradotto automaticamente senza revisione editoriale. Ci scusiamo per eventuali errori.