Skip to main content
O widget da web oferece aos visitantes do seu site uma conversa por clique para falar com um agente de IA, usando o microfone do navegador. É um SDK separado de JavaScript / React com sua própria referência do SDK — este guia se concentra na configuração do lado do ThunderPhone necessária para o widget.
Você pode fazer tudo isso sem cURL: a página Widgets da web do painel (/dashboard/web-widgets) cria o widget, define seu modo e agente, gerencia os domínios permitidos e fornece o snippet de incorporação.

​
Pré-requisitos

1

Criar um agente

O agente cujo prompt e voz executarão a sessão do widget. Defina widget_enabled: true (o padrão).
2

Definir o modo de roteamento

  • mode="agent" — um agente estático por chave. Mais simples.
  • mode="webhook" — seu servidor escolhe o agente para cada visitante por meio de um webhook web.incoming. Use isso para usuários autenticados, testes A/B ou roteamento por página.
3

Listar os domínios permitidos

As chaves publicáveis são bloqueadas por origem. Você deve informar cada nome de host que incorporará o widget. localhost / 127.0.0.1 são sempre permitidos durante o desenvolvimento local.

​
Criar uma chave publicável

A resposta inclui uma key que começa com pk_live_.... As chaves publicáveis são públicas por design — é seguro incluí-las no bundle do seu front-end. Consulte a referência de chaves publicáveis para ver todos os campos.
allowed_domains deve conter pelo menos uma entrada. *.example.com corresponde a subdomínios (por exemplo, api.example.com), mas não ao domínio raiz. Curingas simples como * ou *.* são rejeitados.

​
Adicione o widget ao seu site

Três opções de integração são abordadas na documentação do SDK do widget:

Componente React

<ThunderPhoneWidget publishableKey="pk_live_..." />.

Hook headless

useThunderPhone() para UIs personalizadas.

Tag de script CDN

ThunderPhone.mount({...}) para sites sem bundler.
Os três aceitam a mesma publishableKey e renderizam o botão de microfone e o elemento de áudio durante a chamada. O context do widget é truncado em 12.000 caracteres (aproximadamente 3.400 tokens de texto típico em inglês) e conta para a taxa adicional pelo tamanho do prompt.

​
Webhooks no modo widget

Quando mode="webhook", o ThunderPhone chama seu webhook_url a cada início de sessão com uma carga web.incoming. Retorne a configuração do agente que deseja executar para esse visitante — ela segue o mesmo esquema de resposta das chamadas telefônicas:
Você pode combinar o contexto da sua própria sessão (qual cliente está navegando, em qual página ele está) no prompt e trocar agentes a cada lançamento.

​
Observe as sessões

As sessões do widget aparecem em GET /v1/calls com direction="widget" — a mesma transcrição, gravação, avaliação e cobrança das chamadas telefônicas. Filtre por direction para criar um painel exclusivo para widgets.

​
Próximas etapas

Referência do SDK do widget

Detalhes de integração com React / hook / CDN.

Configuração dinâmica por chamada

Implemente o fluxo mode="webhook" de ponta a ponta.

Referência de chaves publicáveis

Todos os campos do recurso de chave.

API de sessões de microfone

Ignore o widget; use o LiveKit diretamente para interfaces personalizadas.