Browser widget

The browser widget lets a visitor talk to your bot from a web page, with no phone call. The page connects to the gateway over a WebSocket, sends microphone audio up and plays the bot's spoken reply. Browser sessions use the same speech recognition, text to speech and AI brain settings as phone calls, so the bot answers the same way on the web. See AI brain for the brain settings. The language comes from the language value in the page.

If your gateway is run for you, go to Hosted customers.

Enable the endpoint

The browser endpoint is off by default. Add these lines to .env and restart the gateway. If you have not installed the gateway yet, start with Quick start: binary or Quick start: Docker.

WEBSOCKET_AUDIO_ENABLED=true
WEBSOCKET_AUDIO_HOST=127.0.0.1
WEBSOCKET_AUDIO_PORT=8082

Every browser session takes one slot in the same concurrent-call limit as phone calls, which is your licence cap. An open endpoint lets anyone spend your speech and AI provider budget and can crowd out real phone calls. Do these three things before you give out the address:

1. Put a TLS proxy such as nginx in front, so pages connect with wss://. Browsers also require HTTPS before they allow the microphone.
2. Bind the endpoint to 127.0.0.1 and keep port 8082 closed in the firewall.
3. Set an origin allowlist, as described in Secure it.

A minimal nginx location that passes the WebSocket upgrade to the gateway:

location / {
    proxy_pass http://127.0.0.1:8082;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_read_timeout 3600s;
}

The location path is your choice. If you use a path other than /, the page connects to wss://your-domain/that-path.

Secure it

The origin allowlist is the main control. The API key is a lightweight extra gate, because it sits in the page where any visitor can read it.

WEBSOCKET_AUDIO_ALLOWED_ORIGINS=https://www.example.com,*.example.org
WEBSOCKET_AUDIO_API_KEY=choose-a-long-random-string
WEBSOCKET_AUDIO_MAX_PER_IP=5
WEBSOCKET_AUDIO_ALLOWED_BOT_IDS=support,sales

An origin entry is either an exact origin such as https://www.example.com, or a host wildcard such as *.example.org. Wildcards match on the host only, so https://*.example.org is not treated as a wildcard. Write the bare host form, *.example.org.

The per-address limit needs the real visitor address. Behind a proxy on the same host the gateway reads it from X-Forwarded-For, X-Real-IP or CF-Connecting-IP automatically. Behind a proxy on another machine, set HTTP_TRUST_PROXY=true.

What a page may send

When a page starts a session it can send a metadata object. The gateway accepts these:

• language, the speech language code.
• botId, the bot to talk to. If it is not in WEBSOCKET_AUDIO_ALLOWED_BOT_IDS the gateway logs a warning, ignores it and uses the default bot.
• Any other keys you choose, such as a page name or plan. They are passed to the brain as context.

The gateway always removes these keys, because it owns them: userId, user_id, sessionId, session_id, uuid, apiKey, api_key, authorization, __proto__, constructor and prototype. Metadata that is not an object or is larger than 8 KB is rejected. A page cannot choose the TTS provider, model or voice; those come from your .env.

The address may also carry userId, a value you choose to link one visitor's conversations together. Make it unguessable, such as a random UUID. Never use an email address or a sequential number.

Close codes

The SDK does not reconnect on any of these. Your page decides whether to offer a new session.

Add it to a page

The gateway's HTTP port serves the browser SDK as aivg-sdk.js, for example http://your-host:8081/aivg-sdk.js. The Docker image serves it on the HTTP port; binary installs and hosted customers should use the npm package or the copy Vexyl provides. It is also published as the npm package @vexyl.ai/aivg-sdk, which exports AIVoiceGateway. Copy aivg-sdk.js to your own site and load it with a script tag.

<button id="start">Talk</button>
<script src="aivg-sdk.js"></script>
<script>
const voice = new AIVoiceGateway({
    serverUrl: 'wss://your-domain',
    language: 'en-IN',
    autoGreet: true,
    greetingMessage: 'hi',
    onConnect: ({ uuid }) => console.log('Connected:', uuid),
    onTranscript: (text, { isFinal }) => console.log('User:', text),
    onResponse: (text) => console.log('AI:', text),
    onStatus: (status) => console.log('Status:', status)
});

document.getElementById('start').onclick = async () => {
    await voice.connect();
    await voice.startListening();
};
</script>

The snippet calls connect() and startListening() from a button click. Browsers allow the microphone and audio playback only after a user action.

With autoGreet: true the SDK sends greetingMessage (default hi) to the brain once after connecting, so the bot speaks first and the visitor knows to talk. The gateway accepts one greeting per connection and cuts it to WEBSOCKET_AUDIO_GREETING_MAX_CHARS.

The Docker image also serves test pages on its HTTP port (the binary bundle does not include them): /demo.html (full controls), /index.html (waveform) and /3d.html (animated sphere). Open /demo.html first to check the endpoint before you write your own page.

SDK reference

Microphone audio goes up as WebM/Opus. With Google Chirp3-HD voices the reply streams sentence by sentence as it is made, controlled by WS_AUDIO_TTS_STREAMING (default true). Other voices send one audio message per sentence.

Messages from the gateway

The SDK handles these for you. Use them directly only if you write your own client.

Reply audio arrives as binary messages between these. A browser session has no phone leg, so on transfer the session stays open and your page decides what to do, for example show a contact form or a phone number.

The page can send start, stop, mute, unmute, config, greeting, audio_playback_complete and ping. The SDK sends these for you.

Hosted customers

If Vexyl runs your gateway, you do not set the variables above. We give you a wss:// address and an API key, and we allow the origins you list. See Hosted service, then use the page code in the previous section with that address.

Troubleshooting

For problems with the brain's replies, see AI brain. For other issues, see Troubleshooting. The HTTP endpoints are in HTTP API, and what the bot does mid-conversation is in Conversation behaviour. Webhooks and billing records for browser sessions are in Webhooks and billing.