Como migrar da Twilio para uma API de WhatsApp brasileira

Por que devs brasileiros estão saindo da Twilio

Olha, a Twilio é uma empresa incrível. Eles basicamente inventaram o CPaaS moderno. Mas se você está no Brasil e só precisa de WhatsApp, usar Twilio é tipo alugar um Boeing 747 pra ir de São Paulo a Campinas.

Nos últimos meses, a gente tem visto um padrão claro de devs e startups brasileiras migrando. Os motivos são sempre os mesmos:

Se você se identifica com pelo menos dois desses pontos, esse guia é pra você.

O custo real da Twilio pra quem paga em Real

Vamos fazer a conta que ninguém faz. A Twilio cobra em dólar, e o preço que aparece no site deles não inclui os custos de conversão que você paga aqui no Brasil. Vamos usar um cenário real: uma empresa que envia 10.000 mensagens de template de marketing por mês.

=== TWILIO (preços em USD, convertidos pra BRL) ===

Custo por mensagem de marketing (Twilio):
  Meta conversation fee:        ~$0.0625 USD
  Twilio markup por mensagem:   ~$0.005 USD
  Total por mensagem:           ~$0.0675 USD

10.000 mensagens:               $675.00 USD

Conversão pra BRL (dólar a R$5.80):
  Valor bruto:                  R$ 3.915,00
  Spread cambial do cartão ~4%: R$   156,60
  IOF 6.38%:                    R$   249,78
  ─────────────────────────────────────────
  TOTAL REAL:                   R$ 4.321,38/mês

=== ARARA (preços já em BRL) ===

Plano Essencial:                R$    57,00/mês
Custo Meta (repassado em BRL):  R$ 3.625,00
  (sem spread, sem IOF, sem conversão)
  ─────────────────────────────────────────
  TOTAL REAL:                   R$ 3.682,00/mês

=== ECONOMIA ===
Diferença mensal:               R$   639,38
Diferença anual:                R$ 7.672,56
Economia percentual:            ~15%

E isso no cenário de 10k mensagens. Quanto maior o volume, maior a economia, porque o spread e o IOF são percentuais que escalam junto. Uma empresa que envia 100k mensagens/mês está jogando fora quase R$6.000 por mês só em custos cambiais.

Outro ponto que ninguém fala: a previsibilidade. Com a Twilio, seu custo de mensageria varia junto com o dólar. Se o dólar sobe 10% no mês, seu custo sobe 10%. Com billing em BRL, você sabe exatamente quanto vai pagar e pode planejar o fluxo de caixa.

O que você perde ficando na Twilio (spoiler: nada que você use)

O argumento mais comum pra ficar na Twilio é: "mas é uma plataforma completa". Sim, ela é. E esse é o problema.

Você está pagando pelo overhead de:

• Twilio Programmable SMS -- você não manda SMS, você manda WhatsApp
• Twilio Voice -- você não faz ligação pelo sistema
• Twilio Video -- você não tem videochamada no produto
• SendGrid (email) -- você provavelmente já usa Resend ou outro
• Twilio Flex (contact center) -- você não precisa de um call center
• Twilio Segment (CDP) -- você não tá fazendo customer data platform

Se você só precisa de WhatsApp Business API, você precisa de um BSP focado em WhatsApp. Não de uma plataforma que faz 47 coisas e WhatsApp é só mais uma delas.

Migração de código: Twilio SDK vs Arara SDK

Essa é a parte que assusta todo mundo, mas não deveria. A mudança de código é trivial. Vamos comparar lado a lado.

Enviando mensagem de template

import twilio from 'twilio';

const client = twilio(
  process.env.TWILIO_ACCOUNT_SID,
  process.env.TWILIO_AUTH_TOKEN
);

await client.messages.create({
  from: 'whatsapp:+14155238886',
  to: 'whatsapp:+5511999999999',
  contentSid: 'HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
  contentVariables: JSON.stringify({
    '1': 'Maria',
    '2': 'PED-4521'
  })
});

import { Arara } from '@ararahq/sdk';

const arara = new Arara(process.env.ARARA_API_KEY!);

await arara.messages.send({
  to: '5511999999999',
  type: 'template',
  template: {
    name: 'confirmacao_pedido',
    language: 'pt_BR',
    components: [{
      type: 'body',
      parameters: [
        { type: 'text', text: 'Maria' },
        { type: 'text', text: 'PED-4521' }
      ]
    }]
  }
});

Repare em algumas diferenças importantes:

• Uma credencial vs duas (Account SID + Auth Token)
• Número sem prefixo -- não precisa do whatsapp:+ na frente
• Template por nome -- não por Content SID (quem lembra esses hashes?)
• Parâmetros tipados -- não precisa fazer JSON.stringify de variáveis numeradas

Enviando mensagem de texto livre

await client.messages.create({
  from: 'whatsapp:+14155238886',
  body: 'Seu pedido saiu!',
  to: 'whatsapp:+5511999999999'
});

await arara.messages.send({
  to: '5511999999999',
  type: 'text',
  text: 'Seu pedido saiu!'
});

Recebendo webhooks

// Twilio manda dados como form-urlencoded (sim, em 2025)
app.post('/webhook', express.urlencoded({ extended: false }), (req, res) => {
  const { From, Body, MessageSid } = req.body;
  // From vem como "whatsapp:+5511999999999"
  const phone = From.replace('whatsapp:', '');
  console.log(phone, Body);
  res.status(200).send();
});

// AraraHQ manda JSON limpo
app.post('/webhook', express.json(), (req, res) => {
  const event = req.body;

  if (event.type === 'message') {
    console.log(event.from, event.text?.body);
  }

  if (event.type === 'status') {
    console.log(event.messageId, event.status);
    // status: 'sent' | 'delivered' | 'read' | 'failed'
  }

  res.sendStatus(200);
});

A migração de código, na prática, leva uns 10 minutos se você já tem o projeto organizado. É trocar o import, trocar as credenciais e ajustar o formato do payload.

Passo a passo: migração com zero downtime

Aqui vai o processo completo. O objetivo é que seu sistema nunca fique fora do ar durante a migração.

// Rota temporaria pra validacao paralela
app.post('/webhook/arara', express.json(), (req, res) => {
  console.log('[ARARA]', JSON.stringify(req.body));
  // Compare com os eventos da Twilio pra garantir paridade
  res.sendStatus(200);
});

# Troque as dependencias
npm uninstall twilio
npm install @ararahq/sdk

# Atualize o .env
- TWILIO_ACCOUNT_SID=ACxxxxxxxx
- TWILIO_AUTH_TOKEN=xxxxxxxx
+ ARARA_API_KEY=ara_xxxxxxxxxxxxxxxx

O processo inteiro, do cadastro ao deploy em produção, costuma levar entre 1 e 3 horas dependendo do tamanho do projeto. A maioria do tempo vai em testar, não em codar.

E a portabilidade do número? Posso manter o mesmo?

Essa é a pergunta que todo mundo faz, e a resposta é: sim, você pode manter o mesmo número.

O processo funciona assim: a Meta permite a migração de WABA (WhatsApp Business Account) entre BSPs. Quando você migra sua WABA da Twilio pra AraraHQ, seu número, seus templates aprovados e sua quality rating vêm junto. O fluxo é:

1. Você solicita a migração no dashboard da AraraHQ
2. A AraraHQ envia o request de portabilidade pra Meta
3. A Twilio recebe uma notificação e tem 7 dias pra liberar (mas na prática é automático)
4. A Meta transfere a WABA e o número fica disponível na AraraHQ
5. Todo o processo leva de 24h a 72h

Se por algum motivo você não quiser portar o número (ex: o número é dos EUA e você quer trocar pra um +55), basta registrar um novo número brasileiro no dashboard da AraraHQ. O processo é self-service e leva menos de 5 minutos.

Twilio vs AraraHQ: comparativo direto

Quer ver o comparativo detalhado? Confira a página de comparação Arara vs Twilio.

Perguntas que sempre aparecem

Conclusão: pare de pagar pedágio em dólar

A Twilio fez muito pelo ecossistema de comunicações. Mas pra quem está no Brasil e só precisa de WhatsApp, continuar nela é pagar um preço premium por uma plataforma que você usa 5%.

A migração não é difícil, não é arriscada, e não precisa de downtime. É uma troca de SDK, um ajuste de webhook e uma atualização de variáveis de ambiente. O mais difícil é tomar a decisão.

Se você está enviando mais de 1.000 mensagens por mês pela Twilio, a economia já se paga no primeiro mês.