How-to guide

Voice button on your website

Add a button that lets a visitor talk to your agent, follow the call from your own page, and match the button to a dark card.

What you'll learn

How to put the voice button on a page, restyle it for a dark card, and listen for the call's state from your own code. Create the publishable key and copy the snippet from the dashboard: the key is bound to the agent that answers, and the page never chooses an agent or a prompt.

Add the button

The snippet is one script tag whose source is /v1/public-sessions/embed.js on the VoiceLayer API. Copy it from the dashboard with your key filled in, then set these attributes on it:

AttributeWhat it does
data-vl-keyThe publishable key with the voice surface. Required.
data-vl-mountA selector for the element the button is placed in. Without it the button floats at the bottom right of the page.
data-vl-labelThe button's text. Default "Talk to us".
data-vl-noticeThe note under the button. Default says the call is with an AI agent and may be recorded.
data-vl-tonedark restyles the button for a dark card: a full-width button on a transparent ground, with a quiet outlined End call. Anything else keeps the default.

Before anything is created and before the browser asks for the microphone, the visitor sees what they agree to, with Cancel and I agree. Cancel creates nothing. The tone changes only how the button looks: the consent step, its wording and its order stay the same.

Follow the call from your page

The button dispatches events on the mount element (or on the floating host when there is no mount). They bubble and cross the shadow boundary, so you can listen on the mount or on document.

EventWhen
voicelayer:connectingThe visitor agreed and the session is being made.
voicelayer:listeningConnected (the call is live and the microphone is granted), and the agent is not speaking.
voicelayer:speakingThe agent is speaking.
voicelayer:endedThe call is over. detail.reason says why.

Every event carries detail.state. voicelayer:ended adds detail.reason:

ReasonMeaning
hangupThe visitor pressed End call.
remoteThe room closed or the agent hung up.
limitThe call reached its time limit.
errorSomething failed after the visitor agreed, such as the microphone being blocked.
const talk = document.querySelector('#talk');
talk.addEventListener('voicelayer:speaking', () => card.classList.add('is-speaking'));
talk.addEventListener('voicelayer:listening', () => card.classList.remove('is-speaking'));
talk.addEventListener('voicelayer:ended', (e) => console.log('call ended:', e.detail.reason));

Loudness: voicelayer:level

For a page that moves with the voices, the button also dispatches voicelayer:level on the same element, about 20 times a second while the call is live:

talk.addEventListener('voicelayer:level', (e) => {
  const { agent, user } = e.detail; // each 0 to 1, smoothed
  meter.style.transform = `scale(${1 + agent * 0.2})`;
});

agent is the loudness of the agent's voice and user the visitor's microphone, measured in the visitor's browser with the Web Audio API (RMS). Only those two numbers leave the analyser: no audio is recorded, stored or sent, and nothing runs before the visitor agrees. The audio context starts in their click on I agree and is closed when the call ends. If the browser cannot measure, the call works as before and only the state events above arrive.

Nothing is dispatched before the visitor agrees, and a visitor who declines at the consent step produces no event. A handler that throws never affects the call.

On this page