Web SDK - Riferimento JavaScript per l'Integrazione Web Chat ConvyAI
Panoramica
Il Web SDK di ConvyAI espone un'interfaccia JavaScript che permette al tuo sito di interagire con il bot in modo programmatico - senza utilizzare direttamente l'interfaccia del widget chat. Usalo per avviare conversazioni automaticamente, passare dati del cliente, attivare eventi del bot e ricevere notifiche sul ciclo di vita della conversazione.
Tutte le funzioni SDK sono disponibili dopo che lo snippet HTML è stato incluso nella pagina, tramite:
window.ConvyAI.nome_funzione(parametri)
Lo scambio di dati tra la pagina e l'interfaccia bot avviene tramite postMessage.
Funzioni
startConversation()
Avvia la conversazione con il bot. Equivalente al cliente che clicca il pulsante di engagement.
window.ConvyAI.startConversation()
endConversation()
Termina la conversazione in corso.
window.ConvyAI.endConversation()
sendMessage( text_message )
Invia un messaggio di testo al bot per conto del cliente.
| Parametro | Tipo | Descrizione |
|---|---|---|
text_message | String | Il testo da inviare come messaggio del cliente. |
window.ConvyAI.sendMessage('Ho bisogno di aiuto con il mio ordine')
attachData( obj )
Invia dati del cliente al bot prima dell'avvio della conversazione. I dati vengono allegati alla successiva chiamata startConversation() e resi disponibili come variabili nel flow.
| Parametro | Tipo | Descrizione |
|---|---|---|
obj | Object | Coppie chiave-valore dei dati cliente da passare come variabili. |
window.ConvyAI.attachData({ customerId: '12345', plan: 'premium' })
window.ConvyAI.startConversation()
sendEvent( event_name, parameters )
Attiva un evento del bot. Da usare quando un nodo del flow è configurato per attendere un evento esterno.
| Parametro | Tipo | Descrizione |
|---|---|---|
event_name | String | Il nome dell'evento da attivare, corrispondente al nome configurato nel nodo WAIT_FOR_EVENT. |
parameters | Object | Dati opzionali da passare con l'evento. Disponibili come variabili nel nodo WAIT_FOR_EVENT. Passa {} se non sono necessari dati. |
window.ConvyAI.sendEvent('payment_confirmed', { orderId: 'ORD-789', amount: 42.00 })
init( init_parameters )
Definisce i comportamenti del bot prima dell'avvio della conversazione. Chiamare prima di startConversation().
I valori di init_parameters vengono uniti ai parametri della query string. Se lo stesso parametro è specificato in entrambi i modi, init() ha la precedenza.
| Parametro | Tipo | Descrizione |
|---|---|---|
autoStart | Boolean | Avvia automaticamente la conversazione al caricamento dello script. |
autoStartDelay | Number | Ritardo in millisecondi prima dell'autostart. |
hideButton | Boolean | Nasconde il pulsante di engagement. |
fullPage | Boolean | L'interfaccia del bot occupa l'intera pagina. |
window.ConvyAI.init({ hideButton: true, autoStart: true, autoStartDelay: 3000 })
getVersion()
Restituisce la stringa della versione corrente della GUI.
const version = window.ConvyAI.getVersion()
listen
Si iscrive agli eventi del ciclo di vita della conversazione. Ogni listener accetta una funzione di callback che viene chiamata quando l'evento si verifica.
window.ConvyAI.listen.nome_evento(funzioneCallback)
Eventi disponibili
| Evento | Quando si attiva | Payload callback |
|---|---|---|
conversationCreated() | La conversazione inizia. | { type: 'conversationCreated' } |
conversationClosed() | La conversazione termina. | { type: 'conversationClosed' } |
messageReceived() | Un messaggio viene ricevuto. | { type: 'messageReceived', message: String } |
eventReceived() | Un evento del bot viene ricevuto. | { type: 'eventReceived', ...parametriEvento } |
handoverStarted() | L'handover verso l'agente inizia. | { type: 'handoverStarted' } |
handoverSuccessful() | L'handover si completa con successo. | { type: 'handoverSuccessful' } |
handoverClosed() | La sessione di handover termina. | { type: 'handoverClosed' } |
handoverFailed() | L'handover fallisce (es. timeout queue). | { type: 'handoverFailed' } |
Tutti i callback ricevono un oggetto con una chiave type che indica il nome dell'evento.
Esempi
Bot a schermo intero al caricamento:
window.ConvyAI.init({ fullPage: true })
Ascolto della fine della conversazione:
window.ConvyAI.listen.conversationClosed(function(event) {
console.log('Conversazione terminata', event)
})
Passaggio dati CRM e autostart:
window.ConvyAI.attachData({ email: 'utente@esempio.it', tier: 'gold' })
window.ConvyAI.init({ autoStart: true, autoStartDelay: 1000 })