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

> Configure o Twilio para comunicação por voz na Tig.ai

## Visão geral

O Twilio é uma plataforma de comunicações em nuvem que permite recursos de chamadas de voz, mensagens e vídeo. A integração do Twilio na Tig.ai fornece conectividade contínua para seus agentes de voz.

## Pré-requisitos

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

* Uma [conta Twilio](https://www.twilio.com/try-twilio)
* Account SID e Auth Token do seu Twilio Console
* Pelo menos um número de telefone Twilio
* Uma instância da Tig.ai rodando e acessível

## Configuração

### Etapa 1: Obter as credenciais do Twilio

1. Entre no seu [Twilio Console](https://console.twilio.com/)
2. Encontre seu **Account SID** e **Auth Token** no painel
3. Navegue até **Phone Numbers** → **Manage** → **Active Numbers**
4. Copie seu(s) número(s) de telefone

### Etapa 2: Configurar na Tig.ai

1. Navegue até **/telephony-configurations** e clique em **Add configuration**
2. Selecione **Twilio** como seu provedor
3. Informe suas credenciais:
   * Account SID
   * Auth Token
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.

### 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 roteamento de entrada é conduzido pelo próprio número de telefone — há uma **URL de webhook única para toda a organização**, e a Tig.ai identifica qual agente executar a partir do workflow de entrada atribuído ao número chamado. **Ao salvar um workflow de entrada em um número de telefone, a Tig.ai envia automaticamente a URL do webhook para o `VoiceUrl` desse número na sua conta Twilio** (desde que as credenciais estejam corretas e o número pertença a essa conta).

### Etapa 1: Atribuir um workflow de entrada ao número de telefone

1. Vá até **/telephony-configurations** e abra sua configuração Twilio
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 Twilio Console

1. Vá até **Phone Numbers** → **Manage** → **Active Numbers** no Twilio Console
2. Clique no número de telefone ao qual você atribuiu um workflow de entrada na Etapa 1
3. Na seção **Voice Configuration**, confirme:

   * **Webhook** está definido como: `https://api.tig.ai/api/v1/telephony/inbound/run`
   * **HTTP Method** é `POST`

   <Note>
     A Tig.ai enviou esta URL automaticamente quando você salvou o workflow de entrada
     na Etapa 1. Se o campo estiver vazio, mostrar uma URL diferente, ou a Tig.ai
     tiver exibido um aviso de sincronização, o envio automático falhou — na maioria das vezes
     porque as credenciais estão incorretas ou o número não pertence a esta conta
     Twilio. Cole a URL no campo manualmente, defina o método como
     `POST` e clique em **Save Configuration**.
     substitua `api.tig.ai` pelo domínio do seu backend.
   </Note>

   <img className="block dark:hidden" src="https://mintcdn.com/callguard/w-VUnJAq_m6hhmzP/images/twilio-inbound-config.png?fit=max&auto=format&n=w-VUnJAq_m6hhmzP&q=85&s=117a8ca238675f9f18cca0d58240d30e" alt="Configuração de voz do número de telefone Twilio mostrando a configuração da URL do webhook para chamadas recebidas" width="2252" height="533" data-path="images/twilio-inbound-config.png" />

   <img className="hidden dark:block" src="https://mintcdn.com/callguard/w-VUnJAq_m6hhmzP/images/twilio-inbound-config.png?fit=max&auto=format&n=w-VUnJAq_m6hhmzP&q=85&s=117a8ca238675f9f18cca0d58240d30e" alt="Configuração de voz do número de telefone Twilio mostrando a configuração da URL do webhook para chamadas recebidas" width="2252" height="533" data-path="images/twilio-inbound-config.png" />

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

### Testar chamadas recebidas

1. Ligue para seu número de telefone Twilio 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 Twilio Console

## 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 o Account SID e o Auth Token estão corretos - Cheque se há espaços extras nas
      credenciais - Garanta que as credenciais não foram regeneradas no Twilio Console
  </Accordion>

  <Accordion title="Falha na validação da assinatura do webhook">
    * Confirme se seu Auth Token corresponde exatamente - Verifique se a URL do webhook corresponde
      ao que o Twilio envia - Cheque se você está atrás de um proxy que modifica as 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 vão para a caixa postal">
    * Verifique se o webhook do número Twilio está definido 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 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 - Cheque se a validação da assinatura do webhook está funcionando
      (o Auth Token na Tig.ai corresponde ao Twilio Console) - 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 Twilio Console para uso e cobrança