Integração Twilio

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 no Tigy 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
• Account SID e Auth Token do seu Twilio Console
• Pelo menos um número de telefone Twilio
• Uma instância do Tigy AI rodando e acessível

Configuração

Etapa 1: Obter as credenciais do Twilio

1. Entre no seu Twilio Console
2. Encontre seu Account SID e Auth Token no painel
3. No console do Twilio, abra Phone Numbers (Números de telefone) → Manage (Gerenciar) → Active Numbers (Números ativos).
4. Copie seu(s) número(s) de telefone

Etapa 2: Configurar no Tigy AI

1. No painel do Tigy AI, abra Telefonia e clique em Adicionar configuração.
2. Selecione Twilio como seu provedor
3. Informe suas credenciais:
   • Account SID
   • Auth Token
4. Clique em Salvar configuração
5. Abra a configuração que você acabou de criar e adicione pelo menos um número de telefone em formato E.164.

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 o Tigy AI identifica qual agente executar a partir do agente atribuído ao número chamado. Ao salvar um agente em um número de telefone, o Tigy 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 agente ao número de telefone

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

Etapa 2: Verificar a URL do webhook no Twilio Console

1. No Twilio Console, abra Phone Numbers (Números de telefone) → Manage (Gerenciar) → Active Numbers (Números ativos).
2. Clique no número de telefone ao qual você atribuiu um agente na Etapa 1
3. Na seção Voice Configuration (Configuração de voz), confirme:
   • Webhook está definido como: https://api.tigyai.com/api/v1/telephony/inbound/run
   • HTTP Method (método HTTP) é POST.

Nota

O Tigy AI enviou esta URL automaticamente quando você salvou o agente na Etapa 1. Se o campo estiver vazio, mostrar uma URL diferente, ou o Tigy 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 Salvar configuração. substitua api.tigyai.com pelo domínio do seu backend.

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 do Tigy AI atende e responde
3. Cheque os logs de chamada no painel do Tigy AI e no Twilio Console

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

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

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 vão para a caixa postal

- Verifique se o webhook do número Twilio está definido 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 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 - Cheque se a validação da assinatura do webhook está funcionando
(o Auth Token no Tigy 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

Práticas recomendadas

• Teste sua configuração com uma única chamada recebida
• Monitore o Twilio Console para uso e cobrança