Configurar SMS com Twilio

🇺🇸 Twilio: O provedor global líder em comunicações. Ideal para startups com presença internacional.

Este guia mostra como conectar sua conta Twilio à Notifica para enviar SMS. Todo o processo leva cerca de 10 minutos.

---

O que você precisa

• Conta Twilio (gratuita para testes)
• Número de telefone Twilio (ou Messaging Service)
• Account SID e Auth Token

---

Passo 1: Criar conta Twilio

1. Acesse twilio.com/try-twilio
2. Cadastre-se com email corporativo
3. Verifique seu número de telefone (SMS de confirmação)
4. Complete o perfil da conta

💡 Dica: Twilio oferece US$15 em créditos para novas contas — suficiente para milhares de SMS de teste.

---

Passo 2: Obter credenciais

Account SID e Auth Token

1. No Console Twilio, clique no logo Twilio (canto superior)
2. Copie os valores:

Account SID: ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Auth Token:  [Clique em "Show"] xxxxxxxxxxxxxxxxxxxxxxxxxx

⚠️ Segurança: O Auth Token é sensível. Nunca commite em repositórios.

Comprar um número de telefone

1. Vá em Phone Numbers → Manage → Buy a number
2. Selecione Brasil (+55) ou outro país conforme sua necessidade
3. Escolha um número com capacidade de SMS
4. Clique em Buy

Exemplo de número Twilio: +12025551234 (EUA)
                     ou: +551140042222 (Brasil, se disponível)

💡 Dica: Para Brasil, Twilio tem limitações de SMS A2P. Considere usar um número de curto código (short code) para volume alto.

---

Passo 3: Criar Messaging Service (recomendado)

Para melhor gerenciamento e fallback:

1. Vá em Messaging → Services
2. Clique em Create Messaging Service
3. Nome: "Notifica SMS"
4. Use case: "Notifications, 2-way"
5. Adicione seu número de telefone ao serviço
6. Copie o Messaging Service SID: MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

---

Passo 4: Conectar à Notifica

Via Dashboard

1. Acesse Canais → SMS → Adicionar Provedor
2. Selecione Twilio
3. Preencha:

Nome: Twilio Principal
Account SID: ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Auth Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Phone Number: +12025551234
Messaging Service SID (opcional): MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

4. Clique em Validar e Salvar

Via API

curl -X POST https://app.usenotifica.com.br/v1/channels/sms/providers \
  -H "Authorization: Bearer nk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Twilio Principal",
    "provider": "twilio",
    "credentials": {
      "account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "auth_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "phone_number": "+12025551234",
      "messaging_service_sid": "MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    },
    "settings": {
      "default_sender": "SuaEmpresa",
      "smart_encoding": true,
      "status_callback_enabled": true
    }
  }'

Resposta:

{
  "id": "sms_prov_twilio_001",
  "name": "Twilio Principal",
  "provider": "twilio",
  "status": "pending_validation",
  "phone_number": "+12025551234",
  "created_at": "2024-01-15T10:00:00Z"
}

---

Passo 5: Validar configuração

curl -X POST https://app.usenotifica.com.br/v1/channels/sms/providers/validate \
  -H "Authorization: Bearer nk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "twilio",
    "credentials": {
      "account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "auth_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
  }'

Resposta:

{
  "valid": true,
  "account": {
    "friendly_name": "Sua Empresa",
    "status": "active",
    "balance": "15.00",
    "currency": "USD"
  }
}

---

Passo 6: Testar envio

Via Dashboard

Vá em Canais → SMS → Twilio → Testar

Via API

curl -X POST https://app.usenotifica.com.br/v1/channels/sms/providers/sms_prov_twilio_001/test \
  -H "Authorization: Bearer nk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+5511987654321",
    "message": "Teste de integração Notifica + Twilio! Funcionou! 🚀"
  }'

Resposta:

{
  "success": true,
  "provider_message_id": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "segments": 1,
  "price": "0.0075",
  "currency": "USD"
}

---

Passo 7: Ativar provedor

curl -X POST https://app.usenotifica.com.br/v1/channels/sms/providers/sms_prov_twilio_001/activate \
  -H "Authorization: Bearer nk_live_sua_chave"

---

Configurar Webhooks (status de entrega)

Para receber confirmações de entrega, leitura e falhas:

URL de Webhook Twilio

https://app.usenotifica.com.br/webhooks/sms/twilio/:tenant_id

O tenant_id é fornecido pela Notifica após criar o provedor.

Configurar no Twilio

1. No Console Twilio, vá em Phone Numbers → Manage → Active numbers
2. Clique no seu número
3. Em Messaging, configure:
   • Webhook: https://app.usenotifica.com.br/webhooks/sms/twilio/seu_tenant_id
   • HTTP Method: POST

Ou, se usar Messaging Service:

1. Messaging → Services → Seu Serviço
2. Integration
3. Status Callback: https://app.usenotifica.com.br/webhooks/sms/twilio/seu_tenant_id

---

Enviando SMS via API

Agora que está configurado, envie SMS normalmente:

curl -X POST https://app.usenotifica.com.br/v1/notifications \
  -H "Authorization: Bearer nk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "to": {
      "phone": "+5511987654321"
    },
    "channel": "sms",
    "content": "Seu código de verificação é: 583921"
  }'

Node.js

async function sendSMS(phone, message) {
  const response = await fetch('https://app.usenotifica.com.br/v1/notifications', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.NOTIFICA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      to: { phone },
      channel: 'sms',
      content: message.slice(0, 160) // Twilio cobra por segmento
    })
  });
  
  return response.json();
}

// Enviar OTP
await sendSMS('+5511987654321', 'Seu código é: 583921');

Python

def send_sms(phone: str, message: str):
    response = requests.post(
        'https://app.usenotifica.com.br/v1/notifications',
        headers={'Authorization': f'Bearer {API_KEY}'},
        json={
            'to': {'phone': phone},
            'channel': 'sms',
            'content': message[:160]
        }
    )
    return response.json()

---

Códigos de erro Twilio

Código	Significado	Ação
21608	Número desabilitado para SMS	Contatar suporte Twilio
21610	Mensagem para número opt-out	Remover da lista
21612	Número inválido	Validar formato
21614	Não é número de celular	Verificar número
30003	Unreachable destination	Retry mais tarde
30005	Número desconhecido	Remover da lista
30008	Erro desconhecido	Retry

---

Preços Twilio

Destino	Custo aprox. (USD)
Brasil	$0.04 - $0.08
EUA	$0.0075
Internacional	$0.01 - $0.20

💡 Consulte twilio.com/sms/pricing para valores atualizados.

---

Próximo passo

Configure o Compliance SMS para garantir que seus envios respeitem a LGPD e boas práticas.

Para outras opções de provedor, veja:

• Zenvia (SMS Brasil)
• Provedor Customizado