> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tigyai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integração Telnyx

> Configure o Telnyx para comunicação por voz na Tig.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 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](https://telnyx.com/)
* 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](https://portal.telnyx.com/)
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.

   <Note>
     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.
   </Note>

### 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

   <Note>
     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.
   </Note>

### 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

<AccordionGroup>
  <Accordion title="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`
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Chamadas recebidas não são atendidas">
    * Verifique se a URL do webhook do Call Control Application está definida como
      `https://api.tig.ai/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 na Tig.ai - Confirme que o número chamado existe na sua configuração
      de telefonia da Tig.ai e tem um **Inbound workflow** atribuído - Verifique
      se a instância da Tig.ai está rodando e respondendo
  </Accordion>

  <Accordion title="O agente de voz não responde a chamadas recebidas">
    * Confirme se o número de telefone tem um **Inbound workflow** atribuído em
      /telephony-configurations - Verifique se a API Key corresponde à armazenada
      na sua configuração de telefonia da Tig.ai - Verifique se a conexão WebSocket
      é estabelecida com sucesso - Revise os logs de chamada em busca de mensagens de erro
  </Accordion>
</AccordionGroup>

## 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