使用商家訊息事件 API 記錄事件

訊息事件 API 將會停用

訊息事件 API 將於 2025 年 9 月停用。為做好停用準備，從 2024 年 9 月 24 日 21.0 版本開始，未來的 Graph API 發佈版本將不再支援訊息事件 API。
選擇不更新到最新版 Graph API 的合作夥伴仍可透過呼叫 Graph API 20.0 或之前版本來存取訊息事件 API，直到 2025 年 9 月訊息事件 API 產品正式停用。
如果合作夥伴不更新到最新版 Graph API，我們建議使用轉換 API 進行新的整合。進一步了解轉換 API。

本指南會講解如何記錄應用程式和 Facebook 專頁事件，以分析用戶如何與其 Messenger 體驗互動。

準備工作

您需要準備好以下項目：

page_events 權限
- 如果您的應用程式已獲授予 pages_messaging 權限的進階存取權限，並且該應用程式在過去 90 天內沒有違反任何政策規定，則當您提交應用程式審查時，系統將自動授予此權限的進階存取權限
專頁存取憑證，由可以在被查詢專頁上執行 ANALYZE 任務的用戶所要求

限制

此 API 目前不適用位於歐洲或日本境內的商家和顧客。

政策及使用條款

記錄事件

系統透過向應用程式的 page_activities 關係連線提交 POST 要求來記錄事件：

https://graph.facebook.com/

要求範例：

curl -X POST -H "Content-Type: application/json" -d '{
  "custom_events": [
    {
      "_eventName": "fb_mobile_purchase",
      "_valueToSum": 57.23,
      "fb_currency": "USD"
    }
  ],
  "advertiser_tracking_enabled": 1,
  "application_tracking_enabled": 1,
  "page_id": <PAGE_ID>,
  "page_scoped_user_id": <PSID>,
  "logging_source": "messenger_bot",
  "logging_target": "page"
}' https://graph.facebook.com/v21.0/<APP_ID>/page_activities?access_token=<PAGE_ACCESS_TOKEN>

建議在欄位 _eventName 上使用標準事件。廣告管理員只會報告標準事件，而且廣告目標設定和優化只能使用標準事件（如適用）。

舉例來說，如要記錄購買事件以在廣告管理員中進行歸因，可以使用事件名稱 fb_mobile_purchase。

如需取得標準事件名稱和參數的完整清單，請參閱應用程式事件 API 指南（應用程式事件架構部分）。

下表說明記錄 Messenger 事件時需要向端點提供的屬性和值：

屬性	說明	值
`custom_events`	您想記錄的事件陣列。如需取得標準事件名稱和適用參數的完整清單，請參閱應用程式事件 API 指南。您亦可使用自己的應用程式事件。您可以在陣列中指定多個事件。	使用 JSON 編碼陣列，以指定您的自訂事件詳細資訊。
`page_id`	指定與事件關聯的專頁編號。	請使用與 Bot 關聯的專頁之 Facebook 專頁編號。
`page_scoped_user_id`	指定與記錄事件的 Messenger Bot 相關的專頁專屬用戶帳號。	請使用提供給 Webhook 的專頁專屬用戶帳號。
`advertiser_tracking_enabled`	指定是否啟用廣告追蹤功能。	如要停用，使用 `0`；如要啟用，使用 `1`
`application_tracking_enabled`	指定是否在應用程式層面啟用廣告追蹤功能。	如要停用，使用 `0`；如要啟用，使用 `1`
`logging_source`	指定事件來源。	使用字串 `messenger_bot` 來表示此事件來自 Messenger Bot。
`logging_target`	指定目標實體，此為事件記錄之目的地。	使用字串 `app`、`page` 或 `app_and_page` 來控制哪個實體會收到此事件。詳情請參閱應用程式事件常見問題

使用訊息事件 API 報告潛在顧客

應用程式現在可以開始報告帖子串上的潛在顧客提交資料。lead_submitted 事件允許應用程式自動報告被視為潛在銷售商機的帖子串（例如，用戶分享了他們的聯絡資料並要求就銷售事宜聯絡）。

此事件非常適合用於將特定用戶分辨為潛在顧客，這樣有助商家優先顯示來自此類顧客的帖子串。例如，商家可以設定一個自動化流程來篩選可作為潛在顧客的用戶，並在用戶完成此類流程時觸發此事件，以將其標記為高潛力帖子串，向真人服務人員顯示。

目前，此功能已在公開測試版中推出，廣告管理員中的分析報告功能亦已整合完成，因此潛在顧客資料將在廣告管理員用戶介面上報告。

報告帖子串上發生的潛在顧客事件之 API 呼叫範例：

curl -X POST -H "Content-Type: application/json" -d '{
  "custom_events": [
    {
      "_eventName": "lead_submitted"
    }
  ],
  "advertiser_tracking_enabled": 1,
  "application_tracking_enabled": 1,
  "page_id": <PAGE_ID>,
  "page_scoped_user_id": <PSID>,
  "logging_source": "messenger_bot",
  "logging_target": "page"
}' https://graph.facebook.com/v21.0/<APP_ID>/page_activities?access_token=<PAGE_ACCESS_TOKEN>

使用廣告洞察報告 API 報告潛在顧客

使用廣告洞察報告 API 能視覺化呈現所報告的潛在顧客事件。您可以使用此 API 建立進階分析資料管理中心，以視覺化呈現歸因於 CTX 宣傳活動的潛在顧客。

必要條件

使用此 API 之前，請確保應用程式已完成 ads_read 權限的應用程式審查程序，並獲得進階存取權限。

執行

在廣告宣傳活動級別的洞察報告呼叫範例如下所示：

curl -G \
-d "date_preset=last_7d" \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<AD_CAMPAIGN_ID>/insights"

您可視乎不同細微程度需要，在廣告帳戶、宣傳活動和廣告組合級別呼叫洞察報告 API。

以下呼叫用於獲取潛在顧客：

開發潛在顧客（已歸因）
- /<OBJECT_ID>/insights?fields=actions
- 在結果中，action_type=onsite_converstion.lead_grouped

有關上述操作類型的詳細定義，請參閱廣告動作統計參考資料。

分類潛在顧客最佳操作實例

廣告客戶從事其中一個常見的開發潛在顧客行業（汽車、專業服務、金融服務、B2B、教育、健康）。
廣告客戶要求用戶提供電話號碼或電郵地址等聯絡資訊，而用戶提供該資訊。
在詢問電話號碼或電郵地址之前，會先進行某類資格評估（如 1 至 2 個附加問題）。
如果您在應用程式中提供開發潛在顧客範本，預設在開發潛在顧客流程結束時加入此訊號。

注意：建議不要將有電話號碼或電郵地址的所有對話自動標記為潛在顧客，尤其是在為付款／電子商務目的而需分享電話號碼的市場更是如此。

驗證事件記錄

如果您是應用程式管理員或專頁管理員，您可以在廣告管理員中找出事件，從而驗證設定是否正確。

有關含有 Messenger 的分析工具之特殊考量

一個應用程式可以記錄多個專頁的互動情況。在這些情況下，您可以在同一個應用程式中查看所有專頁的互動事件。
您可以將多個應用程式連結至一個專頁。在這種情況下，如果專頁被封鎖，則與其連結的所有應用程式都將收到 fb_messenger_bot_stopped 事件。
被刪除的 Messenger Bot 對話數量可以大於新用戶動態數量。被刪除的 Messenger Bot 對話數量是用戶刪除對話串的次數。專頁可以在用戶刪除對話串後發起進一步對話。用戶可以刪除其他對話串，這樣做會增加被刪除的 Messenger Bot 對話數量。

開放平台供應商使用情況

記錄目標

如果開放平台允許用戶透過視覺介面構建 Messenger 體驗，通常會使用一個中央應用程式來支援與其連結的所有專頁。如要允許顧客查看他們的事件，您必須將 logging_target 設定為 page 或 app_and_page，以將這些事件記錄至顧客的專頁。

用戶介面

您可以使用視覺化編輯器提供可拖動的區塊，以供用戶選擇事件和定義額外參數。這樣，專頁管理員就可以使用適當事件來規劃 Messenger 流程。在理想情況下，用戶應該可以從下拉式選單中選擇標準事件，因為廣告管理員只會報告標準事件，而且廣告目標設定和優化只能使用標準事件（如適用）。如果沒有與用戶操作相符的標準事件名稱，而且無需廣告分析報告，您可能想提供格式不限的欄位，以便用戶輸入自訂事件名稱和參數。

權限

您需要在應用程式的 Facebook 登入流程中取得必要的 page_events 權限。正如這篇指南所述，您必須將此權限新增至登入按鈕、Facebook JavaScript SDK 呼叫或您手動構建的登入流程的必要權限範圍之內。

其他資源

應用程式事件最佳操作實例指南：提供有關各類應用程式應該使用哪些事件的建議。