Webhook do Messenger para Páginas do Facebook: mensagens e menções
O campo messages dos webhooks de Página do Facebook é disparado quando uma pessoa envia uma mensagem do Messenger para a Página, entregando um array messaging com o ID da pessoa vinculado à Página, o ID da Página, um timestamp e o mid da mensagem, com seu texto ou anexos. O campo mention informa novas menções à Página em publicações e comentários, e a Meta assina ambos com X-Hub-Signature-256.
A easyCoexistence repassa as mensagens e menções do Messenger de cada Página conectada ao seu endpoint HTTPS assim que chegam, assinadas com um segredo daquela Página e sem cópia guardada, e o send_social_dm responde dentro da janela de 24 horas.
Em quanto tempo a Meta espera que um endpoint de webhook do Messenger responda cada notificação com 200 OK.
Depois que as entregas falham por esse tempo, a Meta cancela a inscrição do app nos webhooks da Página até que ele se inscreva de novo.
O ID da pessoa vinculado à Página em um evento messages, único para cada par de pessoa e Página.
Como a referência da Meta marca o campo sender de um evento de menção.
Notificações de webhook passadas não podem ser consultadas depois, então o receptor precisa armazenar o que for necessário.
O que o campo messages envia?
Uma notificação quando uma pessoa envia uma mensagem do Messenger para a Página. A Meta envia mensagens de texto ou com anexos, que podem ser imagens, áudio, vídeo, arquivos ou figurinhas, entre outros tipos, e um link compartilhado pode chegar como anexo de reserva. Uma resposta a uma mensagem anterior traz reply_to com o mid dessa mensagem, e uma resposta rápida traz seu payload.
Como é um evento messages?
Diferente das mudanças do feed, a mensagem chega em um array messaging dentro da entrada da Página. Cada evento tem sender, o ID da pessoa vinculado à Página; recipient, a Página; um timestamp; e message, com seu mid e text, ou attachments com um type e uma URL de payload:
{
"object": "page",
"entry": [
{
"id": "<PAGE_ID>",
"time": 1458692752478,
"messaging": [
{
"sender": { "id": "<PSID>" },
"recipient": { "id": "<PAGE_ID>" },
"timestamp": 1458692752478,
"message": {
"mid": "<MESSAGE_ID>",
"text": "hello, world!"
}
}
]
}
]
}O que o campo mention envia?
Uma mudança com field mention quando a Página é mencionada em uma publicação ou comentário, trazendo post_id ou comment_id, a message, qualquer link, foto ou vídeo, além de item e verb. A Meta alerta que alguns desses IDs de publicação e comentário não podem ser consultados, por falta de permissão ou por privacidade, e sua referência marca o campo sender como exclusivo do Workplace, então uma menção pode chegar sem o seu autor.
Quais campos do Messenger não são repassados?
A easyCoexistence inscreve as Páginas em messages, e não em message_echoes, messaging_postbacks, message_reads ou message_deliveries, então as mensagens enviadas pela Página, os toques em botões e os recibos de leitura ou entrega não são repassados. Uma resposta enviada com send_social_dm retorna, no lugar, o próprio ID de mensagem.
Como os eventos chegam ao seu endpoint?
A Meta entrega os webhooks da Página ao app que a Página instalou, por uma única URL de callback para o app inteiro. A easyCoexistence verifica o X-Hub-Signature-256 da Meta em cada entrega, responde à Meta de imediato e repassa cada entrada de uma Página conectada ao endpoint HTTPS que você definir para ela, assinado com o segredo próprio dessa Página. Defina-o com set_social_webhook_destination pelo Claude ou pelo ChatGPT, ou com PUT /channels/:id/webhook na Partner API; o segredo é exibido uma única vez, definir de novo gera um novo, e uma URL nula desliga o repasse.
Como é um evento repassado?
Um POST contendo a platform, o account_id que list_social_accounts devolve para a conexão da Página, o ID da Página como external_id, e entry: a entrada da Meta para a Página, sem alterações. sender.id é o recipient_id que send_social_dm recebe para uma resposta dentro da janela de 24 horas:
{
"platform": "facebook",
"account_id": "<ACCOUNT_ID>",
"external_id": "<PAGE_ID>",
"entry": {
"id": "<PAGE_ID>",
"time": 1793318400000,
"messaging": [
{
"sender": { "id": "<PSID>" },
"recipient": { "id": "<PAGE_ID>" },
"timestamp": 1793318399000,
"message": { "mid": "<MESSAGE_ID>", "text": "<MESSAGE_TEXT>" }
}
]
}
}Como você verifica um evento repassado?
Cada POST repassado traz um cabeçalho X-EC-Signature no formato t=<unix>,v1=<hex>, em que v1 é o HMAC-SHA256 do timestamp, um ponto e o corpo bruto, com a chave sendo o segredo de assinatura da Página. Calcule sobre o corpo exatamente como recebido, compare em tempo constante e rejeite um timestamp com mais de 5 minutos.
import crypto from "node:crypto";
// rawBody: the request body exactly as received, as a string
export function verify(rawBody, header, secret) {
const sig = Object.fromEntries(header.split(",").map((part) => part.split("=")));
if (!sig.t || !sig.v1) return false;
if (Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(sig.t + "." + rawBody)
.digest("hex");
return expected.length === sig.v1.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
}Uma entrega é repetida?
Não pela easyCoexistence. Cada entrada é repassada uma única vez, em memória, sem cópia guardada para repetir; o repasse espera 8 segundos por uma resposta, não segue redirecionamentos e vai apenas para um endereço HTTPS que resolve para um IP público. A Meta observa que notificações passadas não podem ser consultadas depois, então armazene o necessário assim que chegar. Do lado da Meta, uma entrega com falha é repetida algumas vezes em seguida, então a mesma mensagem pode chegar duas vezes de vez em quando: deduplique pelo seu mid.
Erros comuns
- Fazer o trabalho antes de responder. O repasse não é repetido, então devolva um 2xx imediatamente e processe o evento depois.
- Verificar a assinatura sobre o JSON já interpretado. Calcule o HMAC sobre o corpo bruto exatamente como chegou.
- Presumir que uma mensagem sempre tem texto. Uma figurinha, uma imagem ou um link compartilhado chega em attachments, sem campo text.
- Pular a deduplicação. A Meta pode entregar um evento de novo após uma falha, então use o mid da mensagem como chave antes de agir.
Ative o repasse com set_social_webhook_destination ou pela Partner API. De US$ 9 a US$ 0.75 por conexão por mês, caindo conforme você adiciona conexões, com os primeiros 3 dias grátis.
O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.
Perguntas frequentes
Quais campos de webhook a easyCoexistence inscreve em uma Página?
messages para o Messenger e mention para menções, além de feed para as publicações e comentários da Página.
Uma figurinha ou imagem do Messenger vem com texto?
Não. Uma figurinha, uma imagem ou um link compartilhado chega em attachments, cada um com um type e uma URL de payload, e a mensagem não traz campo text.
Em quanto tempo um endpoint de webhook do Messenger precisa responder?
Com 200 OK em até 5 segundos. Após 1 hora de entregas com falha, a Meta cancela a inscrição do app nos webhooks da Página.
Como respondo a uma mensagem repassada?
Chame send_social_dm com o sender.id do evento como recipient_id, em até 24 horas da mensagem da pessoa.
Continue lendo
Conecte seu primeiro canal em dois minutos.
Sem esperar aprovação das plataformas. Conecte o WhatsApp, o Instagram, o TikTok ou outro canal, peça para a sua IA publicar, responder ou trazer os números, e veja funcionando.
- 3 dias grátis
- Cancele quando quiser
- Só APIs oficiais
- Monitorado 24/7
Verificado em