Migrar o WhatsApp sem risco: rodar a API oficial e a WAME em paralelo

A forma mais segura de migrar da API oficial do WhatsApp é não virar a chave de uma vez: mantenha a instância oficial funcionando, crie uma instância não oficial na WAME (api-wa.me) e use um feature flag para decidir qual das duas atende cada cliente ou segmento. Como as duas usam o mesmo corpo de envio e o mesmo webhook no padrão da Cloud API, o código é um só — e o rollback é trocar o flag. Um plano típico leva uma a duas semanas, e em nenhum momento o atendimento para.

Este guia mostra a arquitetura, o código do roteamento, as métricas para comparar e o momento certo de virar a chave. Se ainda está avaliando o porquê, o contexto de preço está em WhatsApp API mais cara em outubro de 2026.

Por que migrar em paralelo em vez de trocar tudo de uma vez?

Porque migração de canal de atendimento tem três riscos que só aparecem em produção:

• Diferença de comportamento que o teste não pegou (um tipo de mídia, um fluxo com template).
• Diferença de métrica: taxa de entrega, tempo de resposta, erros.
• Impacto no cliente final, que não quer saber de migração nenhuma.

Rodar em paralelo transforma esses riscos em números observáveis. Você move primeiro 5% do tráfego, compara, e só avança quando está igual ou melhor.

Por que a WAME facilita rodar as duas ao mesmo tempo?

A WAME é parceira da Meta (Meta Business Partner / Tech Provider) e oferece, na mesma plataforma e na mesma conta, instâncias oficiais (Cloud API) e não oficiais (conexão por QR Code ou código de pareamento). E as duas falam o mesmo idioma:

O detalhe que viabiliza o paralelo: um parser só. O campo official diz de onde veio o evento; o resto (entry, changes, value.messages, statuses) é igual. A base técnica está em um código só para a API oficial e a não oficial.

E o número de telefone durante o paralelo?

Um número não fica conectado nas duas ao mesmo tempo. Para usar o mesmo número na não oficial, ele precisa sair da Cloud API (na WAME, POST /{key}/instance/official/deregister) e estar ativo no app. Por isso há dois desenhos:

1. Segundo número no paralelo (mais comum). A instância não oficial usa outro número durante a validação — útil para fluxos em que a empresa inicia a conversa e para um segmento de clientes novos.
2. Mesmo número em janela planejada. Você valida o código com um número de teste, e o número principal migra numa janela curta, com a oficial pronta para voltar.

Templates e o histórico de Quality Rating não passam para a não oficial. Se o número usa Coexistência, fale com o suporte antes. O caminho do número está em usar o mesmo número ao sair da Cloud API.

Como implementar o feature flag de roteamento?

O envio escolhe a instância por cliente ou segmento. Um exemplo em Node.js:

const INSTANCIAS = {
  oficial: { base: 'https://us.api-wa.me', key: process.env.KEY_OFICIAL },
  wame: { base: 'https://us.api-wa.me', key: process.env.KEY_NAO_OFICIAL },
};

// Regra do flag: por segmento, por porcentagem ou por cliente
function instanciaPara(cliente) {
  if (cliente.forcarOficial) return 'oficial';           // exceções
  if (cliente.segmento === 'piloto') return 'wame';       // fase 1
  return hash(cliente.id) % 100 < Number(process.env.PCT_WAME) ? 'wame' : 'oficial';
}

async function enviar(cliente, corpoCloudApi) {
  const nome = instanciaPara(cliente);
  const { base, key } = INSTANCIAS[nome];
  const r = await fetch(`${base}/${key}/message`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(corpoCloudApi), // mesmo corpo para as duas
  });
  const resposta = await r.json();
  registrarMetrica(nome, r.status, resposta);
  return resposta;
}

Guarde em qual instância cada conversa está. Se o cliente escreveu para o número da oficial, a resposta sai pela oficial; misturar números no meio da conversa confunde o cliente.

Como receber os webhooks das duas instâncias?

Aponte as duas instâncias para a mesma URL de webhook (cada uma com seu token secreto no caminho) e use o campo official só para métricas e regras específicas:

app.post('/webhook/whatsapp/:segredo', (req, res) => {
  res.sendStatus(200); // responda rápido; processe em fila

  const body = req.body;
  const origem = body.official ? 'oficial' : 'wame';
  const value = body?.entry?.[0]?.changes?.[0]?.value;

  for (const msg of value?.messages ?? []) processarMensagem(msg, origem);
  for (const st of value?.statuses ?? []) registrarStatus(st, origem);
});

Duas diferenças que o parser deve conhecer:

• Mídia recebida: na não oficial, o evento traz id e uma url da WAME (https://us.api-wa.me/{key}/message/{id}/media) para baixar o arquivo, em vez da busca pelo Graph.
• Assinatura: a não oficial não envia X-Hub-Signature; proteja a rota com token secreto na URL. Veja webhook em produção.

Quais métricas comparar antes de avançar?

Compare as duas instâncias no mesmo período, pelos webhooks de statuses e pelos seus logs:

Na instância não oficial, trate também o 429: a WAME freia envio para gente nova demais por minuto e o mesmo texto para muitos números. No paralelo, isso aparece cedo se algum fluxo seu tem cara de disparo. Os sinais de risco estão em sinais de que o número está em risco.

Qual é um cronograma realista?

Um exemplo de uma a duas semanas:

1. Dias 1–2: instância não oficial conectada, webhook apontado, parser com o campo official, flag em 0%.
2. Dias 3–5: segmento piloto (clientes internos ou um grupo pequeno), revisão diária das métricas.
3. Dias 6–10: porcentagem crescente (10%, 25%, 50%), sempre comparando.
4. Virada: atendimento reativo majoritariamente na WAME; oficial mantida para o que precisa dela (templates de marketing, Flows) ou desligada.

Se algo sair do esperado, o rollback é voltar o flag para oficial — sem deploy e sem mexer no parser.

O que deve continuar na oficial?

Nem tudo precisa migrar. Templates de marketing em alto volume, garantia formal da Meta, WhatsApp Flows e pagamentos oficiais seguem melhores na oficial. A conexão não oficial não é afiliada à Meta e o uso é de responsabilidade de quem envia; para atendimento legítimo, a taxa de bloqueio é muito baixa, e a WAME não apoia spam. A divisão de papéis está em estratégia híbrida, e os riscos, em riscos de trocar a oficial pela não oficial.

Em resumo

• Mantenha a oficial ativa e crie uma instância não oficial na mesma conta da WAME.
• Mesmo corpo de envio e mesmo webhook: um código, um parser, campo official para distinguir.
• Feature flag por segmento ou porcentagem; rollback é trocar o flag.
• Compare entrega, leitura, resposta, erros e saúde antes de avançar.
• Uma a duas semanas é um prazo típico.

Conclusão

Migrar da API oficial não precisa ser um salto no escuro. Com a WAME, oficial e não oficial rodam lado a lado, com o mesmo formato da Meta, e a decisão de quem atende cada cliente vira configuração. Você mede, avança em degraus e volta em minutos se precisar. A referência dos endpoints está na documentação, e o passo a passo sem reescrever código está em migrar da oficial para a não oficial sem reescrever.