WhatsApp Business Management API

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/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 欄位提供特定 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/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 物件和您所要求的資料。下列範例中的 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/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"
}

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

情境：您想擷取某個時間範圍內，與某個 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/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 範本分析受限於彙總和匿名化準則，該準則要求最少要有 1000 個事件才能向用戶顯示計數。
  • 按鈕點擊次數分析僅適用於分類為 MARKETING 或 UTILITY 的範本。
  • 不支援由歐盟、英國或日本的 Meta 商業帳號擁有或共享的 WABA，或商家電話號碼包含上述任何國家或地區之電話國碼／區碼的 WABA。

回報故障

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

  • 問題主題：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 帳號分析欄位的圖形 API 參考資料。