Skip to main content
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.
ThunderPhone widget in light and dark themes with various accent colors

​
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.
Publishable keys (pk_live_...) are not the same as your secret API tokens. Publishable keys are designed for client-side use and are scoped to widget sessions on your allowed domains. Never use your secret API token in client-side code.

​
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 key customization props:
PropDefaultDescription
theme'light''light' for white glass, 'dark' for dark glass
primaryColor'#000000' (light) / '#ffffff' (dark)Accent color for the start button, waveform, and connecting indicator
title'Voice assistant'Text displayed in the widget
position'bottom-right'Viewport corner: 'bottom-right', 'bottom-left', 'top-right', 'top-left'
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
/>
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:

React Component

Pre-built UI component with built-in call controls and status display. Import, pass props, done.

Headless Hook

Full control over the UI. The useThunderPhone hook manages the voice session while you build your own interface.

CDN / Script Tag

No bundler required. Load the widget via a script tag for static sites, WordPress, and other non-React environments.

​
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.
Need help? Contact us at support@thunderphone.com