Skip to main content
Por padrão, cada número de telefone e chave publicável tem um agente estático atribuído. Quando você precisa de personalização por quem liga ou por visitante — roteamento VIP, contexto de usuário autenticado, testes A/B de prompt — alterne para o modo webhook e deixe seu servidor decidir.

Como funciona

  1. Inscreva-se no evento telephony.incoming (telefone) ou web.incoming (widget). Ambos são webhooks bloqueantes: o ThunderPhone espera até 10 segundos pela sua resposta antes de continuar a chamada.
  2. O ThunderPhone envia {call_id, from_number, to_number} (as sessões do widget incluem campos específicos do widget em vez de números — consulte o schema da solicitação).
  3. Seu servidor responde com uma configuração do agente (prompt, voz, produto, ferramentas). O ThunderPhone usa essa configuração na chamada.
  4. Se você retornar {}, exceder o tempo limite ou ocorrer um erro, o agente atribuído estaticamente será usado como fallback. Padrão seguro.
Funciona de forma idêntica para chamadas telefônicas (telephony.incoming) e sessões de widget (web.incoming), sejam entregues a um endpoint de webhook ou ao webhook legado de URL única.

1. Configure o destino do webhook

Para números de telefone, inscreva seu endpoint em telephony.incoming:
A resposta inclui um secret de uso único — salve-o; você o usará para verificação de assinatura.

2. Implemente o manipulador

Três regras práticas:
  • Verifique a assinatura em todas as solicitações (consulte Verificar assinaturas de webhook). Não ignore isso no desenvolvimento — faça corretamente uma vez e reutilize.
  • Responda rápido. Dez segundos é o limite máximo, e cada segundo é silêncio para quem liga. Faça consultas ao banco de dados se precisar, mas não chame LLMs downstream de forma síncrona — se quiser geração dinâmica de prompt, pré-calcule e armazene em cache.
  • Use um fallback limpo. Qualquer estado inesperado deve retornar {} para que o agente atribuído estaticamente atenda a chamada.

3. Esquema de resposta

O corpo da resposta corresponde exatamente ao esquema de resposta de chamada recebida. Os campos mais usados:
A ordem de fala por chamada e max_hold_seconds não estão disponíveis na resposta do webhook. Configure-os no Agente referenciado.

Padrões

Contexto do usuário autenticado

Em widgets no modo webhook, a página do visitante já sabe quem ele é. Chame seu webhook com um parâmetro de string de consulta que o SDK do widget encaminha (?customer_id=123) e busque o cliente no servidor.

Lançamento A/B de prompts

Antes de implementar isso manualmente, observe que o ThunderPhone tem um recurso nativo de Experimentos (/dashboard/experiments e a aba A/B do criador de agentes) que define variantes, divide o tráfego e compara resultados por variante — sem webhook necessário. Se ainda precisar de controle no webhook: aplique hash em call_id → bucket; forneça o prompt A para 0..49 e o prompt B para 50..99. Registre qual bucket você escolheu no seu próprio banco de dados e depois correlacione com a nota da chamada concluída.

Roteamento baseado em horário

Horário comercial → agente de “suporte ao vivo”; fora do horário comercial → agente de “registrar uma mensagem”. Alternância simples com new Date().getUTCHours() no seu manipulador.

Próximas etapas

Referência de webhook para chamadas recebidas

Esquemas exatos de solicitação + resposta, incluindo todas as chaves de configuração.

Verificar assinaturas de webhook

Configure o HMAC corretamente uma vez; reutilize em todos os lugares.

Criar uma integração de ferramenta

Combine roteamento dinâmico com ferramentas por agente.

Semântica de entrega

Novas tentativas, ordenação, tempos limite.