Calls from your website: Web SDK
A visitor to your website presses a button and talks to the agent from the browser — over the microphone, with no phone line. This is what thePOST /v1/calls/web endpoint and the @hubtalk-ai/web-sdk browser SDK are for; the SDK also ships a ready-made widget: a button in the corner of the page and a call panel.
If someone just needs to talk to the agent and nothing has to be embedded, a demo link is enough. The Web SDK is for when the call starts on your website, on your domain, with variables your system knows.
How it works
- The visitor presses the call button on your page.
- The page asks your server to start a call. The server calls
POST /v1/calls/webwith the organization’s API key and gets a session:access_tokenandurl. - The server hands the session to the page, and the page passes it to the SDK. From there the conversation runs directly between the browser and the platform, and the call state reaches the page as events.
What you need first
- The agent is published. The published version takes the call; a draft does not connect. A web call needs no telephony binding.
- An API key is issued — the API keys section, see Access key. The key stays on your server.
- The page is served over HTTPS. Without a secure connection the browser does not grant the microphone.
localhostduring development is the exception.
POST /v1/calls/web
Creates a web call and issues a session for the browser. Your server makes the request, with the Authorization: Bearer <API key> header.
201 Created: the call object plus three session fields.
You can hand the whole response to the page and pass it to the SDK as is: the SDK ignores extra fields.
Errors
Key and rate limit errors common to all endpoints are in Errors.
Retries. The
Idempotency-Key header protects against a double call on retries: a repeat with the same key within 24 hours returns the same session, and no second call is made. One retry key per call: the next visitor needs a new one.
One session per call. The token lives 2 hours and is never refreshed, so issue a new session for every call rather than holding one on an open page.
The call in History and webhooks
A web call shows up in History right away as an active conversation on the Web call channel (channel: "web", direction: "web"). Transcript, recording, post-call analysis and webhooks work as for a phone call. In the scenario, {{direction}} equals web — the agent can use it to talk to a website visitor differently than on the phone.
The lifecycle is shorter than a phone call’s: queued → ongoing → ended, with no ringing and no failed. Number and trunk fields of a web call are empty, answered_at is null.
Installing the SDK
dist folder holds ready-made files for a plain <script> tag: voice-client.bundle.js — the client, widget.bundle.js and widget.css — the widget. Host them on your own server:
Your first call
On the server, an endpoint that callsPOST /v1/calls/web and returns the response to the page. An example in Node.js (Express):
Call
startCall inside a click handler. The browser allows the agent’s audio and the microphone only after a user action. On iPhone Safari a network request between the click and startCall() can use up that action — in that case fetch the session ahead of time, for example when the call panel opens.VoiceClient
Options
new VoiceClient(options?) — every option is optional.
Methods
Events
Text-only calls
startCall(session, { audio: false }) starts the same call with no microphone and no sound: the browser asks for no permissions, and the conversation runs in text through sendText() and transcript events. This is the mode for a visitor who cannot or does not want to speak aloud. The agent’s replies arrive at speaking pace.
SDK errors
Every failure is aVoiceError object: { code, message, state, cause? }. Decide by code; message is a line for logs, and the visitor-facing text is yours.
The ready-made widget
If you do not need your own layout, the package has a widget: a button in the corner of the page and a call panel with the agent’s state, a timer, microphone and end buttons, a chat and the transcript after the call. Widget texts are in English or Russian.dist:
The widget styles come in a separate
widget.css file and apply only inside the widget — they do not change the look of your page.
Live avatar
In'avatar' mode the panel shows live video of an AI avatar: a face that speaks with the agent’s voice, in sync with the speech. The video travels over the same connection as the audio.
- Platform support turns the avatar on for the agent and sets which face appears in the call. Write to support naming the agent that needs the avatar, and ask which face was chosen.
- Your server asks for the avatar with
"avatar": trueinPOST /v1/calls/web. The widget tells you when:createSessionreceives{ avatar, avatarQuality }, andavataristruein'avatar'mode. This is a request, not a guarantee: if the agent has no avatar turned on, the call is audio-only, and the API response does not change. - The placeholder is yours. While there is no video — before the call, in the first seconds, when the video drops — the stage shows your image
avatar.posterUrlor a pair of silent clips. Pick a placeholder that looks like the avatar’s face, or the switch will be noticeable.
While the video plays, an AI avatar label shows on it. If your jurisdiction requires telling visitors they are talking to AI, that stays on your side: the label helps but does not replace such a notice.
Without the widget, the same video is available in
VoiceClient: the agentVideoChanged event ({ available }) says whether video is there, and attachAgentVideo(element) puts it into your <video>.
Page requirements
- HTTPS. Without a secure connection the browser does not grant the microphone, and
startCallfails withWEBRTC_UNSUPPORTED. - Content Security Policy. If your site has a CSP, allow: the host the SDK files load from — in
script-srcandstyle-src; your server and the address from the session’surlfield (HTTPS and WSS) — inconnect-src;blob:— inmedia-src. For the avatar: the placeholder image host — inimg-src, the clip host — inmedia-src; with clips alsostyle-src-attr 'unsafe-inline'. - Browsers. WebRTC support is required — every modern desktop and mobile browser has it.