Skip to main content
Quando uma chamada telefônica recebida chega a um número sem um agente atribuído, ou uma sessão do widget web é iniciada em uma chave publicável em mode="webhook", o ThunderPhone envia uma solicitação bloqueante telephony.incoming / web.incoming para a sua URL legada de webhook e aguarda até 10 segundos por uma resposta de configuração. Use esse intercâmbio para escolher dinamicamente um prompt, uma voz e ferramentas por chamada — consulte o guia de configuração dinâmica de chamadas para ver o padrão completo.
Endpoints de webhook inscritos também recebem telephony.incoming / web.incoming — para todas as chamadas recebidas e sessões web, configuradas com agente ou não — mas essas entregas são notificações sem espera com um event_id, nunca bloqueantes. Somente o webhook legado de URL única realiza o intercâmbio de configuração desta página. Os formatos das notificações de endpoint estão no catálogo de eventos.
O intercâmbio bloqueante não tem alternativa: se o seu manipulador retornar um status diferente de 2xx, exceder o tempo limite ou retornar uma configuração que não passe na validação, a chamada será rejeitada (a chamada telefônica não é conectada; a solicitação de sessão do widget falha com 502/422). Responda rápido — quem liga ouve o tom de chamada enquanto você decide.

Payload da solicitação

Para chamadas telefônicas (telephony.incoming):
Para sessões do widget web (web.incoming), data identifica a página de incorporação em vez de números de telefone:
Widgets no modo webhook entregam esta solicitação ao próprio webhook_url da chave publicável quando um está definido, recorrendo à URL de webhook no nível da organização. Em ambos os casos, ela é assinada com o secret do webhook da organização.

Esquema de resposta

Retorne um objeto JSON descrevendo a configuração do agente para esta chamada. prompt e voice são obrigatórios; todo o restante é opcional.
Chaves de nível superior desconhecidas são ignoradas silenciosamente — um nome de campo com erro de digitação não rejeita a configuração, apenas não é aplicado. A ordem de fala e max_hold_seconds não são aceitos aqui; eles são configuráveis apenas no próprio Agente.
Como prompt e voice são obrigatórios, retornar {} ou qualquer resposta que falhe na validação rejeita a chamada com 422 — não há alternativa de agente estático nesta rota (um número ou chave no modo webhook não tem um agente atribuído).

Exemplo de manipulador


Resposta com ferramentas de função

Anexe ferramentas para que a IA possa chamar suas APIs durante a conversa:
As solicitações ao endpoint da ferramenta são assinadas com o mesmo segredo de webhook da organização que assinou esta troca. Consulte Ferramentas de função para ver a estrutura exata e o formato de solicitação assinada.

Guia rápido de níveis de produto


Relacionado

telephony.complete / web.complete

O evento de fim de chamada sem bloqueio.

Ferramentas de função

Esquema JSON completo para tools[] e o contrato de endpoint assinado.

Endpoints de webhook

Assine várias URLs para telephony.incoming / web.incoming.

Configuração dinâmica de chamada

Padrões para prompts, ferramentas e testes A/B por quem liga.