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 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

Enable the widget on your agent

Open the agent you want to use and toggle on Embeddable Widget. Only agents with this toggle enabled can be connected to via the widget.
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
      apiKey="pk_live_your_publishable_key"
      agentId={123}
    />
  )
}
That’s it. Your users will see a call button that connects them to your AI agent with a single click.

​
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 default widget UI is fully customizable with CSS. See the Styling guide for available CSS classes and examples.
Need help? Contact us at support@thunderphone.com