Iniciar sessãoIniciar teste gratuito
easyCoexistence APIs oficiais

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.

5 seconds

Em quanto tempo a Meta espera que um endpoint de webhook do Messenger responda a cada notificação com 200 OK.

1 hour

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.

PSID

O ID da pessoa limitado à Página num evento messages, único para cada par pessoa e Página.

Workplace only

Como a referência da Meta marca o campo sender de um evento de menção.

No history

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:

A messages event, as Meta sends it
{
  "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:

A forwarded messages event
{
  "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.

Node.js: verifying X-EC-Signature
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.
Fazer isto com a EasyCoexistence

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