Migrar da API oficial para a não oficial do WhatsApp sem reescrever o sistema

Migrar da API oficial para a não oficial do WhatsApp sem reescrever o sistema é possível quando a API de destino fala o mesmo formato da Cloud API. Na WAME (api-wa.me), o envio aceita o mesmo corpo JSON, a resposta vem no mesmo envelope e o webhook sai no padrão da Meta — então a migração é trocar URL e autenticação e ajustar três pontos: mídia enviada, mídia recebida e templates. Este guia mostra cada passo com o código de antes e de depois.

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

• Não muda: corpo de envio, envelope de resposta, envelope de erro, estrutura do webhook, messages[], statuses[], context, interactive.
• Muda: URL base, autenticação, object do webhook, mídia enviada (só link), mídia recebida (baixar pela url da WAME) e templates (viram texto livre).
• Tempo típico: uma tarde para o código, mais o planejamento do número.

Por que migrar agora?

Porque a partir de 1º de outubro de 2026 a Meta passa a cobrar toda mensagem de serviço e toda Utility de resposta dentro da janela de 24h, desde a primeira, sem faixa mensal grátis. Para quem atende muito, cada resposta vira custo. O contexto completo está em WhatsApp API mais cara em outubro de 2026 e as alternativas em alternativa à API oficial depois de outubro.

A API não oficial da WAME cobra por instância, não por mensagem. E, como fala o formato da Meta, o custo de trocar é baixo.

Passo 1: o que muda no envio?

Só a URL e a autenticação. O corpo é o mesmo.

Antes (Cloud API):

const res = await fetch(
  `https://graph.facebook.com/v21.0/${PHONE_NUMBER_ID}/messages`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${META_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      messaging_product: 'whatsapp',
      to: '5511999999999',
      type: 'text',
      text: { body: 'Seu pedido saiu para entrega.' },
    }),
  }
);

Depois (WAME):

const res = await fetch(
  `https://us.api-wa.me/${WAME_KEY}/message`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      messaging_product: 'whatsapp',
      to: '5511999999999',
      type: 'text',
      text: { body: 'Seu pedido saiu para entrega.' },
    }),
  }
);

A key da instância vai na URL e já autentica a chamada. Se você quiser uma camada extra, dá para exigir um token de acesso, ativado no painel da instância.

A dica para fazer isso sem espalhar mudança pelo código é isolar a URL numa variável de ambiente:

// Antes: https://graph.facebook.com/v21.0/PHONE_NUMBER_ID/messages
// Depois: https://us.api-wa.me/SUA_KEY/message
const MESSAGES_URL = process.env.WHATSAPP_MESSAGES_URL;

Passo 2: a resposta muda?

Não. O sucesso vem no mesmo formato da Cloud API:

{
  "messaging_product": "whatsapp",
  "contacts": [{ "input": "5511999999999", "wa_id": "5511999999999" }],
  "messages": [{ "id": "3EB0C767D26A1D8E4B2A" }]
}

E o erro também:

{
  "error": {
    "message": "\"text.body\" is required",
    "type": "invalid_request",
    "code": 100,
    "error_data": { "messaging_product": "whatsapp", "details": "\"text.body\" is required" }
  }
}

Quem guarda messages[0].id para casar com os status do webhook continua fazendo exatamente o mesmo.

Passo 3: o parser de webhook precisa mudar?

Quase nada. Primeiro, configure a instância para entregar no 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": "meta"
  }'

O parser que você já tem continua lendo entry[0].changes[0].value.messages e value.statuses. A única diferença estrutural é o campo object, que vem como wame em vez de whatsapp_business_account:

// Antes
if (body.object !== 'whatsapp_business_account') return;

// Depois (aceita as duas origens)
if (!['whatsapp_business_account', 'wame'].includes(body.object)) return;

O metadata.phone_number_id traz a key da instância — se você roteia por esse campo para descobrir de qual cliente é a mensagem, basta mapear a key no lugar do phone number id. O campo a campo completo está em webhook compatível com a Cloud API.

Um cuidado de segurança: o webhook da Cloud API vem assinado com X-Hub-Signature-256; o da instância não oficial, não. Proteja a URL com um segredo no caminho, como no exemplo acima, e não deixe o endpoint aceitar qualquer origem. Veja segurança da API: token e webhook.

Passo 4: como fica a mídia enviada?

Na Cloud API, dá para enviar mídia por link ou por id de um upload prévio. Na instância não oficial, só por link:

// Continua funcionando
{ type: 'image', image: { link: 'https://cdn.seusite.com/nota.jpg', caption: 'Sua nota' } }

// Não funciona na não oficial: troque o upload por uma URL pública
{ type: 'image', image: { id: '1234567890' } }

Se o seu sistema sobe o arquivo para a Meta e guarda o id, a troca é servir o arquivo por uma URL (seu storage, S3, CDN) e mandar o link.

Passo 5: como fica a mídia recebida?

Na Cloud API, o webhook traz só o id da mídia, e você consulta a Graph API para obter a URL e depois baixa. Na WAME, o webhook já traz a URL de download:

{
  "type": "image",
  "image": {
    "id": "3EB0A1B2C3D4",
    "url": "https://us.api-wa.me/SUA_KEY/message/3EB0A1B2C3D4/media",
    "mime_type": "image/jpeg",
    "caption": "comprovante"
  }
}

A mudança no código é trocar a função que resolvia o media id pela leitura direta de image.url. Detalhes de tamanho e formatos em mídia no webhook do WhatsApp.

Passo 6: o que fazer com os templates?

Na API não oficial não existe template nem janela de 24h. Qualquer mensagem pode ser texto livre, a qualquer hora. Na migração, a chamada de template vira uma mensagem comum:

// Antes: template aprovado com variáveis
{
  type: 'template',
  template: {
    name: 'pedido_enviado',
    language: { code: 'pt_BR' },
    components: [{ type: 'body', parameters: [{ type: 'text', text: 'Carla' }] }],
  },
}

// Depois: texto com as variáveis já preenchidas
{ type: 'text', text: { body: 'Oi, Carla! Seu pedido saiu para entrega.' } }

Liberdade traz responsabilidade: sem template, o filtro contra mensagem indesejada passa a ser você. Mande só para quem pediu. A diferença está explicada em API sem template e sem janela de 24h.

O que é idêntico e o que muda: tabela de referência

E o número?

Esse é o ponto que exige planejamento. Um número registrado na Cloud API não fica ativo no app do WhatsApp ao mesmo tempo, e a conexão não oficial usa o número como aparelho vinculado do app. Para usar o mesmo número, ele precisa sair da Cloud API e voltar para o app — templates e o histórico de qualidade da Cloud API não vão junto. Em instâncias oficiais da WAME, a saída é feita pelo endpoint de descadastro (POST /{key}/instance/official/deregister).

Muita gente prefere não mexer no número principal no primeiro momento: conecta um número novo pela não oficial, move o atendimento aos poucos e compara. O roteiro está em migrar em paralelo sem risco e o passo a passo do número em usar o mesmo número ao sair da Cloud API.

Conclusão

Migrar da API oficial para a não oficial costumava significar reescrever envio, webhook e tratamento de status. Na WAME (api-wa.me), significa trocar a URL, trocar a autenticação e ajustar mídia e templates — o resto do sistema continua falando o formato da Cloud API. Com a cobrança por mensagem de serviço a partir de 1º de outubro de 2026, essa troca deixou de ser detalhe técnico e virou decisão de custo. Faça num ambiente de teste, rode em paralelo e só então vire o tráfego. Os endpoints estão na documentação, e o roteiro rápido em checklist para trocar graph.facebook.com pela WAME.