接口文档SDK业务专题开发者工具

消息订阅工具

为了保证您可以及时接收到账户/广告等审核结果、财务充值进度等实时消息,无需自行调用相关接口做实时查询,我们为您提供了消息订阅工具。您可以在应用管理界面,订阅您所需要的消息类型,本期已支持广告通过审核、广告未通过审核、广告通过流量二次审核、广告未通过流量二次审核、账户余额不足预警、广告主账户审核通过/拒绝/冻结提醒等类型的消息订阅。更多消息类型请密切关注官网通知。

现在就去体验

整体流程

您需要在开发者官网-应用程序管理-应用编辑详情页选择您需要订阅的消息类型,并根据官网提供的消息格式等信息提前搭建消息接收服务。

具体操作步骤:

  1. 您可在应用程序管理的详情页面,根据该应用已有的接口权限,订阅对应的消息类型。

1) 初次创建消息订阅时,您需要填写回调地址(消息推送的获取地址)及密钥(获取消息推送权限的唯一标识,一般为3-32个的数字或英文字母),我们会根据您提供的回调参数及密钥信息,为您推送一条测试消息体。测试消息体内容请参考的详细记录。
测试消息体的格式为:

 { 
    "event_type": "EVENT_TYPE_TEST", 
    "account_id": 999999, //固定999999 
    "event_id":1000, //固定1000 
    "event_data": { 
        "EVENT_TYPE_TEST": {} 
    } 
 } 
  • 您接收到此消息后,请按照正常消息做处理并返回。

2) 您可在此步骤对不同类型的消息做订阅或取消订阅操作。

— 如果您已有广告管理接口权限,A广告主通过Oauth接口授权了广告管理权限给您,B广告主未授权,则您仅可接收到A广告主的消息通知。

  1. 订阅消息的请求及返回参数的详细信息如下:
    • 请求地址:由调用方定义(仅支持HTTPS协议)
    • 请求方式:POST
    • 请求字段:

以下字段在URL中传递

名称 类型 必填 限制 描述
signature string 40个英文字符 加密签名,生成规则为signature = sha1(post内容+secret),其中字符串的拼接就是简单的相加操作. 例如: hello + + world -> hello world。使用方法为:compare(signature, signature_in_URL),即比较请求中的签名与计算的签名是否吻合。
timestamp timestamp 精度为秒 发送请求时的时间戳
nonce string 建议接收端可以设置该字段为不允许重复,避免请求重放:接收端把nonce缓存下来,比对每次请求的值是否已经存在。同时可利用timestamp字段来丢弃超过设定时间的请求,这样就只用保存一小段时间内的nonce。 nonce(number used once的缩写),用于标识每个HTTP请求的字符串,MKT API侧确保不会重复。

以下字段在HTTP body中传递(json格式)

名称 类型 必填 限制 描述
event_type enum 详见【事件类型枚举值】 事件类型
account_id enum 事件所属帐号id
event_id string 事件标识id
event_data struct 不同类型事件包含的数据详见【事件数据结构】 事件数据结构,可以为空结构。不为空时包含:key-事件类型(event_type),value-各个事件具体的消息数据。

本期支持的消息内容:

所属权限分类 消息名称 事件类型枚举值 事件数据结构
广告管理(Ads Management) 广告审核不通过 EVENT_TYPE _AD_REVIEW_DISAPPROVED {
“event_type”: “EVENT_TYPE_AD_REVIEW_DISAPPROVED”,
“account_id”: 1111111,
“event_id”:11111,
“event_data”: {
“EVENT_TYPE_AD_REVIEW_DISAPPROVED”: {
“adgroup_id”: 111111,
“ad_id”: 111111,
“message”: “”,//审核驳回原因
“datetime”: “2019-07-18 10:10:00”
}
}
}
广告审核通过 EVENT_TYPE _AD_REVIEW_APPROVED {
“event_type”: “EVENT_TYPE_AD_REVIEW_APPROVED”,
“account_id”: 1111111,
“event_id”:11111,
“event_data”: {
“EVENT_TYPE_AD_REVIEW_APPROVED”: {
“adgroup_id”: 111111,
“ad_id”: 111111,
“datetime”: “2019-07-18 10:10:00”
}
}
}
广告未通过流量二次审核 EVENT_TYPE_AD_MEDIA_REVIEW_DISAPPROVED {
“event_type”: “EVENT_TYPE_AD_MEDIA_REVIEW_DISAPPROVED”,
“account_id”: 1111111,
“event_id”:11111,
“event_data”: {
“EVENT_TYPE_AD_MEDIA_REVIEW_DISAPPROVED”: {
“adgroup_id”: 11111,
“ad_id”: 11111,
“message”: “”,
“datetime”: “2019-07-18 10:10:00”
}
}
}
广告通过流量二次审核 EVENT_TYPE_AD_MEDIA_REVIEW_APPROVED {
“event_type”: “EVENT_TYPE_AD_MEDIA_REVIEW_APPROVED”,
“account_id”: 1111111,
“event_id”:11111,
“event_data”: {
“EVENT_TYPE_AD_MEDIA_REVIEW_APPROVED”: {
“adgroup_id”: “”,
“ad_id”: 11111,
“datetime”: “2019-07-18 10:10:00”
}
}
}
推广计划日消耗达到日预算 EVENT_TYPE_CAMPAIN_DAYBUDGET_RUNOUT   {
"event_type": "EVENT_TYPE_CAMPAIN_DAYBUDGET_RUNOUT",
“account_id”: 1111111,
“event_id”:11111,
"event_data": {
"EVENT_TYPE_CAMPAIN_DAYBUDGET_RUNOUT": {
"datetime": "",
"campaign_id": ""
}
}
}
推广计划日消耗超过日预算的80% EVENT_TYPE_CAMPAIN_DAYBUDGET_LOW   {
"event_type": "EVENT_TYPE_CAMPAIN_DAYBUDGET_LOW",
“account_id”: 1111111,
“event_id”:11111,
"event_data": {
"EVENT_TYPE_CAMPAIN_DAYBUDGET_LOW": {
"datetime": "1970-01-01 00:00:00",
"campaign_id": 1
}
}
}
推广计划总消耗超过总预算 EVENT_TYPE_CAMPAIN_TOTAL_BUDGET_RUNOUT   {
"event_type": "EVENT_TYPE_CAMPAIN_TOTAL_BUDGET_RUNOUT",
“account_id”: 1111111,
“event_id”:11111,
"event_data": {
"EVENT_TYPE_CAMPAIN_TOTAL_BUDGET_RUNOUT": {
"datetime": "1970-01-01 00:00:00",
"campaign_id": 1
}
}
}
推广计划总消耗超过总预算的80% EVENT_TYPE_CAMPAIN_TOTAL_BUDGET_LOW   {
"event_type": "EVENT_TYPE_CAMPAIN_TOTAL_BUDGET_LOW",
“account_id”: 1111111,
“event_id”:11111,
"event_data": {
"EVENT_TYPE_CAMPAIN_TOTAL_BUDGET_LOW": {
"datetime": "1970-01-01 00:00:00",
"campaign_id": 1
}
}
}
广告组总消耗达到总预算 EVENT_TYPE_ADGROUP_TOTAL_BUDGET_RUNOUT   {
"event_type": "EVENT_TYPE_ADGROUP_TOTAL_BUDGET_RUNOUT",
“account_id”: 1111111,
“event_id”:11111,
"event_data": {
"EVENT_TYPE_ADGROUP_TOTAL_BUDGET_RUNOUT": {
"datetime": "1970-01-01 00:00:00",
"adgroup_id": 1
}
}
}
广告组总消耗达到总预算的80% EVENT_TYPE_ADGROUP_TOTAL_BUDGET_LOW   {
"event_type": "EVENT_TYPE_ADGROUP_TOTAL_BUDGET_LOW",
“account_id”: 1111111,
“event_id”:11111,
"event_data": {
"EVENT_TYPE_ADGROUP_TOTAL_BUDGET_LOW": {
"datetime": "1970-01-01 00:00:00",
"adgroup_id": 1
}
}
}
广告日消耗超过日预算 EVENT_TYPE_ADGROUP_DAYBUDGET_RUNOUT {
"event_type": "EVENT_TYPE_ADGROUP_DAYBUDGET_RUNOUT",
“account_id”: 1111111,
“event_id”:11111,
"event_data": {
"EVENT_TYPE_ADGROUP_DAYBUDGET_RUNOUT": {
"datetime": "1970-01-01 00:00:00",
"adgroup_id": 1
}
}
}
广告日消耗超过日预算的80% EVENT_TYPE_ADGROUP_DAYBUDGET_LOW {
"event_type": "EVENT_TYPE_ADGROUP_DAYBUDGET_LOW",
“account_id”: 1111111,
“event_id”:11111,
"event_data": {
"EVENT_TYPE_ADGROUP_DAYBUDGET_LOW": {
"datetime": "1970-01-01 00:00:00",
"adgroup_id": 1
}
}
}
视频转码成功 EVENT_TYPE_MEDIA_STATUS_VALID   {
"event_type": "EVENT_TYPE_MEDIA_STATUS_VALID",
“account_id”: 1111111,
“event_id”:11111,
"event_data": {
"EVENT_TYPE_MEDIA_STATUS_VALID": {
"video_id": "",
"datetime": ""
}
}
}
视频转码失败 EVENT_TYPE_MEDIA_STATUS_ERROR {
"event_type": "EVENT_TYPE_MEDIA_STATUS_ERROR",
"account_id": 1111111,
"event_id": "111111",
"event_data": {
"EVENT_TYPE_MEDIA_STATUS_ERROR": {
"video_id": "",
"datetime": "",
"ad_details_list": ""//转码失败的视频影响到的广告列表
}
}
}
落地页风控审核通过消息 EVENT_TYPE_PAGE_REVIEW_APPROVED   {
"event_type": "EVENT_TYPE_PAGE_REVIEW_APPROVED",
“account_id”: 1111111,
“event_id”:11111,
"event_data": {
"EVENT_TYPE_PAGE_REVIEW_APPROVED": {
"message": "",
"page_url": "",
"datetime": ""
}
}
}
落地页风控审核不通过消息 EVENT_TYPE_PAGE_REVIEW_DISAPPROVED   {
"event_type": "EVENT_TYPE_PAGE_REVIEW_DISAPPROVED",
“account_id”: 1111111,
“event_id”:11111,
"event_data": {
"EVENT_TYPE_PAGE_REVIEW_DISAPPROVED": {
"message": "",
"page_url": "",
"datetime": ""
}
}
}
ocpa赔付账单消息 EVENT_TYPE_OCPA_COMPENSATE_BILL   {
"event_type": "EVENT_TYPE_OCPA_COMPENSATE_BILL",
“account_id”: 1111111,
“event_id”:11111,
"event_data": {
"EVENT_TYPE_OCPA_COMPENSATE_BILL": {
"message": "",
"exposureDate": "",//曝光日期
"compensateMoney": "",//赔付金额
"url": "",//账单详情查询页面
"datetime": ""//消息发送日期
}
}
}
账号管理(Account Management) 账户余额不足预警 EVENT_TYPE_ADVERTISER_BALANCE_LOW   {
"event_type": "EVENT_TYPE_ADVERTISER_BALANCE_RUNOUT",
“account_id”: 1111111,
“event_id”:11111,
"event_data": {
"EVENT_TYPE_ADVERTISER_BALANCE_RUNOUT": {
"datetime": "1970-01-01 00:00:00"
}
}
}
账户余额过低预警 EVENT_TYPE_ADVERTISER_BALANCE_LOW  {
"event_type": "EVENT_TYPE_ADVERTISER_BALANCE_LOW",
“account_id”: 1111111,
“event_id”:11111,
"event_data": {
"EVENT_TYPE_ADVERTISER_BALANCE_LOW": {
"datetime": "",
"trigger": "" //账户余额低于此阈值(当前固定为20000分)就会触发本消息
}
}
}
账户日消耗超过日预算的80% EVENT_TYPE_ADVERTISER_DAYBUDGET_LOW   {
"event_type": "EVENT_TYPE_ADVERTISER_DAYBUDGET_LOW",
“account_id”: 1111111,
“event_id”:11111,
"event_data": {
"EVENT_TYPE_ADVERTISER_DAYBUDGET_LOW": {
"datetime": "1970-01-01 00:00:00"
}
}
}
账户日消耗达到日预算 EVENT_TYPE_ADVERTISER_DAYBUDGET_RUNOUT   {
"event_type": "EVENT_TYPE_ADVERTISER_DAYBUDGET_RUNOUT",
“account_id”: 1111111,
“event_id”:11111,
"event_data": {
"EVENT_TYPE_ADVERTISER_DAYBUDGET_RUNOUT": {
"datetime": "", //消息发送时间
"budget_date": "", //达到日预算的日期
"day_buget": "" //账户当前设置的日预算
}
}
}
广告主账户审核通过 EVENT_TYPE_ADVERTISER_REVIEW_APPROVED   {
"event_type": "EVENT_TYPE_ADVERTISER_REVIEW_APPROVED",
“account_id”: 1111111,
“event_id”:11111,
"event_data": {
"EVENT_TYPE_ADVERTISER_REVIEW_APPROVED": {
"datetime": ""
}
}
}
广告主账户审核不通过 EVENT_TYPE_ADVERTISER_REVIEW_DISAPPROVED   {
"event_type": "EVENT_TYPE_ADVERTISER_REVIEW_DISAPPROVED",
“account_id”: 1111111,
“event_id”:11111,
"event_data": {
"EVENT_TYPE_ADVERTISER_REVIEW_DISAPPROVED": {
"message": "",
"datetime": ""
}
}
}
广告主账户审核冻结提醒 EVENT_TYPE_ADVERTISER_REVIEW_FREEZED   {
"event_type": "EVENT_TYPE_ADVERTISER_REVIEW_FREEZED",
“account_id”: 1111111,
“event_id”:11111,
"event_data": {
"EVENT_TYPE_ADVERTISER_REVIEW_FREEZED": {
"message": "",
"datetime": ""
}
}
}

公众号解绑状态通知
EVENT_TYPE_WECHAT_ACCOUNT_UNAUTHORIZED

{

“event_type”: EVENT_TYPE_WECHAT_ACCOUNT_UNAUTHORIZED,

“account_id”: 1111111,

“event_id”:11111,

“event_data”: {

EVENT_TYPE_WECHAT_ACCOUNT_UNAUTHORIZED: {

“wechat_account_id”: “1111111”,

“datetime”: “2019-07-18 10:10:00”

}

}

}

应答字段:

名称 类型 必填 描述
code int64 返回码,接收成功时为0
data struct 返回数据

data:

名称 类型 必填 描述
event_id string 接收成功时请返回消息正文中的event_id值
  1. 我们仅在收到HTTP status = 200的响应,并且code = 0 ,event_id与请求中的event_id相同时,才认为消息推送成功。
  2. 如果消息推送后3秒内未接收到您的响应时,则认为推送失败;对于推送失败的消息,我们会在消息推送失败后每隔5分钟重试3次,如果重试3次仍不成功,则停止尝试,且推送失败的消息不会再做存储推送。请您及时检查并确保所提供的回调地址及密钥是可用的。
  3. 如果您收到event_id相同的消息,仅需返回成功,无需对所有消息均做入库处理。

如果您在消息订阅工具的使用过程中需要技术支持或者反馈问题,可以将相关内容邮件至 marketing_api@tencent.com,我们会及时响应。如果您同时也是推广客户,也可以向与您接口的腾讯广告运营人员寻求帮助。

查看更多工具