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.
Campo de webhook da Page para novas menções a uma Page, incluindo menções em comentários e publicações.
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.
Como as pessoas mencionam uma Page em uma publicação ou comentário: digitam @ e o nome da Page, e depois a escolhem.
Por quanto tempo a Meta repete uma notificação de Page que falhou, com frequência decrescente, antes de descartá-la.
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:
{
"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_ideopen_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.
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.
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.
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