---
title: "Migrar o WhatsApp sem risco: rodar a API oficial e a WAME em paralelo"
description: "Como migrar da API oficial do WhatsApp sem virar a chave de uma vez: duas instâncias, feature flag, métricas comparadas e rollback em minutos."
url: "https://wame.api.br/blog/migrar-whatsapp-em-paralelo-sem-risco"
language: "pt-BR"
og:type: "article"
published_time: "2026-09-28"
modified_time: "2026-09-28"
author: "Raphael Serafim"
keywords: "migrar whatsapp sem risco, rodar api oficial e não oficial em paralelo, feature flag whatsapp api, migrar api oficial whatsapp, api whatsapp não oficial, alternativa api oficial whatsapp, rollback migração whatsapp"
reading_time: "8 min de leitura"
---

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

> Como migrar da API oficial do WhatsApp sem virar a chave de uma vez: duas instâncias, feature flag, métricas comparadas e rollback em minutos.

**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 (wame.api.br) 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](/blog/mudanca-cobranca-whatsapp-api-outubro-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:

| Item | Instância oficial na WAME | Instância não oficial na WAME |
| --- | --- | --- |
| Envio | `POST /{key}/message` com corpo da Cloud API | O mesmo endpoint e corpo |
| Resposta do envio | `messaging_product`, `contacts`, `messages[].id` | O mesmo formato |
| Webhook | Envelope da Meta | Envelope da Meta (`webhookFormat: "meta"`) |
| Campo `official` no envelope | `true` | `false` |
| Templates | Sim | Não (texto livre) |
| Cobrança da Meta por mensagem | Sim (a partir de out/2026 também serviço) | Não; plano fixo por instância |

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](/blog/mesmo-codigo-api-oficial-e-nao-oficial-whatsapp).

## 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](/blog/usar-mesmo-numero-sair-cloud-api).

## Como implementar o feature flag de roteamento?

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

```js
const INSTANCIAS = {
  oficial: { base: 'https://server.wame.api.br', key: process.env.KEY_OFICIAL },
  wame: { base: 'https://server.wame.api.br', 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:

```js
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://server.wame.api.br/{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](/blog/webhook-producao-assinatura-retry-idempotencia).

## 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:

| Métrica | Como medir | Sinal de alerta |
| --- | --- | --- |
| Taxa de entrega | `delivered` ÷ enviadas | Queda relevante na nova |
| Taxa de leitura | `read` ÷ entregues | Queda persistente |
| Taxa de resposta do cliente | Conversas com retorno ÷ iniciadas | Queda persistente |
| Erros de envio | Respostas com `error` e status `failed` | Erro recorrente de um tipo |
| Tempo de resposta | Envio até `delivered` | Aumento consistente |
| Saúde do número (não oficial) | Evento `health` no webhook de conexão | `should_pause: true` |

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](/blog/sinais-numero-whatsapp-risco-bloqueio).

## 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](/blog/estrategia-hibrida-api-oficial-nao-oficial-whatsapp), e os riscos, em [riscos de trocar a oficial pela não oficial](/blog/riscos-trocar-api-oficial-por-nao-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](/docs), e o passo a passo sem reescrever código está em [migrar da oficial para a não oficial sem reescrever](/blog/migrar-api-oficial-para-nao-oficial-sem-reescrever).

## Perguntas frequentes

### Como migrar da API oficial do WhatsApp sem risco?

Rodando as duas em paralelo. Na WAME (wame.api.br), você mantém uma instância oficial e cria uma instância não oficial na mesma conta, com o mesmo código, porque as duas usam o corpo de envio e o webhook no padrão da Cloud API da Meta. Um feature flag decide qual instância atende cada cliente ou segmento, e voltar atrás é trocar o flag.

### Preciso de dois códigos para rodar oficial e não oficial ao mesmo tempo?

Não. A WAME aceita o mesmo corpo da Cloud API em POST /{key}/message nas duas instâncias e entrega o webhook no mesmo envelope da Meta. O campo official (true ou false) no envelope diz de qual instância veio o evento, e o resto do parser é o mesmo.

### Quanto tempo leva uma migração em paralelo do WhatsApp?

Uma a duas semanas é um prazo comum: alguns dias com um grupo pequeno de clientes, alguns dias ampliando por segmento e a virada final quando as métricas de entrega, resposta e erro estiverem equivalentes. O prazo depende do volume e de quantos fluxos dependem de recursos exclusivos da oficial, como templates.

### Posso usar o mesmo número nas duas instâncias ao mesmo tempo?

Não. Um número registrado na Cloud API não conecta ao mesmo tempo pela conexão não oficial; para usar o mesmo número na não oficial, ele precisa sair da Cloud API e estar ativo no app. Em paralelo, o comum é usar um segundo número na instância não oficial durante o teste, ou migrar o número numa janela planejada.

### Como faço rollback se a migração do WhatsApp der errado?

Com feature flag, o rollback é trocar o valor do flag para a instância oficial, sem deploy. Como o parser de webhook é o mesmo para as duas instâncias, nada no sistema precisa mudar. Mantenha a instância oficial ativa até terminar a validação.