CTWA dataset

CTWA数据集管理

借助数据集，您可以：

• **根据业务需求查看客户动态，忽略来源。**您可以使用一个数据集编号来代表您的网站、应用、线下和消息事件数据，无需为每个集成工具都使用单独的编号。如此您便可以一站式监测事件和管理设置。
• **减少对打造和维护多款 API 集成工具的需求。**一直以来，转化 API 都是用于直接将您的网站数据关联至 Meta，而单独的应用事件 API、线下转化 API 和消息事件 API 则是用于直接关联您的移动应用、线下和消息数据。现在，如果您创建数据集并绑定自己的应用，则可以使用转化 API 直接关联您的网站、移动应用、线下和消息数据。这样，您只需管理一个与 Meta 集成的 API 集成工具即可。

功能

此 API 包含 3 个接口：

// 创建数据集
/api/wa/createDataset

// 获取数据集
/api/wa/getDataset

// 上报数据集事件
/api/wa/eventsByPhone

鉴权机制

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

请求参数

header参数：

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

创建数据集

使用此端点创建号码的数据集，如果 WhatsApp Business 商业账户已有关联的 dataset_id，它将返回该编号。

接口

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

body参数：

参数名	类型	必选	示例值	说明
appkey	String	是	pem28kje	应用appkey
messaging_product	String	是	whatsapp	值必须为“whatsapp”
business_phone	String	是	86133xxx	商户的WhatsApp号码，需要带国码。如86158xxxx1795
dataset_name	String	否		数据集的名称

请求示例

{
    "appkey": "xxx",
    "messaging_product": "whatsapp",
    "business_phone": "852xxx",
    "dataset_name":"capi_dataset"
}

响应结果

参数	描述
id	dataset_id 数据集id

响应示例 SUCCESS

{
    "code": 0,
    "data": {
        "id": "263073281065xxx"
    },
    "message": "请求成功"
}

响应示例 FAIL

{
    "code": 9002,
    "data": null,
    "message": "Phone number error"
}

获取数据集

使用此端点获取数据集。

接口

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

body参数：

参数名	类型	必选	示例值	说明
appkey	String	是	pem28kje	应用appkey
messaging_product	String	是	whatsapp	发送消息的通道，应用于WhatsApp消息的发送时，值必须为“whatsapp”
business_phone	String	是	86133xxx	商户的WhatsApp号码，需要带国码。如86158xxxx1795

请求示例

{
    "appkey": "xxx",
    "messaging_product": "whatsapp",
    "business_phone": "xxx"
}

响应结果

参数	类型	描述
data	Array[Object]	包含：数据集信息

data Array[Object]

参数	类型	描述
id	String	数据集id
name	String	数据集名称

响应示例 SUCCESS

{
    "code": 0,
    "data": {
        "data": [
            {
                "name": "capi_dataset",
                "id": "263073281065xxx"
            }
        ]
    },
    "message": "请求成功"
}

响应示例 SUCCESS [未创建数据集]

{
    "code": 0,
    "data": {
        "data": []
    },
    "message": "请求成功"
}

响应示例 FAIL

{
    "code": 9002,
    "data": null,
    "message": "Phone number error"
}

上报数据集事件

使用此端点上报数据集事件。

接口

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

body参数：

参数名	类型	必选	示例值	说明
appkey	String	是	pem28kje	应用appkey
messaging_product	String	是	whatsapp	发送消息的通道，应用于WhatsApp消息的发送时，值必须为“whatsapp”
business_phone	String	是	86133xxx	商户的WhatsApp号码，需要带国码。如86158xxxx1795
data	Array[Object]	是		自定义事件内容

data Array[Object]

参数名	类型	必选	示例值	说明
event_name	String	是	Purchase	标准事件或自定义事件的名称.。示例值ViewContent, Search, AddToCart, AddToWishlist, InitiateCheckout, AddPaymentInfo, Purchase, Lead, Other
event_time	String	是	1764125989	Unix 时间戳（以秒为单位），表示事件的实际发生时间，您必须以格林威治标准时间 (GMT) 时区格式发送该日期。
action_source	String	是	business_messaging	您可通过此字段指定转化发生的位置。了解事件发生的位置有助于确保将广告投放至正确的受众。您可在 action_source 字段中发送的值如下： email — 转化通过邮件发生。 website — 转化在网站上完成。 app — 转化在移动应用上完成。 phone_call — 转化通过电话完成。 chat — 转化通过消息应用、短信或在线消息功能完成。 physical_store — 转化在实体店面对面完成。 system_generated — 转化自动发生，例如将订阅续费设置为每月自动支付。 business_messaging — 转化是通过 Messenger、Instagram 或 WhatsApp 的直达广告产生的。 other — 转化通过本文未列出的其他方式完成。
messaging_channel	Array[Object]	是	whatsapp	固定值 whatsapp
user_data	Object	是		包含客户信息数据的映射
custom_data	Object	否		包含事件其他企业数据的映射。

user_data Object

参数名	类型	必选	示例值	说明
whatsapp_business_account_id	String	是		wabaId
ctwa_clid	String	是		Meta 为 WhatsApp 直达广告生成的编号。Click to WhatsApp ad click ID。WhatsApp 直达广告点击编号 (ctwa_clid) 是一个个人标识符，对每次点击而言都是唯一的。当用户进入来自 WhatsApp 直达广告所发起的对话时，该标识将提供给商家。该标识符需要通过上报事件 API 调用发回给 Meta。ctwa_clid 字段可从消息 Webhook 下的引用对象中获取。

请求示例

{
    "appkey": "xxx",
    "messaging_product": "whatsapp",
    "business_phone": "xxx",
    "data": [
        {
            "event_name": "Purchase",
            "event_time": 1764125989,
            "action_source": "business_messaging",
            "messaging_channel": "whatsapp",
            "user_data": {
                "whatsapp_business_account_id": "xxx",
                "ctwa_clid": "DDDAfeg_NKU066K1Vaq0ymlzZyQB89i1g7z5i1MxOQmLcUC1DH_aBdTDItHj_fYNC_YyKKVph_S2c6dDsEC5PpMGB9XBaJn_xhmfobFaprPcP6O3xTXn8r-hs0h09erpF3XMWY3III8-g"
            },
            "custom_data": {
                "currency": "USD",
                "value": 123
            }
        }
    ]
}

响应结果

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

响应示例 SUCCESS [事件上报成功]

{
    "code": 0,
    "data": {
        "events_received": 1.0,
        "messages": [],
        "fbtrace_id": "AJoWFO4juxSZdyGt3z1SdjC"
    },
    "message": "请求成功"
}

响应示例 SUCCESS [未设置数据集 进行上报事件则无效]

{
    "code": 0,
    "data": {},
    "message": "请求成功"
}

响应示例 FAIL [ctwa_clid无效]

{
    "code": 0,
    "data": {
        "error": {
            "error_user_title": "Messaging Event Invalid Ctwa Clid",
            "code": 100.0,
            "error_subcode": 2804087.0,
            "message": "Invalid parameter",
            "type": "OAuthException",
            "is_transient": false,
            "fbtrace_id": "ALcL1CqdOavWvME2aZqT7qo",
            "error_user_msg": "The ctwa_clid parameter is invalid, please provide a valid value for the ctwa_clid parameter in user data."
        }
    },
    "message": "请求成功"
}

响应示例 FAIL [whatsapp_business_account_id无效]

{
    "code": 0,
    "data": {
        "error": {
            "error_user_title": "Invalid WhatsApp Business Account ID",
            "code": 100.0,
            "error_subcode": 2804115.0,
            "message": "Invalid parameter",
            "type": "OAuthException",
            "is_transient": false,
            "fbtrace_id": "AN5FCwDtHuWzo06WCXXYnrG",
            "error_user_msg": "The whatsapp_business_account_id parameter provided for your Purchase events with business_messaging action source from whatsapp channel is invalid. Provide a valid value for the whatsapp_business_account_id parameter in user data."
        }
    },
    "message": "请求成功"
}