商家訊息轉換 API

轉換 API 可讓廣告主透過單一端點（而不需要透過多個來源），將網路、應用程式、實體商店和商家訊息事件傳送到 Meta。這種整合可以簡化廣告主的技術堆疊，並使用資料集在 Meta 事件管理工具中建立更全面的視圖。

本文件提供將商家訊息事件整合至轉換 API 的指南。使用商家訊息轉換 API 的好處包括（但不限於）：

直接在廣告管理員分析報告中查看結果：廣告主可以直接在 Meta 介面上，根據購買數量和每次購買成本等重要結果（而不是所發起的對話），輕鬆瞭解發訊廣告行銷活動成果。
簡化資料整合：一個 API 可跨多個訊息平台（Messenger、WhatsApp）和管道（網站、應用程式、商店、訊息）取得和分享資料。
改善合作夥伴成效衡量：透過廣告洞察報告 API，直接在合作夥伴主控板上啟用發訊廣告行銷活動歸因工具。

必要條件

資料集

透過轉換 API 傳送的商家訊息事件必須與資料集建立關聯。

資料集可讓廣告主將事件資料從網路、應用程式、商店和商家訊息事件來源連接至轉換 API 並進行管理。資料集會顯示您選擇設定之下列任何整合工具提供的事件資料：

Meta 像素（網站事件）
應用程式事件 API（應用程式事件，包括 Facebook iOS SDK、Facebook Android SDK、行動衡量合作夥伴（MMP））
離線轉換 API（Meta 用於離線事件的舊版 API）

資料集可讓您從單一介面檢視所有顧客活動，並可讓您減少組建和維護多個 API 整合工具的工作量。

在事件管理工具中，廣告主可依據其起始點使用不同的選項來建立資料集。或者，您可以在事件管理工具中建立全新的資料集，只要在離線事件組合建立期間或透過現有行動應用程式或在訊息事件組合建立期間進行連結即可。請注意，在將行動應用程式事件傳送至轉換 API 之前，必須將資料集連結至應用程式，且只能將一個應用程式與資料集連結。請查看更多詳情和此文件的指示。

權限

若要以廣告主身分實作直接整合，請按照這裡的必備條件和權限相關指示操作。
若要實作合作夥伴平台整合，您需要：
- ads_read、ads_management、pages_messaging、whatsapp_business_messaging、pages_show_list 和 instagram_manage_messages 的進階存取權限。
- 廣告管理一般存取權限功能。
- 根據事件類型，您需要有 Messenger 或 WhatsApp 事件的 page_events 進階存取權限，或 Instagram Direct 的 instagram_manage_events 進階存取權限。

合作夥伴設置

如果您要實作合作夥伴整合做為平台，可以使用商家專用 Facebook 登入（建議）或 Meta Business 擴充功能設置方法。

請參閱商家訊息轉換 API 指南，其中含有整合指南和逐步操作說明。

用於訊息和 WhatsApp 的資料集 API

資料集 API 可用來擷取附加至給定頁面的 dataset_id。稍後會在轉換 API 中使用這個 dataset_id。為了能夠使用資料集 API，您需要客戶透過「商家專用 Facebook 登入」或「Meta Business 擴充功能」授予 Messenger 或 WhatsApp 事件的 page_events 權限給您的應用程式。

為了擷取 dataset_id，您需要使用 page_id 和 access_token 發出 GET 呼叫至資料集 API。請參閱下面的範例呼叫：

https://graph.facebook.com/v16.0/{PAGE_ID}/dataset?access_token={TOKEN}

回應會是一個代表 dataset_id 的編號。您現在可以使用此編號和先前收到的存取權杖來呼叫轉換 API，以將訊息事件傳送至 Meta。

用於 Instagram 的資料集 API

資料集 API 可用來擷取附加至給定頁面的 dataset_id。稍後會在轉換 API 中使用這個 dataset_id。為了能夠使用資料集 API，您需要客戶透過「商家專用 Facebook 登入」或「Meta Business 擴充功能」授予 instagram_manage_events 權限給您的應用程式。

為了擷取 dataset_id，您需要使用 ig_user_id 和 access_token 發出 GET 呼叫至資料集 API。呼叫範例如下：

https://graph.facebook.com/v16.0/{IG_USER_ID}/dataset?access_token={TOKEN}

回應會是一個代表 dataset_id 的編號。您現在可以使用此編號和先前收到的存取權杖來呼叫轉換 API，以將訊息事件傳送至 Meta。

配置

設定商家訊息事件參數

您可以參閱此文件，瞭解可透過轉換 API 傳送的最新參數組合。��要傳送商家訊息事件，可以針對不同的訊息平台，在「用戶資料」裝載中分享下列欄位：

平台	參數	說明
Messenger	`page_id`	Messenger 的必要項目與商家相關聯的 Facebook 粉絲專頁編號。
Messenger	`page_scoped_user_id`	Messenger 的必要項目粉絲專頁範圍用戶編號（PSID）可識別與粉絲專頁互動的用戶。您可以從這個 Webhook 取得 PSID。
WhatsApp	`page_id`	WhatsApp 的必要項目與 WhatsApp Business 相關聯的 Facebook 粉絲專頁編號。
WhatsApp	`ctwa_clid`	WhatsApp 的必要項目 `ctwa_clid` 只能從 Business API 2.45.1 和以上版本（內部部署）或雲端 API 上的訊息 Webhook 下的 referral 物件取得。
Instagram	`ig_account_id`	Instagram 的必要項目與商家相關聯的 Instagram 帳號編號。
Instagram	`ig_sid`	Instagram 的必要項目 Instagram 範圍用戶編號（IGSID）可識別與 Instagram 互動的用戶。您可以從這個 Webhook 取得 IGSID。

傳送事件

若要傳送新的事件，請從下列路徑發出 POST 要求至轉換 API：

https://graph.facebook.com/{API_VERSION}/{DATASET_ID}/events?access_token={TOKEN}

當您發佈到此關係連線時，Meta 會建立新的商家訊息事件。如需詳細資訊，請參閱此開發人員文件。

以下概述這些參數在裝載整體架構中的適當位置。

用於 Messenger 事件：

{
  "data": [
    {
      "event_name": "Purchase",
      "event_time": 1675999999,
      "action_source": "business_messaging",
      "messaging_channel": "messenger",
      "user_data": {
        "page_id": <PAGE_ID>,
        "page_scoped_user_id": <PSID>
      },
      "custom_data": {
        "currency": "USD",
        "value": 123
      }
    }
  ],
  "partner_agent": "<PARTNER_NAME>"
}

用於 WhatsApp 事件：

{
  "data": [
    {
      "event_name": "Purchase",
      "event_time": 1675999999,
      "action_source": "business_messaging",
      "messaging_channel": "whatsapp",
      "user_data": {
        "page_id": <PAGE_ID>,
        "ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a", // <CLICK_TO_WHATSAPP_CLICK_ID>
      },
      "custom_data": {
        "currency": "USD",
        "value": 123
      }
    }
  ],
  "partner_agent": "<PARTNER_NAME>"
}

用於 Instagram 事件：

CTD CAPI 要求範例

POST /{dataset_id}/events

{
  "data": [
    {
      "event_name": "Purchase",
      "event_time": 1675999999,
      "action_source": "business_messaging",
      "messaging_channel": "instagram",
      "user_data": {
        "ig_account_id": <IG_ACCOUNT_ID>,
        "ig_sid": <IGSID>
      },
      "custom_data": {
        "currency": "USD",
        "value": 123
      }
    }
  ],
  "partner_agent": "<PARTNER_NAME>"
}

疑難排解

請使用事件管理工具中的測試事件工具進行測試：

前往「事件管理工具」，選擇與頁面連結的資料集
點擊「測試事件」頁籤
選擇��銷管道和訊息管道
點擊圖形 API 測試工具按鈕
「圖形 API 測試工具」會填入預填的裝載內容
點擊「提交」按鈕

逐步解說影片

請觀看此影片，瞭解如何實作整合的逐步說明。

發生錯誤

播放此影片時發生問題。

了解詳情

常見問題

商家訊息轉換 API 支援哪種類型的訊息事件？

答：商家訊息轉換 API 目前僅支援商家訊息的潛在顧客提交和購買事件。請注意，訊息事件應僅代表發生在訊息對話串中的顧客互動，而不是發生在網站等其他管道中的轉換。您可以在整合過程中選擇對應的集客力動作來源，以輕鬆區分您的事件。

Meta 是否有提供指引，說明針對不同的轉換 API 整合，應維持相同的應用程式，或使用不同的應用程式？

答：最佳作法是合作夥伴應使用單一應用程式，以便 Meta 可以識別合作夥伴傳送的所有事件。如果您是已經擁有多個應用程式的合作夥伴，請確認 partner_agent 設定為指派給您的合作夥伴代理商名稱。如果您不確定，請洽詢您的 Meta 代表。

如果轉換發生在訊息對話串以外的地方（例如，我的網站或應用程式上），我們如何將事件傳遞至 Meta？

答：如果轉換發生在訊息對話串以外的地方，您還是應該使用相關的轉換 API 產品，將該事件傳回 Meta。例如，如果轉換發生在您的網站上，請使用網路轉換 API。如果轉換發生在您的應用程式上，請使用應用程式事件轉換 API。該事件仍會歸因於網路轉換 API 的點擊編號。您可以在這裡找到完整的參數清單。

轉換 API 是否會針對發訊廣告啟用最佳化功能？

答：轉換 API 僅針對 Messenger 發訊廣告啟用購買最佳化存取權限，但目前不適用於 WhatsApp 廣告最佳化。對於 WhatsApp 發訊廣告，您可以最佳化廣告行銷活動來激發更多對話。

我是否可以將現有的資料集重複用於商家訊息轉換 API？

答：可以，我們支援與現有資料集連結，您可以參考可用的選項來決定您的商家適合的選項。

如果我現在使用網站轉換 API，將商家訊息功能新增至同一個整合是否會干擾我現有的整合？

答：將商家訊息功能新增至現有 CAPI 整合不會有風險。歸因是以頁面/資料集編號為依據，與應用程式編號無關。

我可以將幾個資料集連結至一個頁面？

答：您只能將一個資料集連結至一個頁面。

在透過商家訊息轉換 API 傳送事件之前，是否需要先刪除重複的事件資料？

答：Meta 不會協助為商家訊息轉換 API 進行事件重複資料刪除，因此強烈建議廣告主在透過商家訊息轉換 API 傳送事件之前，先進行事件重複資料刪除。

另請參閱

轉換 API 總覽
使用轉換 API
轉換 API 參數
最佳作法
使用 Business API 2.45.1 和以上版本的 WhatsApp Business 平台（內部部署或雲端 API）
Instagram 訊息 API