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 端點。
粉絲專頁 Webhook 欄位,用於接收粉絲專頁的新提及,包括留言與貼文中的提及。
粉絲專頁 Webhook 送達應用程式的 callback URL 前,具 MODERATE 權限的粉絲專頁管理員必須授予的權限。
用戶如何在貼文或留言中提及粉絲專頁:輸入 @ 及粉絲專頁名稱,然後選取。
Meta 放棄前重試失敗粉絲專頁通知的時長,重試頻率會逐步降低。
/{page-id}/tagged 端點為每則標記了該粉絲專頁的公開貼文新增的欄位。
什麼會觸發提及 Webhook?
有人在貼文或留言中提及粉絲專頁。在 Facebook 上,提及的方法是輸入 @ 及粉絲專頁名稱,然後從建議選項中選取。Meta 的參考文件將該欄位描述為粉絲專頁的新提及,包括留言與貼文中的提及。Facebook 幫助中心提到,粉絲專頁的設定可以阻止他人提及它。
提及通知的樣子是怎樣的?
一個 POST,object 設為 page,並包含一個 entry,對應被提及的粉絲專頁:其 ID、時間,以及一個 changes 陣列,其 field 為 mention。Meta 的參考文件列出了 value 的欄位,但沒有提供範例,因此以下貼文中提及的範例,是根據該列表構建的:
{
"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 權限掛鉤。
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 地址;不跟隨重新導向,亦不保留副本。
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,之後再查詢貼文。
轉發使用該粉絲專頁專屬的密鑰簽名,且不保留副本,因此你的 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 監察
驗證日期