Webhook de ligação: receba o resultado de cada chamada com IA

Quem pede uma ligação pela API quer saber o que aconteceu nela sem precisar abrir um painel. É para isso que existe o webhook de ligação: quando a chamada termina, a respondendo.app faz um POST na URL que você indicou com tudo o que importa daquela conversa. Seu sistema recebe, grava e decide o próximo passo sozinho.

Neste artigo você vai ver o que chega no webhook, como preparar o endpoint que recebe os dados e quais cuidados deixam a integração estável mesmo com muitas ligações por dia.

O que é um webhook de ligação

Webhook é um aviso de servidor para servidor. Em vez de o seu sistema perguntar de tempos em tempos se a ligação já acabou, a plataforma avisa uma única vez, no momento certo. No caso das ligações com IA, o momento certo é o fim da chamada: a pessoa desligou, a IA registrou o desfecho e a gravação ficou pronta.

Você informa o endereço no próprio pedido da ligação, no campo webhook_url do POST /v1/ligacoes. Cada ligação pode ter a sua URL, o que facilita separar campanhas, clientes ou ambientes de teste e produção.

O que chega no webhook de ligação

O corpo do POST é um JSON com o resultado inteiro da chamada. Os campos mais usados são:

• atendida: true quando a pessoa atendeu e false quando ninguém atendeu.
• duração e código SIP: quanto tempo a conversa durou e o código técnico da chamada, útil para relatórios.
• resultado: o desfecho que a IA registrou, como confirmado, interessado, agendado ou sem interesse, com uma anotação curta.
• resumo: duas ou três frases dizendo o que foi conversado.
• transcrição: a conversa fala a fala, com quem falou e em que segundo.
• gravação: o link assinado do áudio, que vale por uma hora e pode ser renovado pela API.
• variáveis: as mesmas que você mandou no pedido, para cruzar com o seu cadastro sem esforço.

Na página do JSON você vê o pedido mínimo que inicia a ligação, e a documentação da API mostra o exemplo completo do que volta no fim.

Como preparar o endpoint que recebe os dados

O endpoint é uma rota comum do seu sistema que aceita POST com JSON. Na prática, ele precisa fazer quatro coisas:

1. Responder rápido. Devolva o status 200 assim que receber e deixe o processamento pesado para depois, numa fila ou tarefa em segundo plano.
2. Guardar o id da ligação. Ele é a chave para não processar o mesmo aviso duas vezes caso ele chegue de novo.
3. Atualizar o cadastro. Use as variáveis para achar o contato e grave o resultado, o resumo e a anotação no lugar certo.
4. Iniciar a próxima ação do seu fluxo. Um e-mail, uma tarefa para o vendedor ou a mudança de etapa no funil.

Se você usa ferramentas de automação, o caminho é ainda mais curto: o webhook pode apontar direto para um gatilho do n8n, do Make ou do Zapier, que repassa os dados para planilha, CRM ou mensagem interna.

Boas práticas para um webhook de ligação estável

Algumas decisões simples evitam dor de cabeça quando o volume cresce:

• Trate o aviso como definitivo, mas idempotente. Grave pelo id da ligação e ignore repetições.
• Não dependa só do webhook para relatórios. A rota GET /v1/ligacoes/{id} devolve o mesmo resultado a qualquer momento, e o painel guarda o histórico de entregas de cada aviso.
• Baixe a gravação logo, se precisar dela. O link é assinado e expira; a gravação também tem prazo para ficar guardada. Quem precisa arquivar o áudio deve copiar para o próprio armazenamento.
• Separe ligações não atendidas. Com atendida: false você pode agendar uma nova tentativa em outro horário, em vez de tratar como recusa.

Exemplo de uso: do formulário ao funil

Imagine a loja fictícia do Roberto, que vende cursos de fotografia. Quando alguém preenche o formulário do site, o sistema dele chama a API e a IA liga em poucos segundos para entender o que a pessoa procura. No fim, o webhook de ligação chega com resultado interessado e a anotação de que o André quer o curso de fim de semana.

O endpoint do Roberto lê o resultado e move o card para a etapa certa no CRM, coloca o resumo como nota e cria uma tarefa para o vendedor ligar de volta com a proposta. Ninguém precisou ouvir a ligação para saber o que fazer, e o vendedor já começa a conversa sabendo o contexto. Quando o resultado é sem interesse, o mesmo endpoint só marca o contato e encerra o fluxo.

Perguntas frequentes

O webhook chega mesmo quando a pessoa não atende?

Sim. O aviso chega com atendida: false, para o seu sistema decidir se tenta de novo mais tarde.

Preciso usar webhook para usar a API?

Não. Você pode consultar cada ligação pela rota de consulta ou acompanhar tudo pelo painel. O webhook só deixa o processo automático.

Dá para ver se o meu servidor recebeu o aviso?

Dá. O painel mostra as entregas de webhook com o status que o seu servidor devolveu, o que ajuda a encontrar falhas de integração.

Comece a receber resultados hoje

Para testar, crie um agente a partir de um modelo pronto, aponte o webhook_url para um endpoint seu e faça a primeira chamada. Veja também como funciona cada etapa da ligação. Crie sua conta com o Google e use o crédito de teste para ver o webhook de ligação chegando no seu sistema.