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

Facebook 專頁的 Messenger webhook:訊息與提及事件

當用戶向專頁發送 Messenger 訊息時,Facebook 專頁 webhook 的 messages 欄位便會觸發,傳送 messaging 陣列,內含發送者的專頁範圍 ID、專頁 ID、時間戳記,以及訊息的 mid,連同文字或附件。mention 欄位會回報貼文和留言中新提及專頁的內容,而 Meta 會以 X-Hub-Signature-256 為兩者簽署。

easyCoexistence 會把每個已連接專頁的 Messenger 訊息與提及,即時轉發至你的 HTTPS 端點,以該專頁專屬的密鑰簽署,且不保留副本;send_social_dm 可在 24 小時窗口期內回覆。

5 seconds

Meta 要求 Messenger webhook 端點多快以 200 OK 回應每則通知。

1 hour

若交付失敗持續這麼久,Meta 會取消應用程式對該專頁 webhook 的訂閱,直至重新訂閱為止。

PSID

messages 事件中的發送者專頁範圍 ID,每個人與專頁的組合各不相同。

Workplace only

Meta 的參考文件如何標示 mention 事件的 sender 欄位。

No history

過去的 webhook 通知之後無法查詢,因此接收方必須儲存所需內容。

messages 欄位會發送什麼?

當用戶向專頁發送 Messenger 訊息時,會發出通知。Meta 會發送文字訊息或附件訊息,附件類型包括圖片、音訊、影片、檔案及貼圖等,分享的連結可能以後備附件的形式送達。回覆較早的訊息時會帶有 reply_to,並附上該訊息的 mid;快速回覆則會帶有其 payload 欄位。

messages 事件的結構是怎樣的?

與動態變更不同,訊息會放在專頁 entry 內的 messaging 陣列中送達。每個事件包含:sender,即該用戶的專頁範圍 ID;recipient,即專頁;timestamp,即時間戳記;以及 message,其中包括 mid 和 text,或附有 type 及負載 URL 的 attachments:

A messages event, as Meta sends it
{
  "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:

A forwarded messages event
{
  "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 分鐘的時間戳記。

Node.js: verifying X-EC-Signature
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 作為識別鍵。
使用 EasyCoexistence 完成這項設定

使用 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 監察

驗證日期