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 Ultravox SDK
  • Live caption display during the call

Prerequisites

  • A Truedy API key (create one in Settings → API Keys)
  • 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 Ultravox 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