Webhook compatível com a Cloud API da Meta: o que é idêntico e o que muda na WAME

Na WAME (api-wa.me), o webhook no formato meta segue a mesma estrutura da WhatsApp Cloud API: entry[].changes[].value com messaging_product, metadata, contacts[], messages[] e statuses[], e os mesmos tipos de mensagem e de status. As diferenças são poucas e objetivas — o campo object, o entry.id, o phone_number_id, a URL da mídia e a assinatura. Este artigo é a tabela de referência campo a campo para quem vai migrar um parser da Cloud API.

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

• Igual: estrutura do envelope, value.messages[], value.statuses[], value.contacts[], tipos de mensagem, context, referral, interactive.
• Diferente: object vem wame, entry.id vem mascarado, phone_number_id é a key da instância, mídia traz url de download, sem X-Hub-Signature-256.
• Extras: chat_type, group_id para grupos e from_me para mensagens enviadas pelo próprio número.

Como ativar o formato da Meta?

Por padrão, a instância entrega no formato nativo da WAME. Para o formato da Cloud API, defina webhookFormat:

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"
  }'

Os valores possíveis são native (padrão), meta e both. O both envia os dois formatos e é útil durante a migração, quando parte do sistema ainda lê o formato antigo.

Como é uma mensagem recebida?

{
  "object": "wame",
  "provider": "whatsapp",
  "instance": "SUA_KEY",
  "official": false,
  "entry": [{
    "id": "ID_CODIFICADO",
    "changes": [{
      "field": "messages",
      "value": {
        "messaging_product": "whatsapp",
        "metadata": {
          "display_phone_number": "5511988887777",
          "phone_number_id": "SUA_KEY"
        },
        "contacts": [{ "profile": { "name": "Carla" }, "wa_id": "5511999999999" }],
        "messages": [{
          "from": "5511999999999",
          "chat_type": "individual",
          "id": "3EB0C767D26A1D8E4B2A",
          "timestamp": "1790000000",
          "type": "text",
          "text": { "body": "Meu pedido ainda não chegou" }
        }]
      }
    }]
  }]
}

Repare que, abaixo de entry, tudo tem o nome e a posição que a Cloud API usa. O parser típico continua funcionando:

const value = body?.entry?.[0]?.changes?.[0]?.value;
const msg = value?.messages?.[0];
const nome = value?.contacts?.[0]?.profile?.name;

Como é um status de entrega?

{
  "object": "wame",
  "entry": [{
    "changes": [{
      "field": "messages",
      "value": {
        "messaging_product": "whatsapp",
        "metadata": { "display_phone_number": "5511988887777", "phone_number_id": "SUA_KEY" },
        "statuses": [{
          "id": "3EB0C767D26A1D8E4B2A",
          "status": "read",
          "timestamp": "1790000060",
          "recipient_id": "5511999999999",
          "conversation": { "id": null, "expiration_timestamp": null, "origin": { "type": null } },
          "pricing": { "billable": null, "pricing_model": null, "type": null, "category": null }
        }]
      }
    }]
  }]
}

O id é o mesmo que voltou em messages[0].id na resposta do envio, então a conciliação que você já faz continua valendo. As chaves conversation e pricing existem, mas com null: parsers que leem esses campos não quebram, e nada é cobrado pela Meta na instância não oficial. Quando o envio falha, o status vem failed com errors[], no mesmo formato de código, título e detalhe da Meta.

Tabela de paridade campo a campo

O que muda na prática para o seu código?

Quatro ajustes cobrem quase todos os casos.

1. Validação do object

Se o seu código descarta o que não é whatsapp_business_account, aceite também wame:

const ORIGENS = ['whatsapp_business_account', 'wame'];
if (!ORIGENS.includes(body.object)) return res.sendStatus(200);

2. Roteamento por phone_number_id

Na WAME, metadata.phone_number_id é a key da instância. Se você usa esse campo para descobrir de qual cliente é o evento, cadastre a key no lugar do ID da Meta. O envelope também traz a key em instance, no topo. O entry.id vem mascarado e não serve para roteamento.

3. Download de mídia

Na Cloud API, o webhook traz o id e você chama a Graph API para obter a URL. Na WAME, a URL já vem no evento:

// Antes: resolver o media id na Graph API
// const url = await obterUrlNaGraph(msg.image.id);

// Depois: a URL de download já chega no webhook
const url = msg.image.url; // https://us.api-wa.me/SUA_KEY/message/ID/media

4. Verificação de origem

Sem X-Hub-Signature-256, a proteção é um segredo no caminho da URL e, se possível, restrição de origem. Um endpoint com caminho previsível aceita evento forjado de qualquer um. Veja webhook em produção: assinatura, retry e idempotência.

O que vem a mais no webhook da WAME?

Três campos que a Cloud API não entrega da mesma forma e que ajudam muito:

• chat_type: individual, group, newsletter ou broadcast, sempre presente.
• group_id: o JID do grupo, só em mensagens de grupo. Nesse caso, from é quem enviou.
• from_me: marca mensagens enviadas pelo próprio número, por exemplo por um atendente no celular, quando o webhook de mensagens enviadas está ligado. É o que permite pausar o bot quando um humano assume, como em celular e API no mesmo número.

Além disso, o formato meta cobre os eventos que só existem na conexão não oficial: ligações (campo call), entradas e saídas em grupos (campo groups), conexão (campo connection) e saúde do número (campo health).

E o formato serve para Instagram e Messenger?

Sim. O mesmo envelope é usado para os três canais da WAME, com o campo provider dizendo de onde veio. O padrão está em um webhook para WhatsApp, Instagram e Messenger.

Por que isso importa depois de outubro de 2026?

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. Muitas empresas querem tirar o atendimento da cobrança por mensagem, e o maior custo dessa troca seria reescrever o parser de webhook. Com o formato meta, esse custo praticamente some. O contexto está em alternativa à API oficial depois de outubro e o lado do envio em um código só para a API oficial e a não oficial.

Conclusão

O webhook da WAME (api-wa.me) no formato meta foi feito para que um parser escrito para a WhatsApp Cloud API funcione com o mínimo de mudança: mesma estrutura de entry, changes e value, mesmos messages[] e statuses[], mesmos tipos. O que muda — object, phone_number_id, URL de mídia e assinatura — cabe em quatro ajustes pontuais. Ligue o webhookFormat como both durante a transição, compare os eventos lado a lado e troque para meta quando o parser estiver pronto. O passo a passo completo da migração está em migrar da API oficial para a não oficial sem reescrever.