Migrar Baileys para WhatsApp Cloud API sem downtime

Por Que “Apenas Trocar” Causa Downtime

Você está rodando seu bot no Baileys há meses. Agora você conhece os riscos — padrões de detecção que levam a banimentos são reais, e a fiscalização da Meta está ficando mais rígida. Você quer migrar para a API Cloud do WhatsApp. Mas não pode simplesmente apertar um botão.

O que quebra se você “apenas trocar”:

Perda de sessão — Baileys mantém uma sessão de dispositivo persistente (como um WhatsApp Web vinculado). Quando você desliga sem handoff adequado, clientes no meio de uma conversa veem seu número ficar offline. Novas mensagens que eles enviam durante o intervalo são perdidas ou atrasadas.
Contexto da conversa — O estado da conversa do seu agente (onde cada cliente está no fluxo, requisições pendentes, preferências do usuário) vive na memória ou banco de dados da sua instância Baileys. A API Cloud não herda esse estado automaticamente.
Roteamento de webhook — Baileys entrega mensagens via WebSocket ou endpoint REST local. A API Cloud entrega via webhooks HTTPS com validação de assinatura. Se seu agente não estiver pronto para receber webhooks da Cloud API quando você matar o Baileys, as mensagens caem num buraco negro.
Lag de aprovação de templates — A API Cloud requer templates pré-aprovados para mensagens iniciadas pela empresa fora da janela de 24 horas. Se você não criou e aprovou templates antes da migração, perde a capacidade de enviar notificações proativas.
Registro de número — Você não pode usar seu número pessoal do Baileys diretamente na API Cloud. Você precisa de um número empresarial registrado. Clientes que salvaram seu número antigo não saberão automaticamente sobre o novo.

O playbook abaixo evita tudo isso.

Pré-Voo: O Que Configurar Antes do Dia da Migração

1. Registre Seu Número Empresarial na API Cloud

Se você está usando Baileys com um número pessoal do WhatsApp, não pode migrar esse número para a API Cloud. Contas pessoais e contas de Business API são fundamentalmente diferentes.

Suas opções:

Novo número empresarial — Registre um novo número de telefone através do Meta Business Manager (registro direto como Tech Provider) ou através de uma ponte gerenciada como Pipes.bot (fluxo BYON). Este é o caminho mais limpo.
Número pool (para agentes pessoais) — Se seu caso de uso é um agente de IA pessoal (não suporte empresarial), ative um número pool no Pipes.bot. Clientes enviam mensagens para o número pool; mensagens são roteadas para seu agente. Seu número pessoal do Baileys permanece separado.

Cronograma: Reserve 24–48 horas para verificação do número e aprovações iniciais de templates.

2. Crie e Aprove Templates de Mensagem

A API Cloud requer templates de mensagem para mensagens proativas enviadas fora da janela de atendimento ao cliente de 24 horas.

Templates necessários antes da migração:

Mensagem de boas-vindas — Enviada quando o cliente contata seu novo número pela primeira vez
Notificação de handoff (opcional) — Se você está migrando clientes do número Baileys antigo para o novo número Cloud API, precisa de um template para notificá-los: “Estamos fazendo upgrade! Salve este novo número: +55…”
Templates críticos de negócio — Confirmações de pedido, lembretes de compromisso, códigos de autenticação, atualizações de envio

Como criar:

Vá para WhatsApp Manager → Message Templates
Escreva o texto do template com placeholders de variáveis (ex.: {{1}} para nome do cliente)
Submeta para aprovação da Meta (geralmente 1–24 horas)
Teste templates aprovados em sandbox antes da produção

Motivos comuns de rejeição: Linguagem spam, opt-in pouco claro, contexto empresarial ausente. Leia as diretrizes de templates da Meta.

3. Configure e Valide Endpoint de Webhook

A API Cloud entrega mensagens via HTTPS POST para sua URL de webhook. Diferente do Baileys (que seu código consulta ou conecta), a API Cloud é baseada em push.

Requisitos:

URL HTTPS pública com certificado SSL válido
Endpoint GET para handshake de verificação (Meta envia hub.challenge, você ecoa de volta)
Endpoint POST para notificações de mensagem
Validação de assinatura HMAC-SHA256 (usando seu App Secret)
Tratamento de idempotência (Meta retenta entregas falhadas)

Checklist de implementação:

Webhook responde à verificação GET com hub.challenge
Handler POST valida header X-Hub-Signature-256
Deduplicação por wamid (message ID) para prevenir processamento duplo em retentativas
Responde 200 OK em até 20 segundos
Enfileira trabalho do agente assincronamente (não bloqueia webhook em inferência LLM)

Leia o guia completo de webhook: Webhooks da API Cloud do WhatsApp para agentes de IA: retries, idempotência, assinaturas

Testando:

Registre URL de webhook no WhatsApp Manager
Envie mensagem de teste do seu WhatsApp pessoal para seu número Cloud API
Verifique que webhook recebe notificação com assinatura correta
Confirme que seu agente processa e responde com sucesso

Se você está usando uma ponte gerenciada como Pipes.bot: A ponte lida com validação de assinatura de webhook e lógica de retry para você. Você conecta seu agente via WebSocket de saída (sem webhook público necessário).

4. Verifique Portabilidade do Contexto da Conversa

Seu bot Baileys armazena estado da conversa em algum lugar:

Na memória (pior caso — perdido ao reiniciar)
Redis ou cache similar
Banco de dados (Postgres, MongoDB, etc.)

Antes da migração, audite:

Que estado você armazena? (etapa da conversa, preferências do usuário, requisições pendentes, variáveis de sessão)
O estado é chaveado por número de telefone? (bom) ou por ID de sessão do Baileys? (ruim)
Você consegue mapear ID de cliente Baileys para ID de cliente Cloud API? Ambos usam IDs do WhatsApp (formato internacional como 5511999999999), então isso deve ser direto

Estratégia de migração:

Se o estado é chaveado por número de telefone (wa_id), nenhuma mudança necessária — Cloud API usa os mesmos IDs
Se o estado inclui metadados específicos de sessão Baileys, escreva um script de migração para remover isso antes do cutover
Teste que seu agente pode retomar uma conversa iniciada no Baileys depois que é continuada na Cloud API

Arquitetura Dual-Run: Execute Ambos Durante o Cutover

A estratégia de migração mais segura é dual-run: mantenha o Baileys vivo enquanto valida a Cloud API em paralelo, depois troque o tráfego.

Arquitetura:

Fase 1 (Teste):
  Cliente → WhatsApp → Baileys → Seu Agente (produção)
                    → Cloud API (número de teste) → Seu Agente (staging)

Fase 2 (Dual-run):
  Cliente → WhatsApp → Baileys → Seu Agente (recebe, processa, responde)
                    → Cloud API → Seu Agente (recebe, loga, sem resposta)

Fase 3 (Cutover):
  Cliente → WhatsApp → Cloud API → Seu Agente (produção)
  (Baileys desligado)

Como implementar Fase 2 (dual-run):

Roteie webhooks Cloud API para seu agente mas configure uma flag cloud_api_dry_run = true
Seu agente processa mensagens Cloud API (mantém estado da conversa) mas não envia respostas via Cloud API
Baileys continua a receber e responder normalmente
Logue discrepâncias: se uma mensagem chega na Cloud API mas não no Baileys (ou vice-versa), alerte seu monitoramento

Por que isso funciona:

Clientes não veem mudança — Baileys ainda responde
Você valida que Cloud API entrega mensagens corretamente
Testa sua validação de assinatura de webhook e idempotência em tráfego de produção
Estado da conversa já está sincronizado quando você muda para Cloud API

Duração: Execute em modo dual por 24–72 horas. Monitore por:

Taxa de entrega de webhook Cloud API corresponde à taxa de mensagens Baileys
Sem falhas de validação de assinatura
Sem processamento duplicado (idempotência funcionando)
Agente consegue reconstruir estado da conversa a partir de mensagens Cloud API

Checklist de Cutover de Webhook

Quando a validação dual-run passar, você está pronto para fazer o cutover.

A troca:

Anuncie janela de manutenção (opcional) — “Estamos fazendo upgrade dos nossos sistemas. Você pode experimentar atraso de 1–2 minutos nas respostas por volta de [horário].”
Pare o Baileys de enviar respostas — Configure uma flag no seu agente: baileys_readonly = true. Baileys ainda recebe (para logging) mas não envia.
Habilite respostas Cloud API — Configure cloud_api_active = true. Seu agente começa a enviar respostas via Graph API.
Monitore por 15 minutos — Verifique que respostas saem com sucesso, clientes as recebem, sem erros.
Desligue WebSocket Baileys — Desconecte sessão Baileys graciosamente (não apenas mate o processo — chame sock.logout() se sua biblioteca suportar).
Atualize materiais voltados ao cliente — Se você migrou para um novo número, atualize seu site, assinaturas de email, perfis sociais.

Crítico: Faça isso durante horas de baixo tráfego (ex.: 2–4h da manhã no seu mercado principal). Se algo der errado, você tem tempo para fazer rollback antes do tráfego de pico.

Risco de Sessão e Multi-Dispositivo ao Matar o Baileys

Baileys emula um dispositivo vinculado. Quando você o desliga, o WhatsApp vê um evento de “dispositivo desconectado”. Veja o que acontece:

Efeitos imediatos:

WebSocket Baileys fecha
Servidores WhatsApp marcam seu dispositivo emulado como offline
Se você nunca reconectar o Baileys, o “dispositivo” permanece na lista de dispositivos vinculados da sua conta mas inativo

O que NÃO acontece:

Sua conta pessoal do WhatsApp não é deslogada (se você estava usando um número pessoal via Baileys)
Mensagens enviadas para seu número após o Baileys desconectar não são perdidas — são enfileiradas pelos servidores WhatsApp. Quando você conecta Cloud API com o mesmo número (se usou BYON), essas mensagens são entregues à Cloud API. Se está usando um novo número, mensagens antigas ficam com a conta antiga.

Peculiaridade multi-dispositivo:

Se você estava usando Baileys com um número pessoal e migra para um novo número empresarial Cloud API, seu número pessoal permanece ativo. Clientes que enviam mensagens para seu número antigo alcançam seu app WhatsApp pessoal (se você ainda o usa). É por isso que comunicar a mudança de número é crítico.

Mitigação:

Use seu telefone pessoal para enviar mensagem broadcast: “Agora estou usando [novo número] para conversas do bot. Por favor, salve este contato.”
Se o número antigo é apenas para o bot (não uso pessoal), você pode deletar a conta WhatsApp após a migração para forçar clientes a usar o novo número. (Aviso: Isso é irreversível.)

Plano de Rollback: E Se a Cloud API Falhar?

Sempre tenha um caminho de rollback.

Cenário: Você faz cutover para Cloud API, mas 30 minutos depois descobre:

Validação de assinatura de webhook está quebrada (erro de configuração)
Limites de taxa da Cloud API são atingidos (você esqueceu de solicitar throughput maior)
Seu agente trava sob carga da Cloud API
API da Meta tem uma interrupção (raro mas possível)

Passos de rollback:

Re-habilite respostas Baileys — Configure baileys_readonly = false, reinicie conexão WebSocket Baileys
Desabilite respostas Cloud API — Configure cloud_api_active = false
Comunique aos clientes — “Estamos experimentando problemas técnicos. Serviço restaurado via nosso método de contato anterior.”
Investigue e corrija — Debug problema Cloud API em staging
Retente cutover quando corrigido

Janela de rollback: Baileys pode reconectar em minutos. Dados de sessão (chaves de criptografia) persistem no seu arquivo de credenciais Baileys. Desde que você não o tenha deletado, pode reconectar.

Após migração bem-sucedida: Mantenha credenciais Baileys em backup por 7 dias, depois delete. Isso previne reconexão acidental (que poderia disparar detecção de ban).

FAQ: Perguntas Específicas de Migração

Posso migrar meu número de telefone Baileys para Cloud API?

Se é um número pessoal: Não. Contas pessoais do WhatsApp não podem ser convertidas em contas de Business API. Você precisa de um novo número de telefone empresarial.

Se é um número empresarial usado anteriormente com Baileys: Tecnicamente sim, via BYON (Bring Your Own Number) na Cloud API. Mas:

Você precisará verificar propriedade via SMS ou ligação
WhatsApp pode sinalizar o número se foi usado anteriormente com APIs não oficiais (Baileys)
Mais seguro começar com um número novo

O que acontece com mensagens enviadas durante o intervalo de cutover?

Se há uma janela de 2 minutos onde o Baileys está down e a Cloud API ainda não está live:

Cliente envia mensagem → WhatsApp a enfileira
Quando Cloud API fica online → Mensagens enfileiradas são entregues ao seu webhook em segundos
Nenhuma mensagem é perdida desde que o intervalo de cutover seja <5 minutos

A lógica de retry de webhook da Meta lida com interrupções breves. Mas não deixe o intervalo exceder 10 minutos ou as retentativas podem desistir.

Preciso migrar histórico de conversas?

Conteúdo de mensagens: Não. A API Cloud do WhatsApp não dá acesso a mensagens históricas. Apenas novas mensagens (pós-migração) chegam via webhooks.

Estado da conversa: Sim. Se seu agente precisa saber “este cliente está no meio do fluxo de checkout”, esse estado deve persistir através da migração. Armazene em banco de dados chaveado por número de telefone do cliente (wa_id).

Como testo a migração sem afetar clientes de produção?

Estratégia 1: Número de teste

Registre um número de teste separado na Cloud API
Execute seu agente em modo staging conectado ao número de teste
Envie mensagens de teste do seu WhatsApp pessoal
Valide fluxo completo antes de tocar no número Baileys de produção

Estratégia 2: Rollout canário

Se você tem múltiplas instâncias Baileys (ex.: uma por cliente em produto SaaS), migre 5% das instâncias primeiro
Monitore por 48 horas
Se estável, migre os 95% restantes

WAHA ou Evolution API podem ajudar na migração?

Não. WAHA e Evolution API são wrappers em torno do Baileys. Usam o mesmo protocolo de engenharia reversa por baixo dos panos. Migrar do Baileys para WAHA não é uma migração — é permanecer em infraestrutura não oficial com os mesmos riscos de ban.

Leia: Baileys vs WhatsApp Cloud API: por que o bot toma ban

Migrar para Cloud API afeta custos de mensagem?

Sim. A partir de 1º de outubro de 2026, mensagens service da Cloud API são cobradas (com 1.000 grátis por mês por número).

Antes da migração (Baileys):

Custo: $0 por mensagens (mas risco de perder número = custo infinito)

Após migração (Cloud API):

Primeiras 1.000 mensagens service/mês: Grátis
Depois de 1.000: ~$0.0068/mensagem (Brasil) ou taxa utility local
Mais custo do seu LLM (se usar agente IA)

Leia guia de otimização de custo: Playbook de service messages de outubro 2026 do WhatsApp

Posso rodar Baileys e Cloud API no mesmo número simultaneamente?

Não. Um número WhatsApp só pode estar ativo em uma plataforma por vez:

Registrado na Business API → Não pode usar com Baileys
Vinculado a conta pessoal → Não pode registrar na Business API

A estratégia “dual-run” descrita acima usa:

Baileys no seu número antigo (ex.: +55 11 98888-8888)
Cloud API em um número novo (ex.: +55 11 97777-7777)

Ou, se você tem ambientes de teste e produção separados, rode em contas diferentes.

Quando uma Ponte Gerenciada Simplifica a Migração

Se você está migrando um bot de produção e não quer gerenciar infraestrutura de webhook, use uma ponte gerenciada como Pipes.bot.

O que o Pipes.bot fornece para migração:

Já registrado como Tech Provider da Meta — Pule o processo de onboarding de semanas
Conexão WebSocket de saída — Seu agente conecta ao Pipes.bot (sem URL de webhook público necessária). Sem mudanças no seu firewall ou infraestrutura.
Validação de webhook e tratamento de retry embutidos — Validação de assinatura HMAC, idempotência e enfileiramento são tratados pelo Pipes.bot
Números pool ou BYON — Use um número fornecido pelo Pipes.bot (para teste ou agentes pessoais) ou registre seu próprio número empresarial
Teste dual-run — Conecte Cloud API via Pipes.bot enquanto Baileys ainda está rodando. Teste em paralelo, depois troque.

Fluxo de migração com Pipes.bot:

Cadastre-se no Pipes.bot, crie um App
Ative um número pool ou registre seu número empresarial (BYON)
Conecte seu agente ao WebSocket Pipes.bot (mesmo código do agente que fala com Baileys, apenas camada de transporte diferente)
Execute em modo dry-run (recebe mas não responde) enquanto Baileys está live
Valide por 48 horas
Troque: Desabilite respostas Baileys, habilite respostas Cloud API via Pipes.bot
Desligue Baileys

Rollback: Desconecte do WebSocket Pipes.bot, reconecte Baileys. Sem mudanças de infraestrutura necessárias.

Próximos Passos: Inicie a Migração

Semana 1: Configuração

Registre número empresarial na Cloud API (direto ou via Pipes.bot)
Crie e submeta templates de mensagem para aprovação
Configure endpoint de webhook (ou conexão WebSocket Pipes.bot)
Escreva script de migração de estado da conversa (se necessário)

Semana 2: Validação

Teste conexão webhook/WebSocket com mensagens de teste
Habilite modo dual-run (Cloud API recebe mas não responde)
Monitore por 48 horas: verifique entrega, validação de assinatura, idempotência

Semana 3: Cutover

Agende janela de cutover (horas de baixo tráfego)
Desabilite respostas Baileys → Habilite respostas Cloud API
Monitore por erros
Desligue Baileys após 24 horas de operação Cloud API estável

Semana 4: Limpeza

Comunique novo número aos clientes (se aplicável)
Delete credenciais e arquivos de sessão Baileys
Atualize documentação e runbooks
Comemore infraestrutura compatível

Ordem de leitura recomendada:

Baileys vs WhatsApp Cloud API: por que o bot toma ban — Entenda os riscos dos quais você está migrando
Webhooks da API Cloud do WhatsApp para agentes de IA — Implementação técnica de endpoint de webhook
Playbook de service messages de outubro 2026 do WhatsApp — Otimização de custo após migração
Guia de início rápido do Pipes.bot — Se usar ponte gerenciada

Para suporte de migração ou perguntas técnicas, a equipe do Pipes.bot está disponível — o fundador Tulio Faria responde pessoalmente a todas as consultas.