Building a Custom Voice Widget
This guide walks through building a full voice widget from scratch β a floating button on your website that lets visitors speak with a Truedy AI agent in real time, with live captions.What youβll build
- A βTalk to AIβ button on your website
- Server-side endpoint that fetches a
joinUrlfrom Truedy (keeps your API key safe) - Browser JS that connects audio using the browser voice SDK
- Live caption display during the call
This is the custom UI flow. Your server creates a WebRTC call through
Truedyβs public API, then your browser joins the returned URL with the
browser voice client SDK. It does not use Truedyβs managed-widget capability
token. Capability authorization is used only by the hosted
widget.js
runtime for saved widget configurations.Prerequisites
- A Truedy API key (create one in Settings β API Keys). Workspace-scoped keys can be used directly; account-scoped master keys also require
TRUEDY_WORKSPACE_ID. - A Truedy agent (create one in the dashboard)
- Node.js backend (examples use Express, but any server works)
Step 1 β Create a server-side endpoint
Your backend holds the API key and proxies thejoinUrl request. Never expose your Truedy API key in frontend code.
Step 2 β Install the browser voice SDK
Step 3 β Frontend widget
Step 4 β Style the widget (optional)
Passing context to the agent
Usevariables to give the agent information about the current visitor. Any {{placeholder}} in your agentβs prompt is replaced at call time:
Agent instructions (set in Truedy dashboard):
Keeping the API key safe
Next steps
- Calls API reference β full Web Call endpoint docs
- Agents β manage agents via API
- Webhooks β get notified when calls end and receive transcripts

