Skip to main content

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 the POST /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

  1. The visitor presses the call button on your page.
  2. The page asks your server to start a call. The server calls POST /v1/calls/web with the organization’s API key and gets a session: access_token and url.
  3. 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.
The API key never reaches the browser. Only your server knows it. The page gets a one-time session for one call — it lets the browser into this conversation and nothing else.

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. localhost during 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.
Response — 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

Without a bundler. The package’s 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:
No third-party CDN is needed: everything the SDK requires is inside these files.

Your first call

On the server, an endpoint that calls POST /v1/calls/web and returns the response to the page. An example in Node.js (Express):
The server sets the call variables. If a value comes from the page, accept only the fields you expect yourself — that way a visitor cannot slip foreign data into the scenario. On the page:
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 a VoiceError 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.
Without a bundler — the same files from 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": true in POST /v1/calls/web. The widget tells you when: createSession receives { avatar, avatarQuality }, and avatar is true in '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.posterUrl or 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 startCall fails with WEBRTC_UNSUPPORTED.
  • Content Security Policy. If your site has a CSP, allow: the host the SDK files load from — in script-src and style-src; your server and the address from the session’s url field (HTTPS and WSS) — in connect-src; blob: — in media-src. For the avatar: the placeholder image host — in img-src, the clip host — in media-src; with clips also style-src-attr 'unsafe-inline'.
  • Browsers. WebRTC support is required — every modern desktop and mobile browser has it.