Vai al contenuto

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.

Attributi e variabili
NomeDoveCosa fa
data-chiavesulla riga <script>La chiave pubblica del tuo spazio (comincia con bvk_). Obbligatoria: senza, il loader non fa niente.
data-senza-bottonesulla riga <script>Nasconde il bottone tondo e la nuvoletta di benvenuto. Serve con la chat incorporata o con i tuoi pulsanti.
data-bvoce-altosulla 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-altovariabile CSS su :rootLo 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-aprisu un tuo pulsante o linkAl clic apre la chat: scrivi, chiama o video.
La riga di base
<script src="https://bvoce.blagoweb.com/w.js" data-chiave="bvk_ESEMPIO_la_tua_chiave" async></script>
Con una barra fissa in basso di 80 pixel
<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.

Chat incorporata
<!-- 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.

Un pulsante che apre la chat
<button data-bvoce-apri="scrivi">Scrivici</button>
Il codice completo
// 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' });
Per chiamarla prima che il loader sia pronto
<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.

Gli eventi nel dataLayer
EventoQuando
bvoce_apertola persona apre la chat
bvoce_contattolascia nome e recapito
bvoce_appuntamentochiede un appuntamento
bvoce_chiamatainizia una chiamata o una videochiamata
Come arriva un evento
// 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 per il Pixel di Meta, in Tag Manager
<!-- 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>
Senza Tag Manager: GA4 e Meta Pixel
<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.

Ascolto in sola lettura
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.

Le tre voci, ognuna nella sua direttiva
script-src https://bvoce.blagoweb.com
frame-src https://bvoce.blagoweb.com
connect-src https://bvoce.blagoweb.com
Per esempio, in una sola riga
Content-Security-Policy: script-src https://bvoce.blagoweb.com; frame-src https://bvoce.blagoweb.com; connect-src https://bvoce.blagoweb.com;
Permissions-Policy, se la usi
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.

Senti come risponde bvoce con i dati della tua attività.

Parla con noiSenti come risponde