Componente React - ThunderPhone

O componente ThunderPhoneWidget renderiza uma barra de chamada glassmórfica com controles integrados para silenciar, encerrar a chamada e exibir o status da conexão. É a forma mais rápida de adicionar IA de voz a um app React.

Instalação

npm install @thunderphone/widget

Uso básico

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

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

Você deve importar o arquivo CSS para que o widget seja renderizado corretamente. Sem ele, o widget ficará sem estilo.

Propriedades

O componente aceita as seguintes propriedades por meio de ThunderPhoneWidgetProps:

Propriedade	Tipo	Obrigatória	Padrão	Descrição
`publishableKey`	`string`	Sim	—	Chave de API publicável (`pk_live_...`) das configurações de Desenvolvedores. O agente é resolvido automaticamente pela configuração do widget da chave.
`theme`	`'light' \| 'dark'`	Não	`'light'`	Esquema de cores. Aplica a classe `tp--light` ou `tp--dark` à raiz do widget.
`primaryColor`	`string`	Não	`'#000000'` (claro) / `'#ffffff'` (escuro)	String de cor CSS usada como cor de destaque (botão de chamada, forma de onda, indicadores ativos).
`title`	`string`	Não	`'Voice assistant'`	Texto exibido na barra do widget.
`position`	`'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'`	Não	`'bottom-right'`	Posição fixa do widget na viewport.
`apiBase`	`string`	Não	`'https://api.thunderphone.com/v1'`	Substituição da URL base da API.
`language`	`string`	Não	—	Substituição de idioma por sessão — um código de idioma ou localidade, como `en`, `es` ou `fr-FR`. Quando não definido, o idioma configurado do agente é aplicado.
`voice`	`string`	Não	—	Substituição de voz por sessão — um nome de voz, como `maria`. Quando não definido, a voz configurada do agente é aplicada.
`context`	`string`	Não	—	Contexto factual da página ou do site por sessão enviado ao agente (por exemplo, detalhes da página que o visitante está visualizando). Truncado no servidor para 12.000 caracteres.
`onConnect`	`() => void`	Não	—	Chamado quando a sessão de voz é conectada com sucesso.
`onDisconnect`	`() => void`	Não	—	Chamado quando a sessão termina.
`onError`	`(error) => void`	Não	—	Chamado em caso de erros. O objeto `error` tem os campos `error` (código) e `message`.
`className`	`string`	Não	—	Nome adicional de classe CSS aplicado ao contêiner do widget.
`ringtone`	`boolean \| string`	Não	`false`	Reproduz um toque durante a conexão. `true` para o toque padrão ou uma string de URL para áudio personalizado.

Exemplos

Tema escuro com cor personalizada

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

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      theme="dark"
      primaryColor="#8b5cf6"
      title="Talk to our AI"
    />
  )
}

Posição personalizada

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

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      position="bottom-left"
    />
  )
}

Idioma, voz e contexto por sessão

As props language, voice e context são encaminhadas para a solicitação de sessão (POST /widget/session) quando uma chamada é iniciada, substituindo os padrões configurados do agente para essa sessão:

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

function PricingPageWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      language="es"
      voice="maria"
      context="Page: Pricing. Plans: Starter $29/mo, Pro $99/mo. Annual billing saves 20%."
    />
  )
}

Use context para fornecer ao agente conhecimento factual sobre a página em que o visitante está — detalhes do produto, preços ou perguntas frequentes específicas da página. O conteúdo é truncado no servidor para 12.000 caracteres.

Com callbacks de eventos

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

function SupportWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      onConnect={() => {
        console.log('Voice session connected')
        analytics.track('widget_call_started')
      }}
      onDisconnect={() => {
        console.log('Voice session ended')
        analytics.track('widget_call_ended')
      }}
      onError={(error) => {
        console.error(`Widget error: ${error.error} - ${error.message}`)
      }}
    />
  )
}

Com estilização personalizada

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

function BrandedWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      primaryColor="#4a90d9"
      className="my-custom-widget"
    />
  )
}

.my-custom-widget .tp-button--end {
  background-color: #e74c3c;
}

Consulte o guia de estilização para ver todas as classes CSS e propriedades personalizadas disponíveis.

Com toque

Reproduza um som de telefone tocando enquanto a conexão é estabelecida:

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

function PhoneWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      ringtone={true}
    />
  )
}

Use um toque personalizado fornecendo a URL de um arquivo de áudio:

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

O toque é reproduzido em loop enquanto o widget está no estado connecting e diminui suavemente quando o agente se conecta.

Com base de API personalizada

Você só precisa definir apiBase se estiver usando um endpoint de API auto-hospedado ou de proxy. O padrão aponta para https://api.thunderphone.com/v1.

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  apiBase="https://your-proxy.example.com/v1"
/>

Tratamento de erros

Quando o callback onError é acionado, ele recebe um objeto de erro com dois campos:

Campo	Tipo	Descrição
`error`	`string`	Código de erro legível por máquina
`message`	`string`	Descrição de erro legível por humanos

Os códigos de erro comuns incluem domínio não permitido, agente não encontrado e chave de API inválida.

Próximas etapas

Hook headless

Precisa de controle total sobre a interface? Use o hook useThunderPhone.

Estilização

Personalize cores, tamanhos e layout com propriedades personalizadas de CSS.

​Instalação

​Uso básico

​Propriedades

​Exemplos

​Tema escuro com cor personalizada

​Posição personalizada

​Idioma, voz e contexto por sessão

​Com callbacks de eventos

​Com estilização personalizada

​Com toque

​Com base de API personalizada

​Tratamento de erros

​Próximas etapas

Hook headless

Estilização

Instalação

Uso básico

Propriedades

Exemplos

Tema escuro com cor personalizada

Posição personalizada

Idioma, voz e contexto por sessão

Com callbacks de eventos

Com estilização personalizada

Com toque

Com base de API personalizada

Tratamento de erros

Próximas etapas