Webhook de menção no Facebook: quando alguém menciona a sua Página
O campo mention dos webhooks de Página do Facebook avisa uma aplicação quando alguém menciona a Página numa publicação ou num comentário. A Meta envia um change com field definido como mention, cujo value pode trazer o post_id, o comment_id de um comentário, o texto em message, as hiperligações e os conteúdos multimédia anexados, e item e verb, num POST assinado com X-Hub-Signature-256.
A easyCoexistence subscreve cada Página que liga ao campo mention, junto com feed e messages, e reencaminha os seus eventos de menção para o seu endpoint HTTPS à medida que chegam, assinados com um segredo próprio dessa Página e sem guardar cópia, para que o seu agente saiba de cada menção à medida que acontece.
Campo de webhook de Página para novas menções, incluindo menções em comentários e publicações.
Permissão que um administrador da Página com privilégios MODERATE tem de conceder antes de os webhooks da Página chegarem ao URL de callback de uma aplicação.
Como as pessoas mencionam uma Página numa publicação ou comentário: escrevem @ e o nome da Página e selecionam-na.
Tempo durante o qual a Meta volta a tentar uma notificação falhada de Página, com frequência decrescente, antes de a descartar.
Campo que o edge /{page-id}/tagged acrescenta a cada publicação pública em que a Página foi marcada.
O que dispara o webhook de menção?
Alguém que menciona a Página numa publicação ou num comentário. No Facebook, faz-se uma menção escrevendo @ e o nome da Página e escolhendo-a nas sugestões, e a referência da Meta descreve o campo como novas menções de uma Página, incluindo menções em comentários e publicações. O Centro de Ajuda do Facebook indica que as definições de uma Página 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 Página mencionada: o seu ID, um time e um array changes cujo field é mention. A referência da Meta lista os campos do value, mas não dá exemplo, por isso este exemplo de menção numa publicação é 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 Página.comment_id: o ID do comentário, quando a menção está num comentário;parent_id: o ID do comentário pai.- message: o texto que contém a menção.
- link, photo, photos e video: hiperligações e conteúdos anexados à publicação ou ao comentário.
- item e verb: o tipo de objeto e o que lhe aconteceu, a partir das mesmas listas que o campo feed usa.
created_time: a data de criação da publicação ou do comentário.- from e
message_tags: o autor e os perfis marcados no texto, ambos marcados apenas para Workplace. - Também listados: action,
album_id,event_id,photo_id,video_id,share_id, published,reaction_type,recipient_ideopen_graph_story_id.
Que permissão precisa o campo mention?
pages_manage_metadata, que a Meta exige que um administrador da Página com privilégios MODERATE conceda antes de os webhooks da Página chegarem a uma aplicação. A Página é subscrita através de POST /{page-id}/subscribed_apps com mention entre os subscribed_fields, com um token de Página de alguém com a tarefa CREATE_CONTENT, MANAGE ou MODERATE, e com pages_manage_metadata e pages_show_list. A aplicação também subscreve mention, já que só são entregues os campos subscritos aos dois níveis, e as Páginas geridas por pessoas sem função na aplicação precisam dessas permissões em Advanced Access.
Como se lê a publicação ou o comentário que menciona a Página?
Pelo seu ID, com o token da Página, quando a Meta o permite. Um token de Página lê as publicações feitas para ou pela Página; as publicações partilhadas publicamente de outras Páginas precisam de pages_manage_posts e da funcionalidade Page Public Content Access, num token de administrador da Página; e a Meta liga 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 pode a Página encontrar as suas menções?
No edge tagged. GET /{page-id}/tagged lista as publicações públicas em que a Página foi marcada, cada uma com um tagged_time, o que também abrange publicações anteriores à configuração do webhook. Exige um token de Página de alguém com a tarefa CREATE_CONTENT, MANAGE ou MODERATE, com pages_read_user_content e pages_show_list, e a Meta indica que pode ser necessária a funcionalidade Page Public Content Access. Numa publicação de uma pessoa, a Meta devolve dados apenas a quem a escreveu.
Como é que a easyCoexistence entrega os eventos de menção?
Subscreve cada Página à menção, junto com feed e messages, quando a Página é ligada à easyCoexistence. A sua aplicação verifica o X-Hub-Signature-256 em cada entrega, responde de imediato à Meta e envia por POST cada entrada da Página, sem alterações, para o endpoint HTTPS que definir 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, um ponto e o corpo bruto, com a chave do segredo de assinatura da Página.
- O segredo começa por whsec_ e é mostrado uma só vez; voltar a definir o URL emite um novo, e um URL null interrompe o reencaminhamento.
- Cada entrada é enviada uma vez, com espera 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 define-o como a hora em que a notificação foi enviada; o created_time do value indica a data da publicação ou do comentário.
- Tratar uma consulta falhada como um evento com defeito. 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.
- Ir buscar a publicação antes de responder ao encaminhamento. Os encaminhamentos não são repetidos, por isso devolva um 2xx de imediato e consulte a publicação depois.
De US$ 9 a US$ 0.75 por ligação por mês, descendo à medida que acrescenta ligações, com os primeiros 3 dias gratuitos.
Perguntas frequentes
O webhook de menção diz quem mencionou a Página?
Não no caso de uma Página: a referência da Meta marca from apenas para Workplace. Consultar a publicação ou o comentário pelo seu ID pode devolver o autor, quando as permissões da Meta o permitem.
Posso obter menções anteriores à subscrição da Página?
Não pelo webhook, já que a Meta não mantém histórico de notificações para consultar. O edge tagged lista as publicações públicas em que a Página foi marcada.
Em que é que o campo mention se distingue de feed?
feed comunica alterações no próprio feed da Página, como publicações, comentários e reações nele feitos; mention comunica que a Página foi mencionada com @ numa publicação ou comentário. Cada campo é subscrito de forma independente.
As regras de comentários da easyCoexistence atuam sobre menções?
Não. As regras e automações atuam sobre comentários do campo feed e sobre mensagens do Messenger; as alterações de menção são reencaminhadas para o seu endpoint tal como a Meta as enviou.
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