Webhook do Messenger para Páginas do Facebook: mensagens e menções
O campo messages dos webhooks de Páginas do Facebook dispara quando uma pessoa envia à Página uma mensagem do Messenger, entregando um array messaging com o ID da pessoa limitado à Página (sender), o ID da Página, um carimbo temporal e o mid da mensagem com o seu texto ou anexos. O campo mention comunica novas menções à Página em publicações e comentários, e a Meta assina ambos com X-Hub-Signature-256.
A easyCoexistence reencaminha as mensagens e menções do Messenger de cada Página ligada para o seu endpoint HTTPS à medida que chegam, assinadas com um segredo próprio dessa 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 a cada notificação com 200 OK.
Depois de as entregas falharem durante este tempo, a Meta cancela a subscrição da aplicação aos webhooks da Página até voltar a subscrever.
O ID da pessoa limitado à Página num evento messages, único para cada par 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 mais tarde, pelo que o recetor tem de guardar o que precisa.
O que envia o campo messages?
Uma notificação quando uma pessoa envia à Página uma mensagem do Messenger. A Meta envia mensagens de texto ou mensagens com anexos, que podem ser imagens, áudio, vídeo, ficheiros ou autocolantes, entre outros tipos, e uma ligação partilhada pode chegar como anexo alternativo. Uma resposta a uma mensagem anterior traz reply_to com o mid dessa mensagem, e uma resposta rápida traz o seu payload.
Como é um evento messages?
Ao contrário das alterações do feed, uma mensagem chega num array messaging dentro da entrada da Página. Cada evento tem sender, o ID da pessoa limitado à Página; recipient, a Página; um carimbo temporal; e message, com o seu mid e text, ou attachments com um type e um URL do 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 envia o campo mention?
Uma alteração com o campo mention quando a Página é mencionada numa publicação ou num comentário, trazendo post_id ou comment_id, a mensagem, qualquer ligação, foto ou vídeo, e item e verb. A Meta avisa que alguns desses IDs de publicações e comentários não podem ser consultados, por falta de permissão ou por privacidade, e a sua referência marca o campo sender como exclusivo do Workplace, pelo que uma menção pode chegar sem o respetivo autor.
Que campos do Messenger não são reencaminhados?
A easyCoexistence subscreve as Páginas a messages, e não a message_echoes, messaging_postbacks, message_reads ou message_deliveries; por isso, as mensagens enviadas pela Página, os toques em botões e os recibos de leitura ou de entrega não são reencaminhados. Uma resposta enviada com send_social_dm devolve, em vez disso, o seu próprio ID de mensagem.
Como chegam os eventos ao seu endpoint?
A Meta entrega os webhooks da Página à aplicação que a Página instalou, através de um único URL de callback para a aplicação inteira. A easyCoexistence verifica o X-Hub-Signature-256 da Meta em cada entrega, responde de imediato à Meta e reencaminha cada entrada de uma Página ligada para o endpoint HTTPS que definir para essa Página, assinado com o segredo próprio dessa Página. Defina-o com set_social_webhook_destination a partir do Claude ou do ChatGPT, ou com PUT /channels/:id/webhook na Partner API; o segredo é mostrado uma só vez, definir de novo emite um novo, e um URL nulo desliga o reencaminhamento.
Como é um evento reencaminhado?
Um POST com a plataforma, o account_id que list_social_accounts devolve para a ligaçã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 verifica um evento reencaminhado?
Cada POST reencaminhado traz um cabeçalho X-EC-Signature na forma t=<unix>,v1=<hex>, em que v1 é o HMAC-SHA256 do carimbo temporal, de um ponto e do corpo bruto, com a chave de assinatura secreta da Página. Calcule-o sobre o corpo exatamente como foi recebido, compare em tempo constante e rejeite um carimbo temporal 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 é reencaminhada uma só vez, em memória, sem cópia guardada para repetir o envio; o reencaminhamento aguarda 8 segundos por uma resposta, não segue redirecionamentos e só vai para um endereço HTTPS que resolva para um IP público. A Meta indica que notificações passadas não podem ser consultadas mais tarde, por isso guarde o que precisar à medida que chega. A montante, a Meta repete uma entrega falhada algumas vezes de seguida, pelo que a mesma mensagem pode ocasionalmente chegar-lhe duas vezes: elimine duplicados pelo seu mid.
Erros comuns
- Fazer o trabalho antes de responder. O reencaminhamento não repete envios, por isso devolva um 2xx de imediato e processe o evento depois.
- Verificar a assinatura sobre JSON já analisado. Calcule o HMAC sobre o corpo bruto exatamente como chegou.
- Assumir que uma mensagem tem sempre texto. Um autocolante, uma imagem ou uma ligação partilhada chega como anexos, sem campo text.
- Saltar a eliminação de duplicados. A Meta pode entregar um evento outra vez depois de uma falha, por isso use o mid da mensagem como chave antes de agir.
Ative o reencaminhamento com set_social_webhook_destination ou com a Partner API. De US$ 9 a US$ 0.75 por ligação por mês, descendo à medida que acrescenta ligações, com os primeiros 3 dias grátis.
Perguntas frequentes
Que campos de webhook a easyCoexistence subscreve numa 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.
Um autocolante ou uma imagem do Messenger vem com texto?
Não. Um autocolante, uma imagem ou uma ligação partilhada chega em anexos, cada um com um type e um URL do payload, e a mensagem não traz campo text.
Com que rapidez deve um endpoint de webhook do Messenger responder?
Com 200 OK em até 5 segundos. Depois de 1 hora de entregas falhadas, a Meta cancela a subscrição da aplicação aos webhooks da Página.
Como respondo a uma mensagem reencaminhada?
Chame send_social_dm com o sender.id do evento como recipient_id, dentro de 24 horas da mensagem da pessoa.
Continue a ler
Ligue o seu primeiro canal em dois minutos.
Sem revisões de plataformas para esperar. Ligue o WhatsApp, o Instagram, o TikTok ou outro canal, peça depois à sua IA que publique, responda ou faça um relatório, e veja-a trabalhar.
- 3 dias grátis
- Cancele quando quiser
- Só APIs oficiais
- Monitorizado 24/7
Verificado em