Facebook 專頁的 Messenger webhook:訊息與提及事件
當用戶向專頁發送 Messenger 訊息時,Facebook 專頁 webhook 的 messages 欄位便會觸發,傳送 messaging 陣列,內含發送者的專頁範圍 ID、專頁 ID、時間戳記,以及訊息的 mid,連同文字或附件。mention 欄位會回報貼文和留言中新提及專頁的內容,而 Meta 會以 X-Hub-Signature-256 為兩者簽署。
easyCoexistence 會把每個已連接專頁的 Messenger 訊息與提及,即時轉發至你的 HTTPS 端點,以該專頁專屬的密鑰簽署,且不保留副本;send_social_dm 可在 24 小時窗口期內回覆。
Meta 要求 Messenger webhook 端點多快以 200 OK 回應每則通知。
若交付失敗持續這麼久,Meta 會取消應用程式對該專頁 webhook 的訂閱,直至重新訂閱為止。
messages 事件中的發送者專頁範圍 ID,每個人與專頁的組合各不相同。
Meta 的參考文件如何標示 mention 事件的 sender 欄位。
過去的 webhook 通知之後無法查詢,因此接收方必須儲存所需內容。
messages 欄位會發送什麼?
當用戶向專頁發送 Messenger 訊息時,會發出通知。Meta 會發送文字訊息或附件訊息,附件類型包括圖片、音訊、影片、檔案及貼圖等,分享的連結可能以後備附件的形式送達。回覆較早的訊息時會帶有 reply_to,並附上該訊息的 mid;快速回覆則會帶有其 payload 欄位。
messages 事件的結構是怎樣的?
與動態變更不同,訊息會放在專頁 entry 內的 messaging 陣列中送達。每個事件包含:sender,即該用戶的專頁範圍 ID;recipient,即專頁;timestamp,即時間戳記;以及 message,其中包括 mid 和 text,或附有 type 及負載 URL 的 attachments:
{
"object": "page",
"entry": [
{
"id": "<PAGE_ID>",
"time": 1458692752478,
"messaging": [
{
"sender": { "id": "<PSID>" },
"recipient": { "id": "<PAGE_ID>" },
"timestamp": 1458692752478,
"message": {
"mid": "<MESSAGE_ID>",
"text": "hello, world!"
}
}
]
}
]
}mention 欄位會發送什麼?
當專頁在貼文或留言中被提及時,會發出 field 為 mention 的變更通知,內容包括 post_id 或 comment_id、訊息、任何連結、相片或影片,以及 item 和 verb。Meta 提醒,部分貼文及留言 ID 因權限不足或私隱理由而無法查詢;其參考文件亦標示 sender 欄位僅適用於 Workplace,因此提及事件可能未附上作者。
哪些 Messenger 欄位不會轉發?
easyCoexistence 只為專頁訂閱 messages,不訂閱 message_echoes、messaging_postbacks、message_reads 或 message_deliveries,因此專頁發出的訊息、按鈕點擊,以及已讀或已送達回條均不會轉發。使用 send_social_dm 發送的回覆,會改為返回其本身的訊息 ID。
事件如何送達你的端點?
Meta 會透過整個應用程式共用的單一回調 URL,將專頁 webhook 送達已安裝該專頁的應用程式。easyCoexistence 會檢查每次送達的 X-Hub-Signature-256,立即回應 Meta,並把已連接專頁的每個 entry 轉發至你為該專頁設定的 HTTPS 端點,以該專頁自己的密鑰簽署。你可以在 Claude 或 ChatGPT 中使用 set_social_webhook_destination 設定,或在 Partner API 使用 PUT /channels/:id/webhook 設定;密鑰只會顯示一次,重新設定會發出新密鑰,而 URL 設為 null 即會停止轉發。
轉發的事件是什麼樣子?
會以 POST 送出,內含 platform、account_id(即 list_social_accounts 為該專頁連接提供的值)、專頁 ID 作為 external_id,以及 entry,即 Meta 為該專頁發出的 entry,原封不動。sender.id 即是在 24 小時窗口期內回覆時,send_social_dm 所需的 recipient_id:
{
"platform": "facebook",
"account_id": "<ACCOUNT_ID>",
"external_id": "<PAGE_ID>",
"entry": {
"id": "<PAGE_ID>",
"time": 1793318400000,
"messaging": [
{
"sender": { "id": "<PSID>" },
"recipient": { "id": "<PAGE_ID>" },
"timestamp": 1793318399000,
"message": { "mid": "<MESSAGE_ID>", "text": "<MESSAGE_TEXT>" }
}
]
}
}如何驗證轉發的事件?
每次轉發的 POST 都會帶有 X-EC-Signature 標頭,格式為 t=<unix>,v1=<hex>,其中 v1 是時間戳記、句號、原始主體的 HMAC-SHA256,以該專頁的簽署密鑰為密鑰。請以原樣收到的原始主體計算,以恆定時間比較,並拒絕超過 5 分鐘的時間戳記。
import crypto from "node:crypto";
// rawBody: the request body exactly as received, as a string
export function verify(rawBody, header, secret) {
const sig = Object.fromEntries(header.split(",").map((part) => part.split("=")));
if (!sig.t || !sig.v1) return false;
if (Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(sig.t + "." + rawBody)
.digest("hex");
return expected.length === sig.v1.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
}交付會被重試嗎?
easyCoexistence 不會重試。每個 entry 只會在記憶體中轉發一次,不保留副本以供重試;轉發會等候 8 秒回應,不跟隨重新導向,且只會發送至解析為公共 IP 的 HTTPS 地址。Meta 指出,過去的通知之後無法查詢,因此請在收到時即儲存所需內容。在上游,Meta 會在失敗後短時間內連續重試數次,因此同一訊息偶爾可能送達兩次:請以其 mid 去除重複。
常見錯誤
- 先做工作,後回應。轉發不會重試,因此應立即返回 2xx,之後再處理事件。
- 在解析後的 JSON 上驗證簽署。應對原樣收到的原始主體計算 HMAC。
- 假設訊息必定有文字。貼圖、圖片或分享連結會以附件形式送達,並沒有 text 欄位。
- 略過去重。失敗後 Meta 可能再次送出事件,因此行動前應以 mid 作為識別鍵。
使用 set_social_webhook_destination 或 Partner API 開啟轉發。每個連接每月 US$ 9 起,連接越多越便宜,最低降至 US$ 0.75,首 3 天免費試用。
常見問題
easyCoexistence 會為專頁訂閱哪些 webhook 欄位?
messages 用於 Messenger,mention 用於提及,另外 feed 用於專頁的貼文和留言。
Messenger 貼圖或圖片會附帶文字嗎?
不會。貼圖、圖片或分享連結會放在 attachments 中,每項都附有 type 及負載 URL,訊息並沒有 text 欄位。
Messenger webhook 端點必須多快回應?
須在 5 秒內以 200 OK 回應。若交付失敗持續 1 小時,Meta 會取消應用程式對專頁 webhook 的訂閱。
如何回覆一則已轉發的訊息?
在用戶訊息發出後 24 小時內,以事件中的 sender.id 作為 recipient_id 呼叫 send_social_dm。
繼續閱讀
兩分鐘內連接您的第一個頻道。
無需等待平台審核。連接 WhatsApp、Instagram、TikTok 或其他頻道,然後請您的 AI 發佈貼文、回覆訊息或匯報數據,並看着它運作。
- 免費試用 3 天
- 隨時取消
- 只用官方 API
- 24/7 監察
驗證日期