Skip to main content
Baileys é uma biblioteca open source que conecta um número pelo protocolo do WhatsApp Web: roda na sua infra, autentica por QR Code e mantém um socket aberto. A Arara envia pela WhatsApp Business Platform da Meta, por API REST. Migrar é trocar de arquitetura, não só de biblioteca. Esta página vale também para whatsapp-web.js e wppconnect, que seguem o mesmo padrão.

O que muda

O que você passa a ter: templates, webhooks de status de entrega e leitura, dashboard com inbox e campanhas, e recursos como Brain, Smart Links e recuperação de receita. O que você perde:
  • Mensagem sem template a qualquer hora: fora da janela de 24h, só template.
  • Latência de aprovação: template novo depende da Meta.
  • Recursos do WhatsApp Web: grupos, status, listas de transmissão e stickers não são enviados pela Arara.

Diff de arquitetura

Baileys roda como processo persistente:
Se o processo cai, a sessão pode ser perdida e o QR Code precisa ser lido de novo. Com a Arara, o seu lado é stateless:

Diff de código

Envio

Mensagem recebida

isValidAraraSignature recalcula sha256= + HMAC-SHA256 de {X-Arara-Timestamp}.{corpo cru} com o secret da organização e compara em tempo constante. Implementação completa em Webhooks e SDK Node.

Localização, reação e botões

A API aceita esses tipos em POST /v1/messages, dentro da janela de 24h. O SDK Node 2.0.0 aceita interactive, location e reaction em sdk.messages.send, mas os tipa só como objeto genérico, então confira a forma de cada um na tabela:
Cada requisição leva um tipo: templateName, body, interactive, location ou reaction. Mais de um responde 400.

Plano de migração

1. Inventário

  • Todos os pontos do backend que usam o socket.
  • Todos os tipos de mensagem enviados (texto, mídia, localização).
  • Integrações que dependem disso (CRM, loja, ERP).

2. Templates

Tudo que é enviado sem o cliente ter falado nas últimas 24h vira template aprovado:
  • “Oi João, recebemos seu pedido” → pedido_confirmado, UTILITY
  • “Promoção da semana” → oferta_semana, MARKETING
  • “Seu código é 1234” → codigo_verificacao, AUTHENTICATION
Crie pelo dashboard ou POST /v1/templates e aguarde a aprovação antes do cutover.

3. Código

  • makeWASocket → new NodeSDK({ apiKey }) ou chamadas HTTP.
  • sock.sendMessage → sdk.messages.send (template ou texto) ou POST /v1/messages (outros tipos).
  • sock.ev.on('messages.upsert') → rota HTTP de webhook com validação de assinatura.

4. Número

  • Número no app WhatsApp Business: pode ser conectado em coexistência, mantendo o app. Mensagens enviadas pelo celular chegam como message.echo.
  • Número que só existe na sessão do Baileys: registrado na plataforma, deixa de funcionar pelo WhatsApp Web. Planeje a janela de troca.
  • Número novo: roda em paralelo e migra a base aos poucos.
A conexão é feita no dashboard (https://app.ararahq.com), em Números.

5. Cutover

Deploy do código novo, acompanhamento no dashboard e desligamento do processo Baileys depois de validado.

Pegadinhas

Sessão local

Depois de migrar, remova arquivos de sessão, volumes e credenciais do Baileys.

Formato do telefone

Baileys usa JID (5511999999999@s.whatsapp.net). Na Arara, o envio usa +5511999999999 e o webhook de entrada traz data.from só com dígitos.

Grupos

A Arara não envia para grupos. Se a operação dependia disso, valide antes de migrar.

Próximos passos

Conceitos WhatsApp

Janela de 24h e templates.

Migrar do Z-API

Outro gateway via WhatsApp Web, mesma lógica.