EntrarComeçar teste grátis
easyCoexistence APIs oficiais

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.

5 seconds

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

1 hour

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.

PSID

O ID da pessoa vinculado à Página em um evento messages, único para cada par de 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 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:

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 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:

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 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.

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 é 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.
Fazendo isso com o EasyCoexistence

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