Developer cookbook

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. Criar um agente

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

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

   Chaves publicáveis são vinculadas à 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#

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"]
  }'

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.

O context do widget é truncado em 12.000 caracteres (aproximadamente 3.400 tokens de texto típico em inglês) e conta para a cobrança 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 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#