Installing the Netcoder AI voicebot on your website

Installation guide • Voicebot

The Netcoder voicebot is a lightweight widget you add to any website with a single tag of HTML. Visitors talk to your AI agent out loud, right in their browser, with no phone and nothing to install: they click, allow the microphone, and speak as they would on the phone. The agent answers by voice, and the conversation is shown on screen as it happens.

1. Installation

Add the following script tag just before the closing </body> tag on every page where the voicebot should appear. Replace the placeholder values with the ones for your account (see section 4).

<script src="https://cdn.netcoder.com/voicebot.v1.3.js"
        data-backend-url="wss://relay.netcoder.ca/voice"
        data-client-key="YOUR-CLIENT-GUID"
        data-agent-key="YOUR-AGENT-GUID"
        data-language="en"></script>

That is all that is required. It places a floating phone button in the bottom-right corner of the page; the call card, the audio, the styling and the conversation are provided by the script, and nothing else needs to be installed on your server.

The simplest way to get it is from the Netcoder app: open your AI agent, then Test & Deploy, Integration code. The code is shown with your keys already filled in, ready to copy.

Two conditions apply: the page must be served over HTTPS, as browsers only give a page the microphone on a secure connection, and your AI agent must have a Web Voice channel, which Netcoder sets up.

2. Display styles

The same script offers three ways to present the voicebot, chosen with the data-container and data-collapsed attributes.

Floating button (default)

Without data-container, the voicebot is a round phone button fixed in the bottom-right corner, like a chat bubble. A click opens the call card above it.

Beside the chatbot — when the Netcoder chatbot is on the same page, the phone button moves to the left of the chat bubble instead of covering it. The two scripts can be in any order.
One panel at a time — the call card and the chat window open in the same corner, so opening one closes the other.
A call is never forgotten — if the visitor hides the card during a call, the call goes on and the phone button turns green and pulses until it ends. Closing the card with its × button hangs up.

Inline card

With data-container, the full card is drawn inside an element of your page instead, for example on a demo or a contact page. Add an empty element where the card should appear, and point data-container at it with a CSS selector:

<div id="voice-demo"></div>
<script src="https://cdn.netcoder.com/voicebot.v1.3.js"
        data-backend-url="wss://relay.netcoder.ca/voice"
        data-client-key="YOUR-CLIENT-GUID"
        data-agent-key="YOUR-AGENT-GUID"
        data-language="en"
        data-container="#voice-demo"></script>

The card takes the full width of its container, up to 420 px, centred in it. If the selector matches nothing, the script falls back to the floating button.

Compact inline card

Add data-collapsed="true" to an inline card to start it as a single row — the title, the status and a smaller call button — that opens into the full card when the call starts. It suits a sidebar or a narrow column.

<script src="https://cdn.netcoder.com/voicebot.v1.3.js"
        ...
        data-container="#voice-contact"
        data-collapsed="true"></script>

3. Configuration parameters

Set on the script tag.

Attribute	Required	Description	Default
`data-backend-url`	Yes	Address of the Netcoder relay: `wss://relay.netcoder.ca/voice`
`data-client-key`	Yes	Your client key
`data-agent-key`	Yes	The key of your AI agent, which needs a Web Voice channel
`data-language`		`en` or `fr`: the card, what is heard and the voice	`en`
`data-title`		Name shown on the card	Assistant Netcoder
`data-subtitle`		Line under the title
`data-welcome`		First sentence of the agent, 300 characters at most	That of the language
`data-accent-color`		Main colour	`#D97955`
`data-accent-text-color`		Colour of the text on the main colour	`#FFFFFF`
`data-container`		CSS selector of the element to draw the card in	Floating button
`data-collapsed`		`true`: an inline card starts as one row
`data-debug`		`true`: logs the call in the browser console

4. Getting your keys

The client key and the agent key are GUIDs that identify your account and the AI agent that answers, for example 3f2a7b10-9c4d-4e21-8a6f-1b2c3d4e5f60. Both are shown in the Netcoder app, on the page of your AI agent, under Test & Deploy, Integration code, each with a button to copy it. The voicebot and the chatbot share the same keys: the same agent answers both, with the same knowledge and the same rules.

If a key is missing or malformed, the card shows “Invalid configuration: data-client-key and data-agent-key must be valid GUIDs.” when the visitor starts a call, and the server is not contacted. If the keys are valid but not recognized, or the agent has no Web Voice channel, the call does not go through: check the values in the app.

5. Language and voice

The data-language attribute sets the language of the card (status, buttons, messages), the language the speech is transcribed in, the language the agent answers in, and the voice it speaks with:

en — English (default).
fr — French.

Use only these two values. On a bilingual website, set the matching language on each page, and match data-title and data-welcome to it.

The voice of the agent is chosen in the Netcoder app, in the Voice section of the page of your AI agent, after listening to each voice in French and in English: a Quebec, French or international French, a Canadian, American or British English, a man's or a woman's voice. There is nothing to change in the code of your page.

6. Using it with the chatbot

The voicebot is designed to sit next to the Netcoder chatbot, so visitors choose between typing and talking. Add both scripts to the page; with the same keys, the same agent answers both:

<script src="https://cdn.netcoder.com/chatbot.v2.2.js"
        data-backend-url="wss://relay.netcoder.ca/chatbot"
        data-client-key="YOUR-CLIENT-GUID"
        data-agent-key="YOUR-AGENT-GUID"
        data-language="en"></script>
<script src="https://cdn.netcoder.com/voicebot.v1.3.js"
        data-backend-url="wss://relay.netcoder.ca/voice"
        data-client-key="YOUR-CLIENT-GUID"
        data-agent-key="YOUR-AGENT-GUID"
        data-language="en"></script>

The phone button places itself to the left of the chat bubble, and only one of the two panels is open at a time. Note the two endpoints: /chatbot for the chatbot, /voice for the voicebot.

7. Styling with CSS

For more than the title and the two colours, style the widget from your own stylesheet. Its styles load after yours: start your selectors with body to win, rather than using !important.

body #ncv-launcher { bottom: 96px; }

Selector	What it is
`--ncv-accent`	Variable: the main colour, from `data-accent-color`
`--ncv-on-accent`	Variable: the text on it, from `data-accent-text-color`
`#ncv-launcher`	The floating phone button, 60 × 60 px
`#ncv-popup`	The floating panel, 360 px wide; `ncv-open` when open
`.ncv-card`	The card; `data-state` gives the state of the call
`.ncv-transcript`	The conversation; `.ncv-msg` with `.ncv-user` or `.ncv-agent`
`.ncv-call`	The call button, green, red during a call

White text on the default #D97955 is below the WCAG AA contrast of 4.5:1: darken the accent, or use a dark text colour such as #1B1B1B.

8. How it works

When the visitor starts a call, the browser asks for the microphone. The widget then streams the audio over a secure WebSocket to the Netcoder relay, which transcribes it as the visitor speaks; the words appear on the card as they are recognized. When the visitor pauses, the sentence goes to your AI agent, and its answer is turned into speech and streamed back, so the agent starts speaking within moments.

Interruptions — the visitor can talk over the agent at any time, as on the phone: it stops speaking and listens.
Time limit — calls are limited in length, five minutes at present. The card shows the time elapsed against the limit, and the agent says goodbye when it is reached.
Busy lines — the number of calls at the same time is limited. When every line is taken, the visitor is asked to try again in a few minutes.
Ending the call — the call ends when the visitor hangs up, closes the floating card, or leaves the page.
If speech fails — if the voice is unavailable, the call goes on and the answers are shown as text on the card.

9. Testing and troubleshooting

Test before you install — in the Netcoder app, Test & Deploy on the page of your AI agent calls it exactly as your visitors will.
The button does not appear — check that the script URL is reachable and that the code is placed before </body>. After changing the code, hard-refresh the page (Ctrl+Shift+R).
Microphone access denied — the visitor refused the microphone, or blocked it earlier. The card says so; it can be allowed again from the lock icon of the address bar.
The microphone is not offered at all — the page is not served over HTTPS. Browsers only allow the microphone on secure pages (and on localhost for development).
“Cannot reach the assistant” — the relay could not be reached or refused the call. Check the keys, the backend URL, and that the agent has a Web Voice channel.
Nothing happens on an https:// page — the backend URL must start with wss://, not ws://.
Browser not supported — the voicebot needs a recent Chrome, Edge, Firefox or Safari. Older browsers get a message instead of a call.
The agent does not hear the visitor — add ?ncv-debug to the address of the page, or data-debug="true" to the script tag, and open the browser console during a call. It shows the microphone used, the sound level sent every two seconds, and every message of the relay. A level that stays at 0.000 while the visitor speaks means the browser uses the wrong microphone, or a muted one.
Any domain works — the voicebot can be embedded on any website; nothing needs to be configured on your server.

10. Complete example

A floating voicebot with every option set:

<script src="https://cdn.netcoder.com/voicebot.v1.3.js"
        data-backend-url="wss://relay.netcoder.ca/voice"
        data-client-key="3f2a7b10-9c4d-4e21-8a6f-1b2c3d4e5f60"
        data-agent-key="a1b2c3d4-e5f6-4788-9a0b-1c2d3e4f5a6b"
        data-language="en"
        data-title="Alicia"
        data-subtitle="Customer service"
        data-welcome="Hello, I'm Alicia. How can I help you?"
        data-accent-color="#D97955"
        data-accent-text-color="#FFFFFF"></script>

Need help, or a Web Voice channel for your agent? Book a meeting or write to us.