Incorpore o widget da web

Adicione um agente de voz ao seu site de marketing ou suporte com uma única tag de script — visitantes falam com ele diretamente pelo navegador, sem precisar de número de telefone.

O widget da web oferece aos visitantes do seu site uma conversa de 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 de que o widget precisa.

Pré-requisitos#

1. Crie um agente

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

2. Defina o modo de roteamento
   • mode="agent" — um agente estático por chave. O mais simples.
   • mode="webhook" — seu servidor escolhe o agente por visitante por meio de um webhook web.incoming. Use isso para usuários autenticados, testes A/B ou roteamento por página.
3. Liste os domínios permitidos

   Informe cada nome de host que incorporará o widget. Os navegadores enviam a origem da página com cada solicitação de sessão, portanto a lista impede que sua chave funcione quando alguém a copia para outro site. Isso não é autenticação: um script fora de um navegador pode enviar qualquer cabeçalho Origin. localhost não é permitido automaticamente em produção; para testar localmente com a API de produção, adicione localhost à lista.

4. Escolha as substituições do navegador

   Decida quais configurações de sessão sua página pode enviar. Chaves novas não aceitam nenhuma; consulte Substituições do navegador.

Criar uma chave publicável#

curl -X POST https://api.thunderphone.com/v1/publishable-key \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":            "Marketing site (prod)",
    "mode":            "agent",
    "agent_id":        12,
    "allowed_domains": ["example.com", "*.example.com"],
    "allowed_overrides": ["context"]
  }'

curl -X POST https://api.thunderphone.com/v1/publishable-key \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":            "Support (dynamic)",
    "mode":            "webhook",
    "webhook_url":     "https://example.com/thunderphone/widget-hook",
    "allowed_domains": ["support.example.com"]
  }'

A resposta inclui uma key que começa com pk_live_.... Chaves publicáveis são públicas por definição — é seguro incluí-las no bundle do seu front-end. Consulte a referência de chaves publicáveis para ver todos os campos.

Adicione o widget ao seu site#

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

As três opções aceitam a mesma publishableKey e renderizam o botão do microfone e o elemento de áudio durante a chamada.

Substituições do navegador#

O widget pode enviar quatro configurações por sessão a partir da página:

Sua chave publicável é pública, portanto qualquer pessoa que a tenha pode enviar essas configurações, inclusive por meio de um script que falsifica seu domínio. Por isso, cada uma fica desativada até que você a permita na chave: marque-a em Substituições do navegador ao criar ou editar o widget no painel, ou defina allowed_overrides pela API de chaves publicáveis. Permita apenas o que sua página realmente envia.

Uma solicitação de sessão que contenha uma configuração não permitida pela chave falha com 400 e a identifica:

{
  "error": "override_not_allowed",
  "fields": ["voice"],
  "message": "This publishable key does not allow the browser to set `voice`. ..."
}

A verificação se aplica em ambos os modos. No modo webhook, uma configuração permitida também é encaminhada ao seu webhook web.incoming (context chega como website_context). Chaves criadas antes de essa configuração existir permitem todas as quatro, para que incorporações existentes continuem funcionando; desative o que você não usa.

O context do widget é truncado em 12.000 caracteres (aproximadamente 3.400 tokens de texto típico em inglês) e conta para a sobretaxa pelo tamanho do prompt. O agente recebe a instrução de tratá-lo como conteúdo da página, não como instruções.

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 você deseja executar para aquele visitante — ela segue o mesmo esquema de resposta das chamadas telefônicas:

{
  "prompt":  "You are a VIP concierge for Jane Doe.",
  "voice":   "john",
  "product": "storm-base",
  "tools":   [ /* per-customer tools */ ]
}

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 por implantação.

Observe as sessões#

As sessões do widget aparecem em GET /v1/calls com direction="widget" — com 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#