Twilio é um provedor internacional de telecomunicações. Ele permite que o bot ligue para clientes e os conecte aos seus funcionários em mais de 100 países onde a Twilio oferece números de telefone, incluindo México, Brasil, Turquia, Espanha, Alemanha, França, Emirados Árabes Unidos, Tailândia, Malásia e muitos outros.

O que você obtém após conectar o Twilio:

  • ligar para um cliente com um clique diretamente no cartão da conversa;
  • chamadas automatizadas baseadas em cenários — o bot liga para o cliente e lê uma mensagem de texto em voz alta;
  • chamadas em grupo — o bot liga para o cliente e o conecta ao primeiro funcionário disponível;
  • gravação de todas as chamadas, com o link da gravação armazenado nas variáveis do pedido;
  • eventos de chamada (chamando, atendida, concluída) diretamente na conversa — você pode usá-los para criar cenários.

Etapa 1. Criar uma Conta e Comprar um Número

  1. Cadastre-se em twilio.com e conclua o processo de verificação.
  2. No Console Twilio, abra Phone Numbers → Buy a number e selecione um número no país desejado. Certifique-se de que Voice esteja habilitado — alguns números suportam apenas SMS e não podem ser usados para chamadas.

Etapa 2. Copiar Suas Credenciais de Acesso

Na página principal do Console Twilio, em Account Info, você encontrará dois valores:

Item Como se parece
Account SID ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Auth Token oculto; clique em Show para revelá-lo

⚠️ Copie o Auth Token exatamente como aparece, sem espaços extras antes ou depois. Nós o usamos para verificar a autenticidade de cada solicitação do Twilio. Um único caractere invisível extra pode resultar em chamadas funcionando, mas eventos de chamada não aparecendo na conversa.

O Auth Token fornece acesso total à sua conta Twilio e aos fundos nela. Não o envie por mensageiros nem o publique em qualquer lugar.

Etapa 3. Conectar o Twilio na Sua Conta

Abra Project → Integrations → Telephony → Twilio e preencha os três campos:

Campo O que inserir
Account SID da Etapa 2
Auth Token da Etapa 2
Twilio Number o número que você comprou, no formato internacional: +14155550100

O número deve ser inserido no formato E.164: +, código do país e número de telefone, sem espaços, parênteses ou hífens.

Após salvar, uma callback URL aparecerá na página. Copie-a. Em seguida, abra as configurações do número comprado no Console Twilio e, em Voice & Fax, configure:

  • A call comes in → Webhook → cole a URL copiada e selecione HTTP POST.

Sem essa configuração, as chamadas de saída funcionarão, mas as chamadas de entrada e os eventos de chamada na conversa não.

Para desconectar a integração, limpe o campo Account SID e salve as configurações.

Etapa 4. Adicionar Números de Telefone dos Funcionários

O Twilio liga para os funcionários em números de telefone comuns — não há ramais internos aqui.

Abra a aba Team, selecione um funcionário e preencha o campo Twilio Phone Number com o número completo no mesmo formato:

+905551112233

Sem esse número, o botão de chamada no cartão do cliente não funcionará para esse funcionário.

Ligando pelo Cartão do Cliente

Um botão de chamada aparecerá ao lado do número de telefone do cliente no cartão da conversa. Clicar nele inicia a seguinte sequência:

  1. O Twilio liga para o funcionário — o funcionário vê seu número Twilio como identificador de chamada.
  2. O funcionário atende a chamada.
  3. Só então o Twilio liga para o cliente e conecta as duas partes.

A ordem é intencional: o cliente não precisa ouvir o toque enquanto o funcionário se aproxima do telefone. Se o funcionário não atender, o cliente não é chamado.

Chamadas a partir de Cenários do Bot

Quatro métodos estão disponíveis na calculadora.

twilio_employee_call(client_phone, employee_phone, caller_id)

Conecta um funcionário a um cliente. Funciona da mesma forma que o botão de chamada no cartão do cliente: primeiro o funcionário é chamado e depois o cliente.

twilio_employee_call(client_phone, "+905551112233")

O terceiro argumento é opcional. Ele especifica o número de telefone que o cliente verá como identificador de chamada. Por padrão, seu número Twilio é usado.

twilio_group_call(client_phone, employee_phones, caller_id)

Liga para o cliente e, assim que o cliente atende, chama simultaneamente todos os funcionários na lista especificada. A chamada é conectada ao primeiro funcionário que atender.

twilio_group_call(client.phone, "+905551112233,+905554445566,+905557778899")

⚠️ A ordem é invertida aqui. Diferente do método anterior, o cliente atende primeiro e pode ouvir alguns segundos de silêncio enquanto o Twilio liga para os funcionários. Esta é uma limitação do Twilio: chamar um grupo simultaneamente e conectar a primeira pessoa que atender só funciona assim. Se for importante que o cliente não espere, use twilio_employee_call.

twilio_play_message(client_phone, text, voice, language)

Liga para o cliente e lê o texto especificado usando fala sintetizada. Isso é útil para lembretes de consultas, confirmações de pedidos e notificações de entrega.

twilio_play_message(client.phone, "Olá! Este é um lembrete sobre sua consulta amanhã às 15:00.", "alice", "pt-BR")

A voz alice é universal e suporta os principais idiomas, incluindo tr-TR, es-ES, es-MX, pt-BR, de-DE, fr-FR, en-US, ru-RU e ar-XA.

Sempre especifique o idioma explicitamente — caso contrário, o Twilio pode ler o texto usando pronúncia em inglês.

Não inclua senhas, códigos de verificação ou outras informações confidenciais na mensagem: a chamada pode ser atendida por uma caixa postal.

Retorna um link para a gravação da chamada. Raramente é necessário porque o link normalmente aparece automaticamente (veja a próxima seção). Pode ser útil se o link da gravação não foi recebido e precisar ser solicitado novamente.

twilio_get_record_link()

Se nenhum argumento for fornecido, a chamada mais recente do cliente é usada.

Variáveis e Eventos

Após cada chamada, o bot armazena as seguintes variáveis no pedido do cliente:

Variável O que contém
twilio_call_id Identificador da chamada Twilio
twilio_call_disposition resultado da chamada: completed, busy, no-answer, failed, canceled
twilio_call_duration duração da chamada em segundos
twilio_record_link link para a gravação
twilio_record_id Identificador da gravação Twilio

Eventos no formato twilio_call_event <status> são enviados para a conversa. Você pode usá-los como condições em seus cenários:

Evento Quando é enviado
twilio_call_event initiated a chamada foi criada
twilio_call_event ringing o telefone está tocando
twilio_call_event answered a chamada foi atendida
twilio_call_event completed a chamada terminou
twilio_call_event busy / no-answer / failed / canceled a chamada não pôde ser concluída
twilio_call_event recording a gravação da chamada está pronta

⚠️ Aguarde o evento recording antes de usar o link da gravação, não o evento completed. O Twilio processa o arquivo de gravação após a chamada já ter terminado. No momento em que o evento completed é recebido, a variável twilio_record_link ainda está vazia. Um cenário que envia a gravação para um gerente ou CRM deve, portanto, ser acionado pelo evento recording.

Um cenário típico de "não conseguiu falar com o cliente — envie uma mensagem" funciona assim: condição para twilio_call_event no-answer ou busy → envie uma mensagem para o cliente.

Gravações de Chamadas

A gravação está habilitada por padrão para todas as chamadas envolvendo um funcionário. Ambos os lados da conversa são gravados a partir do momento em que a chamada é atendida. Os arquivos são armazenados na sua conta Twilio e são cobrados pela Twilio.

⚠️ A URL twilio_record_link aponta diretamente para o Twilio e é protegida pelas credenciais da sua conta. Você não pode simplesmente abri-la em um navegador ou enviá-la a um cliente — um erro de acesso será exibido. Para baixar a gravação, abra o Console Twilio e vá para Monitor → Logs → Calls, depois encontre a chamada usando seu twilio_call_id.

⚖️ A gravação de chamadas é regulamentada por lei. Em muitos países — incluindo Alemanha, França, Espanha e em muitos estados dos EUA — o consentimento de ambas as partes pode ser necessário, e em alguns casos um aviso falado deve ser reproduzido no início da chamada. Como proprietário da conta Twilio, você é responsável por cumprir os requisitos aplicáveis. Se essas regras se aplicam a você, comece a chamada com um aviso de gravação ou desative a gravação nas configurações do seu número Twilio.

Solução de Problemas

A Chamada Não É Criada e um Erro de Autenticação É Retornado

O Account SID ou Auth Token está incorreto. Copie-os novamente do Console Twilio. As causas mais comuns são um espaço extra ou copiar acidentalmente o Test Token em vez do Auth Token principal.

Chamadas Funcionam, mas Não Há Eventos ou Gravações na Conversa

A callback URL não foi configurada nas configurações do número Twilio (veja Etapa 3), ou está configurada com o método HTTP errado. O método deve ser HTTP POST.

Outra causa comum é que o Auth Token foi alterado no Twilio, mas o token antigo ainda está configurado na sua conta. Nesse caso, as assinaturas de solicitação não correspondem mais, então todos os callbacks são rejeitados.

Erro 21606 ou "From number not valid"

O número inserido no campo Twilio Number não foi comprado na sua conta Twilio ou não suporta chamadas de voz.

Abra Phone Numbers → Manage → Active numbers e certifique-se de que o número esteja listado e tenha capacidade Voice.

Erro 21215 — Geo Permissions

Por padrão, o Twilio bloqueia chamadas para muitos países como medida de prevenção a fraudes.

Abra Voice → Settings → Geo Permissions e habilite os destinos necessários.

Um Cliente Liga, mas um Cartão de Conversa É Criado para o Número do Funcionário

O callback está configurado com a URL errada. Copie a callback URL da página de integração novamente, certificando-se de copiar a URL inteira, incluindo tudo após o ponto de interrogação.

Conta de Teste: Twilio Reproduz uma Mensagem de Voz Antes da Chamada

Este é o comportamento padrão para contas de teste do Twilio. Contas de teste também só podem ligar para números de telefone verificados.

Adicione fundos à sua conta e faça upgrade para uma conta Twilio completa.