EntrarComeçar teste grátis
easyCoexistence APIs oficiais

Webhook de menção no Facebook: quando alguém menciona sua Page

O campo mention dos webhooks de Page do Facebook avisa um app quando alguém menciona a Page em uma publicação ou em um comentário. A Meta envia um objeto changes com field definido como mention, cujo value pode trazer o post_id, o comment_id no caso de comentário, o texto em message, links e mídias anexados, além de item e verb, em um POST assinado com X-Hub-Signature-256.

O easyCoexistence inscreve cada Page que você conecta em mention, ao lado de feed e messages, e encaminha seus eventos de menção ao seu endpoint HTTPS assim que chegam, assinados com um segredo próprio da Page e sem guardar cópia, para que seu agente saiba de cada menção assim que acontece.

mention

Campo de webhook da Page para novas menções a uma Page, incluindo menções em comentários e publicações.

pages_manage_metadata

Permissão que um administrador da Page com privilégios MODERATE precisa conceder antes que os webhooks de Page cheguem à URL de callback de um app.

@ + name

Como as pessoas mencionam uma Page em uma publicação ou comentário: digitam @ e o nome da Page, e depois a escolhem.

36 hours

Por quanto tempo a Meta repete uma notificação de Page que falhou, com frequência decrescente, antes de descartá-la.

tagged_time

Campo que o edge /{page-id}/tagged acrescenta a cada publicação pública em que a Page foi marcada.

O que dispara o webhook de menção?

Alguém mencionando a Page em uma publicação ou comentário. No Facebook, uma menção é feita digitando @ e o nome da Page e escolhendo-a entre as sugestões. A referência da Meta descreve o campo como novas menções a uma Page, incluindo menções em comentários e publicações. A Central de Ajuda do Facebook observa que as configurações de uma Page podem impedir que as pessoas a mencionem.

Como é uma notificação de menção?

Um POST com object definido como page e uma entrada para a Page mencionada: seu ID, um horário e um array changes cujo field é mention. A referência da Meta lista os campos do value, mas não traz exemplo; por isso, este exemplo de menção em publicação foi montado a partir dessa lista:

A mention in a post, from the fields in Meta's reference
{
  "object": "page",
  "entry": [
    {
      "id": "<PAGE_ID>",
      "time": 1793520000,
      "changes": [
        {
          "field": "mention",
          "value": {
            "item": "post",
            "verb": "add",
            "post_id": "<POST_ID>",
            "message": "<TEXT_WITH_THE_MENTION>"
          }
        }
      ]
    }
  ]
}

O que significa cada campo de uma menção?

Estes são os campos do value na referência da Meta; quais deles uma notificação traz depende da publicação ou do comentário:

  • post_id: o ID da publicação que mencionou a Page.
  • comment_id: o ID do comentário, quando a menção está em um comentário; parent_id: o ID do comentário pai.
  • message: o texto que traz a menção.
  • link, photo, photos e video: links para o que a publicação ou comentário anexa.
  • item e verb: o tipo de objeto e o que aconteceu com ele, a partir das mesmas listas usadas pelo campo feed.
  • created_time: quando a publicação ou comentário foi criado.
  • from e message_tags: o autor e os perfis marcados no texto, ambos marcados como somente Workplace.
  • Também listados: action, album_id, event_id, photo_id, video_id, share_id, published, reaction_type, recipient_id e open_graph_story_id.

Qual permissão o campo mention exige?

pages_manage_metadata, que a Meta exige que um administrador da Page com privilégios MODERATE conceda antes que os webhooks de Page cheguem a um app. A Page é inscrita por POST /{page-id}/subscribed_apps com mention entre os subscribed_fields, usando um token de Page de alguém com a tarefa CREATE_CONTENT, MANAGE ou MODERATE, com pages_manage_metadata e pages_show_list. O app também se inscreve em mention, já que só campos inscritos nos dois níveis são entregues, e as Pages administradas por pessoas sem papel no app precisam dessas permissões em Advanced Access.

Como ler a publicação ou comentário que menciona a Page?

Pelo seu ID, com o token da Page, quando a Meta permite. Um token de Page lê publicações feitas para a Page ou por ela; publicações compartilhadas publicamente por outras Pages exigem pages_manage_posts e o recurso Page Public Content Access, com um token de administrador da Page; e a Meta vincula a leitura da publicação de uma pessoa à permissão user_posts dessa pessoa.

Looking up the post or the comment
GET https://graph.facebook.com/<POST_ID>
  ?fields=message,permalink_url,created_time
  &access_token=<PAGE_ACCESS_TOKEN>

GET https://graph.facebook.com/<COMMENT_ID>
  ?fields=message,from,created_time
  &access_token=<PAGE_ACCESS_TOKEN>

Onde mais a Page pode encontrar suas menções?

No edge tagged. GET /{page-id}/tagged lista as publicações públicas em que a Page foi marcada, cada uma com um tagged_time, o que também cobre publicações anteriores à configuração do webhook. Ele exige um token de Page de alguém com a tarefa CREATE_CONTENT, MANAGE ou MODERATE, com pages_read_user_content e pages_show_list, e a Meta diz que o recurso Page Public Content Access pode ser necessário. Em uma publicação de pessoa, a Meta retorna from apenas para quem a escreveu.

Como o easyCoexistence entrega eventos de menção?

Ele inscreve cada Page em mention, ao lado de feed e messages, quando a Page é conectada. Seu app verifica X-Hub-Signature-256 em cada entrega, responde à Meta imediatamente e envia por POST cada entrada da Page, sem alterações, para o endpoint HTTPS que você define com set_social_webhook_destination ou PUT /channels/:id/webhook na Partner API:

  • X-EC-Signature traz t=<unix>,v1=<hex>: o HMAC-SHA256 do timestamp, de um ponto e do corpo bruto, usando como chave o segredo de assinatura da Page.
  • O segredo começa com whsec_ e é exibido uma única vez; definir a URL novamente emite um novo, e uma URL nula interrompe o encaminhamento.
  • Cada entrada é enviada uma vez, aguardando até 8 segundos, para um endereço HTTPS que resolve para um IP público, sem seguir redirecionamentos e sem guardar cópia.
A forwarded mention, headers included
POST <YOUR_ENDPOINT>
Content-Type: application/json
X-EC-Signature: t=1793520001,v1=<HEX_HMAC_SHA256>

{
  "platform": "facebook",
  "account_id": "<ACCOUNT_ID>",
  "external_id": "<PAGE_ID>",
  "entry": {
    "id": "<PAGE_ID>",
    "time": 1793520000,
    "changes": [
      {
        "field": "mention",
        "value": {
          "item": "post",
          "verb": "add",
          "post_id": "<POST_ID>",
          "message": "<TEXT_WITH_THE_MENTION>"
        }
      }
    ]
  }
}

Erros comuns

  • Ler entry.time como o momento da menção. A Meta o define como o horário em que a notificação foi enviada; created_time no value indica a data da publicação ou do comentário.
  • Tratar uma busca que falha como evento quebrado. A Meta avisa que alguns valores de post_id e comment_id nas notificações de menção não podem ser consultados, por falta de permissão ou por privacidade; por isso, guarde o texto da mensagem do próprio evento.
  • Buscar a publicação antes de responder ao encaminhamento. Os encaminhamentos não são repetidos; então retorne um 2xx imediatamente e busque a publicação depois.
Fazendo isso com o EasyCoexistence

De US$ 9 a US$ 0.75 por conexão por mês, com redução conforme você adiciona conexões, e 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

O webhook de menção informa quem mencionou a Page?

Não para uma Page: a referência da Meta marca from como somente Workplace. Buscar a publicação ou o comentário pelo ID pode retornar o autor, quando as permissões da Meta permitem.

Posso receber menções de antes de a Page ser inscrita?

Não pelo webhook, já que a Meta não mantém histórico de notificações para consulta. O edge tagged lista as publicações públicas em que a Page foi marcada.

Em que o campo mention difere de feed?

feed informa alterações no próprio feed da Page, como publicações, comentários e reações ali; mention informa que a Page foi mencionada com @ em uma publicação ou comentário. Cada campo é inscrito separadamente.

As regras de comentário do easyCoexistence agem sobre menções?

Não. Regras e automações agem sobre comentários do campo feed e sobre mensagens do Messenger; as alterações de mention são encaminhadas ao seu endpoint exatamente como a Meta as enviou.

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