DEV Community: Raphael Serafim

Um webhook para WhatsApp, Instagram e Messenger — o formato de payload que elimina o if/else

Raphael Serafim — Wed, 09 Sep 2026 15:23:05 +0000

Se você já integrou WhatsApp num produto, conhece o roteiro. Integra o WhatsApp. Aí o cliente pede Instagram Direct. Depois Messenger. Três APIs, três credenciais, três formatos de webhook e três parsers para manter — para fazer, no fim, a mesma coisa: alguém mandou uma mensagem e você precisa responder.

Este artigo é sobre colapsar isso em uma integração só. Na prática: um endpoint, uma chave, um envelope de webhook, com um campo dizendo de qual canal a mensagem veio.

A ideia: normalizar o envelope, não o conteúdo

A Cloud API da Meta já tem um envelope bem definido: entry[] → changes[] → value → messages[]. Instagram Direct e Messenger também entregam conversas pelo grafo da Meta, mas o payload que chega não é idêntico entre os produtos.

A normalização é direta: manter o envelope da Meta exatamente como ele é e acrescentar um campo na raiz dizendo qual é o canal.

{
  "object": "wame",
  "provider": "instagram",
  "official": true,
  "instance": "552199999999",
  "entry": [{
    "changes": [{
      "field": "messages",
      "value": {
        "messages": [{
          "from": "5511999998888",
          "type": "text",
          "text": { "body": "Chegou meu pedido?" }
        }]
      }
    }]
  }]
}

Dois campos carregam toda a informação de roteamento:

provider — whatsapp, instagram ou messenger
official — se veio pela Cloud API da Meta ou pela conexão não oficial por QR Code

O resto é byte por byte a mesma estrutura nos três canais. É esse o truque inteiro, e é por isso que o handler abaixo não tem ramificação.

Lendo: um parser, três canais

A versão ingênua ramifica por canal e duplica o caminho de acesso:

// não faça
if (body.provider === 'whatsapp') {
  const m = body.entry[0].changes[0].value.messages[0];
  salvar(m.from, m.text.body);
} else if (body.provider === 'instagram') {
  const m = body.entry[0].changes[0].value.messages[0];
  salvar(m.from, m.text.body);
}
// ...e mais um else pro messenger

Como o envelope não muda, o if não tem motivo para existir:

app.post('/webhook', (req, res) => {
  const { provider, official, entry } = req.body;

  const msg = entry?.[0]?.changes?.[0]?.value?.messages?.[0];
  if (!msg) return res.sendStatus(200);

  salvar({
    canal: provider,
    de: msg.from,
    tipo: msg.type,
    texto: msg.text?.body,
  });

  res.sendStatus(200);
});

Duas observações que evitam incidente em produção:

Responda 200 rápido. Webhooks no padrão da Meta tentam de novo quando a resposta não é 2xx. Confirme o recebimento primeiro e processe numa fila depois — senão um banco lento vira entrega duplicada.

Nunca assuma que messages[0] existe. Eventos de status (entregue, lido) chegam no mesmo endpoint com outro formato dentro de value. O optional chaining ali em cima não é enfeite.

Enviando: a mesma chamada, muda um campo

curl -X POST "https://us.api-wa.me/SUA_KEY/message/text" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999998888",
    "text": "Seu pedido saiu para entrega",
    "provider": "whatsapp"
  }'

Node / TypeScript:

import { Wame, TypeMessage } from '@raphaelvserafim/client-api-whatsapp';

const wa = new Wame({ server, key });

await wa.message.send({
  type: TypeMessage.TEXT,
  body: {
    to: '5511999998888',
    text: 'Seu pedido saiu para entrega',
    provider: 'instagram', // a única diferença
  },
});

PHP:

use Api\Wame\Wame;

$wa = new Wame([
  'server' => 'https://server.api-wa.me',
  'key'    => 'SUA_KEY',
]);

$wa->message->sendText('5511999998888', 'Seu pedido saiu para entrega');

Mesmo endpoint, mesma credencial, mesmo formato de resposta. Trocar de canal é trocar uma string.

API oficial ou não oficial: o que muda de verdade

Toda integração de WhatsApp chega nessa bifurcação, e ela merece uma resposta honesta em vez de uma resposta comercial.

	Oficial (Cloud API da Meta)	Não oficial (QR Code)
Custo	Mensalidade da instância + cobrança da Meta por template que você inicia	Mensalidade fixa, sem custo por mensagem
Risco de bloqueio	Não existe por usar a API — o número opera dentro das regras da Meta	Existe. Depende do comportamento do número: volume, velocidade e denúncias
Selo verde	Elegível, mediante aprovação da Meta	Não
Limite de disparo	Tier da Meta: começa limitado e cresce com a qualidade do número	Sem limite da plataforma; o limite prático é o comportamento do número
Ativação	Embedded Signup, o fluxo OAuth da própria Meta	Leitura de QR Code, como o WhatsApp Web
Uso ideal	Conformidade, selo verde, campanha em volume	Atendimento, automação, protótipo, custo previsível

A parte que costuma ser omitida: ninguém pode garantir que um número na conexão não oficial não será bloqueado. Quem promete isso está vendendo alguma coisa. O risco vem do comportamento, não da plataforma. Se previsibilidade importa mais que preço, o caminho é a oficial.

Desde 1º de julho de 2025, a Meta cobra por mensagem de template entregue, e não mais por conversa de 24 horas. Responder dentro da janela de 24h aberta pelo cliente é gratuito — a maior parte do atendimento do dia a dia não gera custo por mensagem. Você paga pelos templates que inicia.

O que essa abordagem não resolve

Vale dizer com todas as letras, porque alinha expectativa:

Paridade de recursos não é total. Instagram e Messenger não têm o sistema de templates do WhatsApp, e o WhatsApp não tem o contexto de resposta a story do Instagram. Um envelope unificado normaliza o transporte, não as capacidades de cada produto.
Webhook unificado não é caixa de entrada unificada. Se vários atendentes precisam responder do mesmo número, ainda falta algo como o Chatwoot ou uma inbox sua por cima.
Rate limit continua por canal. Uma credencial só não funde o sistema de tiers da Meta entre os produtos.

Perguntas frequentes

Preciso criar um app no Meta for Developers?
Pelo caminho oficial via Business Partner, não. O app aprovado, o webhook e o token ficam do lado do provedor. Indo direto, sim — mais verificação de negócio, verify token, validação de assinatura HMAC e renovação de token de System User.

Preciso virar Tech Provider para revender?
Não. Dá para conectar a conta oficial dos seus clientes por meio de um parceiro que já tenha a aprovação da Meta.

Consigo continuar usando o número no celular?
Sim, pela Coexistência da Meta: o mesmo número funciona no app WhatsApp Business e na Cloud API ao mesmo tempo. Requisitos: o número precisa estar no app Business, o app precisa ser aberto pelo menos a cada duas semanas, e não pode ser desinstalado nem registrado em outro serviço.

Dá para migrar da não oficial para a oficial depois?
Sim, mantendo o mesmo número. É a principal razão para manter os dois tipos de conexão atrás do mesmo SDK: a migração vira configuração, não reescrita.

E agentes de IA?
Existe um servidor MCP, então assistentes como o Claude conseguem ler e responder conversas nos três canais. Vale saber o limite: o MCP roda dentro de um turno do usuário — o agente age quando você pede. Atendimento automático 24 horas é webhook ou um fluxo no n8n, não MCP.

Resumo

Se você está colocando WhatsApp dentro de um produto, a decisão que mais economiza manutenção não é qual biblioteca usar — é se o seu handler de webhook vai precisar ramificar por canal. Normalize o envelope e o if desaparece.

Documentação, especificação OpenAPI, coleção do Postman e um llms.txt (para integrar com ajuda de IA) estão em api-wa.me/docs. SDKs no npm e no Composer.

Se você integrou Instagram Direct ou Messenger de outro jeito, comenta como estruturou o handler — quero ler.

One webhook for WhatsApp, Instagram and Messenger — the payload shape that lets you write a single parser

Raphael Serafim — Wed, 09 Sep 2026 15:07:10 +0000

Disclosure: I work on WAME API, a Meta Business Partner. The payload format below is what our platform emits, but the structural idea — normalizing three channels into one envelope — applies to any integration you build yourself.

If you have ever wired WhatsApp into a product, you know the shape of the problem. You integrate WhatsApp. Then the client asks for Instagram Direct. Then Messenger. Three APIs, three credentials, three webhook formats, three parsers to maintain — for what is, functionally, the same thing: a person sent you a message and you need to answer it.

This post is about collapsing that into one integration. Concretely: one endpoint, one API key, one webhook envelope, with a single field telling you which channel the message came from.

The core idea: normalize the envelope, not the content

Meta's Cloud API already has a well-defined webhook envelope: entry[] → changes[] → value → messages[]. Instagram Direct and Messenger deliver conversations through the Meta graph as well, but the payload you receive is not identical across products.

The normalization is straightforward: keep Meta's envelope exactly as it is, and add one field at the root that names the channel.

{
  "object": "wame",
  "provider": "instagram",
  "official": true,
  "instance": "552199999999",
  "entry": [{
    "changes": [{
      "field": "messages",
      "value": {
        "messages": [{
          "from": "5511999998888",
          "type": "text",
          "text": { "body": "Is my order on the way?" }
        }]
      }
    }]
  }]
}

Two fields carry all the routing information you need:

provider — whatsapp, instagram or messenger
official — whether the message came through Meta's Cloud API or through an unofficial QR Code connection

Everything else is byte-for-byte the same structure across the three channels. That is the entire trick, and it is why the handler below has no branching.

Reading it: one parser, three channels

The naive version of this handler branches per channel and duplicates the access path:

// don't
if (body.provider === 'whatsapp') {
  const m = body.entry[0].changes[0].value.messages[0];
  save(m.from, m.text.body);
} else if (body.provider === 'instagram') {
  const m = body.entry[0].changes[0].value.messages[0];
  save(m.from, m.text.body);
}
// ...and one more for messenger

Since the envelope does not change, the branch has no reason to exist:

app.post('/webhook', (req, res) => {
  const { provider, official, entry } = req.body;

  const message = entry?.[0]?.changes?.[0]?.value?.messages?.[0];
  if (!message) return res.sendStatus(200);

  save({
    channel: provider,
    from: message.from,
    type: message.type,
    text: message.text?.body,
  });

  res.sendStatus(200);
});

Two practical notes that will save you an incident:

Always return 200 fast. Meta-style webhooks retry on non-2xx. Acknowledge first, process in a queue afterwards — otherwise a slow database turns into duplicate deliveries.

Never assume messages[0] exists. Status events (delivered, read) arrive on the same endpoint with a different value shape. The optional chaining above is not decoration.

Sending: the same call, one field changes

curl -X POST "https://us.api-wa.me/YOUR_KEY/message/text" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999998888",
    "text": "Your order is out for delivery",
    "provider": "whatsapp"
  }'

Node / TypeScript:

import { Wame, TypeMessage } from '@raphaelvserafim/client-api-whatsapp';

const wa = new Wame({ server, key });

await wa.message.send({
  type: TypeMessage.TEXT,
  body: {
    to: '5511999998888',
    text: 'Your order is out for delivery',
    provider: 'instagram', // the only difference
  },
});

PHP:

use Api\Wame\Wame;

$wa = new Wame([
  'server' => 'https://server.api-wa.me',
  'key'    => 'YOUR_KEY',
]);

$wa->message->sendText('5511999998888', 'Your order is out for delivery');

Same endpoint, same credential, same response shape. Switching channels is a string.

Official Cloud API vs unofficial QR Code

This is the fork every WhatsApp integration hits, and it deserves an honest answer rather than a sales one.

	Official (Meta Cloud API)	Unofficial (QR Code)
Cost model	Instance fee + Meta's per-message charge on templates you initiate	Flat monthly fee, no per-message cost
Ban risk	None from using the API — the number operates inside Meta's rules	Real. Depends on the number's behaviour: volume, speed, how many people report it
Green tick	Eligible, subject to Meta approval	No
Throughput	Meta tier system: starts limited, grows with quality rating	No platform limit; the practical limit is the number's behaviour
Setup	Embedded Signup (Meta's own OAuth flow)	Scan a QR code, like WhatsApp Web
Best for	Compliance, green tick, high-volume campaigns	Support desks, automation, prototypes, predictable cost

The part people gloss over: nobody can guarantee an unofficial number will not be blocked. Any vendor promising otherwise is selling you something. The risk comes from behaviour, not from the platform. If predictability matters more than price, use the official path.

Since July 1, 2025, Meta charges per delivered template message rather than per 24-hour conversation. Replying inside a customer-initiated 24-hour window is free — most day-to-day support generates no per-message cost. You pay for the templates you start.

What this approach does not solve

Worth stating plainly, because it sets expectations correctly:

Feature parity is not total. Instagram and Messenger do not have WhatsApp's template system, and WhatsApp does not have Instagram's story-reply context. A unified envelope normalizes transport, not product capabilities.
A unified webhook is not a unified inbox. If several agents need to answer from the same number, you still need something like Chatwoot or your own inbox on top.
Rate limits stay per-channel. One credential does not merge Meta's tier system across products.

FAQ

Do I need to create an app on Meta for Developers?
For the official path through a Business Partner, no. The approved app, webhook and token live on the provider's side. Going direct, yes — plus business verification, verify token, HMAC signature validation and System User token rotation.

Do I need to become a Tech Provider to resell?
No. Reselling official connections to your own clients is possible through a partner that already holds Meta approval.

Can I keep using the number on my phone?
Yes, through Meta's Coexistence: the same number works on the WhatsApp Business app and the Cloud API simultaneously. Requirements: the number must be in the WhatsApp Business app, the app must be opened at least once every couple of weeks, and it must not be uninstalled or registered elsewhere.

Can I migrate from unofficial to official later?
Yes, keeping the same number. This is the main reason to keep both connection types behind one SDK — the migration is a configuration change, not a rewrite.

What about AI agents?
There is an MCP server, so assistants like Claude can read and reply to conversations across the three channels. Worth knowing the boundary: MCP runs inside a user turn — the agent acts when you ask. Unattended 24/7 answering is a webhook or an n8n flow, not MCP.

Takeaway

If you are building WhatsApp into a product, the decision that saves the most maintenance is not which library to use — it is whether your webhook handler will need to branch per channel. Normalize the envelope and the branch disappears.

Docs, OpenAPI spec, Postman collection and an llms.txt (for integrating with AI assistants) are at api-wa.me/docs. SDKs: npm and Composer.

If you have integrated Instagram Direct or Messenger with a different approach, I would like to read how you structured the handler — drop it in the comments.

Como implementar OTP (código de confirmação) por WhatsApp no Brasil

Raphael Serafim — Fri, 03 Jul 2026 00:37:58 +0000

Guia prático para adicionar verificação por código OTP via WhatsApp oficial no seu sistema, com exemplos em Node.js, PHP e Python — e comparação honesta de custos entre WhatsApp, SMS e e-mail

Como implementar OTP (código de confirmação) por WhatsApp no Brasil

Se você tem um cadastro, login ou checkout, em algum momento vai precisar confirmar que o usuário realmente controla o número de telefone que informou. Esse é o trabalho do OTP (One-Time Password, ou senha de uso único): você envia um código, o usuário digita, você confere.

No Brasil, mandar esse código por WhatsApp costuma ser melhor que por SMS — mais gente lê, entrega mais e custa menos. Neste post eu mostro como implementar isso na prática, com código que roda, e comparo os canais de forma honesta (inclusive citando alternativas pagas).

Por que WhatsApp e não SMS?

Critério	WhatsApp oficial	SMS	E-mail
Entregabilidade	Alta	Média	Baixa (cai em spam)
Taxa de leitura	~98%	~90%	~20%
Custo por envio	~R$ 0,03	R$ 0,08–0,15	Baixo, mas pouco lido
Copiar código	Botão nativo	Manual	Manual

O SMS ainda é um bom fallback para quem não usa WhatsApp, mas como canal principal de OTP no Brasil, o WhatsApp ganha na maioria dos casos.

⚠️ Use sempre a API oficial do WhatsApp (WhatsApp Business Platform), não automação de WhatsApp Web. Automação não oficial derruba a entrega e corre risco de bloqueio pela Meta.

O fluxo em 2 passos

Toda implementação de OTP tem a mesma forma:

Enviar o código (send) → você gera um código e manda pelo canal.
Verificar o código (verify) → o usuário digita e você confere.

O detalhe importante: a resposta do send confirma que a mensagem foi aceita, mas a entrega no aparelho é assíncrona. Para OTP isso não é problema — a própria verificação já é a prova de entrega. Se o usuário digitou o código certo, chegou. Você não precisa de webhook nem de polling de status.

Implementando com uma API pronta

Você pode falar direto com a WhatsApp Business Platform, mas isso exige aprovação de template, gestão de número e conta na Meta. Para ir mais rápido, dá pra usar um provedor que já cuida disso. As opções mais conhecidas:

Twilio Verify — global, robusto, ~US$ 0,05 por verificação.
Zenvia / Infobip — grandes players com presença no Brasil.
entrar.api.br — opção brasileira de baixo custo (R$ 0,03 por OTP enviado, verificação grátis), com dois endpoints simples e sem SDK.

Abaixo uso a entrar.api.br porque a API é minimalista (bom pra exemplo), mas o padrão vale pra qualquer provedor.

1. Enviar o código

curl -X POST https://cpf.entrar.api.br/api/otp/send \
  -H "Authorization: Bearer SEU_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"telefone":"+5511999999999"}'

# → { "ok": true, "otpId": "...", "status": "pending" }

Guarde o otpId — é ele que amarra o código ao usuário.

2. Verificar o código

curl -X POST https://cpf.entrar.api.br/api/otp/verify \
  -H "Authorization: Bearer SEU_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"otpId":"...","codigo":"123456"}'

# → { "ok": true, "verified": true }

Exemplos por linguagem

Node.js

async function enviarOtp(telefone) {
  const res = await fetch("https://cpf.entrar.api.br/api/otp/send", {
    method: "POST",
    headers: {
      Authorization: "Bearer SEU_API_SECRET",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ telefone }),
  });
  return res.json(); // { ok, otpId, status }
}

async function verificarOtp(otpId, codigo) {
  const res = await fetch("https://cpf.entrar.api.br/api/otp/verify", {
    method: "POST",
    headers: {
      Authorization: "Bearer SEU_API_SECRET",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ otpId, codigo }),
  });
  return res.json(); // { ok, verified }
}

PHP

function enviarOtp(string $telefone): array {
  $ch = curl_init("https://cpf.entrar.api.br/api/otp/send");
  curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
      "Authorization: Bearer SEU_API_SECRET",
      "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode(["telefone" => $telefone]),
  ]);
  return json_decode(curl_exec($ch), true);
}

Python

import requests

def enviar_otp(telefone: str) -> dict:
    res = requests.post(
        "https://cpf.entrar.api.br/api/otp/send",
        headers={"Authorization": "Bearer SEU_API_SECRET"},
        json={"telefone": telefone},
    )
    return res.json()

Boas práticas de segurança

Códigos de uso único e com expiração curta (ex.: 10 minutos).
Limite tentativas de verificação por otpId para evitar força bruta.
Rate-limit no reenvio — não deixe reenviar OTP em loop para o mesmo número.
Nunca exponha o API Secret no front-end — mantenha só no back-end.

Conclusão

OTP por WhatsApp resolve verificação de telefone no Brasil com boa entrega e custo baixo. O fluxo é simples — send e verify — e você não precisa de webhook: a verificação já é a confirmação de entrega. Se quiser o caminho mais barato e direto, a entrar.api.br cobra R$ 0,03 por envio; se precisar de escala global com fallback automático de canal, Twilio Verify e Infobip são alternativas maduras.

Escrevi este guia com base na implementação real da entrar.api.br, uma camada de identidade brasileira (CPF + OTP + verificação de idade) usada em produção por instituições como a faculdade Unifama e plataformas de alto volume como o 123 Bolão.

API WhatsApp

Raphael Serafim — Mon, 07 Oct 2024 19:27:57 +0000

Descubra uma abordagem única para aprimorar suas interações no WhatsApp com nossa API não oficial.
Simplifique a comunicação, envie mensagens de forma versátil e alcance resultados excepcionais para o seu negócio
https://api-wa.me