A Twilio é uma provedora internacional de telecomunicações. Ela permite que o bot ligue para clientes e os conecte com seus funcionários em qualquer um dos 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 a Twilio:
- ligar para um cliente com um clique diretamente do cartão de 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 construir cenários.
Etapa 1. Criar uma Conta e Comprar um Número
- Cadastre-se em twilio.com e conclua o processo de verificação.
- No Console da 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. Copie Suas Credenciais de Acesso
Na página principal do Console da Twilio, em Account Info, você encontrará dois valores:
| Item | Como aparece |
|---|---|
| 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 requisição da 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 ou publique em qualquer lugar.
Etapa 3. Conecte a Twilio na Sua Conta
Abra Projeto → Integrações → Telefonia → Twilio e preencha os três campos:
| Campo | O que inserir |
|---|---|
| Account SID | da Etapa 2 |
| Auth Token | da Etapa 2 |
| Número Twilio | 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 URL de callback aparecerá na página. Copie-a. Em seguida, abra as configurações do número comprado no Console da 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. Adicione os Números de Telefone dos Funcionários
A Twilio liga para os funcionários em números de telefone comuns — não há ramais internos aqui.
Abra a aba Equipe, selecione um funcionário e preencha o campo Número de Telefone Twilio 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 do Cartão do Cliente
Um botão de chamada aparecerá ao lado do número de telefone do cliente no cartão de conversa. Clicar nele inicia a seguinte sequência:
- A Twilio liga para o funcionário — o funcionário vê seu número Twilio como identificador de chamada.
- O funcionário atende a chamada.
- Só então a 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 dirige ao 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 a Twilio liga para os funcionários. Esta é uma limitação da 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 compromissos, confirmações de pedidos e notificações de entrega.
twilio_play_message(client.phone, "Olá! Este é um lembrete sobre seu compromisso 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, a Twilio pode ler o texto usando pronúncia em inglês.
Não inclua senhas, códigos de verificação ou outras informações sensíveis na mensagem: a chamada pode ser atendida por uma caixa postal.
twilio_get_record_link(call_id)
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
recordingantes de usar o link da gravação, não o eventocompleted. A Twilio processa o arquivo de gravação após a chamada já ter terminado. No momento em que o eventocompletedé recebido, a variáveltwilio_record_linkainda está vazia. Um cenário que envia a gravação para um gerente ou CRM deve, portanto, ser acionado pelo eventorecording.
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_linkaponta diretamente para a 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 da Twilio e vá para Monitor → Logs → Calls, depois encontre a chamada usando seutwilio_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 uma notificação falada deve ser reproduzida 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 da 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 URL de callback 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 na Twilio, mas o token antigo ainda está configurado na sua conta. Nesse caso, as assinaturas de requisiçã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 Número Twilio não foi comprado sob sua conta Twilio ou não suporta chamadas de voz.
Abra Phone Numbers → Manage → Active numbers e certifique-se de que o número está listado e tem capacidade de Voice.
Erro 21215 — Geo Permissions
Por padrão, a 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 URL de callback 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: A Twilio Reproduz uma Mensagem de Voz Antes da Chamada
Este é o comportamento padrão para contas de teste da 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.