Como funciona
- Inscreva-se no evento
telephony.incoming(telefone) ouweb.incoming(widget). Ambos são webhooks bloqueantes: o ThunderPhone espera até 10 segundos pela sua resposta antes de continuar a chamada. - 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). - Seu servidor responde com uma configuração do agente (prompt, voz, produto, ferramentas). O ThunderPhone usa essa configuração na chamada.
- 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
- Chamadas telefônicas
- Widget web
Para números de telefone, inscreva seu endpoint em A resposta inclui um
telephony.incoming: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 comnew 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.