Iniciar sessãoIniciar teste gratuito
easyCoexistence APIs oficiais

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.

mention

Campo de webhook de Página para novas menções, incluindo menções em comentários e publicações.

pages_manage_metadata

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.

@ + name

Como as pessoas mencionam uma Página numa publicação ou comentário: escrevem @ e o nome da Página e selecionam-na.

36 hours

Tempo durante o qual a Meta volta a tentar uma notificação falhada de Página, com frequência decrescente, antes de a descartar.

tagged_time

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:

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 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_id e open_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.

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 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.
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 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.
Fazer isto com a EasyCoexistence

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