WhatsApp Business 管理 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）付费的商家，系统不再显示 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

分析数据为约计数据，由于数据处理时存在微小差异，此数据可能与结算单上显示的数据有所不同。

示例

您可以给定一个时间范围，然后获取与您的 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 模板分析数据的情况下，模板分析数据才适用于 On-Premises API。
  • On-Premises API 模板分析数据需要遵守汇总和匿名化处理守则，即事件数量需要至少达到 1,000 个，系统才会向用户显示相关计数。
  • 按钮点击量分析仅适用于归类为 MARKETING 或 UTILITY 的模板。
  • 如果 WABA 由欧盟、英国或日本的 Meta 业务帐户所有或已与该帐户共享，或者该商业帐号的公司电话号码中包含来自这三个区域中国家或地区的国家/地区电话区号，该商业帐号将不受支持。

报告漏洞

要报告模板分析漏洞，请提交站内支持工单，并在其中选择以下选项：

  • 问题主题：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
}

参考文档

如需各字段所有可用值的列表，请参阅图谱 API 参考文档中的 WhatsApp Business 商业帐号“分析”字段。