Widget

Embeddable Voice Widget

Add a voice AI agent to any website with a few lines of code

The ThunderPhone embeddable voice widget lets your website visitors talk to an AI agent directly from the browser. No phone call required -- users click a button and start a real-time voice conversation powered by ThunderPhone.

The widget renders as a glassmorphic bar that adapts to light and dark themes, with customizable accent colors and positioning. It is distributed as the @thunderphone/widget npm package and is also available via CDN for non-bundler environments.

Prerequisites#

Before embedding the widget, complete these three steps in the ThunderPhone Dashboard:

1. Create a publishable API key

   Go to Developers in the dashboard settings and create a publishable key. Publishable keys start with pk_live_ and are safe to include in client-side code.

2. Configure allowed domains

   In the same Developers settings, add the domains where the widget will be embedded. localhost is always allowed for development. Wildcards are supported (e.g., *.example.com).

3. Create a web widget

   Go to Web Widgets in the dashboard and create a widget. Select the agent you want to expose and the publishable key to use. The agent is resolved automatically from your publishable key configuration.

Quick Start#

Install the package:

npm install @thunderphone/widget

Drop the widget into your app:

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      theme="dark"
      primaryColor="#8b5cf6"
    />
  )
}

That's it. Your users will see a glassmorphic call bar that connects them to your AI agent with a single click.

Customization#

The widget has four appearance props:

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
/>

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  theme="dark"
  primaryColor="#8b5cf6"
  title="Ask our AI"
/>

Three more props customize the session rather than the look -- all are forwarded to the session request when a call starts:

See the React component reference for the full props table.

For a fully custom UI, use the headless hook to manage the voice session while you build your own interface. The hook exposes real-time audio levels for building audio-reactive visualizations.

Integration Options#

Choose the integration method that fits your stack:

Styling#

The widget ships with built-in light and dark themes controlled by the theme prop, and an accent color controlled by the primaryColor prop. For deeper customization, you can override CSS custom properties and classes. See the Styling guide for details.