Documentação / Integração Telnyx

Integração Telnyx

Configure o Telnyx para comunicação por voz no Tigy AI

Visão geral

O Telnyx é uma plataforma de comunicações em nuvem que fornece voz programável por meio da sua API Call Control. A integração do Telnyx no Tigy AI usa o Call Control mais o streaming de mídia via WebSocket para alimentar seus agentes de voz.

Pré-requisitos

Antes de configurar a integração com o Telnyx, você precisará:

Uma conta Telnyx
Uma API Key do Telnyx Mission Control Portal
Um Call Control Application (opcional — deixe o campo em branco no Tigy AI e criaremos um automaticamente para você ao salvar, com a URL do webhook de entrada predefinida)
Pelo menos um número de telefone Telnyx atribuído a esse Call Control Application
Uma instância do Tigy AI rodando e acessível

Configuração

Etapa 1: Obter as credenciais do Telnyx

Entre no Telnyx Mission Control Portal
Navegue até API Keys e crie (ou copie) uma API Key
(Opcional) Navegue até Call Control → Applications e crie (ou abra) o aplicativo que você usará com o Tigy AI e copie o Connection ID (Call Control App ID) dele. Pule isso se quiser que o Tigy AI crie automaticamente o Call Control Application para você ao salvar.
Navegue até Numbers → My Numbers e atribua seus números de telefone ao Call Control Application que você usará com o Tigy AI (se você estiver deixando o Tigy AI criar o aplicativo automaticamente, faça isso depois de salvar a configuração na Etapa 2)

Etapa 2: Configurar no Tigy AI

No painel do Tigy AI, abra Telefonia e clique em Adicionar configuração.
Selecione Telnyx como seu provedor
Informe suas credenciais:
- API Key
- Call Control App ID (Connection ID) — opcional. Deixe em branco e o Tigy AI criará automaticamente um Call Control Application ao salvar (com a URL do webhook de entrada já configurada) e armazenará o Connection ID dele nesta configuração.
Clique em Salvar configuração
Abra a configuração que você acabou de criar e adicione pelo menos um número de telefone em formato E.164.

Nota

Se o Tigy AI criou o Call Control Application automaticamente para você, você ainda precisa atribuir seus números Telnyx a esse aplicativo no Telnyx Portal em Numbers → My Numbers. O aplicativo criado automaticamente é chamado tigy-<aleatório> — o Connection ID dele é mostrado na configuração salva.

Configuração de chamadas recebidas

O Telnyx entrega os webhooks recebidos no nível do Call Control Application — a URL do webhook é configurada uma única vez no aplicativo e se aplica a todos os números atribuídos a ele. Ao salvar um agente em um número de telefone, o Tigy AI envia automaticamente a URL do webhook para o webhook_event_url do seu Call Control Application (desde que as credenciais estejam corretas). Se o Tigy AI criou o aplicativo automaticamente ao salvar a configuração, a URL do webhook já está definida e esta etapa é um no-op.

Etapa 1: Atribuir um agente ao número de telefone

No painel, abra Telefonia e selecione sua configuração Telnyx.
Na seção Números de telefone, edite o número que deve receber chamadas.
Defina o agente para o agente que deve atender
Salve

Etapa 2: Verificar a URL do webhook no Call Control Application

Vá até Call Control → Applications no Telnyx Portal
Abra o aplicativo cujo Connection ID você configurou no Tigy AI
Em Webhook Settings (Configurações do webhook), confirme:
- Webhook URL está definida como: https://api.tigyai.com/api/v1/telephony/inbound/run
- HTTP Method (método HTTP) é POST.
Certifique-se de que os números de telefone que você quer usar para entrada estão atribuídos a este aplicativo

Nota

O Tigy AI enviou esta URL automaticamente quando você salvou o agente na Etapa 1. A mesma URL é compartilhada entre todos os números do Call Control Application — o Tigy AI corresponde a chamada recebida ao agente certo usando a atribuição de agente do número chamado. Se o campo estiver vazio, mostrar uma URL diferente, ou o Tigy AI tiver exibido um aviso de sincronização ao salvar, o envio automático falhou — na maioria das vezes porque a API Key ou o Connection ID no Tigy AI está incorreto. Cole a URL no campo manualmente, defina o método como POST e salve. no Tigy AI, substitua api.tigyai.com pelo domínio do seu backend.

Testar chamadas recebidas

Ligue para seu número de telefone Telnyx configurado a partir de outro telefone
Verifique se o agente de voz do Tigy AI atende e responde
Cheque os logs de chamada no painel do Tigy AI e no Telnyx Portal

Solução de problemas

Erro de número de telefone inválido

Garanta que os números de telefone incluam o código do país em formato E.164: `+1234567890`

Falha na autenticação

- Verifique se a API Key está correta e ativa - Cheque se há espaços extras na
chave - Garanta que a chave não foi revogada no Telnyx Portal

Falha na validação da assinatura do webhook

- O Telnyx assina os webhooks com Ed25519 - confirme se a chave pública no
aplicativo não mudou - Verifique se a URL do webhook corresponde ao que o Telnyx
envia - Cheque se você está atrás de um proxy que modifica os corpos das requisições

Sem áudio nas chamadas

- Verifique se a conexão WebSocket foi estabelecida - Cheque as regras de firewall para
tráfego WebSocket - Garanta que o pipeline de áudio esteja configurado corretamente

Chamadas recebidas não são atendidas

- Verifique se a URL do webhook do Call Control Application está definida como
`https://api.tigyai.com/api/v1/telephony/inbound/run` - Garanta que a URL
do webhook seja acessível publicamente pela internet - Confirme que o número chamado
está atribuído ao mesmo Call Control Application cujo Connection ID está
configurado no Tigy AI - Confirme que o número chamado existe na sua configuração
de telefonia do Tigy AI e tem um **agente** atribuído - Verifique
se a instância do Tigy AI está rodando e respondendo

O agente de voz não responde a chamadas recebidas

- Confirme se o número de telefone tem um **agente** atribuído em
/telephony-configurations - Verifique se a API Key corresponde à armazenada
na sua configuração de telefonia do Tigy AI - Verifique se a conexão WebSocket
é estabelecida com sucesso - Revise os logs de chamada em busca de mensagens de erro

Práticas recomendadas

Teste sua configuração com uma única chamada recebida
Monitore o Telnyx Portal para uso e cobrança
Use um Call Control Application dedicado para o Tigy AI para que a URL de webhook compartilhada não entre em conflito com outros sistemas

← Voltar à documentação