Registrar o webhook da Telnyx e solução de problemas de chamadas
Como registrar a Webhook URL do seu canal Telnyx no Mission Control e diagnosticar por que uma chamada não aparece na Caixa de entrada.
O que é isto e quando serve
O canal Telnyx (Voz programável) conecta seu número Telnyx ao Omnifox para fazer e receber chamadas dentro da Caixa de entrada. Para que cada evento da chamada (recebida, atendida, encerrada, gravação) apareça na conversa, a Telnyx precisa avisar o Omnifox por um webhook. Se o webhook não estiver registrado corretamente, as chamadas acontecem mas não aparecem no inbox — ou nem chegam até você.
Este guia é de nível intermediário: você já criou o canal e agora precisa registrar o webhook na Telnyx e diagnosticar por que uma chamada não chega.
Requisitos
- Um canal Telnyx já criado em Canais → Conectar canal → Telnyx.
- Acesso ao portal Telnyx Mission Control.
- À mão: sua API Key, o Connection ID e, opcional mas recomendado, a Signing Key (chave pública Ed25519) da Connection.
Passos para registrar o webhook
- No Omnifox abra Canais, entre no seu canal Telnyx e copie o campo Webhook URL (somente leitura). Ele tem o formato
https://omnifox.io/api/webhooks/telnyx. - Na Telnyx vá em Voice API → Connections e abra a Connection usada para este número. O id dela é o Connection ID que você colou no Omnifox.
- Na aba Webhook da Connection, cole a Webhook URL do Omnifox em Webhook URL e escolha HTTP POST.
- Copie a Signing Key que a Telnyx mostra nessa mesma seção e cole no campo Public Key do canal no Omnifox. Com ela, o Omnifox verifica a assinatura Ed25519 de cada evento. Se deixar vazio, o Omnifox aceita os eventos sem verificar a assinatura (menos seguro).
- Confirme que o Connection ID e a API Key do canal no Omnifox coincidem com os do portal e salve.
Verificação
- Faça uma chamada de teste real para o número. Na conversa do contato você deve ver, em ordem: Chamada recebida, Chamada atendida e Chamada encerrada com a duração.
- Quando houver gravação, aparece a linha Gravação disponível com o link do MP3.
- O Omnifox roteia cada evento procurando o Connection ID do payload; por isso o id do canal deve ser exatamente o da Connection que dispara a chamada.
Se não funcionar
- Nenhum evento aparece: a Webhook URL não está colada na Connection certa, ou a Connection que recebe a chamada não é a do Connection ID configurado no Omnifox.
- Chega um 403 / assinatura inválida: a Signing Key colada em Public Key não pertence a essa Connection. Copie de novo em Connection → Webhook → Signing Key, ou esvazie o campo temporariamente para confirmar que o resto do fluxo funciona.
- "no channel route": o
connection_iddo evento não corresponde a nenhum canal. Verifique se o Connection ID no Omnifox está sem espaços. - Chamadas de saída falham: geralmente falta o número de origem (Default From). Configure-o no canal ou informe-o pela tela de chamada.
Dicas
- Mantenha sempre a Signing Key configurada em produção: é a única forma de garantir que os eventos vêm mesmo da Telnyx.
- Se você rotacionar a API Key na Telnyx, atualize-a também no Omnifox (veja o artigo de editar credenciais) ou as chamadas de saída deixarão de ser criadas.
Artigos relacionados
Artigos relacionados
-
Códigos de erro do WhatsApp (Meta): o que significam e o que fazer
Tabela com os códigos de erro da Meta mais comuns ao enviar pelo WhatsApp (131026, 131047, 131049, 130497, 141006, 131031, 131056, 132000, 190, 368…) e como resolver cada um.
-
Como conectar o Telegram
Conecte um bot do Telegram à sua caixa de entrada do Omnifox em minutos usando o BotFather.
-
Comentários do Instagram e do Facebook: responder e moderar pelo Omnifox
Veja e responda os comentários das suas publicações e anúncios do Facebook e do Instagram, em público ou no privado, e configure respostas automáticas.
-
Enviar e receber vídeos em cada canal: formatos e tamanhos máximos
Quais vídeos você pode enviar e receber pelo WhatsApp, Instagram, Messenger, Telegram, chat do site e e-mail, com os tamanhos máximos reais e o que fazer com um vídeo pesado.
-
Conectar o WhatsApp escaneando um código QR
Vincule seu WhatsApp ao Omnifox em um minuto, como no WhatsApp Web. Ideal para testar: tem limites, não permite campanhas e não é a API oficial.