Trocar graph.facebook.com pela WAME: checklist de migração em 30 minutos

Trocar o graph.facebook.com pela WAME (api-wa.me) é, na maior parte, uma troca de configuração: a WAME aceita o mesmo corpo de envio da WhatsApp Cloud API e entrega o webhook no mesmo formato da Meta. Com a integração bem isolada, o código muda em cerca de 30 minutos — URL, autenticação e cinco ajustes pontuais. Este checklist percorre cada item na ordem em que você vai encontrá-los.

A camada não oficial da WAME não é afiliada, endossada ou suportada pelo WhatsApp ou pela Meta. O uso é de responsabilidade de quem envia.

Em resumo

• 5 min: criar a instância, conectar um número de teste e anotar a key.
• 10 min: trocar variáveis de ambiente e a função de envio.
• 10 min: ajustar o webhook (object, roteamento e mídia).
• 5 min: trocar templates por texto e mídia por id por link.
• Depois: rodar o plano de teste e só então virar produção.

Por que fazer isso agora?

A partir de 1º de outubro de 2026, a Meta passa a cobrar por mensagem toda mensagem de serviço e toda Utility de resposta dentro da janela de 24h, desde a primeira. Atendimento que era de graça vira custo. A instância não oficial da WAME cobra um plano fixo por instância, sem cobrança por mensagem. Veja o contexto em alternativa à API oficial depois de outubro.

Checklist 1: preparar o terreno (5 minutos)

• Crie uma instância no painel da WAME.
• Conecte um número de teste por QR Code ou código de pareamento. Não comece pelo número de produção.
• Anote a key da instância. Ela identifica e autentica a instância na URL.
• Se quiser uma camada extra, ative o token de acesso no painel.
• Tenha uma URL pública para o webhook de teste, com um segredo no caminho.

Checklist 2: onde procurar no código

Antes de trocar, descubra onde a Cloud API aparece. Um grep resolve:

grep -rn "graph.facebook.com" src/
grep -rn "whatsapp_business_account" src/
grep -rn "phone_number_id" src/
grep -rn "\"template\"\|type: 'template'" src/
grep -rn "X-Hub-Signature" src/

Cada resultado cai em um dos itens abaixo. Se aparecer em muitos arquivos, vale primeiro centralizar numa função enviarWhatsApp() e num parseWebhook() — isso já reduz a migração a dois arquivos.

Checklist 3: variáveis de ambiente (5 minutos)

Troque as variáveis por outras que descrevam o destino, não o fornecedor:

# Antes
META_API_VERSION=v21.0
META_PHONE_NUMBER_ID=123456789012345
META_ACCESS_TOKEN=EAAG...

# Depois
WHATSAPP_MESSAGES_URL=https://us.api-wa.me/SUA_KEY/message
WHATSAPP_AUTH_HEADER=

Com a URL completa numa variável, você volta para a Cloud API trocando um valor, se precisar.

Checklist 4: função de envio (5 minutos)

async function enviarWhatsApp(corpo) {
  const headers = { 'Content-Type': 'application/json' };
  if (process.env.WHATSAPP_AUTH_HEADER) {
    headers.Authorization = process.env.WHATSAPP_AUTH_HEADER; // Cloud API: "Bearer ..."
  }
  const res = await fetch(process.env.WHATSAPP_MESSAGES_URL, {
    method: 'POST',
    headers,
    body: JSON.stringify(corpo),
  });
  const json = await res.json();
  if (json.error) throw new Error(`${json.error.code}: ${json.error.message}`);
  return json.messages?.[0]?.id; // mesmo formato na Cloud API e na WAME
}

O corpo (messaging_product, to, type, text, image, interactive...) não muda. A resposta também não: contacts[].wa_id e messages[].id. O envelope de erro segue o mesmo error.message, error.code e error_data.

Checklist 5: webhook (10 minutos)

Configure a instância para o formato da Meta:

curl -X PUT "https://us.api-wa.me/SUA_KEY/instance" \
  -H "Content-Type: application/json" \
  -d '{
    "allowWebhook": true,
    "allowNumber": "all",
    "webhookMessage": "https://seu-sistema.com.br/webhook/SEGREDO",
    "webhookFormat": "both"
  }'

Use both durante o teste para comparar os dois formatos e troque para meta depois. No código:

• Object: aceite wame além de whatsapp_business_account.
• Roteamento: metadata.phone_number_id é a key da instância. Se você mapeia cliente por esse campo, cadastre a key. A key também vem em instance, no topo do envelope.
• Assinatura: não há X-Hub-Signature-256 na instância não oficial. Valide o segredo do caminho e desligue a checagem de assinatura para essa origem.
• Mídia recebida: leia a url que vem em image, audio, video, document ou sticker em vez de resolver o id na Graph API.
• Status: statuses[] continua igual, com sent, delivered, read e failed — e played para áudio. conversation e pricing chegam com null.

O campo a campo está em webhook compatível com a Cloud API.

Checklist 6: mídia enviada e templates (5 minutos)

• Mídia por id: a instância não oficial só aceita link. Onde o sistema faz upload na Meta e manda image.id, sirva o arquivo por uma URL pública e mande image.link.
• Templates: type: "template" só funciona em instância oficial. Na não oficial não há template nem janela de 24h — troque por type: "text" com as variáveis já preenchidas.
• Tipos aceitos no /message: text, image, audio, video, document, sticker, location, reaction, interactive e contacts. Outro tipo retorna erro.

Detalhes com antes e depois em migrar da API oficial para a não oficial sem reescrever.

Checklist 7: plano de teste

Rode esta lista contra o número de teste antes de mexer em produção:

Se todos passarem, a sua camada de mensagens está pronta.

Checklist 8: virar produção

• Decida o que fica na oficial (templates de marketing em volume, por exemplo) e o que vai para a não oficial (atendimento). O desenho está em estratégia híbrida.
• Planeje o número: um número registrado na Cloud API não fica ativo no app ao mesmo tempo, e a conexão não oficial usa o app. Veja usar o mesmo número ao sair da Cloud API.
• Vire o tráfego aos poucos, como em migrar em paralelo sem risco.
• Ligue o webhook de conexão para receber o evento de saúde do número e pausar envios quando ele recomendar.

Quais erros mais aparecem na primeira tentativa?

Os mesmos cinco, em quase toda migração:

Um sexto aparece depois, em produção: o sistema que disparava templates em lote passa a disparar texto livre no mesmo ritmo. Na não oficial, isso bate no freio da API (429) quando são muitos números novos por minuto ou o mesmo texto para muita gente. Espalhe os envios com fila, como em fila, rate limit e retry.

O que o checklist não resolve?

Duas coisas dependem de você, não do código:

• Comportamento de envio. Na não oficial, a responsabilidade é de quem envia. A WAME não apoia spam e a API recusa com 429 padrões de disparo em massa. Para quem fala com quem pediu, a taxa de bloqueio é muito baixa.
• Exigências formais. Se o seu cliente exige a API oficial por contrato, mantenha essa parte na oficial — a WAME oferece as duas no mesmo formato.

Conclusão

Sair do graph.facebook.com para a WAME (api-wa.me) não é reescrever a integração: é trocar a URL, a autenticação e cinco detalhes — object do webhook, roteamento, mídia recebida, mídia enviada e templates. Com o checklist acima e um número de teste, você valida tudo antes de 1º de outubro de 2026 e decide com calma o que migrar. A referência dos endpoints está na documentação, e o formato completo do envio em um código só para a API oficial e a não oficial.