Um código só para a API oficial e a não oficial do WhatsApp (corpo da Cloud API)

Sim, dá para escrever uma única integração que serve a API oficial e a não oficial do WhatsApp: na WAME, o endpoint POST /{key}/message aceita exatamente o corpo da WhatsApp Cloud API e devolve o mesmo envelope de resposta, e o webhook no formato meta entrega os eventos no padrão da Meta. Você começa pela API não oficial — conectando por QR Code, sem aprovação —, e quando quiser migrar ou rodar as duas, troca a key da instância em vez de reescrever envio e recebimento.

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

O problema que isso resolve

Quem começa com uma API não oficial costuma escrever o código no formato daquela API: to e text num endpoint, url e caption noutro, webhook com o formato próprio da biblioteca. Funciona. Até o dia em que o cliente pede a API oficial — por exigência de compliance, volume de notificação ou política interna — e o time descobre que precisa reescrever a camada de mensagens inteira.

O caminho inverso também dói: quem nasceu na Cloud API e quer grupos, status ou ligações precisa aprender outro formato do zero.

A saída é escrever uma vez, no formato da Meta, e deixar a plataforma traduzir. É o que o POST /{key}/message faz.

O envio: corpo da Cloud API, qualquer instância

O corpo é o mesmo que você mandaria para o graph.facebook.com:

curl -X POST "https://us.api-wa.me/SUA_KEY/message" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "5511999999999",
    "type": "text",
    "text": { "body": "Seu pedido saiu para entrega.", "preview_url": false }
  }'

Mídia usa link, como na Meta:

curl -X POST "https://us.api-wa.me/SUA_KEY/message" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "5511999999999",
    "type": "document",
    "document": {
      "link": "https://exemplo.com/nota-fiscal.pdf",
      "filename": "nota-fiscal.pdf",
      "caption": "Sua nota fiscal"
    }
  }'

Os tipos aceitos nesse endpoint são text, image, audio, video, document, sticker, location, reaction, interactive (botões, lista e cta_url) e contacts. Se a key for de uma instância não oficial, a mensagem sai pelo número conectado por QR Code; se for de uma instância oficial, sai pela Cloud API. O seu código não sabe a diferença — e nem precisa saber.

O recebimento: webhook no envelope da Meta

Do lado da entrada, configure o formato 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-dominio.com/webhook",
    "webhookFormat": "meta"
  }'

Todo evento passa a chegar como na Cloud API:

{
  "object": "wame",
  "provider": "whatsapp",
  "entry": [{
    "id": "<instance-id>",
    "changes": [{
      "field": "messages",
      "value": {
        "messages": [{
          "from": "5511999999999",
          "id": "wamid.XXXX",
          "type": "text",
          "text": { "body": "qual o prazo de entrega?" }
        }]
      }
    }]
  }]
}

O mesmo extrator lê mensagens de instância oficial e não oficial. O campo provider indica o canal — o mesmo envelope vale para Instagram e Messenger, como explicado em um webhook para WhatsApp, Instagram e Messenger.

Durante uma migração, o valor both ajuda: a instância envia o formato nativo e o meta, e você troca os consumidores aos poucos sem janela de corte.

O que muda de verdade entre oficial e não oficial

Formato igual não quer dizer regras iguais. Vale deixar explícito no código o que é de cada lado:

Quando o seu código manda para uma instância oficial um tipo de mensagem que ela não suporta, a API responde 422 com uma mensagem clara. É um erro de lógica — não tente de novo; trate como decisão de produto.

As diferenças de regra estão detalhadas em API sem template e sem janela de 24h e no comparativo oficial vs não oficial.

Arquitetura: capacidades por instância

O jeito limpo de lidar com essas diferenças é não espalhar if (oficial) pelo código. Declare as capacidades de cada instância num lugar só e consulte antes de montar a mensagem:

const INSTANCIAS = {
  loja_sp:   { key: process.env.KEY_SP,   oficial: false },
  loja_rj:   { key: process.env.KEY_RJ,   oficial: true  },
};

const capacidades = (inst) => ({
  textoLivreFrio: !inst.oficial,
  grupos: !inst.oficial,
  status: !inst.oficial,
  templates: inst.oficial,
});

async function enviar(instId, corpoMeta) {
  const inst = INSTANCIAS[instId];
  const r = await fetch(`https://us.api-wa.me/${inst.key}/message`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ messaging_product: 'whatsapp', ...corpoMeta }),
  });
  if (r.status === 422) throw new Error(`Tipo não suportado em ${instId}`);
  if (r.status === 429) throw new Error('Freio de envio: desacelere a fila');
  return r.json(); // mesmo envelope de resposta da Cloud API
}

Com isso, a regra de negócio pergunta "essa instância pode iniciar conversa com texto livre?" em vez de "essa instância é oficial?". Quando uma loja migrar, você muda um booleano.

Para recursos que só existem num lado — criar grupo, postar status, ligar —, use os endpoints específicos (/groups, /status/text, /call) guardados atrás da capacidade correspondente. São exatamente os recursos que tornam a camada não oficial interessante; veja as vantagens da API não oficial.

Três estratégias que funcionam

1. Validar na não oficial, migrar depois. Você conecta um número em minutos, testa o produto com clientes reais e, quando o volume ou o contrato exigir, cria a instância oficial e troca a key. O esforço da migração vira regra de negócio (templates para iniciar conversa), não reescrita de integração. O passo a passo de levar o número está em migrar para a API oficial sem perder o número.

2. Rodar as duas lado a lado. Oficial para notificação transacional em volume (confirmação, cobrança, rastreio, com template), não oficial para atendimento rico, grupos de clientes e status. O mesmo código envia para as duas; o que muda é a instância escolhida por tipo de mensagem.

3. Oferecer as duas no seu SaaS. Se você revende WhatsApp dentro de um CRM ou ERP, pode deixar o cliente escolher o tipo de conexão. A sua camada de mensagens não muda — só a tabela de capacidades. Mais sobre esse modelo em WhatsApp API para CRM e SaaS.

Cuidados que não mudam com o formato

Escrever no formato da Meta não muda o que protege o número na camada não oficial:

• Fale com quem pediu. Texto livre é liberdade, não licença para disparo. A WAME não apoia spam.
• Respeite o 429. Ele aparece quando a instância fala com números novos demais em pouco tempo ou repete o mesmo texto para números demais. Desacelere a fila em vez de insistir.
• Contato frio: texto antes de interativa. Botões e listas podem não aparecer na primeira mensagem de uma conversa que nunca existiu. Abra com texto.
• Ouça o evento de saúde. No webhook de conexão chega o evento health com should_pause; quando vier verdadeiro, pare a fila.

Com isso, a taxa de bloqueio na camada não oficial fica muito baixa para quem usa do jeito certo. Os detalhes estão em o que realmente derruba um número.

Conclusão

A escolha entre API oficial e não oficial não precisa ser uma aposta irreversível no código. Escrevendo o envio no corpo da Cloud API com POST /{key}/message e o recebimento no webhook meta, a mesma integração serve os dois tipos de instância: você começa rápido na não oficial, migra ou combina com a oficial trocando a key, e isola as diferenças reais — templates e janela de um lado, grupos, status e ligações do outro — numa tabela de capacidades por instância. A referência completa está na documentação.