Skip to main content

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 joinUrl from 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 the joinUrl 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

Use variables 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):
From your backend:

Keeping the API key safe


Next steps