Website widget
Put a voice agent on your own website. Visitors click a button and talk to the agent in their browser. There's no phone number to buy, and visitors never leave your site.
A Voice channel connects the widget to an agent. Each voice channel has:
- the agent it talks to;
- a widget API key (it starts with
vois_pk_) that the embed code uses; - a list of allowed domains that may use the key.
The widget API key is a public key. It is meant to sit in your page's code: it only lets a browser open a widget session with the channel's agent, from the domains you allow.
Set up the widget
- Open your project and go to Channels & numbers.
- Click New channel and choose Voice.
- On the channel page, name the channel and choose its agent.
- Under Widget API key, add your site under Allowed domains, for example
https://www.example.comor*.example.com. - Click Generate key. Copy the key now: it is shown only once. The embed code on the page already contains it.
- Copy the Embed code and paste it into your site, just before the closing
</body>tag. - Set the channel's status to Active and click Save changes.
The widget works for as long as its key is valid. To turn it off, revoke the key on the project's API keys page, or remove the embed code from your site.
The embed code
The console fills in your project, agent and key, and the right hosts for your project's region. Copy it from the channel page rather than typing it. It looks like this:
<!-- VoisX Voice Widget -->
<script src="https://in.app.voisx.ai/chat-widget.js" data-public-key="vois_pk_..." data-api-base="https://in.api.voisx.ai" async></script>
<script>
window.addEventListener("load", function () {
window.VoisChat && window.VoisChat.mount({
projectId: "123",
agentId: "456",
publicKey: "vois_pk_...",
});
});
</script>
The widget draws itself inside a Shadow DOM, so your page's styles don't change it and its styles don't leak into your page.
For a React app, open Settings > Widget in your project, click Get widget code and choose the React version. It gives you a component that loads the script once and mounts the widget.
Restrict the widget to your domains
When a key has Allowed domains, only pages on those domains can open a widget session with it. A request from any other site is refused with 401. Domains can be exact (https://www.example.com) or a wildcard for subdomains (*.example.com).
A key with no allowed domains works on any site. Always add your domains before you go live.
You can't change the domains of an existing key. To apply a new list, click Regenerate key and update the embed code on your site. The previous key keeps working until you revoke it on the project's API keys page.
Open your browser's developer console. A 401 means the page's domain isn't in the key's allowed domains, or the key was revoked. A 429 means the key has reached its request limit for now.
Design the widget
Open your project's Settings > Widget to design how the widget looks. The design applies to every widget embed in the project, and saved changes show up on your site the next time the page loads. You don't need to change the embed code.
| Tab | What you can change |
|---|---|
| Colors | Theme presets, or your own colors for the header, background, chat bubbles, waveforms, buttons and branding bar. |
| Branding | Your agent's logo (PNG, JPEG, WEBP or GIF; square works best). |
| Text | The welcome title and description, the listening text, the connect and disconnect buttons, the font and the corner radius. |
| Features | Whether visitors can drag the widget, minimize it, see live waveforms, and whether the "Powered by" bar shows. |
The Header title is not saved with the design. It goes into the embed code, so copy the code again after you change it.
Recognise signed-in visitors
If the agent has memory turned on, the widget remembers each visitor per browser. To recognise your signed-in users on any device, pass their user ID and a signature that your server makes with the channel's widget identity secret:
userHash = hex(HMAC-SHA256(widget identity secret, userId))
- On the channel page, under Signed-in visitors, click Reveal secret and copy it into your server's configuration.
- On your server, compute
userHashfor the signed-in user. - Add
userIdanduserHashto theVoisChat.mount()call. You can also set them asdata-user-idanddata-user-hashon the script tag. Either way, keep theVoisChat.mount()call from the embed code: the script doesn't start the widget on its own.
- mount()
- Script attributes
window.VoisChat.mount({
projectId: "123",
agentId: "456",
publicKey: "vois_pk_...",
userId: "user-8812", // rendered by your server
userHash: "3f1c9a…", // rendered by your server
});
<script
src="https://in.app.voisx.ai/chat-widget.js"
data-public-key="vois_pk_..."
data-api-base="https://in.api.voisx.ai"
data-user-id="user-8812"
data-user-hash="3f1c9a…"
async
></script>
Leave both out for visitors who aren't signed in. Unsigned user IDs are ignored unless the agent allows them. For signing code in Node.js and Python, see Agent memory: identify signed-in users.
Never put the widget identity secret in page code, a mobile app or a public repository. If it leaks, click Rotate secret. Signatures made with the old secret stop working at once, so signed-in visitors are treated as anonymous until your server uses the new secret.
Call settings in the widget
Most of the agent's Call Settings also apply in the browser: end-call phrases, hang up after silence, max call duration, silence timeout and barge-in sensitivity. Live transfer and keypad input are phone-only. If call recording is on for your organization, widget calls are recorded too. See Phone numbers: call settings.
Gate the chat behind a form
A Form channel shows a form on your site. It runs in one of two modes:
- Lead capture. Submissions are stored and shown on the channel's Submissions tab. Nothing happens after submit.
- Live chat. The form is a gate. After the visitor submits it, they talk to the channel's agent.
For Live chat, embed the widget with the form channel's ID instead of an agent ID. Use a widget API key from the same project that allows the form channel's agent, for example the key of a voice channel for that agent. The widget shows the form first and connects to the agent once it's submitted:
<script src="https://in.app.voisx.ai/chat-widget.js" data-public-key="vois_pk_..." data-api-base="https://in.api.voisx.ai" async></script>
<script>
window.addEventListener("load", function () {
window.VoisChat && window.VoisChat.mount({
projectId: "123",
channelId: "789",
publicKey: "vois_pk_...",
});
});
</script>
Use your project's region hosts, as in the embed code the console gives you for a voice channel. The channel ID is the number after ch_ on the channel page.
A form channel only works while its status is Active.
Other ways to reach an agent
- Phone numbers: give the agent a phone number, with no web integration.
- Bring your own carrier (SIP): connect numbers you already have.
- WhatsApp: let the agent answer messages on your WhatsApp Business number. Create a WhatsApp channel in Channels & numbers.