bvoce per sviluppatori
Aggiornato il 17 ottobre 2026
Risposta in breve. bvoce si mette con una riga di JavaScript e si controlla con pochi attributi HTML e una funzione, window.bvoce. Quando la persona apre la chat, lascia un contatto, chiede un appuntamento o chiama, la chat scrive un evento nel dataLayer del tuo sito: lo leggi con Google Tag Manager o a mano, per esempio per GA4 e Meta Pixel.
Cosa trovi in questa pagina
- Gli attributi della riga e dei blocchi, in una tabella.
- La chat incorporata in una sezione della pagina.
- I comandi per aprire e chiudere la chat, e per dirle chi è la persona e cosa sta guardando.
- I quattro eventi del
dataLayer, con gli esempi per GA4 e Meta Pixel. - L'ascolto dei messaggi del browser, le regole per la CSP e il permesso del microfono.
La riga e i suoi attributi
La chat si mette con una sola riga prima di </body>. Il file è piccolo (meno di 5 KB), si carica in modo asincrono, non usa cookie e prepara la chat vera solo quando la persona si avvicina o tocca il bottone. La chiave è pubblica: sta anche nel codice della tua pagina. Quello che decide dove può comparire è l'elenco «Su quali siti» nel pannello bvoce.
| Nome | Dove | Cosa fa |
|---|---|---|
data-chiave | sulla riga <script> | La chiave pubblica del tuo spazio (comincia con bvk_). Obbligatoria: senza, il loader non fa niente. |
data-senza-bottone | sulla riga <script> | Nasconde il bottone tondo e la nuvoletta di benvenuto. Serve con la chat incorporata o con i tuoi pulsanti. |
data-bvoce-alto | sulla riga <script> | Altezza in pixel di una barra fissa in basso: il bottone, la nuvoletta e la chat restano sopra. Vince sulla variabile CSS. |
--bvoce-alto | variabile CSS su :root | Lo stesso, per le barre che compaiono e spariscono: aggiornala quando la barra cambia (0px se non c'è). Il bottone la segue. |
data-bvoce="incorporato" | su un tuo <div> | La chat vera dentro la pagina, al posto del bottone. Altezza minima 560 px, cambiabile con lo stile del div. |
data-bvoce-apri | su un tuo pulsante o link | Al clic apre la chat: scrivi, chiama o video. |
<script src="https://bvoce.blagoweb.com/w.js" data-chiave="bvk_ESEMPIO_la_tua_chiave" async></script><script src="https://bvoce.blagoweb.com/w.js" data-chiave="bvk_ESEMPIO_la_tua_chiave" data-bvoce-alto="80" async></script>La chat dentro la pagina
Per avere la chat in una sezione della pagina, e non il bottone in un angolo, usa la riga senza bottone e un blocco con l'attributo data-bvoce. Puoi metterne più di uno. Il loader cerca i blocchi una volta sola, quando parte: nelle applicazioni a pagina singola il blocco deve essere già nella pagina quando la riga viene caricata.
<!-- 1. La riga senza bottone, in fondo alla pagina -->
<script src="https://bvoce.blagoweb.com/w.js" data-chiave="bvk_ESEMPIO_la_tua_chiave" data-senza-bottone="1" async></script>
<!-- 2. Il blocco, dove vuoi la chat. L'altezza minima di serie è 560 px -->
<div data-bvoce="incorporato" style="min-height: 640px"></div>Comandi: window.bvoce e data-bvoce-apri
Qualsiasi pulsante può aprire la chat con l'attributo data-bvoce-apri. Da codice c'è la funzione window.bvoce. L'identità è facoltativa: passala solo se la persona è già riconosciuta dal tuo sito e ha visto la tua informativa sulla privacy.
<button data-bvoce-apri="scrivi">Scrivici</button>// Apre la chat scritta, la telefonata dal browser o la videochiamata
window.bvoce('apri', 'scrivi');
window.bvoce('apri', 'chiama');
window.bvoce('apri', 'video');
window.bvoce('chiudi');
// Se il tuo sito ha già riconosciuto la persona (area clienti), l'assistente la saluta per nome
window.bvoce('identifica', { nome: 'Mario', email: 'mario@esempio.it', telefono: '+39333...' });
// Dove si trova e cosa sta guardando
window.bvoce('contesto', { pagina: '/prodotto/42', prodotto: 'Lenzuola in lino', carrello: '2 articoli' });<script>
// Se chiami window.bvoce prima che il loader sia pronto, i comandi aspettano in coda e partono appena è caricato.
window.bvoce = window.bvoce || function () {
(window.bvoce.q = window.bvoce.q || []).push(arguments);
};
</script>Eventi nel dataLayer
Quando succede qualcosa, la chat scrive un evento nel dataLayer del tuo sito, con il campo bvoce impostato a 1. Gli eventi sono quattro. Si leggono con Google Tag Manager o con un piccolo ascoltatore. Sono dati di conversione del tuo sito: usali con Google Analytics, Meta o Google Ads solo dopo il consenso, come il resto dei tuoi strumenti.
| Evento | Quando |
|---|---|
bvoce_aperto | la persona apre la chat |
bvoce_contatto | lascia nome e recapito |
bvoce_appuntamento | chiede un appuntamento |
bvoce_chiamata | inizia una chiamata o una videochiamata |
// Quello che bvoce scrive nel dataLayer quando qualcuno lascia un recapito
{ event: 'bvoce_contatto', bvoce: 1, tipo: 'contatto' }Esempio per GA4 e Meta Pixel
Con Google Tag Manager: crea un attivatore di tipo «Evento personalizzato» con il nome dell'evento (per esempio bvoce_contatto), collegalo a un tag «Evento» di GA4 con nome generate_lead e a un tag HTML personalizzato per il Pixel di Meta.
Senza Tag Manager, questo piccolo ascoltatore inoltra gli eventi a gtag.js e al Pixel che hai già nel sito.
<!-- Tag "HTML personalizzato", attivatore "Evento personalizzato" con nome evento bvoce_contatto.
Il Pixel di Meta deve già essere caricato sul sito (dopo il consenso). -->
<script>
if (typeof fbq === 'function') fbq('track', 'Lead');
</script><script>
// Per chi non usa Tag Manager: gtag.js (GA4) e il Pixel di Meta sono già nel sito, caricati dopo il consenso.
window.dataLayer = window.dataLayer || [];
var spingi = window.dataLayer.push;
window.dataLayer.push = function () {
for (var i = 0; i < arguments.length; i++) {
if (arguments[i] && arguments[i].bvoce === 1) inoltra(arguments[i]);
}
return spingi.apply(window.dataLayer, arguments);
};
function inoltra(voce) {
if (typeof gtag === 'function') {
// generate_lead è l'evento raccomandato da GA4 per un contatto; gli altri restano con il nome di bvoce
gtag('event', voce.event === 'bvoce_contatto' ? 'generate_lead' : voce.event, { origine: 'bvoce' });
}
if (typeof fbq === 'function') {
if (voce.event === 'bvoce_contatto') fbq('track', 'Lead');
else if (voce.event === 'bvoce_appuntamento') fbq('track', 'Schedule');
else if (voce.event === 'bvoce_chiamata') fbq('track', 'Contact');
}
}
</script>Messaggi dal browser (postMessage)
La chat gira in un riquadro (iframe) che parla con la tua pagina con postMessage. Quel canale è di bvoce e non va usato per comandare la chat: per quello ci sono window.bvoce e data-bvoce-apri. Puoi però ascoltarlo in sola lettura, per esempio per fare altro quando la persona lascia un contatto. Controlla sempre da dove arriva il messaggio.
window.addEventListener('message', function (e) {
// Solo i messaggi che arrivano davvero da bvoce
if (e.origin !== 'https://bvoce.blagoweb.com') return;
var d = e.data;
if (!d || d.bvoce !== 1) return;
if (d.t === 'evento') {
// d.nome è uno tra bvoce_aperto, bvoce_contatto, bvoce_appuntamento, bvoce_chiamata
console.log('bvoce:', d.nome, d.dati);
}
});Content-Security-Policy e permessi del browser
Se il sito ha una Content-Security-Policy, aggiungi l'indirizzo di bvoce a tre direttive: lo script, la chat (iframe) e la richiesta dell'aspetto. Se imposti anche una Permissions-Policy, lascia il microfono e la camera al riquadro di bvoce, altrimenti telefonata e videochiamata dal browser non partono.
script-src https://bvoce.blagoweb.com
frame-src https://bvoce.blagoweb.com
connect-src https://bvoce.blagoweb.comContent-Security-Policy: script-src https://bvoce.blagoweb.com; frame-src https://bvoce.blagoweb.com; connect-src https://bvoce.blagoweb.com;Permissions-Policy: microphone=(self "https://bvoce.blagoweb.com"), camera=(self "https://bvoce.blagoweb.com")Domande frequenti
Posso provare la chat in locale?
Sì, ma l'indirizzo dal quale la apri deve essere nell'elenco «Su quali siti» del pannello bvoce. Aggiungi localhost (con la porta, se serve) mentre sviluppi e toglilo dopo.
Gli eventi passano dati della persona?
No. L'evento dice solo che è successo qualcosa, con al massimo un campo tipo. Nome, email e telefono restano in bvoce e nelle tue richieste.
Il loader cambia senza avviso?
Il file w.js si aggiorna dal nostro server, per correggere errori e migliorare la chat. Gli attributi e i comandi descritti qui sono quelli supportati.
Posso scaricare w.js e servirlo dal mio dominio?
No: una copia ferma smetterebbe di funzionare quando aggiorniamo la chat. Se ti serve per la CSP, aggiungi l'indirizzo di bvoce, come spiegato sopra.
Dove sono le API per leggere conversazioni e contatti?
Dal pannello, con i collegamenti e i webhook descritti nella pagina Integrazioni. Per un collegamento su misura scrivici.