Skip to content

analytics

Jump to bottom
GiuFLim edited this page Dec 24, 2025 · 2 revisions

统计分析

  • 模板统计分析的回溯期为90天
  • 消息统计分析的回溯期为1年

功能

此 API 包含 2 个接口：

// 消息统计分析
/api/wa/messageAnalytics

// 模板统计分析
/api/wa/templateAnalytics

鉴权机制

鉴权规则请参考地址：API接口调用约定

请求参数

header参数：

参数名 类型 必选 示例值 说明
accessKey String 是 fme2na3kdi3ki 用户身份标识
ts String 是 1655710885431 当前请求的时间戳（单位是毫秒），牛信服务端允许用户端请求最大时间误差为60秒
bizType String 是 2 WhatsApp业务类型，取固定值“2”
action String 是 mt WhatsApp业务操作，取固定值“mt”
sign String 是 6e9506557d1f289501d333ee2c365826 API入参参数签名，签名算法

消息统计分析

提供与特定 WABA 关联的电话号码所发送和送达的消息数量

接口

  • URL：https://api2.nxcloud.com/api/wa/messageAnalytics
  • Method：POST
  • Content-Type：application/json
  • 需要鉴权：是

body参数：

参数名 类型 必选 示例值 说明
appkey String 是 pem28kje 应用appkey
messaging_product String 是 whatsapp 值必须为“whatsapp”
business_phone String 是 86133xxx 商户的WhatsApp号码，需要带国码。如86158xxxx1795
start Long 是 1764547200 检索分析数据时所依日期范围的开始时间戳。(按照waba时区设置)
end Long 是 1766275200 检索分析数据时所依日期范围的结束时间戳。(按照waba时区设置)
granularity String 否 day 检索分析数据时依照的精细度。支持的选项：half_hour(半小时维度) day(日维度) month(月维度) 如果此参数省略，系统将仅返回day的分析数据。

请求示例

  • day
{
    "appkey": "xxx",
    "business_phone": "xxx",
    "messaging_product": "whatsapp",
    "start": 1765987200,
    "end": 1766160000,
    "granularity":"day"
}
  • month
{
    "appkey": "xxx",
    "business_phone": "xxx",
    "messaging_product": "whatsapp",
    "start": 1764547200,
    "end": 1766275200,
    "granularity":"month"
}

响应结果

参数 类型 描述
code Integer
message String
data Array[Object] 返回结构

data Array[Object]

参数 类型 描述
start Long 开始时间戳(按照waba时区返回)
end Long 结束时间戳(按照waba时区返回)
sent Long 发送量
delivered Long 送达量

响应示例 SUCCESS

{
    "code": 0,
    "data": {
        "data": [
            {
                "start": 1765987200,
                "end": 1766073600,
                "delivered": 4609,
                "sent": 4679
            },
            {
                "start": 1766073600,
                "end": 1766160000,
                "delivered": 4387,
                "sent": 4452
            }
        ],
        "granularity": "DAY"
    },
    "message": "请求成功"
}

响应示例 FAIL

{
    "code": 0,
    "data": {
        "error": {
            "error_user_title": "Insight Time Window For Monthly Data Invalid",
            "code": 100.0,
            "error_subcode": 2388087.0,
            "message": "Invalid parameter",
            "type": "OAuthException",
            "is_transient": false,
            "fbtrace_id": "ANC18rIMBcSBefSnVQSpdBO",
            "error_user_msg": "Too small time window to get monthly granularity data."
        }
    },
    "message": "请求成功"
}

模板成效分析

模板分析数据会描述模板已发送、已送达和已阅读的数量以及模板中网址按钮或快速回复按钮的点击量。此外，已接入Lite版营销消息的商家可以追踪站外转化指标。按照WABA 时区的默认时区，以每日的精细程度返回数据，回溯窗口期最长可达90天。

限制

  • 按钮点击量分析仅适用于归类为 MARKETING 或 UTILITY 的模板。

  • WhatsApp 模板消息的已读和点击事件数据的追溯期最长为自消息发送当天起 7 天的时间。7 天的窗口期过后，相应的已读/点击量将重置为零，且系统不会再记录这些消息的后续更新。

接口

  • URL：https://api2.nxcloud.com/api/wa/templateAnalytics
  • Method：POST
  • Content-Type：application/json
  • 需要鉴权：是

body参数：

参数名 类型 必选 示例值 说明
appkey String 是 pem28kje 应用appkey
messaging_product String 是 whatsapp 值必须为“whatsapp”
business_phone String 是 86133xxx 商户的WhatsApp号码，需要带国码。如86158xxxx1795
template_name Array[String] 是 ["marketing_en_w"] 模板名称数组，支持多个最多支持10个
language String 否 en_US 模板语言，如果存在同名模板，可以通过模板语言精确查询
start String 是 2025-12-21 检索分析数据时所依日期范围的开始时间。可以表示为YYYY-MM-DD 格式的日期字符串。由于模板分析数据在 UTC 时区是以每日的精细程度提供，未对应 0:00 UTC 的开始时间 Unix 时间戳将调整回当前日期的 00:00 UTC。
end String 是 2025-12-23 检索分析数据时所依日期范围的结束时间。可以表示为YYYY-MM-DD 格式的日期字符串。由于模板分析数据在 UTC 时区是以每日的精细程度提供，未对应 0:00 UTC 的结束时间 Unix 时间戳将调整回当前日期的 00:00 UTC。
product_type String 否 marketing_messages_lite_api 如果此参数省略，系统将仅返回marketing_messages_lite_api 的分析数据。 cloud_api：验证和通知模板设置该值。marketing_messages_lite_api：营销模板设置该值

请求示例

  • marketing_messages_lite_api
{
    "appkey": "xxx",
    "business_phone": "xxx",
    "messaging_product": "whatsapp",
    "template_name": ["marketing_en_w"],
    "start": "2025-12-21",
    "end": "2025-12-23",
    "product_type": "marketing_messages_lite_api"
}
  • cloud_api
{
    "appkey": "xxx",
    "business_phone": "xxx",
    "messaging_product": "whatsapp",
    "template_name": ["otp_en_w"],
    "start": "2025-12-21",
    "end": "2025-12-23",
    "product_type": "cloud_api"
}

响应结果

参数 类型 描述
code Integer
message String
data Array[Object] 返回结构

data Array[Object]

参数 类型 描述
template_id String 模板id
template_name String 模板名称
start Long 开始时间戳(按照waba时区返回)
end Long 结束时间戳(按照waba时区返回)
sent Long 发送量
delivered Long 送达量
read Long 已读量
clicked Array[Object] 点击量

clicked Array[Object]

返回的点击量指标是一组 JSON 对象，每个 JSON 对象都包含一种类型和值。仅为 MARKETING 或 UTILITY 类模板返回网址按钮和快速回复按钮的点击量。

参数 类型 描述
button_content String 按钮内容
count Long 点击量
type 类型 url_button — 网址按钮的点击量总数。unique_url_button — 点击的独立用户人数可追踪点击过某一按钮的不同 WhatsApp 账户数目。该指标能帮助您了解参与您行动号召的个人用户数量，同时消除同一收件人的重复点击数，提供准确的参与度衡量。

响应示例 SUCCESS

{
    "code": 0,
    "data": {
        "data": [
            {
                "template_name": "mkt_65",
                "read": 0,
                "start": 1766246400,
                "template_id": "7597xxx7425",
                "end": 1766332800,
                "delivered": 0,
                "sent": 0,
                "clicked": [
                    {
                        "button_content": "oportunidad",
                        "count": 0,
                        "type": "url_button"
                    },
                    {
                        "button_content": "oportunidad",
                        "count": 0,
                        "type": "unique_url_button"
                    }
                ]
            },
            {
                "template_name": "mkt_65",
                "read": 0,
                "start": 1766332800,
                "template_id": "75975xxx7425",
                "end": 1766419200,
                "delivered": 0,
                "sent": 0,
                "clicked": [
                    {
                        "button_content": "oportunidad",
                        "count": 0,
                        "type": "url_button"
                    },
                    {
                        "button_content": "oportunidad",
                        "count": 0,
                        "type": "unique_url_button"
                    }
                ]
            },
            {
                "template_name": "mkt_65",
                "read": 20811,
                "start": 1766419200,
                "template_id": "7597xxx7425",
                "end": 1766505600,
                "delivered": 37480,
                "sent": 40816,
                "clicked": [
                    {
                        "button_content": "oportunidad",
                        "count": 5965,
                        "type": "url_button"
                    },
                    {
                        "button_content": "oportunidad",
                        "count": 5462,
                        "type": "unique_url_button"
                    }
                ]
            }
        ]
    },
    "message": "请求成功"
}

响应示例 FAIL

{
    "code": 0,
    "data": {
        "error": {
            "error_user_title": "Incorrect Start and End Times",
            "code": 100.0,
            "error_subcode": 4182001.0,
            "message": "Invalid parameter",
            "error_data": "End time must be within the query period of the last 90 days.",
            "error_user_msg": "Start time must be earlier than end time."
        }
    },
    "message": "请求成功"
}

简介

短信

语音

云呼叫中心（NXLink）

云呼叫中心（AI自动外呼）

Flash Call

短链

邮件验证码

DID号码

通用

号码检测

WhatsApp

Viber

Zalo ZNS

Super Message API

隐私号(旧)

PNS

坐席（旧版）

AI Agent

Clone this wiki locally