消息订阅工具
为了保证您可以及时接收到账户/广告等审核结果、财务充值进度等实时消息，无需自行调用相关接口做实时查询，我们为您提供了消息订阅工具。您可以在应用管理界面，订阅您所需要的消息类型，本期已支持广告通过审核、广告未通过审核、广告通过流量二次审核、广告未通过流量二次审核、账户余额不足预警、广告主账户审核通过/拒绝/封停（原状态名为：冻结）提醒等类型的消息订阅。更多消息类型请密切关注官网通知。
整体流程
您需要在开发者官网-应用程序管理-应用编辑详情页选择您需要订阅的消息类型，并根据官网提供的消息格式等信息提前搭建消息接收服务。
具体操作步骤：
- 您可在应用程序管理的详情页面，根据该应用已有的接口权限，订阅对应的消息类型。
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广告主的消息通知。
- 订阅消息的请求及返回参数的详细信息如下：
- 请求地址：由调用方定义（仅支持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 | int | 是 | 事件所属帐号id | |
| event_id | string | 是 | 事件标识id | |
| event_data | struct | 是 | 不同类型事件包含的数据详见【事件数据结构】 | 事件数据结构，可以为空结构。不为空时包含：key-事件类型（event_type），value-各个事件具体的消息数据。 |
本期支持的消息内容：
| 所属权限分类 | 消息名称 | 事件类型枚举值 | 事件数据结构 |
| 广告管理（Ads Management） | 广告审核不通过 |
EVENT_TYPE _AD_REVIEW_DISAPPROVED （adx广告的event_data中会多outer_creative_id、outer_advertiser_id值类型是字符串的字段） |
{ “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 （adx广告的event_data中会多outer_creative_id、outer_advertiser_id值类型是字符串的字段） |
{ “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_AUTO_DERIVED_CREATIVE_FINISHED |
{ “event_type”: “EVENT_TYPE_AD_AUTO_DERIVED_CREATIVE_FINISHED”, “account_id”: 1111111, “event_id”: “11111”, “event_data”: { “EVENT_TYPE_AD_AUTO_DERIVED_CREATIVE_FINISHED”: { “adgroup_id”: 111111, “ad_id”: 111111, “adcreative_id”: 111111, “message”: “”, “datetime”: “2021-04-09 16: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": 1000 //账户当前设置的日预算 } } } |
|
| 广告主账户审核通过 | 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值 |
- 我们仅在收到HTTP status = 200的响应，并且code = 0 ，event_id与请求中的event_id相同时，才认为消息推送成功。
- 如果消息推送后3秒内未接收到您的响应时，则认为推送失败；对于推送失败的消息，我们会在消息推送失败后每隔5分钟重试3次，如果重试3次仍不成功，则停止尝试，且推送失败的消息不会再做存储推送。请您及时检查并确保所提供的回调地址及密钥是可用的。
- 如果您收到event_id相同的消息，仅需返回成功，无需对所有消息均做入库处理。
如果您在消息订阅工具的使用过程中需要技术支持或者反馈问题，可以将相关内容邮件至 marketing_api@tencent.com，我们会及时响应。如果您同时也是推广客户，也可以向与您接口的腾讯广告运营人员寻求帮助。
