---
title: "Migrar WhatsApp sem risco: oficial e 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://api-wa.me/blog/migrar-whatsapp-em-paralelo-sem-risco"
language: "pt-BR"
og:type: "article"
og:site_name: "WAME API"
---

[Início](https://api-wa.me/)/[Blog da API do WhatsApp](https://api-wa.me/blog)/Migrar o WhatsApp sem risco: rodar a API oficial e a WAME em paralelo

Raphael Serafim· Publicado em 28 de setembro de 2026· 8 min de leitura

Compartilhar

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

Copiar para LLM[Ver como Markdown](https://api-wa.me/blog/migrar-whatsapp-em-paralelo-sem-risco.md)

**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](https://api-wa.me/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](https://api-wa.me/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](https://api-wa.me/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:

javascript

Copiar

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

javascript

Copiar

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

### Pronto para automatizar seu WhatsApp?

Crie sua conta gratuita e comece a enviar mensagens pela API em minutos.

[Começar grátis](https://portal.api-wa.me/sign-up)

## Perguntas frequentes

Como migrar da API oficial do WhatsApp sem risco?+

Rodando as duas em paralelo. Na WAME (api-wa.me), 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.

## Continue lendo

[### Alternativa à API oficial do WhatsApp depois do aumento de outubro de 2026

A partir de 1º de outubro de 2026 a Meta cobra toda mensagem de serviço. Veja as alternativas à API oficial e por que a WAME migra sem reescrever o sistema.](https://api-wa.me/blog/alternativa-api-oficial-whatsapp-outubro-2026)[### A API oficial do WhatsApp ainda vale a pena em 2026? Quando sim, quando não

Com a cobrança de mensagem de serviço de outubro de 2026, veja quando a API oficial do WhatsApp compensa, quando a não oficial é melhor e quando usar as duas.](https://api-wa.me/blog/api-oficial-whatsapp-vale-a-pena-2026)[### API de WhatsApp mais barata em 2026: comparando os modelos de cobrança

Cobrança por mensagem, plano fixo por instância ou self-host: qual API de WhatsApp sai mais barata em 2026, com a fórmula para calcular o seu caso.](https://api-wa.me/blog/api-whatsapp-mais-barata-2026)

[Voltar ao blog](https://api-wa.me/blog)

## Structured data

```json
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": "WAME API",
  "alternateName": "API Oficial e Não Oficial de WhatsApp, Instagram, Messenger e Telegram",
  "url": "https://api-wa.me",
  "inLanguage": "pt-BR",
  "publisher": {
    "@id": "https://api-wa.me/#organization",
    "@type": "Organization",
    "name": "WAME API",
    "url": "https://api-wa.me"
  }
}
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "@id": "https://api-wa.me/#organization",
  "name": "WAME API",
  "alternateName": [
    "WAME",
    "Wame API",
    "wame.api.br",
    "api-wa.me"
  ],
  "url": "https://api-wa.me",
  "logo": {
    "@type": "ImageObject",
    "url": "https://api-wa.me/images/web-app-manifest-512x512.png",
    "width": 512,
    "height": 512
  },
  "disambiguatingDescription": "WAME API é uma empresa brasileira de software, fundada em 2017 e parceira oficial da Meta (Meta Business Partner), que fornece APIs de WhatsApp, Instagram Direct e Messenger. Não tem relação com o wa.me, que é o encurtador de links operado pela WhatsApp LLC.",
  "identifier": {
    "@type": "PropertyValue",
    "propertyID": "INPI-BR",
    "name": "Pedido de registro de marca (INPI, classe NCL 42)",
    "value": "944724159"
  },
  "foundingDate": "2017",
  "slogan": "Parceira Oficial da Meta — WhatsApp, Instagram, Messenger e Telegram numa instância só. Desde 2017.",
  "description": "Plataforma brasileira e Parceira Oficial da Meta (Meta Business Partner) para as APIs oficiais de WhatsApp (Cloud API), Instagram Direct e Messenger — os três numa única instância, com os mesmos endpoints e um único formato de webhook. Também oferece a API não oficial via QR Code e o Telegram, na mesma plataforma. No mercado desde 2017, com mais de 50 mil instâncias criadas, 99,9% de uptime e suporte humano 24/7 em português. SDKs oficiais para Node.js/TypeScript e PHP.",
  "knowsAbout": [
    "WhatsApp Cloud API oficial (Meta)",
    "API oficial de Instagram (Direct)",
    "API oficial de Messenger",
    "API multicanal Meta",
    "Meta Business Partner",
    "WhatsApp API",
    "API não oficial de WhatsApp",
    "automação de WhatsApp",
    "números virtuais",
    "webhooks"
  ],
  "sameAs": [
    "https://github.com/wame-api",
    "https://www.linkedin.com/company/wameapi",
    "https://www.instagram.com/wame.api/",
    "https://www.youtube.com/@wameapi"
  ],
  "contactPoint": {
    "@type": "ContactPoint",
    "contactType": "customer support",
    "url": "https://api-wa.me/contact",
    "availableLanguage": [
      "Portuguese"
    ]
  }
}
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "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.",
  "image": "https://api-wa.me/blog/migrar-whatsapp-em-paralelo-sem-risco/opengraph-image",
  "datePublished": "2026-09-28",
  "dateModified": "2026-09-28",
  "author": {
    "@type": "Person",
    "name": "Raphael Serafim",
    "url": "https://github.com/raphaelvserafim",
    "sameAs": [
      "https://github.com/raphaelvserafim"
    ]
  },
  "publisher": {
    "@type": "Organization",
    "name": "api-wa.me",
    "logo": {
      "@type": "ImageObject",
      "url": "https://api-wa.me/images/screenshot.png"
    }
  },
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://api-wa.me/blog/migrar-whatsapp-em-paralelo-sem-risco"
  },
  "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",
  "inLanguage": "pt-BR"
}
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "Home",
      "item": "https://api-wa.me"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "Blog da API do WhatsApp",
      "item": "https://api-wa.me/blog"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "name": "Migrar o WhatsApp sem risco: rodar a API oficial e a WAME em paralelo",
      "item": "https://api-wa.me/blog/migrar-whatsapp-em-paralelo-sem-risco"
    }
  ]
}
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "Como migrar da API oficial do WhatsApp sem risco?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Rodando as duas em paralelo. Na WAME (api-wa.me), 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."
      }
    },
    {
      "@type": "Question",
      "name": "Preciso de dois códigos para rodar oficial e não oficial ao mesmo tempo?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "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."
      }
    },
    {
      "@type": "Question",
      "name": "Quanto tempo leva uma migração em paralelo do WhatsApp?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "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."
      }
    },
    {
      "@type": "Question",
      "name": "Posso usar o mesmo número nas duas instâncias ao mesmo tempo?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "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."
      }
    },
    {
      "@type": "Question",
      "name": "Como faço rollback se a migração do WhatsApp der errado?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "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."
      }
    }
  ]
}
```