商務式訊息轉換 API：設置指南

轉換 API 是一種 Meta 商業工具，可讓商務式訊息合作夥伴直接從他們的伺服器分享有權存取的客戶資料，其設計旨在自動遵照 Meta 的用戶隱私控制項。這讓商務式訊息合作夥伴能夠可靠地傳送客戶寶貴的商家聊天室顧客互動相關資料，以瞭解並增進客戶的 WhatsApp、Messenger 或 Instagram 發訊廣告成效，進而提升營運效率並促進業務成長。

本指南旨在支援商務式訊息合作夥伴代表其客戶完成 WhatsApp、Messenger 或 Instagram 的轉換 API 技術整合。內容包括：

整合前必備條件
整合步驟
透過轉換 API 傳送事件
使用事件管理工具來驗證事件

注意：轉換 API 還可以讓廣告主將網站、應用程式、離線（包括實體店）和 CRM 事件傳送到 Meta。目前已與其他使用案例轉換 API 整合的商務式訊息合作夥伴，仍需要進行以下步驟，以與商務式訊息轉換 API 整合。

Messenger 發訊廣告

整合前必備條件

在開始進行任何整合之前，務必確認已建立正確的技術基礎，並已針對特定資產和平台授予相關的存取權限。

建立 Facebook 開發人員應用程式

如果還沒有，請依照指示建立。

與 Messenger API 整合

具有下列項目的進階存取權限：

page_events 權限
- 您需要在開發人員「應用程式主控板」的「權限和功能」區塊中，申請 page_events 權限的進階存取權限。如果您已經有 pages_messaging 權限的進階存取權限，在您申請後，您的應用程式應該會自動獲得 page_events 權限。
「廣告管理一般存取權限」功能。如需其他指引，請前往這裡。
- 若要獲得「進階存取權限」功能的資格，您需要在過去 15 天內成功進行總計 1500 次的行銷 API 呼叫，且錯誤率低於 10%。這包括具有應用程式角色的用戶透過轉換 API 進行的呼叫。

整合步驟

1. 取得存取權杖

您需要具有下列必要權限的存取權杖，才能呼叫資料集 API 和轉換 API：

page_events

重複使用「商家專用 Facebook 登入」所產生的權杖。

2. Get page_id

確認您知道需要回報事件之粉絲專頁的粉絲專頁編號。

3. 設定資料集

透過轉換 API 分享事件資料給 Meta 時，Meta 需要知道與這些事件相關聯的來源。資料集可讓您集中連結和管理不同來源（例如您的網站、行動應用程式、實體店面或商家聊天室）的事件資料。您可以在這裡深入瞭解資料集的相關資訊。

資料集是透過合作夥伴平台或直接在事件管理工具上建立的。商家擁有資料集，如果商家與合作夥伴合作，資料集的存取權限也會授予合作夥伴。

發出 POST 呼叫至資料集 API，以使用 page_id 和 access_token 來建立資料集。如果已經有與粉絲專頁相關聯的現存 dataset_id，則會傳回該編號。呼叫範例如下：

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

回應會是代表 dataset_id 的編號。您現在可以使用此編號和「商家專用 Facebook 登入」所產生的存取權杖來呼叫轉換 API，以將訊息事件傳送至 Meta。

注意：如果粉絲專頁與商業帳號相關聯，而且已將 business_management 權限授予該商業帳號，則資料集會顯示在該商業帳號之下。否則，將會對廣告主隱藏資料集。

4. 擷取粉絲專頁範圍編號（PSID）

粉絲專頁範圍編號（PSID）是用戶與商家對話中代表用戶的識別碼。此識別碼會透過訊息 Webhook 揭示，並用於整個傳送／接收 API。傳送對應特定用戶（PSID）的轉換事件時，也會在轉換 API 中使用此識別碼。

確認您知道需要回報訊號之粉絲專頁的 PSID。

透過轉換 API 傳送事件

在整合的最後階段中，現在可以使用在先前步驟中取得的所有資訊（access_token、page_id、dataset_id、PSID），透過轉換 API 來傳送事件。

在行銷活動期間，當事件即時發生時，請使用 dataset_id 和 access_token，透過轉換 API 將這些事件通知 Meta。發出 POST 要求至此 API：

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

以下是單一購買事件的 API 呼叫範例。

{
  "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>"
}

使用事件管理工具來驗證事件

透過轉換 API 成功將事件傳送到 Meta 後，您應該會看到該事件反映在特定資料集的事件管理工具中。您可以在這裡進一步瞭解事件管理工具及其用法。

注意：如果您是合作夥伴，您需要指導廣告主如何在事件管理工具中存取資料集，以驗證是否收到事件。

WhatsApp 發訊廣告

整合前必備條件

在開始進行任何整合之前，務必確認已建立正確的技術基礎，並已針對特定資產和平台授予相關的存取權限。

建立 Facebook 開發人員應用程式

如果還沒有，請依照指示建立。

具有下列項目的進階存取權限：

whatsapp_business_management 權限
whatsapp_business_manage_events 權限
- 您需要在「開發人員應用程式主控板」的「權限和功能」區塊中，申請 whatsapp_business_manage_events 權限的進階存取權限。如果您已經有 whatsapp_business_messaging 權限的進階存取權限，在您申請後，您的應用程式應該會自動獲得 whatsapp_business_manage_events 權限。
「廣告管理一般存取權限」功能，可讓您的應用程式存取行銷 API。如需其他指引，請前往這裡。
- 若要獲得「進階存取權限」功能的資格，您需要在過去 15 天內成功進行總計 1500 次的行銷 API 呼叫，且錯誤率低於 10%。這包括具有應用程式角色的用戶透過轉換 API 進行的呼叫。

與下列兩種 WhatsApp Business 平台整合選項之一整合：

由 Meta 代管的雲端 API（建議）
內部部署 API（*Biz API 版本：2.45.1）：ctwa_clid，這是透過轉換 API 傳送事件的必要欄位，僅適用於 Biz API 2.45.1 和以上版本的訊息 Webhook。注意：WhatsApp Business 平台在未來 2 年內將完全轉換至我們的新一代雲端 API。內部部署 API 用戶端的最終支援版本將於 2025 年 10 月 23 日過期。瞭解詳情。

與用於驗證和授權的登入解決方案整合（內嵌註冊、商家專用 Facebook 登入）

整合步驟

1. 取得存取權杖

您需要具有下列必要權限的存取權杖，才能呼叫資料集 API 和轉換 API：

whatsapp_business_management
whatsapp_business_manage_events

如果您是與內嵌註冊整合，建議您重複使用從內嵌註冊流程產生的權杖。或者，您可以使用企業整合工具系統用戶存取權杖、系統用戶存取權杖或用戶存取權杖，只要有包含必要權限即可。

2. 擷取 WhatsApp Business 帳號編號

內嵌註冊流程完成時，即可取得 WhatsApp Business 帳號編號（waba_id）。瞭解詳情。

3. 設定資料集 API

透過轉換 API 分享事件資料給 Meta 時，Meta 需要知道與這些事件相關聯的來源。資料集可讓 Meta 企業解決方案合作夥伴集中連結和管理不同來源（例如客戶的網站、行動應用程式、實體店面或商家聊天室）的事件資料。您可以在這裡深入瞭解資料集的相關資訊。資料集為客戶所擁有，並可供具有必要權限的 Meta 企業解決方案合作夥伴存取。

您可以發出 POST 呼叫至資料集 API，以使用 whatsapp_business_account_id 和 access_token 來建立資料集。如果已經有與 WhatsApp Business 帳號相關聯的現存 dataset_id，則會傳回該編號。呼叫範例如下：

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

若要擷取 dataset_id，您可以使用 whatsapp_business_account_id 和 access_token 發出 GET 呼叫至資料集 API。呼叫範例如下：

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

回應會是代表 dataset_id 的編號。現在資料集已經設定好並可供使用了。接下來，您需要擷取 ctwa_clid，這是進行轉換 API 呼叫來傳送事件的必要資訊。

4. 擷取 WhatsApp 發訊廣告點擊編號

WhatsApp 發訊廣告點擊編號（ctwa_clid）是個人識別碼，每次點擊的專屬編號，當用戶進入源自 WhatsApp 發訊廣告的對話時，就會對商家揭示此識別碼。此識別碼需要透過轉換 API 呼叫傳送回 Meta（請參閱下面的章節）。

ctwa_clid 欄位是從訊息 Webhook（雲端 API | 內部部署）下的 referral 物件取得。

收到 ctwa_clid 後，請將其與對話一起儲存。當對話中發生轉換時，請透過轉換 API 傳送對應的 ctwa_clid。以下是收到的訊息範例，其中的 referral 物件包含 ctwa_clid：

{
  "data": [
    {
  "contacts": [
    {
      "profile": {
        "name": "Kerry Fisher "
      },
      "wa_id": "16315551234"
    }
  ],
  "messages": [
    {
      "from": "12345678",
      "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
      "referral": {
        "body": "This is a great product",
        "ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a", // <CLICK_TO_WHATSAPP_CLICK_ID>
        "headline": "Our new product",
        "image": {
          "id": "e144be57-12b1-4035-a520-703fcc87ef45"
        },
        "source_id": "1234567890",
        "source_type": "ad",
        "source_url": "https://fb.me/AAAAA"
      },
      "text": {
        "body": "Can I learn more about your business?"
      },
      "timestamp": "1678189586",
      "type": "text"
    }
  ]
}

透過轉換 API 傳送事件

在整合的最後階段中，現在可以使用在先前步驟中取得的所有資訊（waba_id、dataset_id、ctwa_clid），透過轉換 API 來傳送事件。

在廣告主的行銷活動期間，事件會即時發生。請使用 dataset_id 和存取權杖，透過轉換 API 將這些事件通知 Meta。發出 POST 要求至此 API：

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

以下是單一購買事件的 API 呼叫範例。

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

使用事件管理工具來驗證事件

透過轉換 API 成功將事件傳送到 Meta 後，您應該會看到該事件反映在特定資料集的事件管理工具中。您可以在這裡進一步瞭解事件管理工具及其用法。

注意：如果您是合作夥伴，您需要指導廣告主如何在事件管理工具中存取資料集，以驗證是否收到事件。

Instagram Direct 發訊廣告

整合前必備條件

在開始進行任何整合之前，務必確認已建立正確的技術基礎，並已針對特定資產和平台授予相關的存取權限。

建立 Facebook 開發人員應用程式

如果還沒有，請依照指示建立。

與 Messenger API 整合

具有下列項目的進階存取權限：

instagram_manage_events 權限
- 您需要在開發人員「應用程式主控板」的「權限和功能」區塊中，申請 instagram_manage_events 權限的進階存取權限。如果您已經有 instagram_manage_messages 權限的進階存取權限，您的應用程式應該會自動獲得 instagram_manage_events 權限。
「廣告管理一般存取權限」功能。如需其他指引，請前往這裡。
- 若要獲得「進階存取權限」功能的資格，您需要在過去 15 天內成功進行總計 1500 次的行銷 API 呼叫，且錯誤率低於 10%。這包括具有應用程式角色的用戶透過轉換 API 進行的呼叫。

整合步驟

1. 取得存取權杖

您需要具有下列必要權限的存取權杖，才能呼叫資料集 API 和轉換 API：

instagram_manage_events

重複使用「商家專用 Facebook 登入」所產生的權杖。

2. 取得「instagram_user_id」

確認您知道需要回報事件之 Instagram 帳號的 instagram_user_id。

3. 設定資料集

資料集是透過合作夥伴平台或直接在事件管理工具上建立的。商家擁有資料集，如果商家與合作夥伴合作，資料集的存取權限也會授予合作夥伴。

發出 POST 呼叫至資料集 API，以使用 instagram_user_id 和 access_token 來建立資料集。如果已經有與 IG 用戶相關聯的現存 dataset_id，則會傳回該編號。呼叫範例如下：

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

回應會是代表 dataset_id 的編號。您現在可以使用此編號和「商家專用 Facebook 登入」所產生的存取權杖來呼叫轉換 API，以將訊息事件傳送至 Meta。

4. 擷取 Instagram 範圍編號（IGSID）

Instagram 範圍編號（IGSID）是用戶與商家對話中代表用戶的識別碼。此識別碼會透過訊息 Webhook 揭示，並用於整個傳送／接收 API。傳送對應特定用戶（IGSID）的轉換事件時，也會在轉換 API 中使用此識別碼（詳情請參閱下一節）。

確認您知道需要回報事件之 Instagram 帳號的 IGSID。

透過轉換 API 傳送事件

在整合的最後階段中，現在可以使用在先前步驟中取得的所有資訊（dataset_id、存取權杖、instagram_user_id、IGSID），透過轉換 API 來傳送事件。

在行銷活動期間，當事件即時發生時，請使用 dataset_id 和存取權杖，透過轉換 API 將這些事件通知 Meta。發出 POST 要求至此 API：

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

以下是單一購買事件的 API 呼叫範例。

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

使用事件管理工具來驗證事件

透過轉換 API 成功將事件傳送到 Meta 後，您應該會看到該事件反映在特定資料集的事件管理工具中。您可以在這裡進一步瞭解事件管理工具及其用法。

注意：如果您是合作夥伴，您需要指導廣告主如何在事件管理工具中存取資料集，以驗證是否收到事件。

常見問題

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

答：商家訊息轉換 API 現在支援以下類型的商家訊息事件：

Purchase
LeadSubmitted
InitiateCheckout
AddToCart
ViewContent
OrderCreated
OrderShipped
OrderDelivered
OrderCanceled
OrderReturned
CartAbandoned
QualifiedLead
RatingProvided
ReviewProvided

請注意，訊息事件應僅代表發生在訊息對話串中的顧客互動，而不是發生在網站等其他管道中的轉換。您可以在整合過程中選擇對應的集客力動作來源，以輕鬆區分您的事件。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

另請參閱

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