Passa al contenuto principale

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.

ParametroTipoDescrizione
text_messageStringIl 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.

ParametroTipoDescrizione
objObjectCoppie 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.

ParametroTipoDescrizione
event_nameStringIl nome dell'evento da attivare, corrispondente al nome configurato nel nodo WAIT_FOR_EVENT.
parametersObjectDati 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.

ParametroTipoDescrizione
autoStartBooleanAvvia automaticamente la conversazione al caricamento dello script.
autoStartDelayNumberRitardo in millisecondi prima dell'autostart.
hideButtonBooleanNasconde il pulsante di engagement.
fullPageBooleanL'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​

EventoQuando si attivaPayload 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 })

Argomenti correlati​