WhatsApp Business Management API
返回中文(台灣)
這份文件已更新。
中文(台灣) 的翻譯尚未完成。
英文更新時間：11月19日

WhatsApp Business 平台 > Business Management API > 指南

分析工具

本文件說明如何取得傳訊、對話和範本分析資料，例如從商家電話號碼傳送的訊息數量、WhatsApp Business 帳號（WABA）的對話數量及其成本，或指定範本被讀取的次數。

只有在要求時與 WABA 相關聯的商家電話號碼和範本的指標會包含在回應中。

取得資料

使用 WhatsApp Business 帳號端點取得分析資料。

要求語法

GET /<WHATSAPP_BUSINESS_ACCOUNT_ID>
  ?fields=<FIELDS>.<FILTERING_PARAMETER>

查詢字串參數

預留位置說明範例值

<FIELDS>

必要項目。


衡量指標。可使用下列其中一個值：


analytics

<FILTERING_PARAMETERS>

必要項目。


衡量指標篩選參數。請使用點號來加上附加的篩選參數。


若要瞭解有哪些可能的值，請參閱：


.start(1543543200).end(1544148000).granularity(DAY)

傳訊分析

analytics 欄位提供與特定 WABA 相關聯之電話號碼傳送並送達的訊息數量和類型；關於對話衡量指標，請參閱對話分析。呼叫 /{whatsapp-business-account-ID}?fields=analytics.{filtering-parameters} 時，可以附加下列參數。

分析參數

名稱說明（點擊左欄中的箭頭可查看支援的選項。）

start

類型：UNIX 時間戳記

必要項目。

要擷取分析之日期範圍的開始日期。

end

類型：UNIX 時間戳記

必要項目。

要擷取分析之日期範圍的結束日期。

granularity

類型：字串

必要項目。

要擷取分析的精細程度。

支援的選項

  • HALF_HOUR
  • DAY
  • MONTH

phone_numbers

類型：陣列

選用項目。

要擷取分析的電話號碼陣列。如未提供，則會包含已新增至 WABA 的所有電話號碼。

product_types

類型：陣列

選用項目。

要擷取通知的訊息類型（通知訊息和／或顧客支援訊息）。請提供陣列，並包含通知訊息的 0 和顧客支援訊息的 2。如未提供，將同時傳回所有訊息的分析。

country_codes

類型：陣列

選用項目。

您要擷取分析的國家／地區。請提供要包含在內的國家／地區的 2 字母國碼／區碼。如未提供，將同時傳回您曾經通訊的所有國家／地區的分析。

範例

情境：您需要取得您的所有 WABA 相關電話號碼傳送過且已送的訊息數。

建議的解決方案：收集您要呼叫的網址，並且包含下列篩選參數：start、end、granularity。接著對該網址發出 GET 要求：

curl -i -X GET \ 
"https://graph.facebook.com/v21.0/{whatsapp-business-account-ID}
      ?fields=analytics
      .start(1543543200)
      .end(1544148000)
      .granularity(DAY)
      &access_token={access-token}"

若成功，回應會傳回 analytics 物件和您所要求的資料：

{
  "analytics": {
    "phone_numbers": [
      "16505550111",
      "16505550112",
      "16505550113"
    ],
    "country_codes": [
      "US",
      "BR"
    ],
    "granularity": "DAY",
    "data_points": [
      {
        "start": 1543543200,
        "end": 1543629600,
        "sent": 196093,
        "delivered": 179715
      },
      {
        "start": 1543629600,
        "end": 1543716000,
        "sent": 147649,
        "delivered": 139032
      },
      {
        "start": 1543716000,
        "end": 1543802400,
        "sent": 61988,
        "delivered": 58830
      },
      {
        "start": 1543802400,
        "end": 1543888800,
        "sent": 132465,
        "delivered": 124392
      }
      # more data points
    ]
  },
  "id": "102290129340398"
}

對話分析

conversation_analytics 欄位提供特定 WABA 的成本和對話資訊。呼叫 /{whatsapp-business-account-ID}?fields=conversation_analytics.{filtering-parameters} 時，可以附加下列參數。

對話分析參數

名稱說明（點擊左欄中的箭頭可查看支援的選項。）

start

類型：UNIX 時間戳記

必要項目。

要擷取分析之日期範圍的開始日期。

end

類型：UNIX 時間戳記

必要項目。

要擷取分析之日期範圍的結束日期。

granularity

類型：字串

必要項目。

要擷取分析的精細程度。

支援的選項

  • HALF_HOUR
  • DAILY
  • MONTHLY

phone_numbers

類型：陣列

選用項目。

要擷取分析的電話號碼陣列。如未提供，則會包含已新增至 WABA 的所有電話號碼。

metric_types

選用項目。

您要擷取之衡量指標的清單。若傳送空清單，我們會傳回所有衡量指標類型的結果。

支援的選項 {#supported}

  • COST：包含該時間範圍的大概費用，以 WABA 的幣別計算。
  • CONVERSATION：包含該時間範圍的對話計數。

自 2023 年 7 月 1 日起，針對透過解決方案合作夥伴計費的商家，不再顯示 COST。若要瞭解收費情形，請與您的合作夥伴聯絡。如果您透過合作夥伴計費，運作方式如下：

  1. 如果您的要求中未指定 metric_types，系統只會傳回 CONVERSATION
  2. 如果僅指定 CONVERSATION，系統只會傳回 CONVERSATION
  3. 如果僅指定 COST，系統會傳回下列例外情況：
    • 標題：「無法顯示成本」
    • 訊息：「針對透過合作夥伴（即 BSP）計費的商家，不再顯示成本。若要瞭解收費情形，請與您的合作夥伴聯絡。」

如果您查詢的時段包含 2023 年 7 月 1 日當日或之後的日期（例如，2023 年 5 月 1 日至 2023 年 8 月 1 日），則回應中會包含上述例外情況。

查詢 conversation_analytics 端點時，合作夥伴方面沒有變更。

conversation_categories

選用項目。

對話類別清單。若傳送空清單，我們會傳回所有對話類別的結果。

支援的選項

  • AUTHENTICATION
  • MARKETING
  • SERVICE
  • UTILITY

conversation_types

選用項目。

對話類型清單。若傳送空清單，我們會傳回所有對話類型的結果。

支援的選項

conversation_directions

選用項目。

對話方向清單。若傳送空清單，我們會傳回所有對話方向的結果。

支援的選項

  • BUSINESS_INITIATED：商家主動開始的對話。
  • USER_INITIATED：一般用戶／顧客主動開始的對話。

dimensions

選用項目。

您要套用於衡量指標的資料解析清單。若傳送空清單，我們會傳回沒有任何資料解析的結果。

支援的選項

  • CONVERSATION_CATEGORY
  • CONVERSATION_DIRECTION
  • CONVERSATION_TYPE
  • COUNTRY
  • PHONE

分析資料是約略值，因為資料處理過程中的些微差異，所以可能會不同於發票上顯示的資料。

範例

只要指定時間範圍，就能得到與 WABA 相關的對話和成本資訊。您也可以篩選結果和解析結果資料。如需範例，請參閱下方的範例程式碼。

使用所有資料解析取得每月資料

情境：您想擷取某個特定月份中，與某個 WABA 相關之所有電話號碼的所有對話和成本資訊。

建議的解決方案：收集您要呼叫的網址，並且包含下列篩選參數：

  • start：時間範圍開始。在此範例中，是指您需要衡量指標之月份的開始。
  • end：時間範圍結束。在此範例中，是指您需要衡量指標之月份的結束。
  • granularity：您想要的資料點精細程度。下方範例使用 MONTHLY，因此每個資料點代表一個月份的資料。
  • phone_numbers：若傳送空白陣列，我們會傳回與 WABA 相關聯之所有電話號碼的資訊。
  • dimensions：設為所有可用的資料解析："CONVERSATION_CATEGORY"、"CONVERSATION_TYPE"、"COUNTRY" 和 "PHONE"。

在此案例中不需要指定 country_codes、metric_types、conversation_types 和 conversation_categories。若未傳送這些欄位的任何資訊給我們，我們會傳回所有可用選項。設定好網址後，請發出 GET 要求：

curl -i -X GET
"https://graph.facebook.com/v21.0/{whatsapp-business-account-id}
  ?fields=conversation_analytics
  .start(1685602800).end(1688194800)
  .granularity(MONTHLY)
  .phone_numbers([])
  .dimensions(["CONVERSATION_CATEGORY","CONVERSATION_TYPE","COUNTRY","PHONE"])
  &access_token={access-token}"

若成功，回應會傳回 conversation_analytics 物件和您所要求的資料：下列範例中的 WABA 只包含一個電話號碼。

{
  "conversation_analytics": {
    "data": [
      {
        "data_points": [
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 1558,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "REGULAR",
            "conversation_direction": "UNKNOWN",
            "conversation_category": "AUTHENTICATION",
            "cost": 15.58
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 2636,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "REGULAR",
            "conversation_category": "MARKETING",
            "cost": 26.36
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 2238,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "REGULAR",
            "conversation_category": "SERVICE",
            "cost": 22.38
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 1782,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "REGULAR",
            "conversation_category": "UTILITY",
            "cost": 17.82
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 1568,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "FREE_TIER",
            "conversation_category": "AUTHENTICATION",
            "cost": 15.68
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 2716,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "FREE_TIER",
            "conversation_category": "MARKETING",
            "cost": 27.16
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 2180,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "FREE_TIER",
            "conversation_category": "SERVICE",
            "cost": 21.8
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 1465,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "FREE_TIER",
            "conversation_category": "UTILITY",
            "cost": 14.65
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 1433,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "FREE_ENTRY_POINT",
            "conversation_category": "SERVICE",
            "cost": 14.33
          }
        ]
      }
    ]
  },
  "id": "102290129340398",
}

使用所有資料解析和半小時的精細度取得特定電話號碼的資料

情境：您想擷取某個特定時間範圍內，與某個 WABA 相關之所有電話號碼的所有對話和成本資訊。您想在結果中使用所有可能的資料解析。您需要每一個資料點各代表半小時的資料。

建議的解決方案：收集您要呼叫的網址，並且包含下列篩選參數：

  • start：時間範圍開始。
  • end：時間範圍結束。
  • granularity：您想要的資料點精細程度。下方範例使用 HALF_HOUR，因此每個資料點代表半小時的資料。
  • phone_numbers：您需要哪個電話號碼的資訊。
  • dimensions：設為所有可用的資料解析：CONVERSATION_CATEGORY、CONVERSATION_TYPE、COUNTRY 和 PHONE。

在此案例中不需要指定 country_codes、metric_types、conversation_types 和 conversation_categories。若未傳送這些欄位的任何資訊給我們，我們會傳回所有可用選項。設定好網址後，請發出 GET 要求：

curl -i -X GET \
"https://graph.facebook.com/v21.0/{whatsapp-business-account-id}
  ?fields=conversation_analytics
  .start(1685602800)
  .end(1685689200)
  .granularity(HALF_HOUR)
  .phone_numbers(["19195552584"])
  .dimensions(["CONVERSATION_CATEGORY","CONVERSATION_TYPE","COUNTRY,PHONE"])
  &access_token=your-access-token"

若成功，回應會傳回 conversation_analytics 物件和您所要求的資料：

{
  "conversation_analytics": {
    "data": [
      {
        "data_points": [
          {
            "start": 1685602800,
            "end": 1685604600,
            "conversation": 4,
            "phone_number": "19195552584",
            "country": "US",
            "conversation_type": "REGULAR",
            "conversation_direction": "UNKNOWN",
            "conversation_category": "SERVICE",
            "cost": 0.0232
          },
          {
            "start": 1685602800,
            "end": 1685604600,
            "conversation": 4,
            "phone_number": "19195552584",
            "country": "US",
            "conversation_type": "REGULAR",
            "conversation_direction": "UNKNOWN",
            "conversation_category": "MARKETING",
            "cost": 0.0232
          },
         # ... more data points
        ]
      }
    ]
  },
  "id": "102290129340398"
}

使用對話類型資料解析取得每月資料

情境：您想擷取某個時間範圍內，與某個 WABA 相關之所有電話號碼的所有對話和成本資訊。您想依對話類型進行結果資料解析。

建議的解決方案：收集您要呼叫的網址，並且包含下列篩選參數：

  • start：時間範圍開始。
  • end：時間範圍結束。
  • granularity：您想要的資料點精細程度。下方範例使用 MONTHLY，因此每個資料點代表一個月份的資料。
  • phone_numbers：若傳送空白陣列，我們會傳回與 WABA 相關聯之所有電話號碼的資訊。
  • dimensions：設為 CONVERSATION_TYPE。

在此案例中不需要指定 country_codes、metric_types、conversation_types、conversation_directions 和 conversation_categories。若未傳送這些欄位的任何資訊給我們，我們會傳回所有可用選項。設定好網址後，請發出 GET 要求：

curl -i -X GET
"https://graph.facebook.com/v21.0/{whatsapp-buiness-account-id}
      ?fields=conversation_analytics
      .start(1643702400).end(1646121600)
      .granularity(MONTHLY)
      .phone_numbers([])
      .dimensions([CONVERSATION_TYPE])
      &access_token={access-token}"

若成功，回應會傳回 conversation_analytics 物件和您所要求的資料：

{
  "data": [
    {
      "data_points": [
        {
          "start": 1643702400,
          "end": 1646121600,
          "conversation": 8500,
          "conversation_type": "REGULAR",
          "cost": 88.1010
        },
        {
          "start": 1643702400,
          "end": 1646121600,
          "conversation”: 1000,
          "conversation_type": "FREE_TIER",
          "cost": 0.0000
        }
        {
          "start": 1643702400,
          "end": 1646121600,
          "conversation”: 250,
          "conversation_type": "FREE_ENTRY_POINT",
          "cost": 0.0000
        }
      ]
    }
  ]
}

取得依對話類別解析的半小時資料


要求：

curl -i -X GET \
 "https://graph.facebook.com/v21.0/{whatsapp-buiness-account-id}
  ?fields=conversation_analytics
  .start(1685527200)
  .end(1685613600)
  .granularity(HALF_HOUR)
  .conversation_categories(["MARKETING","AUTHENTICATION"])
  .dimensions(["CONVERSATION_CATEGORY"])
  &access_token={access-token}"

回應：

{
  "conversation_analytics": {
    "data": [
      {
        "data_points": [
          {
            "start": 1685529000,
            "end": 1685530800,
            "conversation": 2,
            "conversation_category": "AUTHENTICATION",
            "cost": 0.0128
          },
          {
            "start": 1685527200,
            "end": 1685529000,
            "conversation": 3,
            "conversation_category": "MARKETING",
            "cost": 0.0432
          }
        ]
      }
    ]
  },
  "id": "102290129340398"
}

取得依對話類型和對話類別解析的半小時資料


要求：

curl -i -X GET \
 "https://graph.facebook.com/v21.0/{whatsapp-buiness-account-id}
  ?fields=conversation_analytics
  .start(1685527200)
  .end(1685613600)
  .granularity(HALF_HOUR)
  .conversation_categories(["MARKETING","AUTHENTICATION"])
  .dimensions(["CONVERSATION_CATEGORY","CONVERSATION_TYPE"])
  &access_token={access-token}"

回應：

{
  "conversation_analytics": {
    "data": [
      {
        "data_points": [
          {
            "start": 1685527200,
            "end": 1685529000,
            "conversation": 3,
            "conversation_type": "REGULAR",
            "conversation_category": "MARKETING",
            "cost": 0.0432
          },
          {
            "start": 1685529000,
            "end": 1685530800,
            "conversation": 2,
            "conversation_type": "REGULAR",
            "conversation_category": "AUTHENTICATION",
            "cost": 0.0128
          }
        ]
      }
    ]
  },
  "id": "102290129340398"
}

定價分析工具

當每則訊息定價適用於您的推出群組時，就可以使用定價分析工具。請參閱定價更新。

pricing_analytics 欄位可讓您取得在指定日期範圍內所傳遞之任何訊息的定價資料解析。

要求語法

GET /<WABA_ID> ?fields=pricing_analytics .start(<START>) .end(<END>) .granularity(<GRANULARITY>) .phone_numbers(<PHONE_NUMBERS>) .country_codes(<COUNTRY_CODES>) .metric_types(<METRIC_TYPES>) .pricing_types(<PRICING_TYPES>) .pricing_categories(<PRICING_CATEGORIES>) .dimensions(<DIMENSIONS>)

參數

篩選條件 說明 範例值

<COUNTRY_CODES>

字串陣列

選用項目。

您要擷取分析的國家／地區。請提供要包含在內的國家／地區的 2 字母國碼／區碼。如未提供，將同時傳回您曾經通訊的所有國家／地區的分析。

[
  "US",
  "BR"
]

<DIMENSIONS>

字串陣列

選用項目。

您要套用於衡量指標的資料解析清單。若傳送空清單，我們會傳回沒有任何資料解析的結果。

可能的值如下：

  • PRICING_CATEGORY
  • PRICING_TYPE
  • COUNTRY
  • PHONE
[
  "PRICING_CATEGORY",
  "PRICING_TYPE",
  "COUNTRY"
]

<END>

UNIX 時間戳記

必要項目。

UNIX 時間戳記，用於指示要擷取分析之日期範圍的結束日期。

1728581152

<GRANULARITY>

字串

必要項目。

要擷取分析的精細程度。可使用下列其中一個值：

  • DAY
  • HALF_HOUR
  • MONTH

DAY

<METRIC_TYPES>

字串陣列

選用項目。

您要擷取之衡量指標的陣列。若傳送空陣列，我們會傳回所有衡量指標類型的結果。

可能的值如下：

  • COST：在該時間範圍內所傳遞之訊息的大概費用，以 WABA 的幣別計算。
  • VOLUME：包含該時間範圍內所傳遞的訊息數量。
[
  "COST",
  "VOLUME"
]

<PHONE_NUMBERS>

字串陣列

選用項目。

要擷取分析的電話號碼陣列。如未提供，則會包含與 WABA 相關聯的所有商家電話號碼。

[
  "15550783881",
  "15550783882",
  "15550783883"
]

<PRICING_CATEGORIES>

字串陣列

選用項目。

定價類別陣列。若傳送空陣列，我們會傳回所有定價類別的結果。

可能的值如下：

  • AUTHENTICATION：收取驗證費用的訊息。
  • AUTHENTICATION_INTERATIONAL：收取國際驗證費用的訊息。
  • MARKETING：收取行銷費用的訊息。
  • SERVICE：未收取費用的訊息。包含所有在顧客服務期間內傳送的非範本訊息和公用訊息。
  • UTILITY：收取公用費用的訊息。
[
  "AUTHENTICATION",
  "MARKETING",
  "UTILITY"
]

<PRICING_TYPES>

字串陣列

選用項目。

定價類型陣列。若傳送空陣列，我們會傳回所有定價類型的結果。

可能的值如下：

  • FREE_CUSTOMER_SERVICE：免費訊息，是在顧客服務期間內傳送的非範本訊息和公用訊息。
  • FREE_ENTRY_POINT：在免費進入點顧客服務期間內傳送的所有訊息。
  • REGULAR：可收款的訊息。包含所有驗證和行銷範本訊息，以及在顧客服務期間外傳送的任何公用範本訊息。不含在免費進入點顧客服務期間內傳送的所有訊息。
[
  "REGULAR",
  "FREE_CUSTOMER_SERVICE"
]

<START>

UNIX 時間戳記

必要項目。

UNIX 時間戳記，用於指示要擷取分析之日期範圍的開始日期。

1726014453

<WABA_ID>

字串

必要項目。

WhatsApp Business 帳號編號。

102290129340398

範本分析

範本分析說明範本被傳送、送達和讀取的次數，以及範本中網址按鈕或快速回覆按鈕被點擊的次數。

資料會以 UTC 時區的每日精細度傳回，回溯期長達 90 天。您也可以在 WhatsApp 管理工具 > 訊息範本 > 範本詳細資料 > 洞察報告面板中找到範本分析。

限制

  • 只有當帳號未選擇使用雲端 API 範本分析時，範本分析才適用於內部部署 API。
  • 內部部署 API 範本分析受限於彙總和匿名化準則，該準則要求最少要有 1000 個事件才能向用戶顯示計數。
  • 按鈕點擊次數分析僅適用於分類為 MARKETING 或 UTILITY 的範本。
  • 不支援由歐盟、英國或日本的 Meta 商業帳號擁有或共享的 WABA，或商家電話號碼包含上述任何國家或地區之電話國碼／區碼的 WABA。

回報故障

若要回報範本分析故障，請提交包含下列選項的直接支援問題單：

  • 問題主題：WABiz：雲端 API
  • 要求類型：故障或實作問題

確認範本分析

您必須先在 WhatsApp Business 帳號上確認範本分析，然後才能取得範本分析。您可以使用 WhatsApp 管理工具或 API 來確認範本分析。

透過 API 確認存取權限，即表示您指示 Meta 將洞察報告新增至您的 WhatsApp Business 帳號。這些洞察報告包含連結追蹤功能，以回報網站點擊次數。您可以在各訊息範本關閉連結追蹤功能。您同時指示 Meta 蒐集您與顧客聊天室的資料，並將資料匿名處理。Meta 會將此等資料匿名處理，以提升為您和其他商家提供的服務品質。

若要透過 API 確認，請傳送以下要求：

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>?is_enabled_for_insights=true

確認後，我們就會開始擷取 WhatsApp Business 帳號的範本分析。一旦確認，即無法停用範本分析。

成功後，API 會以您的 WhatsApp Business 帳號編號進行回應。舉例來說：

{                          
  "id": 102290129340398
}

範本分析參數

名稱說明範例值

start

UNIX 時間戳記

必要項目。

您要擷取分析資料的日期範圍開始時間戳記。範本分析會以 UTC 時區的每日精細度提供，因此非 0:00 UTC 的開始時間戳記會更正為上一個 0:00 UTC。

1543536000

end

UNIX 時間戳記

必要項目。


要擷取分析之日期範圍的結束日期。範本分析會以 UTC 時區的每日精細度提供，因此非 0:00 UTC 的結束時間戳記會更正為下一個 0:00 UTC。

1543708800

granularity

列舉

必要項目。

要擷取分析的精細程度。值必須為 DAILY。

DAILY

template_ids

編號陣列

必要項目。

您想要擷取分析資料的範本編號陣列。

最多 10 個。

[1924084211297547,954638012257287,969725530748535]

metric_types

列舉陣列

選用項目。

透過解決方案合作夥伴計費的商家無法存取 COST 節點。若要瞭解收費情形，請與您的合作夥伴聯絡。

您要擷取的衡量指標類型。如果省略此參數或為空白陣列，則會傳回所有衡量指標類型的分析資料。

可能的值：

  • COST
  • CLICKED
  • DELIVERED
  • READ
  • SENT

您可以在此深入瞭解有關成本和點擊衡量指標的資訊。

[SENT,DELIVERED,READ]

product_type

列舉

選用項目。

您要擷取的衡量指標產品類型。如果省略此參數，則只會傳回雲端 API 的分析資料。

可能的值：

  • CLOUD_API：請使用此產品類型，篩選透過雲端 API 傳送的範本衡量指標
  • MARKETING_MESSAGES_LITE_API：請使用此產品類型，篩選透過行銷訊息 Lite API 傳送的範本衡量指標

MARKETING_MESSAGES_LITE_API

範例

取得所有範本分析資料

情境：在特定一天內，針對驗證範本和內含網址按鈕的行銷範本，取得所有範本分析資料衡量指標類型。

要求範例：

curl -g 'https://graph.facebook.com/v21.0/109259195336416/template_analytics?start=1718064000&end=1718122745&granularity=daily&metric_types=cost%2Cclicked%2Cdelivered%2Cread%2Csent&template_ids=[1421988012088524%2C2632273056924580]' \
-H 'Authorization: Bearer EAAJB...'

回應範例：

{
  "data": [
    {
      "granularity": "DAILY",
      "product_type": "cloud_api", // Only available to businesses in the Marketing Messages Lite API alpha
      "data_points": [
        {
          "template_id": "1421988012088524",
          "start": 1718064000,
          "end": 1718150400,
          "sent": 1,
          "delivered": 1,
          "read": 1,
          "cost": [
            {
              "type": "amount_spent",
              "value": 0.01
            },
            {
              "type": "cost_per_delivered",
              "value": 0.01
            }
          ]
        },
        {
          "template_id": "2632273056924580",
          "start": 1718064000,
          "end": 1718150400,
          "sent": 1,
          "delivered": 1,
          "read": 1,
          "clicked": [
            {
              "type": "quick_reply_button",
              "button_content": "Contact Support",
              "count": 108
            },
            {
              "type": "unique_url_button",
              "button_content": "Tell me more",
              "count": 16
            }
          ],
          "cost": [
            {
              "type": "amount_spent",
              "value": 0.03
            },
            {
              "type": "cost_per_delivered",
              "value": 0.03
            },
            {
              "type": "cost_per_url_button_click",
              "value": 0.03
            }
          ]
        }
      ]
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MjQZD"
    }
  }
}

成本和點擊衡量指標

成本衡量指標會以成本物件陣列的方式傳回，各筆皆含類型和值。類型可以是：

  • amount_spent — 因為傳送該範本，在 start 和 end 時限內所開啟的對話中的總花費金額。請參閱開啟對話。
  • cost_per_delivered — amount_spent 值除以範本在 start 和 end 時限內送達的次數。
  • cost_per_url_button_click — amount_spent 值除以範本的網址按鈕在 start 和 end 時限內遭點擊的次數。不包含快速回覆按鈕點擊次數。如果範本沒有網址按鈕則物件會省略。

點擊衡量指標會以 JSON 物件陣列的方式傳回，各筆皆含類型和值。只有針對分類為 MARKETING 或 UTILITY 之範本中的網址按鈕和快速回覆按鈕，才會傳回點擊次數。

類型可以是：

  • url_button — 點擊網址按鈕的總次數。
  • unique_url_button — 不重複點擊人數追蹤的是曾點擊按鈕的不同 WhatsApp 帳號數量。透過這項衡量指標，您可以瞭解有多少位用戶正在與您的 CTA 互動，同時除去來自同一位接收者的重複點擊，藉此提高衡量互動率的準確度。

停用按鈕點擊次數分析

若要停用個別範本的按鈕點擊次數追蹤，您可以將其 cta_url_link_tracking_opted_out 欄位設為 true。一旦停用後，API 就不會在範本分析中傳回點擊屬性，在 WhatsApp 管理工具中查看範本的洞察報告時，也不會顯示按鈕互動／點擊次數。

要求語法

POST /<TEMPLATE_ID>
  ?cta_url_link_tracking_opted_out=<OPT_OUT>
  &category=<TEMPLATE_CATEGORY>

要求參數

預留位置說明範例值

<WHATSAPP_TEMPLATE_ID>

範本編號

必要項目。

範本編號。

245435364965041

<OPT_OUT>

布林值

必要項目。

指示是否停用範本按鈕點擊次數追蹤。設定 true 為停用範本上的按鈕點擊次數追蹤，設定 false 為啟用。

建立範本時，此值會設為 false。

true

<TEMPLATE_CATEGORY>

字串

必要項目。

範本目前的類別。

如果您將範本類別設為目前類別以外的值，則範本狀態會設為 PENDING，而範本必須經過範本審查以獲得批准。

marketing

要求範例

curl -X POST 'https://graph.facebook.com/v21.0/245435364965041?cta_url_link_tracking_opted_out=true&category=marketing' \
-H 'Authorization: Bearer EAAJB...'

回應範例

成功時，API 會回應如下內容：

{
    "success": true
}

參考資料

如需各欄位所有可能值的清單，請參閱 WhatsApp Business 帳號分析欄位的圖形 API 參考資料。