ログイン無料トライアルを開始
easyCoexistence 公式 API

Facebook メンション Webhook:Page がメンションされたとき

Facebook の Page Webhook の mention フィールドは、投稿やコメントで誰かが Page を @メンションしたときに、アプリへ通知します。Meta はフィールドを mention に設定した change を送ります。value には post_id、コメントの場合は comment_id、message の本文、添付されたリンクとメディア、item と verb などを含めることができ、X-Hub-Signature-256 で署名された POST で届きます。

easyCoexistence は、接続する各 Page を mention フィールドに、feed と messages と並べて購読させ、メンションのイベントが届くたびに HTTPS エンドポイントへ転送します。

mention

Page の Webhook フィールドで、投稿とコメントの両方における Page への新しいメンションを対象とします。

pages_manage_metadata

Page の Webhook がアプリのコールバック URL に届く前に、MODERATE 権限を持つ Page 管理者が付与する必要がある権限です。

@ + name

Facebook で投稿やコメントに Page をメンションする方法:@ と Page の名前を入力し、候補から選びます。

36 hours

Meta が失敗した Page の通知を、間隔を徐々に広げながら再試行し、破棄するまでの期間。

tagged_time

/{page-id}/tagged エッジが、Page がタグ付けされている公開投稿ごとに追加するフィールドです。

メンションの Webhook が発生する条件は?

誰かが投稿またはコメントで Page をメンションしたときです。Facebook では、@ と Page の名前を入力して候補から選ぶとメンションになります。Meta のリファレンスでは、このフィールドを「投稿とコメント内のメンションを含む、Page への新しいメンション」と説明しています。Facebook のヘルプセンターによると、Page の設定によって、ユーザーが Page をメンションできないようにすることもできます。

メンションの通知はどのような形ですか?

object を page に設定した POST で、メンションされた Page を表す entry が 1 件含まれます。その内容は Page の ID、時刻、そして field が mention である changes 配列です。Meta のリファレンスは value のフィールドを列挙していますが、サンプルは示していないため、以下の投稿でのメンションの例は、その一覧をもとに組み立てたものです:

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>"
          }
        }
      ]
    }
  ]
}

メンションの各フィールドの意味は?

以下は Meta のリファレンスに記載されている value のフィールドです。どのフィールドが通知に含まれるかは、投稿またはコメントによって異なります:

  • post_id:メンションを含む投稿の ID です。
  • comment_id:メンションがコメントに含まれる場合の、そのコメントの ID です。parent_id:その親の ID です。
  • message:メンションを含むテキストです。
  • link、photo、photos、video:投稿またはコメントに添付されたものへのリンクです。
  • item と verb:オブジェクトの種類と、そのオブジェクトに起きたこと。フィードのフィールドと同じ一覧から取られます。
  • created_time:投稿またはコメントが作成された時刻です。
  • from と message_tags:投稿者と、テキスト内でタグ付けされたプロフィールです。どちらも Workplace のみ対象とされています。
  • ほかに記載されているフィールド:action、album_id、event_id、photo_id、video_id、share_id、published、reaction_type、recipient_id、open_graph_story_id。

メンションのフィールドにはどの権限が必要ですか?

pages_manage_metadata です。Page の Webhook がアプリに届く前に、MODERATE 権限を持つ Page 管理者がこの権限を付与する必要があると、Meta は定めています。Page は、POST /{page-id}/subscribed_apps を使い、subscribed_fields に mention を含めて購読します。この際、CREATE_CONTENT、MANAGE、MODERATE のいずれかのタスクを持つ人の Page トークンを使い、pages_manage_metadata と pages_show_list を付与します。アプリ側でも mention を購読します。両方のレベルで購読されたフィールドだけが配信されるためです。アプリに役割を持たない人が運用する Page では、それらの権限を Advanced Access で取得する必要があります。

メンションした投稿やコメントはどう読み取りますか?

その ID を使い、Meta が許可する場合は Page のトークンで読み取ります。Page トークンでは、Page に投稿された投稿、または Page が投稿した投稿を読み取れます。他の Page が公開で共有した投稿は、Page 管理者のトークンで、pages_manage_posts と Page Public Content Access 機能が必要です。個人の投稿の読み取りは、その人の user_posts 権限に結び付けられている、と Meta は定めています。

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>

Page のメンションを確認できる他の方法は?

/tagged エッジです。GET /{page-id}/tagged は、Page がタグ付けされている公開投稿を一覧し、それぞれに tagged_time が付きます。Webhook を設定する前の投稿も含まれます。CREATE_CONTENT、MANAGE、MODERATE のいずれかのタスクを持つ人の Page トークンが必要で、pages_read_user_content と pages_show_list を付与します。Meta は、Page Public Content Access 機能が必要になる場合があるとしています。個人の投稿の場合、Meta は from を投稿者本人にのみ返します。

easyCoexistence はメンションのイベントをどのように配信しますか?

Page を接続したときに、feed と messages に加えて、各 Page を mention に購読させます。アプリは各配信の X-Hub-Signature-256 を検証し、Meta にすぐ応答して、Page ごとの各 entry を変更せずに、Partner API の set_social_webhook_destination または PUT /channels/:id/webhook で設定した HTTPS エンドポイントへ POST します:

  • X-EC-Signature は t=<unix>,v1=<hex> の形式で、タイムスタンプ、ドット、生のボディの HMAC-SHA256 を、その Page の署名用シークレットを鍵として計算した値を持ちます。
  • シークレットは whsec_ で始まり、一度だけ表示されます。URL を再設定すると新しいシークレットが発行され、null に設定すると転送が停止します。
  • 各 entry は 1 回だけ送信され、最大 8 秒間応答を待ちます。宛先は、パブリック IP に解決される HTTPS アドレスである必要があります。リダイレクトは辿らず、コピーも保持しません。
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>"
        }
      }
    ]
  }
}

よくある間違い

  • entry.time をメンションの発生時刻と読むこと。Meta はこれを通知を送った時刻に設定します。value の created_time が、投稿またはコメントの作成日時を示します。
  • 参照に失敗したことを、壊れたイベントと扱うこと。Meta は、メンションの通知にある一部の post_id と comment_id は、権限またはプライバシーの理由で照会できない場合があると注意しています。そのため、メッセージ本文はイベント自体のものを保持してください。
  • 転送に応答する前に投稿を取得すること。転送は再試行されないため、すぐに 2xx を返し、投稿の参照は後で行ってください。
EasyCoexistence で実現する

転送は、その Page 用のシークレットで署名され、コピーは保持されません。そのため、お使いのエージェントは各メンションが起きるたびにそれを把握できます。接続 1 件あたり月額 US$ 9 から US$ 0.75 まで、接続を増やすほど下がります。最初の 3 日間は無料です。

よくある質問

メンションの Webhook で、誰が Page をメンションしたか分かりますか?

Page については分かりません。Meta のリファレンスでは from は Workplace のみと明記されています。ID で投稿やコメントを参照すれば、Meta の権限が許す場合は投稿者を取得できることがあります。

Page を購読する前のメンションは取得できますか?

Webhook からは取得できません。Meta は照会可能な通知履歴を保持していないためです。tagged エッジは、Page がタグ付けされている公開投稿を一覧できます。

mention フィールドは feed と何が違いますか?

feed は Page 自身のフィードの変化(そこでの投稿、コメント、リアクションなど)を通知します。mention は、投稿またはコメントで Page が @メンションされたことを通知します。どちらのフィールドも個別に購読します。

easyCoexistence のコメントルールは、メンションにも適用されますか?

いいえ。ルールと自動化は、feed フィールドのコメントと Messenger のメッセージに作用します。mention の変更は、Meta が送ったとおりに、エンドポイントへ転送されます。

続きを読む

最初のチャンネルを 2 分で接続しましょう。

プラットフォームの審査を待つ必要はありません。WhatsApp、Instagram、TikTok などのチャンネルを接続して、AI に投稿、返信、レポートを任せてみてください。

  • 3 日間無料
  • いつでも解約可能
  • 公式 API のみ使用
  • 24/7 監視

確認日