Integração Telnyx

​

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 na Tig.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 na Tig.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 da Tig.ai rodando e acessível

​

Configuração

​

Etapa 1: Obter as credenciais do Telnyx

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

​

Etapa 2: Configurar na Tig.ai

1. Navegue até /telephony-configurations e clique em Add configuration
2. Selecione Telnyx como seu provedor
3. Informe suas credenciais:
   • API Key
   • Call Control App ID (Connection ID) — opcional. Deixe em branco e a Tig.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.
4. Clique em Save Configuration
5. Abra a configuração que você acabou de criar e adicione pelo menos um phone number em formato E.164.
   Se a Tig.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 tig-<aleatório> — o Connection ID dele é mostrado na configuração salva.

​

Etapa 3: Testar sua configuração

1. Crie um workflow de teste
2. Clique em “Call” para verificar a conexão
3. Verifique os logs de chamada para confirmar a conexão bem-sucedida

​

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 workflow de entrada em um número de telefone, a Tig.ai envia automaticamente a URL do webhook para o webhook_event_url do seu Call Control Application (desde que as credenciais estejam corretas). Se a Tig.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 workflow de entrada ao número de telefone

1. Vá até /telephony-configurations e abra sua configuração Telnyx
2. Na seção Phone numbers, edite o número que deve receber chamadas recebidas
3. Defina o Inbound workflow para o agente que deve atender
4. Salve

​

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

1. Vá até Call Control → Applications no Telnyx Portal
2. Abra o aplicativo cujo Connection ID você configurou na Tig.ai
3. Em Webhook Settings, confirme:
   • Webhook URL está definida como: https://api.tig.ai/api/v1/telephony/inbound/run
   • HTTP Method é POST
4. Certifique-se de que os números de telefone que você quer usar para entrada estão atribuídos a este aplicativo
   A Tig.ai enviou esta URL automaticamente quando você salvou o workflow de entrada na Etapa 1. A mesma URL é compartilhada entre todos os números do Call Control Application — a Tig.ai corresponde a chamada recebida ao agente certo usando a atribuição de workflow de entrada do número chamado. Se o campo estiver vazio, mostrar uma URL diferente, ou a Tig.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 na Tig.ai está incorreto. Cole a URL no campo manualmente, defina o método como POST e salve. Na Tig.ai, substitua api.tig.ai pelo domínio do seu backend.

​

Etapa 3: Verificar a configuração

• Garanta que sua instância da Tig.ai seja acessível publicamente
• Verifique se os firewalls permitem os intervalos de IP do Telnyx

​

Testar chamadas recebidas

1. Ligue para seu número de telefone Telnyx configurado a partir de outro telefone
2. Verifique se o agente de voz da Tig.ai atende e responde
3. Cheque os logs de chamada no painel da Tig.ai e no Telnyx Portal

​

Solução de problemas

​

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 a Tig.ai para que a URL de webhook compartilhada não entre em conflito com outros sistemas