Messenger 平台專用 Meta Webhooks

Meta Webhooks 讓您可以收到 Meta 社交關係圖內特定物件相關變更的即時 HTTP 通知。例如，當用戶向您的 Facebook 專頁或 Instagram 專業帳戶傳送訊息時，系統便會傳送通知。Webhooks 通知讓您可以追蹤傳入訊息和訊息狀態更新。如果您之前是透過查詢 Messenger 平台端點來追蹤此類變更，使用 Webhooks 通知也可讓您避免限速限制問題。

如要成功執行適用於 Messenger 或 Instagram 對話的 Webhooks，您需要採取以下操作：

1. 在您的伺服器上建立一個端點，以接收和處理您的 Webhooks 通知，即 JSON 物件
2. 在應用程式管理中心配置 Meta Webhooks 產品
3. 訂閱您想接收的 Meta Webhooks 通知
4. 在與您的商家或 Instagram 專業帳戶連結的 Facebook 專頁上安裝訊息應用程式

必要條件

準備工作：

• 閱讀 Messenger 平台概覽，並實行當中所列使用 Meta 開發內容所需的組件
• 發佈 Meta 應用程式
• 存取要求

  • 標準存取權限，以接收來自擁有應用程式角色之用戶（如應用程式管理員、開發人員和測試人員）的通知；或
  • 進階存取權限，以接收來自顧客（即沒有應用程式角色的用戶）的通知。需要接受應用程式審查。

配置 Node.JS 伺服器

您的伺服器必須能夠處理兩類 HTTPS 要求：驗證要求和事件通知。由於這兩類要求都使用 HTTPs，因此您的伺服器必須已正確配置並安裝有效的 TLS 或 SSL 憑證。系統不支援自行簽署的憑證。

以下各部分將說明每類要求中的內容，以及回應這些要求的方式。

此處所示的程式碼範例擷取自我們在 GitHub 上的應用程式範例。請瀏覽 GitHub 以查看完整範例，並進一步了解如何設定 Webhooks 伺服器。

建立端點

如要建立端點以從 Messenger 平台接收 Webhooks 通知，app.js 檔案可能需要如下所示：

// Create the endpoint for your webhook

app.post("/webhook", (req, res) => {
  let body = req.body;

  console.log(`\u{1F7EA} Received webhook:`);
  console.dir(body, { depth: null });
    
...
   

這段程式碼會建立可接受 POST 要求的 /webhook 端點，會確認有關要求是否為 Webhooks 通知。

傳回 200 OK 回應

端點必須傳回 200 OK 回應，來告知 Messenger 平台已經收到事件，無需重新傳送。一般而言，您應等到通知處理完成後才傳送這個回應。

回應事件通知

您的端點應該在回應所有通知時滿足下列條件：

• 以 200 OK HTTPS 回應
• 時間為 5 秒內

以下程式碼會位於 app.js 檔案內的 app.post 中，可能如下所示：

...
  // Send a 200 OK response if this is a page webhook

  if (body.object === "page") {
    // Returns a '200 OK' response to all requests
    res.status(200).send("EVENT_RECEIVED");
...
    // Determine which webhooks were triggered and get sender PSIDs and locale, message content and more.
...
  } else {
    // Return a '404 Not Found' if event is not from a page subscription
    res.sendStatus(404);
  }
}); 

驗證要求

每當您在應用程式管理中心配置 Webhooks 產品時，我們都會將一項 GET 要求傳送至您的端點網址。驗證要求包含下列查詢字串參數，這些參數會附加至端點網址的尾段，類似下方所示：

驗證要求範例

GET https://www.your-clever-domain-name.com/webhooks? hub.mode=subscribe& hub.verify_token=mytoken& hub.challenge=1158201444

確認驗證要求

每當您的端點收到驗證要求時，系統都必須如下操作：

• 確認 hub.verify_token 值與您在應用程式管理中心配置 Webhooks 產品時，在驗證憑證欄位所設定的字串相符（您尚未設定此憑證）。
• 以 hub.challenge 值回應。

app.js 檔案可能會如下所示：

// Add support for GET requests to your webhook
app.get("/webhook", (req, res) => {
  
// Parse the query params
  let mode = req.query["hub.mode"];
  let token = req.query["hub.verify_token"];
  let challenge = req.query["hub.challenge"];

  // Check if a token and mode is in the query string of the request
  if (mode && token) {
    // Check the mode and token sent is correct
    if (mode === "subscribe" && token === config.verifyToken) {
      // Respond with the challenge token from the request
      console.log("WEBHOOK_VERIFIED");
      res.status(200).send(challenge);
    } else {
      // Respond with '403 Forbidden' if verify tokens do not match
      res.sendStatus(403);
    }
  }
});

備註：PHP 會將參數名稱中的英文句號（.）改為底線（_）。

如果您正在應用程式管理中心配置 Webhooks 產品並因此觸發驗證要求，管理中心會表明您的端點是否已正確地驗證要求。如果您使用 Graph API 的 /app/subscriptions 端點來配置 Webhooks 產品，此 API 會透過回應表明設定成功還是失敗。

事件通知

當您配置 Webhooks 產品時，您將會訂閱某個 object 類型的特定 fields（例如 page 物件的 messages 欄位）。每當其中某個欄位出現變更時，我們都會向您的端點傳送 POST 要求，其中包含描述相關變更的 JSON 裝載。

舉例來說，如果您已訂閱 page 物件的 message_reactions 欄位，而且顧客對您應用程式傳送的訊息表達了心情，我們會傳送如下所示的 POST 要求給您：

{
  "object":"page",
  "entry":[
    {
      "id":"<PAGE_ID>",
      "time":1458692752478,
      "messaging":[
        {
          "sender":{
            "id":"<PSID>"
          },
          "recipient":{
            "id":"<PAGE_ID>"
          },

          ...
        }
      ]
    }
  ]
}

裝載內容

裝載會包含描述相關變更的物件。配置 Webhooks 產品時，您可以指明裝載應該只包含已更改欄位的名稱，還是亦應包含新值。

我們會將所有裝載的格式設定為 JSON，這樣您便可以使用常見的 JSON 剖析方法或套件來剖析裝載。

備註：您將無法查詢過往 Webhook 事件通知數據，因此請務必擷取並儲存您想保留的任何 Webhook 裝載內容。

驗證裝載

我們會使用 SHA256 簽章簽署所有事件通知裝載，而且在相關要求的「X-Hub-Signature-256」標題中包含簽章並在前面加上「sha256=」。雖然您無需驗證裝載，但我們強烈建議您完成驗證。

如要驗證裝載，請按照下列步驟操作：

1. 使用裝載和您應用程式的應用程式密鑰來產生 SHA256 簽章。
2. 比較您的簽章與 X-Hub-Signature-256 標題中的簽章（sha256= 之後的所有內容）。如果簽章一致，則表示裝載真實有效。

app.js 檔案可能會如下所示：

// Import dependencies and set up http server
const express = require("express"),
  bodyParser = require("body-parser"),
  { urlencoded, json } = require("body-parser"),
  app = express().use(bodyParser.json());
    
    ...


// Verify that the callback came from Facebook.
function verifyRequestSignature(req, res, buf) {
  var signature = req.headers["x-hub-signature-256"];

  if (!signature) {
    console.warn(`Couldn't find "x-hub-signature-256" in headers.`);
  } else {
    var elements = signature.split("=");
    var signatureHash = elements[1];
    var expectedHash = crypto
      .createHmac("sha256", config.appSecret)
      .update(buf)
      .digest("hex");
    if (signatureHash != expectedHash) {
      throw new Error("Couldn't validate the request signature.");
    }
  }
}

再次嘗試傳送 Webhooks

若通知未能傳送至您的伺服器，我們會立即再嘗試傳送幾次。您的伺服器應在這些情況下處理重複通知。若在 15 分鐘後，我們仍無法向您傳送通知，系統會向您的開發人員帳戶傳送一個提醒訊息。

如果通知傳送功能持續失效達 1 小時，您就會收到「Webhooks 被停用」提醒，然後您的應用程式就會取消訂閱專頁或 Instagram 專業帳戶的 Webhooks。解決相關問題後，您需要再次訂閱 Webhooks。

測試您的 Webhooks

如要測試您的 Webhooks 驗證，請使用驗證憑證執行以下 cURL 要求：

curl -X GET "localhost:1337/webhook?hub.verify_token=YOUR-VERIFY-TOKEN&hub.challenge=CHALLENGE_ACCEPTED&hub.mode=subscribe"

如果您的 Webhooks 驗證運作正常，您將會看到：

• WEBHOOK_VERIFIED 記錄到節點進程運行所在的指令行中。
• CHALLENGE_ACCEPTED 記錄到傳送 cURL 要求的指令行中。

如要測試您的 Webhook，請傳送下列 cURL 要求：

curl -H "Content-Type: application/json" -X POST "localhost:1337/webhook" -d '{"object": "page", "entry": [{"messaging": [{"message": "TEST_MESSAGE"}]}]}'

如果您的 Webhooks 運作正常，您將會看到：

• TEST_MESSAGE 記錄到節點進程運行所在的指令行中。
• EVENT RECEIVED 記錄到傳送 cURL 要求的指令行中。

訂閱 Meta Webhooks

在您的 Webhooks 伺服器端點或應用程式範例準備就緒後，請前往您應用程式的 Meta 應用程式管理中心訂閱 Meta Webhooks。

在此範例中，我們將使用管理中心配置 Webhook 並訂閱 messages 欄位。每當顧客向您的應用程式傳送訊息，系統都會傳送通知到您的 Webhooks 端點。

1. 在應用程式管理中心，前往產品 > Messenger > 設定。
   • Instagram 訊息功能不支援部分 Messenger 平台 Webhooks。如果您只是為 Instagram 執行 Webhooks，並且知道可用於 Instagram 訊息的 Webhooks，請在此訂閱 Webhooks。如要只查看並為 Instagram 訊息訂閱 Webhooks，您可以前往 Instagram 設定。
2. 在回呼網址欄位中輸入您端點的網址，並在驗證憑證欄位中加入您的驗證憑證。我們會在所有驗證要求中加入此字串。如果您正在使用我們其中一個範例應用程式，則此字串應該就是您用於自家應用程式 TOKEN 配置變數的同一組字串。
3. 根據想收到系統通知的欄位訂閱欄位，然後點擊儲存。
4. 最後一個步驟是訂閱個別欄位。訂閱 photos 欄位，並傳送測試事件通知。
   • 如果您的端點設定正確，它應該會驗證裝載，並會在驗證成功後，執行您為其設定的任何程式碼。如果您正在使用我們的範例應用程式，請在網頁瀏覽器中載入應用程式網址。畫面應該會顯示裝載內容。

您可以隨時使用應用程式管理中心更改您的 Webhooks 訂閱、驗證憑證或 API 版本。

備註：建議您使用最新版本的 API 來接收每個 Webhook 的所有可用資訊。

您亦可使用 /app/subscriptions 端點，以編程方式完成操作。

可用的 Messenger 平台欄位

連結您的應用程式

您需要將 Webhooks 應用程式連結至自家專頁，並為專頁訂閱您想接收的 Webhooks 通知。

新增應用程式

您可透過以下路徑將應用程式連結至專頁：Meta Business Suite > 所有工具 > 商業應用程式。

備註：您需要為企業的所有訊息應用程式訂閱訊息 Webhooks。

為您的專頁訂閱

您需要為自家專頁訂閱您想接收的 Webhooks 通知。

必要條件

• 專頁存取憑證，由可以在所查詢的專頁上執行 MODERATE 任務的用戶所要求
• pages_messaging 和 pages_manage_metadata 權限

如要訂閱 Webhooks 欄位，請使用專頁的存取憑證向專頁的 subscribed_apps 關係連線傳送一則 POST 要求。

curl -i -X POST "https://graph.facebook.com/<PAGE_ID>/subscribed_apps
  ?subscribed_fields=messages
  &access_token=<PAGE_ACCESS_TOKEN>"

回應範例

{
  "success": "true"
}

如要查看您的專頁安裝了哪款應用程式，請改為傳送 GET 要求：

要求範例

curl -i -X GET "https://graph.facebook.com/<PAGE_ID>/subscribed_apps
  &access_token=<PAGE_ACCESS_TOKEN>"

回應範例

{
  "data": [
    {
      "category": "Business",
      "link": "https://my-clever-domain-name.com/app",
      "name": "My Sample App",
      "id": "<APP_ID>",
      "subscribed_fields": [
        "messages"
      ]
    }
  ]
}

如果您的專頁未安裝任何應用程式，API 將傳回空白資料組合。

Graph API 測試工具

您也可以使用 Graph API 測試工具來傳送要求，為您的專頁訂閱 Webhooks 欄位。

1. 在應用程式下拉式選單中選擇您的應用程式。
2. 點擊取得憑證下拉式選單，選擇取得用戶存取憑證，然後選擇 pages_manage_metadata 權限。這會將您的應用程式憑證換取為獲授予 pages_manage_metadata 權限的用戶存取憑證。
3. 再次點擊「取得憑證」，然後選擇您的專頁。這會將您的用戶存取憑證換取為專頁存取憑證。
4. 點擊 GET 下拉式選單，然後選擇 POST，即可更改操作方式。
5. 將預設的 me?fields=id,name 查詢替換為專頁的編號（接著是 /subscribed_apps），然後提交查詢。

後續步驟

• 傳送測試消息：了解如何使用平台傳送訊息。
• 瀏覽我們的應用程式範例：下載應用程式範例的程式碼，進一步了解 Messenger 平台提供的功能。

另請參閱

• 了解如何使用對話指派 API ，在對話從一個應用程式傳遞到另一個應用程式時取得通知
• 進一步了解 Graph API 專用 Meta Webhooks