Pular para conteúdo

Twilio Integration - Lumina Flow Builder

Visão Geral

A integração Twilio do Lumina Flow Builder permite enviar SMS, MMS e realizar chamadas telefônicas automáticas usando a poderosa API do Twilio. Alcance qualquer pessoa no mundo através de comunicação tradicional (SMS/Voz) com automação completa.

O que é Twilio?

Twilio é a plataforma líder mundial para comunicação programável. Com ela você pode:

  • Enviar SMS/MMS: Mensagens de texto simples ou com mídia para qualquer celular
  • Fazer Chamadas: Ligações automatizadas com scripts TwiML (IVR, confirmações, pesquisas)
  • Receber Chamadas/SMS: Webhooks para processar respostas de clientes
  • WhatsApp API: Integração oficial do WhatsApp Business
  • Verificação: Sistema de 2FA (autenticação de dois fatores)

Por que usar Twilio?

  1. Alcance Universal: SMS funciona em TODOS os celulares (7 bilhões de dispositivos)
  2. Alta Taxa de Leitura: 98% dos SMS são lidos em 3 minutos
  3. Confiabilidade: 99.95% uptime, entrega garantida
  4. Compliance: Certificado para saúde, finanças, governo
  5. Preço Competitivo: A partir de $0.0075 por SMS (Brasil)

Nodes Disponíveis

1. SMS Send - Envio de SMS/MMS

Envia mensagens de texto (SMS) ou mensagens com mídia (MMS) para qualquer número.

Casos de uso: - Códigos de verificação 2FA - Confirmações de pedidos - Alertas críticos - Campanhas de marketing - Notificações de entrega

Recursos: - Envio de SMS (até 1600 caracteres) - Envio de MMS (imagens, vídeos, áudio até 5MB) - Substituição de variáveis dinâmicas - Rastreamento via Message SID - Status de entrega em tempo real

Documentação Completa: SMS Send

2. Call Make - Chamadas Telefônicas Automáticas

Inicia chamadas telefônicas automatizadas com scripts TwiML personalizados.

Casos de uso: - IVR (menu telefônico interativo) - Confirmações de consultas - Pesquisas de satisfação (NPS) - Alertas de emergência - Lembretes por voz

Recursos: - Chamadas para qualquer país - Scripts TwiML (falar, gravar, coletar dígitos) - Callbacks de status da chamada - Vozes em português (pt-BR) - Roteamento inteligente

Documentação Completa: Call Make

Configuração Inicial

1. Criar Conta Twilio

  1. Acesse: https://www.twilio.com/try-twilio
  2. Crie conta gratuita (recebe $15 de crédito)
  3. Verifique seu número de telefone
  4. Acesse o Dashboard

2. Obter Credenciais

No Twilio Console Dashboard:

  • Account SID: ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (34 caracteres)
  • Auth Token: Clique no ícone de olho para revelar (32 caracteres)

IMPORTANTE: Nunca exponha estas credenciais! Use variáveis de ambiente.

3. Comprar Número Twilio

Para enviar SMS/Chamadas, você precisa de um número Twilio:

  1. Acesse: Console > Phone Numbers > Buy a Number
  2. Selecione país: Brazil (+55)
  3. Filtros: SMS, Voice (ou ambos)
  4. Compre o número (cerca de $1/mês)

Formato do número: +5511999887766

4. Configurar Variáveis no Lumina

{
  "twilioAccountSid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "twilioAuthToken": "your_auth_token_here",
  "twilioPhoneNumber": "+5511999887766"
}

Melhor prática: Use variáveis de ambiente:

TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token_here
TWILIO_PHONE_NUMBER=+5511999887766

Exemplo Rápido: Primeiro SMS

{
  "name": "Meu Primeiro SMS com Twilio",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "twilio_1",
      "type": "twilio",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Enviar SMS",
        "resource": "sms",
        "operation": "send",
        "from": "+5511999887766",
        "to": "+5511988776655",
        "message": "Olá! Este é meu primeiro SMS automático com Lumina Flow!",
        "responseVariable": "smsResult",
        "config": {
          "accountSid": "{{twilioAccountSid}}",
          "authToken": "{{twilioAuthToken}}"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Sucesso",
        "parameters": {
          "message": "SMS enviado com sucesso! SID: {{smsResult.messageSid}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "twilio_1" },
    { "source": "twilio_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Exemplo Rápido: Primeira Chamada

{
  "name": "Minha Primeira Chamada com Twilio",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "twilio_1",
      "type": "twilio",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Fazer Chamada",
        "resource": "call",
        "operation": "make",
        "from": "+5511999887766",
        "to": "+5511988776655",
        "twimlUrl": "https://handler.twilio.com/twiml/EH1234567890abcdef",
        "responseVariable": "callResult",
        "config": {
          "accountSid": "{{twilioAccountSid}}",
          "authToken": "{{twilioAuthToken}}"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Sucesso",
        "parameters": {
          "message": "Chamada iniciada! Call SID: {{callResult.callSid}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "twilio_1" },
    { "source": "twilio_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

TwiML Simples (hospede em Twilio TwiML Bin): 

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say voice="alice" language="pt-BR">Olá! Esta é uma chamada automática do Lumina Flow. Até logo!</Say>
    <Hangup/>
</Response>

TwiML Básico

TwiML (Twilio Markup Language) é XML que controla chamadas. Principais tags:

Falar (<Say>)

<Say voice="alice" language="pt-BR">Olá, bem-vindo!</Say>

Vozes disponíveis em pt-BR: - alice (melhor qualidade, feminina) - man (masculina, básica) - woman (feminina, básica)

Pausar (<Pause>)

<Pause length="2"/>  <!-- 2 segundos -->

Coletar Dígitos (<Gather>)

<Gather numDigits="1" action="/resposta" method="POST" timeout="5">
    <Say voice="alice" language="pt-BR">Pressione 1 para continuar.</Say>
</Gather>

Gravar (<Record>)

<Record maxLength="30" action="/gravacao" playBeep="true"/>

Discar (<Dial>)

<Dial timeout="20">+5511988776655</Dial>

Encerrar (<Hangup>)

<Hangup/>

Webhooks e Callbacks

Twilio envia webhooks para notificar eventos:

Status de SMS

Configure statusCallback no SMS Send:

POST https://lumina.app.br/webhooks/sms-status

Payload recebido: 

{
  "MessageSid": "SM1234567890abcdef",
  "MessageStatus": "delivered",
  "To": "+5511988776655",
  "From": "+5511999887766",
  "Body": "Mensagem enviada"
}

Status possíveis: - queued: Fila de envio - sent: Enviado para operadora - delivered: Entregue - undelivered: Não entregue - failed: Falhou

Status de Chamada

Configure statusCallback no Call Make:

POST https://lumina.app.br/webhooks/call-status

Payload recebido: 

{
  "CallSid": "CA1234567890abcdef",
  "CallStatus": "completed",
  "CallDuration": "45",
  "To": "+5511988776655",
  "From": "+5511999887766"
}

Status possíveis: - queued: Na fila - ringing: Tocando - in-progress: Em andamento - completed: Completada - busy: Ocupado - no-answer: Não atendeu - failed: Falhou - canceled: Cancelada

Custos Twilio (Referência Brasil)

SMS

  • SMS Enviado: $0.0075 USD por mensagem
  • SMS Recebido: $0.0075 USD por mensagem

MMS

  • MMS Enviado: $0.03 USD por mensagem
  • MMS Recebido: $0.02 USD por mensagem

Chamadas

  • Chamada Saída: $0.013 USD por minuto
  • Chamada Entrada: $0.0085 USD por minuto

Números

  • Número Local: $1 USD/mês
  • Toll-Free (0800): $2 USD/mês

Nota: Preços aproximados. Consulte https://www.twilio.com/pricing para valores atualizados.

Limites e Rate Limits

Conta Trial (Gratuita)

  • $15 de crédito inicial
  • Só pode enviar para números verificados
  • Marca d'água "Sent from your Twilio trial account"

Conta Paga

  • SMS: 100 mensagens/segundo (padrão)
  • Chamadas: 100 chamadas simultâneas (padrão)
  • Sem marca d'água
  • Pode solicitar aumento de limites

Solicitar aumento: 1. Console > Settings > General 2. Request Higher Rate Limits 3. Justifique caso de uso

Compliance e Boas Práticas

LGPD/GDPR

  • Sempre obtenha consentimento explícito antes de enviar SMS/Chamadas
  • Implemente opt-out fácil (responder STOP)
  • Mantenha registro de consentimento com data/hora
  • Respeite DNC (Do Not Call) lists

Horários

Permitido: - Segunda a Sexta: 9h - 18h - Sábado: 9h - 13h - Domingo/Feriados: Apenas emergências

Proibido: - Madrugada (0h - 8h) - Noite (21h - 23h59)

Conteúdo

Sempre incluir: - Nome da empresa no início - Motivo da mensagem/chamada - Forma de opt-out ("Responda STOP para cancelar")

Nunca: - Spam ou conteúdo enganoso - Informações sensíveis sem criptografia - Links encurtados suspeitos

Troubleshooting

Erro: "The 'From' number is not a valid Twilio phone number"

Causa: Número from não está registrado na sua conta.

Solução: 1. Verifique se digitou corretamente (+5511999887766) 2. Confirme que número existe em Console > Phone Numbers 3. Use formato E.164 (+ código país + número)

Erro: "Permission to send an SMS has not been enabled"

Causa: Conta trial tentando enviar para número não verificado.

Solução: 1. Verifique número em Console > Phone Numbers > Verified Caller IDs 2. Ou faça upgrade para conta paga

SMS não chega (status: undelivered)

Causas possíveis: - Número destinatário inválido - Operadora bloqueou (spam filter) - País não suportado para SMS

Solução: 1. Valide número com formato E.164 2. Verifique logs em Console > Monitor > Logs > Errors 3. Teste com seu próprio número primeiro

Chamada cai imediatamente

Causas possíveis: - TwiML URL retorna 404 ou timeout - XML mal formatado - Número bloqueado

Solução: 1. Teste TwiML URL no navegador (deve retornar XML) 2. Valide XML em https://www.twilio.com/docs/voice/twiml 3. Verifique logs em Console > Monitor > Logs > Calls

Erro: "Authentication Error"

Causa: Account SID ou Auth Token inválidos.

Solução: 1. Verifique credenciais em Console > Account 2. Confirme que não há espaços extras 3. Se rotacionou token, atualize configuração

Recursos Avançados

Messaging Services

Para envios em massa, use Messaging Service: - Distribui envios entre múltiplos números - Evita rate limit - Fallback automático

Verify API

Para 2FA robusto: - Gerencia expiração de códigos - Retentativas automáticas - Suporta SMS + Voz

Studio Flows

IVR visual no Twilio Console: - Arraste e solte widgets - Não precisa escrever TwiML - Exporta para produção

Programmable Messaging Insights

Analytics avançado: - Taxa de entrega por operadora - Tempo médio de entrega - Custos por campanha

Segurança

Proteger Credenciais

NUNCA: 

const accountSid = "AC1234567890abcdef"; // ❌ Código hardcoded

SEMPRE: 

const accountSid = process.env.TWILIO_ACCOUNT_SID; // ✅ Variável de ambiente

Validar Webhooks

Twilio assina webhooks com signature. Valide:

const twilio = require('twilio');

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-twilio-signature'];
  const url = 'https://lumina.app.br/webhook';

  if (twilio.validateRequest(authToken, signature, url, req.body)) {
    // Webhook válido
  } else {
    // Webhook fraudulento
    res.status(403).send('Forbidden');
  }
});

IP Whitelist

Configure firewall para aceitar apenas IPs do Twilio: https://www.twilio.com/docs/infrastructure/ips

Integração com Outros Nodes

SMS + Condition

Enviar SMS e verificar status:

START → TWILIO SMS → CONDITION (status == "delivered") → MESSAGE "Entregue" / MESSAGE "Falhou"

Call + Webhook + Database

Receber resposta IVR e salvar:

START → TWILIO CALL → WEBHOOK (receber digits) → DATABASE SAVE → END

Loop + Delay + SMS

Campanha de SMS com intervalo:

START → LOOP (clientes) → TWILIO SMS → DELAY (5s) → END LOOP

Retry + SMS

Retentar SMS se falhar:

START → TWILIO SMS → CONDITION (failed?) → RETRY (max 3x) → END

Exemplos de Casos de Uso Reais

1. Sistema 2FA Banking

  • Cliente solicita login
  • Gera código 6 dígitos
  • Envia SMS com código
  • Valida código digitado
  • Concede acesso se correto

2. Confirmação de Consultas Médicas

  • 24h antes da consulta
  • Liga para paciente
  • Coleta confirmação via DTMF
  • Se cancelar: libera horário
  • Se confirmar: mantém agendamento

3. Alerta de Fraude em Cartão

  • Sistema detecta transação suspeita
  • Liga para cliente imediatamente
  • Pergunta: "Você fez compra de R$ 5000?"
  • Se não: Bloqueia cartão
  • Se sim: Aprova transação

4. Pesquisa NPS Pós-Compra

  • 7 dias após entrega
  • Liga para cliente
  • Coleta nota 0-10
  • Agradece participação
  • Registra no analytics

5. Lembrete de Boleto Vencendo

  • 3 dias antes do vencimento
  • Envia SMS com link de pagamento
  • Se não pagar: SMS dia anterior
  • Se pagar: SMS de confirmação
  • Twilio Console: https://console.twilio.com
  • Documentação SMS: https://www.twilio.com/docs/sms
  • Documentação Voice: https://www.twilio.com/docs/voice
  • TwiML Reference: https://www.twilio.com/docs/voice/twiml
  • Pricing: https://www.twilio.com/pricing
  • Status Page: https://status.twilio.com
  • Support: https://support.twilio.com

Próximos Passos

  1. Leia a documentação completa dos nodes:
  2. SMS Send

  3. Call Make

  4. Crie conta Twilio e obtenha credenciais

  5. Teste primeiro SMS/Chamada

  6. Implemente caso de uso real

  7. Configure webhooks para produção

  8. Monitore analytics e otimize

Documentação criada em: 2025-01-15 Versão: 1.0 Última atualização: 2025-01-15