WhatsApp Business 管理 API

WhatsApp Business 平台 > Business Management API > 指南

分析資料

此文件說明如何獲取訊息往來、對話及範本分析資料，例如商家電話號碼傳送的訊息數量，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/v19.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/v19.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/v19.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/v19.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/v19.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/v19.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"
}

範本分析資料

範本分析資料描述範本的傳送、送達及已讀次數，以及範本中網址按鈕或快速回覆按鈕的點擊次數。

系統會按照世界協調時間（UTC）時區精細至每日回報資料，回溯時間長達 90 天。範本分析資料亦可在 WhatsApp 管理工具 > 訊息範本 > 範本詳細資料 > 洞察報告面板中找到。

限制

  • 如果帳戶未有選擇接收雲端 API 範本分析資料，範本分析資料僅適用於內部部署 API。
  • 內部部署 API 範本分析資料需要符合彙整和匿名化守則，即在向用戶展示計數之前，最少要有 1,000 個事件。
  • 按鈕點擊次數分析資料僅適用於歸類為 MARKETING 或 UTILITY 的範本。
  • 在歐盟、英國或日本的 Meta 商業帳戶所擁有或共用的 WhatsApp Business 帳戶，或所持商家電話號碼的國家／地區代碼為上述國家或地區代碼的 WhatsApp Business 帳戶，均不獲支援。

回報錯誤

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

  • 問題主題：WABiz：雲端 API
  • 要求類型：錯誤或執行問題

確認範本分析資料

您必須確認 WhatsApp Business 帳戶上的範本分析資料，然後才能取得範本分析資料。您可透過 WhatsApp 管理工具或 API 來確認範本分析資料。如要透過 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

列舉陣列

此為選用項目。


您想檢索的衡量數據類型。如果略過陣列或陣列空白，系統會傳回所有衡量數據類型的分析資料。


可能的值：


  • CLICKED
  • DELIVERED
  • READ
  • SENT

只有當範本類別為 MARKETING 或 UTILITY 時，才會傳回當中網址按鈕和快速回覆按鈕的點擊次數。

["SENT","DELIVERED","READ"]

範例

取得所有範本分析資料

情境：您想取得 2 天內與 WhatsApp Business 帳戶相關的單個訊息範本當中所有可用的範本分析資料。

要求範例：

curl -g 'https://graph.facebook.com/v19.0/109259195336416/template_analytics?start=1689379200&end=1689552000&granularity=DAILY&metric_types=[%27SENT%27%2C%27DELIVERED%27%2C%27READ%27%2C%27CLICKED%27]&template_ids=[1924084211297547%2C954638012257287]' \
-H 'Authorization: Bearer EABN8...'

回應範例：

{
  "data": [
    {
      "granularity": "DAILY",
      "data_points": [
        {
          "template_id": "1924084211297547",
          "start": 1689379200,
          "end": 1689465600,
          "sent": 0,
          "delivered": 0,
          "read": 0,
          "clicked": [
            {
              "type": "quick_reply_button",
              "button_content": "Tell me more",
              "count": 3
            },
            {
              "type": "quick_reply_button",
              "button_content": "Get coupon",
              "count": 5
            }
          ]
        },
        {
          "template_id": "1924084211297547",
          "start": 1689465600,
          "end": 1689552000,
          "sent": 0,
          "delivered": 0,
          "read": 0,
          "clicked": [
            {
              "type": "quick_reply_button",
              "button_content": "Tell me more",
              "count": 73
            },
            {
              "type": "quick_reply_button",
              "button_content": "Get coupon",
              "count": 35
            }
          ]
        },
        {
          "template_id": "954638012257287",
          "start": 1689379200,
          "end": 1689465600,
          "sent": 0,
          "delivered": 0,
          "read": 0,
          "clicked": [
            {
              "type": "url_button",
              "button_content": "Visit Website",
              "count": 13
            }
          ]
        },
        {
          "template_id": "954638012257287",
          "start": 1689465600,
          "end": 1689552000,
          "sent": 0,
          "delivered": 0,
          "read": 0,
          "clicked": [
            {
              "type": "url_button",
              "button_content": "Visit Website",
              "count": 12
            }
          ]
        }
      ]
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MjQZD"
    }
  }
}

停用按鈕點擊次數分析資料

您可以透過將個別範本的 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/v19.0/245435364965041?cta_url_link_tracking_opted_out=true&category=marketing' \
-H 'Authorization: Bearer EAAJB...'

回應範例

成功時，API 將傳回以下回應：

{
    "success": true
}

參考資料

如需查閱每個欄位所有可用值的清單，請參閱有關 WhatsApp Business 帳戶分析工具欄位的 Graph API 參考資料。