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

We are making changes to the WhatsApp Business Platform pricing model. See Pricing Updates on the WhatsApp Business Platform.

分析工具

此文件說明如何獲取訊息往來、對話及範本分析資料，例如商家電話號碼傳送的訊息數量，WhatsApp Business 帳戶的對話次數及成本，或特定範本的已讀次數。

回應中只會包含提出要求時與您 WhatsApp Business 帳戶連結的商家電話號碼和範本之衡量數據。

獲取資料

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

要求語法

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

查詢字串參數

預留位置說明範例值

<FIELDS>

此為必要項目。


衡量數據。值可以是以下其一：


analytics

<FILTERING_PARAMETERS>

此為必要項目。


衡量數據篩選參數。使用圓點附加更多篩選參數。


參閱下文，了解可能的值：


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

訊息往來分析資料

analytics 欄位提供與特定 WhatsApp Business 帳戶連結的電話號碼所傳送和送達的訊息數量和類型；如要了解對話衡量數據，請參閱對話分析資料。呼叫 /{whatsapp-business-account-ID}?fields=analytics.{filtering-parameters} 時，您可以附加以下參數。

分析資料參數

名稱說明（點擊左欄的箭咀以了解支援選項。）

start

類型：UNIX 時戳

此為必要項目。

您想檢索的分析資料之日期範圍開始日期。

end

類型：UNIX 時戳

此為必要項目。

您想檢索的分析資料之日期範圍結束日期。

granularity

類型：字串

此為必要項目。

檢索分析資料時所參考的精確度。

支援選項

  • HALF_HOUR
  • DAY
  • MONTH

phone_numbers

類型：陣列

此為選用項目。

檢索分析資料時所針對的電話號碼陣列。若未提供此陣列，則系統會包含已加入您 WhatsApp Business 帳戶的所有電話號碼。

product_types

類型：陣列

此為選用項目。

您想檢索的通知之訊息類型（通知訊息和／或客戶支援訊息）。提供陣列並加入 0（通知訊息適用）和 2（客戶支援訊息適用）。若未提供此陣列，則系統會同時傳回所有訊息。

country_codes

類型：陣列

此為選用項目。

檢索分析資料時所針對的國家／地區。提供包含您想加入的國家／地區的國家／地區代碼（2 個字母）之陣列。若未提供此陣列，則系統會為您曾與其通訊的所有國家／地區傳回分析資料。

範例

情境：您需要獲取與您的 WhatsApp Business 帳戶連結的所有電話號碼所傳送和送達的訊息數量。

建議解決方案：集合您要呼叫的網址並加入以下篩選參數：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 欄位提供特定 WhatsApp Business 帳戶的成本和對話資訊。呼叫 /{whatsapp-business-account-ID}?fields=conversation_analytics.{filtering-parameters} 時，您可以附加以下參數。

對話分析資料參數

名稱說明（點擊左欄的箭咀以了解支援選項。）

start

類型：UNIX 時戳

此為必要項目。

您想檢索的分析資料之日期範圍開始日期。

end

類型：UNIX 時戳

此為必要項目。

您想檢索的分析資料之日期範圍結束日期。

granularity

類型：字串

此為必要項目。

檢索分析資料時所參考的精確度。

支援選項

  • HALF_HOUR
  • DAILY
  • MONTHLY

phone_numbers

類型：陣列

此為選用項目。

檢索分析資料時所針對的電話號碼陣列。若未提供此陣列，則系統會包含已加入您 WhatsApp Business 帳戶的所有電話號碼。

metric_types

此為選用項目。

您想接收的衡量數據清單。如果傳送空白清單，我們會傳回所有衡量數據類型的結果。

支援選項 {#supported}

  • COST：包括該時間範圍內的大概費用，以 WhatsApp Business 帳戶的貨幣單位計算。
  • CONVERSATION：包括該時間範圍內的對話數量。

自 2023 年 7 月 1 日起，系統不會再為透過解決方案合作夥伴計算帳單收費的企業顯示 COST。若要了解您的收費，請聯絡您的合作夥伴。如果您透過合作夥伴計算帳單收費，則會出現以下行為：

  1. 如您未有在要求中指定 metric_types，系統只會傳回 CONVERSATION
  2. 如您只指定了 CONVERSATION，系統只會傳回 CONVERSATION
  3. 如果您只指定了 COST，系統會傳回以下例外狀況：
    • 標題：「無法查看成本」
    • 訊息：「系統不會再為透過合作夥伴（即商業解決方案供應商）計算帳單收費的企業顯示收費。若要了解您的收費，請聯絡您的合作夥伴。」

如果您查詢的時段包含 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

分析資料為大概資料，可能會因資料處理過程中出現的些微差異而與帳單上顯示的資料有所不同。

範例

您可以指定一個時間範圍，然後獲取與您 WhatsApp Business 帳戶相關的對話和成本資訊。您可以按需要篩選並細分結果。請參閱下方的程式碼範例。

獲取每月資料，使用所有資料細節

情境：您想檢索特定月份內與 WhatsApp Business 帳戶連結的所有電話號碼的全部對話和成本資訊。

建議解決方案：集合您要呼叫的網址並加入以下篩選參數：

  • start：所選時間範圍的開始時間。在本案例中，即是您想獲取該月份衡量數據的月初日子。
  • end：所選時間範圍的結束時間。在本案例中，即是您想獲取該月份衡量數據的月尾日子。
  • granularity：您希望資料點有多精確。在下方範例中，我們使用了 MONTHLY，因此每個資料點即代表一個月的資料。
  • phone_numbers：如果傳送空白陣列，我們會傳回與 WhatsApp Business 帳戶連結的所有電話號碼的資訊。
  • 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 物件，其中包含您要求的資料。在下方範例中，WhatsApp Business 帳戶僅包含一個電話號碼。

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

獲取特定電話號碼的資料，使用所有資料細節和半小時精確度

情境：您想檢索特定時間範圍內，與 WhatsApp Business 帳戶連結的特定電話號碼當中的所有對話和成本資訊。獲取結果後，您想儘量使用全部資料細節。您需要每個資料點代表半小時的資料。

建議解決方案：集合您要呼叫的網址並加入以下篩選參數：

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

獲取每月資料，使用對話類型資料細節

情境：您想檢索特定時間範圍內，與 WhatsApp Business 帳戶連結的所有電話號碼當中的所有對話和成本資訊。獲取結果後，您想按對話類型細分資料。

建議解決方案：集合您要呼叫的網址並加入以下篩選參數：

  • start：所選時間範圍的開始時間。
  • end：所選時間範圍的結束時間。
  • granularity：您希望資料點有多精確。在下方範例中，我們使用了 MONTHLY，因此每個資料點即代表半個月的資料。
  • phone_numbers：如果傳送空白陣列，我們會傳回與 WhatsApp Business 帳戶連結的所有電話號碼的資訊。
  • 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：該時間範圍內送達訊息所需的大概費用，以 WhatsApp Business 帳戶的貨幣單位計算。
  • VOLUME：包括該時間範圍內送達的訊息數量。
[
  "COST",
  "VOLUME"
]

<PHONE_NUMBERS>

字串陣列

此為選用項目。

檢索分析資料時所針對的電話號碼陣列。若未提供此陣列，則系統會包含與您 WhatsApp Business 帳戶關聯的所有商家電話號碼資料。

[
  "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 範本分析資料需要符合彙整和匿名化守則，即在向用戶展示計數之前，最少要有 1,000 個事件。
  • 按鈕點擊次數分析資料僅適用於歸類為 MARKETING 或 UTILITY 的範本。
  • 在歐盟、英國或日本的 Meta 商業帳戶所擁有或共用的 WhatsApp Business 帳戶，或所持商家電話號碼的國碼／區碼為上述國碼／區碼的 WhatsApp Business 帳戶，均不獲支援。

回報錯誤

如要回報範本分析資料的錯誤，請提交直接支援工作單，其中需選好以下選項：

  • 問題主題：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

範例

取得所有範本分析資料

情境：檢索特定 1 日，取得該日驗證類別範本和包含網址按鈕的營銷類別範本的所有範本分析資料衡量數據類型。

要求範例：

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 帳戶分析工具欄位的 Graph API 參考資料。