Embed a ThunderPhone voice AI agent on any website. Users can talk to your agent directly from your site using their browser microphone.

npm install @thunderphone/widget

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
    />
  )
}

1. Log in to app.thunderphone.com
2. Go to Developers to create a publishable API key and configure allowed domains
3. Create a Web Widget and select the agent you want to expose
4. Use your publishable key in the widget code above

Use the useThunderPhone hook to build a completely custom UI while the widget handles the voice connection.

import { useThunderPhone } from '@thunderphone/widget'

function CustomCallButton() {
  const phone = useThunderPhone({
    publishableKey: 'pk_live_your_publishable_key',
  })

  const handleClick = () => {
    if (phone.state === 'connected') {
      phone.disconnect()
    } else {
      phone.connect()
    }
  }

  return (
    <>
      <button onClick={handleClick} disabled={phone.state === 'connecting'}>
        {phone.state === 'connecting'
          ? 'Connecting...'
          : phone.state === 'connected'
            ? 'End call'
            : 'Start call'}
      </button>
      {phone.audio}
    </>
  )
}

Important: Always render phone.audio somewhere in your component tree. It's an invisible element that handles the audio connection.

Play a ringing sound while the widget connects, to simulate a phone call:

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  ringtone={true}
/>

Use a custom audio file by passing a URL:

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  ringtone="https://example.com/my-ringtone.mp3"
/>

The ringtone loops during the connecting state and fades out when the agent connects. It is opt-in and disabled by default.

The headless hook accepts the same option:

const phone = useThunderPhone({ publishableKey, ringtone: true })

And the script-tag mount API:

ThunderPhone.mount({ element: '#thunderphone', publishableKey: '...', ringtone: true })

The widget uses plain CSS with tp- prefixed classes, so it won't conflict with your styles. You can override any of these classes:

Example — custom colors:

.tp-button--start {
  background: #4f46e5;
}
.tp-button--start:hover {
  background: #4338ca;
}

Your publishable key can be restricted to specific domains in the Developers settings page. Requests from unlisted domains will be rejected. localhost is always allowed for development.

Wildcard subdomains are supported: *.example.com matches app.example.com, docs.example.com, etc.

If you're not using a bundler, you can load the widget via script tag. This version bundles React internally so no dependencies are needed.

<link rel="stylesheet" href="https://cdn.thunderphone.com/widget/v0.4.0/style.css" />
<script src="https://cdn.thunderphone.com/widget/v0.4.0/widget.js"></script>

<div id="thunderphone"></div>

<script>
  ThunderPhone.mount({
    element: '#thunderphone',
    publishableKey: 'pk_live_your_publishable_key',
  })
</script>

Use latest instead of a version number for the most recent release (cached for 5 minutes):

https://cdn.thunderphone.com/widget/latest/widget.js
https://cdn.thunderphone.com/widget/latest/style.css

ThunderPhone.mount() accepts the same options as the React component props above, plus element (CSS selector or DOM element). It returns a handle for cleanup:

const widget = ThunderPhone.mount({ element: '#thunderphone', publishableKey: '...' })

// Later, to remove the widget:
widget.unmount()

MIT