Como migrar da Evolution API para a API oficial do WhatsApp sem perder o número

Quem migra da Evolution API quase nunca migra por vontade. Migra porque um número caiu, porque um cliente grande exigiu API oficial, ou porque a operação cresceu a ponto de o risco de ban virar risco de contrato. Se você chegou aqui nesse ponto, este é o passo a passo. Se ainda está decidindo, o comparativo está em alternativa à Evolution API para multi-tenant.

O que muda entre Evolution API e Cloud API

A Evolution API mantém uma sessão de WhatsApp Web aberta e finge ser um cliente do WhatsApp. Suas mensagens saem do seu servidor, pela sessão, como se você estivesse com o navegador aberto. Na Cloud API, a Meta hospeda tudo: você chama um endpoint HTTP pra enviar e recebe as mensagens dos clientes por webhook. Não existe sessão pra cair, QR code pra reescanear nem servidor seu no caminho.

Essa diferença de arquitetura explica as duas regras da migração:

• O número só vive em um lugar. Registrou na Cloud API, a sessão da Evolution cai na hora. Não existe período de transição com os dois funcionando.
• Mensagem ativa vira template. Fora da janela de 24 horas depois da última mensagem do cliente, você só inicia conversa com template aprovado pela Meta. O disparo livre da Evolution não existe no oficial.

Passo 1: inventário do que a Evolution faz hoje

Antes de mexer em qualquer coisa, liste o que a sua instância faz. Três perguntas resolvem:

1. Que mensagens saem sem o cliente ter falado antes? Cobrança, lembrete, promoção, aviso de entrega. Cada uma vira um template pra aprovar.
2. O que depende de recurso de app? Grupo, status, enquete, figurinha de terceiros. Isso não existe na Cloud API. Se um fluxo crítico depende de grupo, resolva isso antes de migrar, não depois.
3. Onde as mensagens recebidas chegam hoje? O sistema que consome os eventos da Evolution vai passar a consumir webhooks da Cloud API, com outro formato de payload. Mapeie os campos que você usa.

Passo 2: escolha o caminho do número

Você tem três opções, da mais limpa pra mais específica:

• Mesmo número, dedicado à API. É o caminho padrão: o número sai do app e passa a responder só pela Cloud API. Seus contatos não percebem nada: mesmo nome, mesmo número, e agora com selo de conta verificada alcançável.
• Mesmo número, em Coexistence. O app WhatsApp Business continua no celular do cliente e a API roda junto. Serve quando o dono do número ainda atende manualmente pelo app. Atenção: Coexistence exige o app oficial WhatsApp Business pareado por QR code no fluxo da Meta; não é uma continuação da sessão que a Evolution mantinha. E é menos estável que a conexão dedicada; pra automação de produção, prefira o caminho de cima.
• Número novo. Só faz sentido se o número atual tem histórico ruim (denúncias, bloqueios recentes). Começar limpo custa reconquistar cada contato, então trate como último recurso.

Passo 3: prepare o lado oficial antes de desligar

O erro mais comum: registrar o número primeiro e preparar depois. Como o registro derruba a Evolution, qualquer coisa que faltar vira janela de silêncio com seus clientes. A ordem segura:

1. Crie a conta na plataforma e conecte a WABA do cliente via Embedded Signup, o fluxo oficial da Meta em que o cliente autoriza sem te passar senha.
2. Submeta os templates do seu inventário. A Meta diz que a revisão leva até 24 horas, e em conta nova pode demorar mais, então reserve um dia útil. Comece pelos de utilidade (confirmação, aviso, cobrança), que são os mais baratos e os que a operação não vive sem.
3. Aponte seus sistemas pro webhook novo. Suba o endpoint que recebe os eventos da Cloud API (ou use o forward da plataforma) e teste com um número de teste antes do número real.

Passo 4: a virada

Com templates aprovados e webhook no ar, a virada em si é curta:

1. Desligue os disparos da Evolution (pare os fluxos, não o container ainda).
2. Registre o número na Cloud API. A sessão da Evolution cai; a partir daqui as mensagens chegam pelo webhook.
3. Mande uma mensagem de teste real: um template pra um número seu e uma resposta na janela de 24 horas.
4. Só depois de confirmar os dois sentidos, desligue a instância da Evolution e exporte o que quiser guardar do banco dela.

Passo 5: respeite o aquecimento

Número recém-registrado na Cloud API começa com limite de conversas iniciadas por dia, que sobe conforme a Meta observa a qualidade (leitura, resposta, denúncias). Não despeje a base inteira no primeiro dia: o mesmo comportamento que derrubava número na Evolution derruba a sua nota de qualidade no oficial. Escalone os disparos na primeira semana e monitore o status de qualidade do número.

Quanto custa migrar pra API oficial

Receber mensagem é grátis. Responder dentro da janela de 24 horas é grátis até 30 de setembro de 2026 (depois, R$0,035 por mensagem). Template de utilidade custa R$0,035 e de marketing R$0,3217, cobrados pela Meta por mensagem entregue. A conta completa, com exemplos por volume, está em quanto custa o WhatsApp API em 2026.

O atalho

Todo o lado oficial dessa migração (Embedded Signup, templates, webhooks, isolamento por cliente) é o que a BotoZap entrega pronto. Você faz o inventário e a virada; a burocracia da Meta já está absorvida. Se a sua operação atende mais de um cliente, veja também como revender WhatsApp oficial no Brasil.

Perguntas frequentes