Skip to main content
Quando uma chamada telefônica recebida chega a um número sem um agente atribuído, ou quando uma sessão de widget web é iniciada em uma chave publicável em mode="webhook", o ThunderPhone envia uma solicitação bloqueante de telephony.incoming / web.incoming para sua URL de webhook legada e aguarda até 10 segundos por uma resposta de configuração. Use essa troca 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, com ou sem agente configurado — mas essas entregas são notificações fire-and-forget com um event_id, nunca bloqueantes. Somente o webhook legado de URL única realiza a troca de configuração desta página. Os formatos das notificações de endpoint estão no catálogo de eventos.
A troca bloqueante não tem fallback: se seu manipulador retornar um status diferente de 2xx, exceder o tempo limite ou retornar uma configuração que falhe na validação, a chamada será rejeitada (a chamada telefônica não é conectada; a solicitação da sessão do widget falha com 502/422). Responda rápido — quem liga está ouvindo o tom de chamada enquanto você decide.

Payload da solicitação

Para chamadas telefônicas (telephony.incoming):
Para sessões de widget web (web.incoming), data identifica a página que incorpora o widget em vez de números de telefone:
Widgets no modo webhook enviam esta solicitação para o próprio webhook_url da chave publicável quando ele está definido, usando como fallback a 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 que descreve 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. Speak-order e max_hold_seconds não são aceitos aqui; eles só podem ser configurados 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á fallback de agente estático neste caminho (um número ou chave no modo webhook não tem um agente atribuído).

Limite de tamanho da resposta

As respostas de configuração são limitadas a 5 MiB. Se um manipulador retornar uma resposta maior, inclusive com um status 2xx, o ThunderPhone informa que a resposta excedeu o limite e rejeita a chamada ou sessão do widget. Mantenha a resposta nos campos necessários para a configuração da chamada; hospede dados grandes por meio de ferramentas de função ou outro serviço em vez de incorporá-los à configuração.

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 da solicitação assinada.

Resumo dos níveis de produto


Relacionados

telephony.complete / web.complete

O evento não bloqueante de encerramento da chamada.

Ferramentas de função

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

Endpoints de webhook

Inscreva várias URLs em telephony.incoming / web.incoming.

Configuração dinâmica de chamadas

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