登入開始免費試用
easyCoexistence 官方 API

Facebook 提及 Webhook:有人提及你的粉絲專頁時

Facebook 粉絲專頁 Webhook 的 mention 欄位,會在有人於貼文或留言中 @ 該粉絲專頁時通知應用程式。Meta 發送的一個 changes 項目,其 field 設為 mention,其 value 可包含 post_id、留言的 comment_id、message 中的文字、附加的連結及媒體,以及 item 與 verb。通知以 POST 方式發送,並附有 X-Hub-Signature-256 簽名。

easyCoexistence 會在你連接每個粉絲專頁時,為其訂閱 mention 欄位,與 feed 及 messages 並列,並在事件到達時轉發至你的 HTTPS 端點。

mention

粉絲專頁 Webhook 欄位,用於接收粉絲專頁的新提及,包括留言與貼文中的提及。

pages_manage_metadata

粉絲專頁 Webhook 送達應用程式的 callback URL 前,具 MODERATE 權限的粉絲專頁管理員必須授予的權限。

@ + name

用戶如何在貼文或留言中提及粉絲專頁:輸入 @ 及粉絲專頁名稱,然後選取。

36 hours

Meta 放棄前重試失敗粉絲專頁通知的時長,重試頻率會逐步降低。

tagged_time

/{page-id}/tagged 端點為每則標記了該粉絲專頁的公開貼文新增的欄位。

什麼會觸發提及 Webhook?

有人在貼文或留言中提及粉絲專頁。在 Facebook 上,提及的方法是輸入 @ 及粉絲專頁名稱,然後從建議選項中選取。Meta 的參考文件將該欄位描述為粉絲專頁的新提及,包括留言與貼文中的提及。Facebook 幫助中心提到,粉絲專頁的設定可以阻止他人提及它。

提及通知的樣子是怎樣的?

一個 POST,object 設為 page,並包含一個 entry,對應被提及的粉絲專頁:其 ID、時間,以及一個 changes 陣列,其 field 為 mention。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:物件的類型,以及該物件發生了什麼事,兩者取自 feed 欄位所用的同一組列表。
  • 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。Meta 要求具 MODERATE 權限的粉絲專頁管理員先授予此權限,粉絲專頁 Webhook 才會送達應用程式。粉絲專頁透過 POST /{page-id}/subscribed_apps 訂閱,subscribed_fields 中包含 mention,使用的粉絲專頁存取權杖來自具 CREATE_CONTENT、MANAGE 或 MODERATE 任務的人,並需具備 pages_manage_metadata 與 pages_show_list。應用程式也須訂閱 mention,因為只有在兩個層級都訂閱的欄位才會送達;由在應用程式中沒有角色的人員管理的粉絲專頁,則需要 Advanced Access 中的這些權限。

如何讀取提及粉絲專頁的貼文或留言?

透過其 ID 讀取,並使用粉絲專頁存取權杖(在 Meta 允許的情況下)。粉絲專頁存取權杖可讀取發佈給粉絲專頁或由粉絲專頁發佈的貼文;其他粉絲專頁的公開分享貼文,則需要 pages_manage_posts 權限及 Page Public Content Access 功能,並使用粉絲專頁管理員的存取權杖;而 Meta 將讀取某人個人貼文與該人的 user_posts 權限掛鉤。

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>

粉絲專頁還可在哪裡找到提及?

在 tagged 端點。GET /{page-id}/tagged 列出粉絲專頁被標記的公開貼文,每則附有 tagged_time,這也涵蓋設定 Webhook 之前的貼文。此端點需要具 CREATE_CONTENT、MANAGE 或 MODERATE 任務的人所提供的粉絲專頁存取權杖,並需 pages_read_user_content 與 pages_show_list,Meta 表示可能需要 Page Public Content Access 功能。對於個人的貼文,Meta 只會將 from 欄位回傳給撰寫該貼文的人。

easyCoexistence 如何送達提及事件?

連接粉絲專頁時,它會在 feed 及 messages 之外,同時為每個粉絲專頁訂閱 mention。其應用程式會在每次送達時檢查 X-Hub-Signature-256,立即回覆 Meta,並將該粉絲專頁的每個 entry 原封不動地以 POST 轉發至你於 Partner API 中透過 set_social_webhook_destination 或 PUT /channels/:id/webhook 設定的 HTTPS 端點:

  • X-EC-Signature 內含 t=<unix>,v1=<hex>:以粉絲專頁的簽署密鑰為鍵,對時間戳、一個句點及原始主體計算的 HMAC-SHA256。
  • 密鑰以 whsec_ 開頭,只顯示一次;重新設定 URL 會發出新的密鑰,將 URL 設為 null 則會停止轉發。
  • 每個 entry 只發送一次,等待最多 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 值因權限不足或私隱原因而無法查詢,因此請保留事件本身的 message 文字。
  • 在回覆轉發前便查詢貼文。轉發不會重試,因此應立即回傳 2xx,之後再查詢貼文。
使用 EasyCoexistence 完成這項設定

轉發使用該粉絲專頁專屬的密鑰簽名,且不保留副本,因此你的 AI 代理能即時得知每一次提及。每個連接每月 US$ 9 至 US$ 0.75,連接越多費用越低,前 3 天免費。

常見問題

提及 Webhook 會說明是誰提及了粉絲專頁嗎?

對粉絲專頁而言不會:Meta 的參考文件將 from 標記為僅限 Workplace。在 Meta 權限允許的情況下,以 ID 查詢該貼文或留言,即可取得其作者。

粉絲專頁被訂閱之前的提及,我可以取得嗎?

無法透過 Webhook 取得,因為 Meta 不保留可供查詢的通知記錄。tagged 端點會列出粉絲專頁被標記的公開貼文。

提及欄位與 feed 有何不同?

feed 回報粉絲專頁自身動態消息的變動,例如其中的貼文、留言及反應;mention 則回報粉絲專頁在貼文或留言中被 @ 提及。兩個欄位各自單獨訂閱。

easyCoexistence 的留言規則會作用於提及嗎?

不會。規則與自動化只作用於 feed 欄位的留言及 Messenger 訊息;提及的變動會按 Meta 發送的原樣轉發至你的端點。

繼續閱讀

兩分鐘內連接您的第一個頻道。

無需等待平台審核。連接 WhatsApp、Instagram、TikTok 或其他頻道,然後請您的 AI 發佈貼文、回覆訊息或匯報數據,並看着它運作。

  • 免費試用 3 天
  • 隨時取消
  • 只用官方 API
  • 24/7 監察

驗證日期