VIVO消息推送服务端API接口文档

当前版本：2.9.2

修改记录：

（1）/message/auth接口，鉴权码生成方式优化，增加调用频率为10次/s，取消每天10000次数量限制；

（2）各接口请求体，新增appId，用于跟鉴权信息进行比对，确认是否为应用信息一致，不一致返回错误码10094

一．公共

1.推送超量说明

如果调用接口出现超量限制的返回码，请不要在当天高频次调用服务器相应接口，否则将调低推送量级；

出现“10070：发送总量超出限制”。当天不要调用/message/send 单推接口；

出现“10252：批量发送消息体超出限制”。当天不要调用/message/saveListPayload 保存群推消息公共体接口；

出现“10070：发送总量超出限制”。当天不要调用/message/saveListPayload 保存群推消息公共体接口，以及/message/pushToList 批量推送用户接口；

出现“10254：全量发送超过次数限”。当天不要调用/message/all 全量发送接口；

关于推送量的说明可以参考【vivo推送常见问题汇总】

2.vivo服务器地址

https://api-push.vivo.com.cn

3.公共传入参数

HTTP Header中（推送鉴权接口除外）。

属性名字	类型	是否必填Y/N	描述
authToken	string	Y	当鉴权成功时会返回该字段，推送消息时需要提供authToken，有效期默认为1天，过期后无法使用

4.高级特性extra

注意：回执目前仅支持单推接口且是正式消息 

属性名字	类型	是否必填Y/N	描述
callback	string	Y	第三方接收回执的http接口，最大长度128个字符
callback.param	string	N	第三方自定义回执参数，最大长度64个字符

二．接口定义

1.鉴权

1.1推送鉴权接口

接口说明

要想调用PUSH接口，任何接入方都要有个鉴权操作。其他接口header中必须携带该参数。

接口返回的参数authToken，一个appId可对应多个token，24小时过期，业务方做中心缓存，1-2小时更新一次。

限制：频率限制，单个app 10次/s。超频返回错误码10094。

访问方式

URL	编码方式	协议	method	Content-Type
/message/auth	Utf-8	https	POST	application/json
Curl e.g.：curl -X POST -H     ‘Content-Type:application/json’ -d   ‘${your_request_body}’     https://api-push.vivo.com.cn/message/authRequest body e.g.:{        “appId”:10004,          “appKey”:”25509283-3767-4b9e-83fe-b6e55ac6243e”,        “timestamp”:1501484120000,          “sign”:”8424f52fd5eaedc16474e4f702d230d2″}Response body e.g.:http status 200:业务成功：{         “result”:   0,         “desc”:   “请求成功”,        “authToken”:     “24ojds98fu3jqrioeu982134jieds9fq43u09uaf”}业务异常：{         “result”:   xxx,         “desc”:   “xxx不合法”}http status 500：Internet server error!

接口定义

输入参数：

属性名字	类型	是否必填Y/N	描述
appId	int	Y	用户申请推送业务时生成的appId
appKey	string	Y	用户申请推送业务时获得的appKey
timestamp	long	Y	Unix时间戳 做签名用，单位：毫秒，且在vivo服务器当前utc时间戳前后十分钟区间内。
sign	string	Y	签名 使用MD5算法，字符串trim后拼接（appId+appKey+timestamp+appSecret），然后通过MD5加密得到的值（字母小写）

 输出参数：

属性名字	类型	描述
result	int	接口调用是否成功的状态码 0成功，非0失败
desc	string	文字描述接口调用情况
authToken	string	当鉴权成功时才会有该字段，推送消息时，需要提供authToken，有效期默认为1天，过期后无法使用。一个appId可对应多个token，24小时过期，业务方做中心缓存，1-2小时更新一次。

2.单播

2.1单推接口

接口说明

接入方携带消息内容以及用户regId（或alias）进行通知消息推送。针对每个用户发送不同的通知。

使用场景：如物流、订单状态、游戏预约状态、行程状态、聊天（如微信、评论）等。

限制：根据客户端SDK订阅数自动配置，可发送的用户总量可以在开发者后台查看。

访问方式

URL	编码方式	协议	method	Content-Type
/message/send	Utf-8	https	POST	application/json
Curl e.g.：curl -X POST -H ‘authToken:${your_auth_token}’   -H     ‘Content-Type:application/json’  -d     ‘${your_request_body}’   https://api-push.vivo.com.cn/message/sendRequest body e.g.:{      “appId”:10004,      “regId”:”12345678901234567890123″,      “notifyType”:1,      “title”:”标题1″,      “content”:”内容1″,      “timeToLive”:86400,      “skipType”:2,          “skipContent”:”http://www.vivo.com”,        “networkType”:”1″,      “clientCustomMap”:{              “key1″:”vlaue1”,              “key2″:”vlaue2”    },    “extra”:{              “callback”:”http://www.vivo.com”,              “callback.param”:”vivo”    },          “requestId”:”25509283-3767-4b9e-83fe-b6e55ac6b123″}Response body e.g.:http status 200:业务成功：{         “result”:   0,         “desc”:   “请求成功”,”taskId”:   “121397329”}推送使用的regid或alias不合法，无法送达：{        “result”: 10302,        “desc”: “regId 不合法”,        “invalidUser”: {            “status”: 1,            “userid”:   “15638535410301000000001”      }}业务异常：{         “result”:   xxx,”desc”: “xxx不合法”} http status 500：Internet server error!

接口定义

输入参数：

intent uri

属性名字	类型	是否必填Y/N	描述
appId	int	Y	用户申请推送业务时生成的appId，用于与获取authToken时传递的appId校验，一致才可以推送
regId	string	N	应用订阅PUSH服务器得到的id   长度23个字符（regId，alias 两者需一个不为空，当两个不为空时，取regId）
alias	string	N	别名 长度不超过40字符（regId，alias两者需一个不为空，当两个不为空时，取regId）
notifyType	int	Y	通知类型 1:无，2:响铃，3:振动，4:响铃和振动
title	string	Y	通知标题（用于通知栏消息） 最大20个汉字（一个汉字等于两个英文字符，即最大不超过40个英文字符）
content	string	Y	通知内容（用于通知栏消息） 最大50个汉字（一个汉字等于两个英文字符，即最大不超过100个英文字符）
timeToLive	int	N	消息保留时长 单位：秒，取值至少60秒，最长7天。当值为空时，默认一天
skipType	int	Y	点击跳转类型 1：打开APP首页 2：打开链接 3：自定义 4:打开app内指定页面
skipContent	string	N	跳转内容 跳转类型为2时，跳转内容最大1000个字符，跳转类型为3或4时，跳转内容最大1024个字符，skipType传3需要在onNotificationMessageClicked回调函数中自己写处理逻辑。关于skipContent的内容可以参考【vivo推送常见问题汇总】
networkType	int	N	网络方式 -1：不限，1：wifi下发送，不填默认为-1
classification	int	N	消息类型 0：运营类消息，1：系统类消息。不填默认为0
clientCustomMap	JSON Object	N	客户端自定义键值对 自定义key和Value键值对个数不能超过10个，且长度不能超过1024字符, key和Value键值对总长度不能超过1024字符。app可以按照客户端SDK接入文档获取该键值对
extra	JSON Object	N	高级特性（详见目录：一.公共——5.高级特性 extra）
requestId	string	Y	用户请求唯一标识 最大64字符
pushMode	int	N	推送模式 0：正式推送；1：测试推送，不填默认为0（测试推送，只能给web界面录入的测试用户推送；审核中应用，只能用测试推送）
auditReview	JSON Array	N	第三方审核结果，参见：基于第三方审核结果的消息推送

 输出参数：

属性名字	类型	描述
result	int	接口调用是否成功的状态码 0成功，非0失败
desc	string	文字描述接口调用情况
taskId	string	任务编号
invalidUser	JSON Object	非法用户信息，包括status和userid，userid为接入方传的regid或者alias，status有三种情况：1.userId不存在；2.卸载或者关闭了通知；3.七天不在线；4.非测试用户

3.广播

3.1保存群推消息公共体接口

接口说明

同一条信息覆盖多个用户。此接口需与批量推送用户接口3.2配套使用，批量推送接口用此接口生成taskId批量发送用户。

使用场景：活动、系统升级提醒等。

限制：默认根据客户端SDK订阅数自动配置。

访问方式

URL	编码方式	协议	method	Content-Type
/message/saveListPayload	Utf-8	https	POST	application/json
Curl e.g.：curl -X POST  -H   ‘authToken:${your_auth_token}’ -H     ‘Content-Type:application/json’    -d   ‘${your_request_body}’   https://api-push.vivo.com.cn/message/saveListPayloadRequest body e.g.:{        “appId”:10004,        “title”:”标题1″,        “content”:”内容1″,        “notifyType”:1,        “timeToLive”:86400,        “skipType”:2,          “skipContent”:”http://www.vivo.com”,        “networkType”:”1″,        “clientCustomMap”:{              “key1″:”vlaue1”,              “key2″:”vlaue2”},          “requestId”:”25509283-3767-4b9e-83fe-b6e55ac6b123″}Response body e.g.:http status 200:业务成功：{         “result”:   0,         “desc”:   “请求成功”,”taskId”:   “342982232646905856”}业务异常：{         “result”:   xxx,”desc”: “xxx不合法”}http status 500：Internet server error!

接口定义

输入参数：

属性名字	类型	是否必填Y/N	描述
appId	int	Y	用户申请推送业务时生成的appId，用于与获取authToken时传递的appId校验，一致才可以推送
notifyType	int	Y	通知类型 1:无，2:响铃，3:振动，4:响铃和振动
title	string	Y	通知标题（用于通知栏消息） 最大20个汉字（一个汉字等于两个英文字符，一个表情占一个字符，即最大不超过40个英文字符）
content	string	Y	通知内容（用于通知栏消息） 最大50个汉字（一个汉字等于两个英文字符，一个表情占一个字符，即最大不超过100个英文字符）
timeToLive	int	N	消息保留时长 单位：秒，取值至少900秒，最长7天。当值为空时，默认一天。
skipType	int	Y	点击跳转类型 1：打开APP首页 2：打开链接 3：自定义 4:打开app内指定页面
skipContent	string	N	跳转内容 跳转类型为2时，跳转内容最大1000个字符，跳转类型为3或4时，跳转内容最大1024个字符，skipType传3需要在onNotificationMessageClicked回调函数中自己写处理逻辑。关于skipContent的内容可以参考【vivo推送常见问题汇总】 pushSDK版本号：480以上，不在支持skipType=3，自定义跳转统一使用skipType=4，详见【vivo推送常见问题汇总】中API接入问题的Q11中的intent uri示例。
networkType	int	N	网络方式 -1：不限，1：wifi下发送，不填默认为-1
classification	int	N	消息类型 0：运营类消息，1：系统类消息。不填默认为0
clientCustomMap	JSON Object	N	客户端自定义键值对 自定义key和Value键值对个数不能超过10个，且长度不能超过1024字符, key和Value键值对总长度不能超过1024字符。app可以按照客户端SDK接入文档获取该键值对。
requestId	string	Y	用户请求唯一标识 最大64字符
auditReview	JSON Array	N	第三方审核结果，参见：基于第三方审核结果的消息推送

输出参数：

属性名字	类型	描述
result	int	接口调用是否成功的状态码 0成功，非0失败
desc	string	文字描述接口调用情况
taskId	string	任务编号

3.2批量推送用户接口

接口说明

批量发送用户。此接口与群推消息接口3.1配套使用，首先通过群推消息接口3.1返回taskId，然后此接口带上taskId批量发送用户，可以根据regIds或者aliases分批调用。每次调用时，regIds或者aliases的个数必须大于等于2，小于等于1000。

限制：根据客户端SDK订阅数自动配置，可发送的用户总量可以在开发者后台查看。

访问方式

URL	编码方式	协议	method	Content-Type
/message/pushToList	Utf-8	https	POST	application/json
Curl e.g.：   curl -X POST -H   ‘authToken:${your_auth_token}’ -H       ‘Content-Type:application/json’  -d   ‘${your_request_body}’   https://api-push.vivo.com.cn/message/pushToListRequest body e.g.:{      “appId”:10004,      “regIds”:[              “12345678901234567890121”,              “12345678901234567890122”        ],          “taskId”:”342982232646905856″,          “requestId”:”25509283-3767-4b9e-83fe-b6e55ac6b123″}Response body e.g.:http status 200:业务成功：{    “requestId”: “25509283-3767-4b9e-83fe-b6e55ac6b123”,    “result”: 0,    “desc”: “请求成功”,    “invalidUsers”: [{        “status”: 1,        “userid”: “12345678901234567890121”    }]} 业务异常：{         “result”:   xxx,         “desc”:   “xxx不合法”}http status 500：Internet server error!

接口定义

输入参数：

属性名字	类型	是否必填Y/N	描述
appId	int	Y	用户申请推送业务时生成的appId，用于与获取authToken时传递的appId校验，一致才可以推送
regIds	string[]	N	regId列表 个数大于等于2，小于等于1000（regIds，aliases   两者需一个不为空，两个不为空，取regIds）
aliases	string[]	N	别名列表个数大于等于2，小于等于1000，长度不超过40字符（regIds，aliases 两者需一个不为空，两个不为空，取regIds）
taskId	string	Y	公共消息任务号，取saveListPayload返回的taskId
requestId	string	Y	请求唯一标识，最大64字符
pushMode	int	N	推送模式 0：正式推送；1：测试推送，不填默认为0（测试推送，只能给web界面录入的测试用户推送；审核中应用，只能用测试推送）

输出参数：

属性名字	类型	描述
result	int	接口调用是否成功的状态码 0成功，非0失败
desc	string	文字描述接口调用情况
invalidUser	JSON Object	非法用户信息，包括status和userid，userid为接入方传的regid或者alias，status有三种情况：1.userId不存在；2.卸载或者关闭了通知；3.七天不在线；4.非测试用户

3.3全量发送接口

接口说明

向所有设备推送某条消息。

使用场景：活动、系统升级提醒等。

限制：默认是每个app每日可发送一条。

访问方式

URL	编码方式	协议	method	Content-Type
/message/all	Utf-8	https	POST	application/json
Curl e.g.：curl -X POST -H     ‘authToken:${your_auth_token}’ -H     ‘Content-Type:application/json’  -d ‘${your_request_body}’     https://api-push.vivo.com.cn/message/allRequest body e.g.:{        “appId”:10004,        “notifyType”:1,        “title”:”标题1″,        “content”:”内容1″,        “timeToLive”:86400,        “skipType”:2,          “skipContent”:”http://www.vivo.com”,        “networkType”:”1″,      “clientCustomMap”:{              “key1″:”vlaue1”,              “key2″:”vlaue2”      },          “requestId”:”25509283-3767-4b9e-83fe-b6e55ac6b123″}Response body e.g.:http status 200:业务成功：{         “result”:   0,         “desc”:   “请求成功”,”taskId”:     “12139732”}业务异常：{         “result”:   xxx,”desc”: “xxx不合法”}http status 500：Internet server error!

接口定义

输入参数：

属性名字	类型	是否必填Y/N	描述
appId	int	Y	用户申请推送业务时生成的appId，用于与获取authToken时传递的appId校验，一致才可以推送
notifyType	int	Y	通知类型 1:无，2:响铃，3:振动，4:响铃和振动
title	string	Y	通知标题（用于通知栏消息） 最大20个汉字（一个汉字等于两个英文字符，一个表情占一个字符，即最大不超过40个英文字符）
content	string	Y	通知内容（用于通知栏消息） 最大50个汉字（一个汉字等于两个英文字符，一个表情占一个字符，即最大不超过100个英文字符）
timeToLive	int	N	消息保留时长 单位：秒，取值至少900秒，最长7天。当值为空时，默认一天
skipType	int	Y	点击跳转类型 1：打开APP首页 2：打开链接 3：自定义 4:打开app内指定页面
skipContent	string	N	跳转内容 跳转类型为2时，跳转内容最大1000个字符，跳转类型为3或4时，跳转内容最大1024个字符，skipType传3需要在onNotificationMessageClicked回调函数中自己写处理逻辑。关于skipContent的内容可以参考【vivo推送常见问题汇总】 pushSDK版本号：480以上，不在支持skipType=3，自定义跳转统一使用skipType=4，详见【vivo推送常见问题汇总】中API接入问题的Q11中的intent uri示例。
networkType	int	N	网络方式 -1：不限，1：wifi下发送，不填默认为-1
classification	int	N	消息类型 0：运营类消息，1：系统类消息。不填默认为0
clientCustomMap	JSON Object	N	客户端自定义键值对 自定义key和Value键值对个数不能超过10个，且长度不能超过1024字符, key和Value键值对总长度不能超过1024字符。app可以按照客户端SDK接入文档获取该键值对
requestId	string	Y	用户请求唯一标识 最大64字符
auditReview	JSON Array	N	第三方审核结果，参见：基于第三方审核结果的消息推送

输出参数：

属性名字	类型	描述
result	int	接口调用是否成功的状态码 0成功，非0失败
desc	string	文字描述接口调用情况
taskId	string	任务编号

3.4获取消息推送的统计值接口

接口说明

获取taskId对应的统计信息，taskIds最多100个。 注意：查询的消息类型 【群推送消息/列表推消息】

访问方式

URL	编码方式	协议	method	Content-Type
/report/getStatistics	Utf-8	https	GET	application/json
Curl e.g.：   curl -X GET  -H   ‘authToken:${your_auth_token}’ -H       ‘Content-Type:application/json’     https://api-push.vivo.com.cn/report/getStatistics?appId=10004&taskIds=123138209,23498102,3240910940,109283018Request body e.g.:Response body e.g.:http status 200:业务成功：{        “result”:0,        “desc”:”请求成功”,      “statistics”:[    {          “taskId”:   “298475091219”,          “target”: 10000,          “valid”: 9500,          “send”: 9000,          “receive”: 9000,          “display”: 8000,          “click”: 200,          “targetInvalid”:   200,          “targetUnSub”:   200,          “targetInActive”: 100,          “covered”: 200,          “controlled”:   200,          “targetOffline”:   100    },    {          “taskId”:   “298475091220”,          “target”: 10000,          “valid”: 9500,          “send”: 9000,          “receive”: 9000,          “display”: 8000,          “click”: 200,          “targetInvalid”:   200,          “targetUnSub”:   200,            “targetInActive”: 100,          “covered”: 200,          “controlled”:   200,          “targetOffline”:   100    }]}业务异常：{         “result”:   xxx,         “desc”:   “xxx不合法”}http status 500：Internet server error!

接口定义

输入参数：

属性名字	类型	是否必填Y/N	描述
appId	int	Y	用户申请推送业务时生成的appId，用于与获取authToken时传递的appId校验，一致才可以推送
taskIds	string	Y	查询的任务列表taskIds 用，分隔开 e.g.:   “234567,234568”

输出参数：

属性名字	类型	描述
result	int	接口调用是否成功的状态码 0成功，非0失败
desc	string	文字描述接口调用情况
taskId	string	任务号
target	long	目标总数
targetInvalid	long	不存在的用户总数，根据id找不到任何信息
targetUnSub	long	解订阅的用户总数，用户已卸载或者客户端主动调用turnOffPush()解订阅
targetInActive	long	14天不在网的用户数，手机14天没有联网，信息被后台删除
valid	long	有效目标总数
covered	long	被覆盖的用户消息总数，群推、全推、标签推消息属于营销消息，会被覆盖
controlled	long	被管控的用户消息总数，例如接收的群推消息总数一天超过5条
targetOffline	long	推送后不在线的用户数，截止到当前统计时间为止，没有联网的用户数，呈下降趋势
send	long	下发总数
receive	long	到达总数
display	long	展示总数
click	long	点击总数

4.回执

4.1消息送达回执

接口说明

vivo推送服务器将已送达或和对应设备的alias或者regId通过调用第三方设置的回调，http接口传给开发者服务器。仅单播支持回执（每次调用后，推送服务器会清空这些数据。）

使用：

① 发送消息接口设置扩展参数extra（详见目录：一.公共——5.高级特性 extra）, 包含callback、callback.param。

② vivo推送服务器调用第三方设置的callback url接口。 

③ 字段ackType  【达回执类型】目前只有到达回执ackType=0

访问方式

URL	编码方式	协议	method	Content-Type
第三方设置的callback url（详见：高级特性 extra）	Utf-8	https/http	POST	application/json
Curl e.g.：   curl -X POST -H   ‘Content-Type:application/json’ -d     ‘${your_request_body}’   https://callbackurlRequest body e.g.:{      “taskId1”:{              “param”:”param1″,              “targets”:”alias1,alias2,alias3″，              “ackTime”:1612776166257    },      “taskId2”:{              “param”:”param2″,              “targets”:”regId1,regId2,regId3″，              “ackTime”:1612776166258    }}Response body e.g.:http status 200:http status 500：Internet server error!

接口定义

输入参数：

属性名字	类型	是否必填Y/N	描述
taskId	string	Y	任务编号
param	string	Y	开发者上传的自定义参数值
targets	string	Y	一批alias或者regId列表，之间是用逗号分割
ackTime	long	N	回执到达时间，毫秒时间戳

 回执流程

设备在线：

设备不在线：

5.标签管理

5.1 新增标签接口

接口说明

为应用方增加标签，用于后续标签推送。

访问方式

URL	编码方式	协议	method	Content-Type
/tag/add	Utf-8	https	POST	application/json
Curl e.g.：   curl -X POST   -H   ‘authToken:${your_auth_token}’ -H     ‘Content-Type:application/json’  -d     ‘${your_request_body}’ https://host:port/tag/addRequest   body e.g.:{          “appId”:10004,          “name”:   “shenzhen”,          “desc”:”深圳用户标签”,       “group”:”city”}Response body   e.g.:http status   200:{         “result”: 0,         “desc”: “成功”,}业务异常：{         “result”: xxx,”desc”:     “xxx”}http status   500：Internet   server error!

接口定义

输入参数：

属性名字	类型	是否必填Y/N	描述
appId	int	Y	用户申请推送业务时生成的appId，用于与获取authToken时传递的appId校验，一致才可以推送
name	string	Y	标签名称
desc	string	N	标签描述
group	string	N	标签分类名

输出参数：

属性名字	类型	描述
result	int	接口调用是否成功的状态码 0成功，非0失败
desc	string	文字描述接口调用情况

5.2 更新单个标签接口

接口说明

更新一个标签的信息,更新标签名字、描述、所属分类。

访问方式

URL	编码方式	协议	method	Content-Type
/tag/update	Utf-8	https	POST	application/json
Curl e.g.：   curl -X POST   -H   ‘authToken:${your_auth_token}’ -H     ‘Content-Type:application/json’  -d ‘${your_request_body}’       https://host:port/tag/updateRequest   body e.g.:{           “appId”:10004,           “oldName”:”shenzhen”,           “newName”:”shenzhenbaoan”}Response body   e.g.:http status   200:{    “result”:   0,    “desc”:   “成功”}业务异常：{         “result”: xxx,”desc”:     “xxx”}http status   500：Internet   server error!

接口定义

输入参数：

属性名字	类型	是否必填Y/N	描述
appId	int	Y	用户申请推送业务时生成的appId，用于与获取authToken时传递的appId校验，一致才可以推送
oldName	string	Y	旧标签名称
newName	string	Y	新标签名称
desc	string	N	更新标签描述
group	string	N	更新标签所属分类

输出参数：

属性名字	类型	描述
result	int	接口调用是否成功的状态码 0成功，非0失败
desc	string	文字描述接口调用情况

5.3 给标签添加用户设备接口

接口说明

给标签添加用户设备信息，单次不超过1000个设备。

访问方式

URL	编码方式	协议	method	Content-Type
/tag/addMembers	Utf-8	https	POST	application/json
Curl e.g.：   curl -X POST   -H   ‘authToken:${your_auth_token}’ -H ‘Content-Type:application/json’      -d ‘${your_request_body}’   https://host:port/tag/addMembersRequest   body e.g.:{         “appId”:10004,         “name”:”shenzhen”,         “type”:1,             “ids”:[“15549635570031000000216″,”15549635980031000001086”]}Response body   e.g.:http status   200:{    “result”:   0,    “desc”:   “success”,    “data”: [          {                “status”: 1,                “userid”:   “00000000000000000000004”          },          {                “status”: 1,                “userid”:   “00000000000000000000005”          }    ]}业务异常：{         “result”: xxx,”desc”:     “xxx”}http status   500：Internet   server error!

接口定义

输入参数：

属性名字	类型	是否必填Y/N	描述
appId	int	Y	用户申请推送业务时生成的appId，用于与获取authToken时传递的appId校验，一致才可以推送
name	string	Y	标签名字
type	int	Y	用户类型：1是regId   ,2是别名
ids	JSON Array	Y	用户id

输出参数：

属性名字	类型	描述
result	int	接口调用是否成功的状态码 0成功，非0失败
desc	string	文字描述接口调用情况
data	JSON Array	userid是非法用户id，status有3种状态：1是用户不存在，2是用户push开关关闭，3是用户14天未联网。

5.4 移除标签中的用户设备接口

接口说明

移除标签中的用户设备信息，单次不超过1000个设备。

访问方式

URL	编码方式	协议	method	Content-Type
/tag/removeMembers	Utf-8	https	POST	application/json
Curl e.g.：   curl -X POST   -H   ‘authToken:${your_auth_token}’ -H     ‘Content-Type:application/json’  -d ‘${your_request_body}’       https://host:port/tag/removeMembersRequest   body e.g.:{         “appId”:10004,         “name”:”shenzhen”,         “type”:1,         “ids”:[“15554239157791000000009″,”15554239157791000000008”]}Response body   e.g.:http status   200:{    “result”:   0,    “desc”:   “success”,    “data”: [          {                “status”: 1,                “userid”:   “15554239157791000000008”          },          {                “status”: 1,                “userid”:   “15554239157791000000009”          }    ]}业务异常：{         “result”: xxx,         “desc”:     “xxx”}http status   500：Internet   server error!

接口定义

输入参数：

属性名字	类型	是否必填Y/N	描述
appId	int	Y	用户申请推送业务时生成的appId，用于与获取authToken时传递的appId校验，一致才可以推送
name	string	Y	标签名字
type	int	Y	用户类型：1是regId   ,2是别名
ids	JSON Array	Y	用户id

输出参数：

属性名字	类型	描述
result	int	接口调用是否成功的状态码 0成功，非0失败
desc	string	文字描述接口调用情况
data	JSON Array	userid是非法用户id，status有3种状态：1是用户不存在，2是用户push开关关闭，3是用户14天未联网。

6.标签分类管理

6.1 新增标签分类接口

接口说明

为应用方增加标签分类，用于后续标签分类管理。

访问方式

URL	编码方式	协议	method	Content-Type
/tagGroup/add	Utf-8	https	POST	application/json
Curl e.g.：   curl -X POST   -H   ‘authToken:${your_auth_token}’ -H     ‘Content-Type:application/json’  -d   ‘${your_request_body}’ https://host:port/tagGroup/addRequest body e.g.:{    “appId”:10004,    “name”:   “guangzhou”,     “type”:”city”}Response body   e.g.:http status   200:{         “result”: 0,         “desc”: “成功”,}业务异常：{         “result”: xxx,         “desc”:     “xxx”}http status   500：Internet   server error!

接口定义

输入参数：

属性名字	类型	是否必填Y/N	描述
appId	int	Y	用户申请推送业务时生成的appId，用于与获取authToken时传递的appId校验，一致才可以推送
name	string	Y	标签分类名称
type	int	Y	标签分类类型：1是普通标签，2是互斥标签
desc	string	N	标签分类描述

输出参数：

属性名字	类型	描述
result	int	接口调用是否成功的状态码 0成功，非0失败
desc	string	文字描述接口调用情况

6.2 更新单个标签分类接口

接口说明

更新一个标签分类的信息，包括标签分类名称和描述。

访问方式

URL	编码方式	协议	method	Content-Type
/tagGroup/update	Utf-8	https	POST	application/json
Curl e.g.：   curl -X POST   -H   ‘authToken:${your_auth_token}’ -H     ‘Content-Type:application/json’  -d ‘${your_request_body}’       https://host:port/tagGroup/updateRequest   body e.g.:{      “appId”:10004,      “oldName”: “city”,      “newName”:   “province”,      “desc”:   “这是更新后的描述”}Response body   e.g.:http status   200:{    “result”:   0,    “desc”:   “成功”}业务异常：{         “result”: xxx,         “desc”:     “xxx”}http status   500：Internet   server error!

接口定义

输入参数：

属性名字	类型	是否必填Y/N	描述
appId	int	Y	用户申请推送业务时生成的appId，用于与获取authToken时传递的appId校验，一致才可以推送
oldName	string	Y	旧标签分类名称
newName	string	Y	新标签分类名称
desc	string	N	新标签分类的描述

输出参数：

属性名字	类型	描述
result	int	接口调用是否成功的状态码 0成功，非0失败
desc	string	文字描述接口调用情况

6.3 添加标签到标签分类接口

接口说明

把标签添加进标签分类里面，一次可添加一个或者多个标签，最多不超过100个。

访问方式

URL	编码方式	协议	method	Content-Type
/tagGroup/addToGroup	Utf-8	https	POST	application/json
Curl e.g.：   curl -X POST   -H   ‘authToken:${your_auth_token}’ -H     ‘Content-Type:application/json’  -d ‘${your_request_body}’       https://host:port/tagGroup/addToGroupRequest   body e.g.:{         “appId”:10004,         “name”:”city”,         “tagList”:[“shenzhen”,”guangzhou”]}Response body   e.g.:http status   200:{    “result”:   0,    “desc”:   “成功”}业务异常：{         “result”: xxx,”desc”:     “xxx”}http status   500：Internet   server error!

接口定义

输入参数：

属性名字	类型	是否必填Y/N	描述
appId	int	Y	用户申请推送业务时生成的appId，用于与获取authToken时传递的appId校验，一致才可以推送
name	string	Y	标签分类名称
tagList	JSON Array	Y	一个或多个标签

输出参数：

属性名字	类型	描述
result	int	接口调用是否成功的状态码 0成功，非0失败
desc	string	文字描述接口调用情况

7.标签组合管理

7.1 新增标签组合接口

接口说明

为应用方增加标签组合。 一个标签组合由多个标签组成。

访问方式

URL	编码方式	协议	method	Content-Type
/tagSegment/add	Utf-8	https	POST	application/json
Curl e.g.：   curl -X POST   -H   ‘authToken:${your_auth_token}’ -H     ‘Content-Type:application/json’  -d     ‘${your_request_body}’ https://host:port/tagSegment/addRequest   body e.g.:{    “appId”:10004,    “name”:   “segment1”,          “expression”:{                   “notTags”:[“shenzhen”],                  “andTags”:[],                  “orTags”:[]          }}Response body   e.g.:http status   200:{         “result”: 0,         “desc”: “成功”,}业务异常：{         “result”: xxx,”desc”:     “xxx”}http status   500：Internet   server error!

接口定义

输入参数：

属性名字	类型	是否必填Y/N	描述
appId	int	Y	用户申请推送业务时生成的appId，用于与获取authToken时传递的appId校验，一致才可以推送
name	string	Y	标签组合名称
expression	JSON Object	Y	标签组合表达式：包含三种JSON数组：notTags表示非操作、andTags表示与操作，orTags表示或操作，例如：”tagExpression”:{                 “notTags”:[“琴”,”棋”,”书”,”画”],                  “andTags”:[“深圳”,”广东”],                  “orTags”:[“本科生”,”研究生”]          }可以表示为，不会琴、棋、书、画的广东省深圳市的本科生或研究生的所有用户。当然这些标签需要先在平台或者接口创建后再使用。

输出参数：

属性名字	类型	描述
result	int	接口调用是否成功的状态码 0成功，非0失败
desc	string	文字描述接口调用情况

7.2 更新单个标签组合接口

接口说明

更新一个标签组合的信息

访问方式

URL	编码方式	协议	method	Content-Type
/tagSegment/update	Utf-8	https	POST	application/json
Curl e.g.：   curl -X POST   -H   ‘authToken:${your_auth_token}’ -H     ‘Content-Type:application/json’  -d ‘${your_request_body}’       https://host:port/tagSegment/updateRequest   body e.g.:{            “appId”:10004,           “oldName”:”segment1″,           “newName”:”segment2″,”expression”:   {                    “orTags”: [“shenzhen”],                    “andTags”:     [],                    “notTags”: []    }}Response body   e.g.:http status   200:{    “result”:   0,    “desc”:   “成功”}业务异常：{         “result”: xxx,”desc”:     “xxx”}http status   500：Internet   server error!

接口定义

输入参数：

属性名字	类型	是否必填Y/N	描述
appId	int	Y	用户申请推送业务时生成的appId，用于与获取authToken时传递的appId校验，一致才可以推送
oldName	string	Y	旧标签组合名称
newName	string	Y	新标签组合名称
expression	JSON Object	N	新标签组合表达式：包含三种JSON数组：notTags表示非操作、andTags表示与操作，orTags表示或操作，例如：”tagExpression”:{                 “notTags”:[“琴”,”棋”,”书”,”画”],                  “andTags”:[“深圳”,”广东”],                  “orTags”:[“本科生”,”研究生”]          }可以表示为，不会琴、棋、书、画的广东省深圳市的本科生或研究生的所有用户。当然这些标签需要先在平台或者接口创建后再使用。

输出参数：

属性名字	类型	描述
result	int	接口调用是否成功的状态码 0成功，非0失败
desc	string	文字描述接口调用情况

8.标签推

8.1标签推接口

接口说明

接入方携带消息内容、标签信息进行通知消息推送。

  标签个数的限制：20个

访问方式

URL	编码方式	协议	method	Content-Type
/message/tagPush	Utf-8	https	POST	application/json
Curl e.g.：curl -X POST   -H   ‘authToken:${your_auth_token}’ -H     ‘Content-Type:application/json’  -d ‘${your_request_body}’       https://host:port/message/tagPushRequest   body e.g.:{          “appId”:10004,          “tagExpression”:{                   “notTags”:[“tag1″,”       tag2″,”tag3″,” tag4″],                  “andTags”:[“tag5″,”   tag6″],                  “orTags”:[“tag7″,”tag8”]          },  “segmentName”:   “组合名”,      “notifyType”: 4,    “title”:   “123”,      “content”: “456”,      “timeToLive”: 86400,      “skipType”: 1,      “skipContent”:   “assda”,      “networkType”: -1,      “requestId” :       “25509283-3767-4b9e-83fe-b6e55ac6b123”}Response body   e.g.:http status   200:业务成功：{    “result”:   0,    “desc”:   “请求成功”,    “taskId”:     “2199912448”}业务异常：{         “result”: xxx,”desc”:   “xxx不合法”}http status   500：Internet   server error!

接口定义

输入参数：

属性名字	类型	是否必填Y/N	描述
appId	int	Y	用户申请推送业务时生成的appId，用于与获取authToken时传递的appId校验，一致才可以推送
tagExpression	JSON Object	Y	标签表达式。包含三种JSON数组：notTags表示非操作、andTags表示与操作，orTags表示或操作，例如：”tagExpression”:{                 “notTags”:[“琴”,”棋”,”书”,”画”],                  “andTags”:[“深圳”,”广东”],                  “orTags”:[“本科生”,”研究生”]          }可以表示为，不会琴、棋、书、画的广东省深圳市的本科生或研究生的所有用户。当然这些标签需要先在平台或者接口创建后再使用。
segmentName	string	N	之前创建好的组合名，如果传递组合名，默认用组合名推送，否则如果传递tagExpression，按照标签表达式推送
notifyType	int	Y	通知类型 1:无，2:响铃，3:振动，4:响铃和振动
title	string	Y	通知标题（用于通知栏消息） 最大20个汉字（一个汉字等于两个英文字符，一个表情占一个字符，即最大不超过40个英文字符）
content	string	Y	通知内容（用于通知栏消息） 最大50个汉字（一个汉字等于两个英文字符，一个表情占一个字符，即最大不超过100个英文字符）
timeToLive	int	N	消息保留时长 单位：秒，取值至少60秒，最长7天。当值为空时，默认一天
skipType	int	Y	点击跳转类型 1：打开APP首页 2：打开链接 3：自定义 4:打开app内指定页面
skipContent	string	N	跳转内容 跳转类型为2时，跳转内容最大1000个字符，跳转类型为3或4时，跳转内容最大1024个字符，skipType传3需要在onNotificationMessageClicked回调函数中自己写处理逻辑。pushSDK版本号：480以上，不在支持skipType=3，自定义跳转统一使用skipType=4，详见【vivo推送常见问题汇总】中API接入问题的Q11中的intent uri示例。
networkType	int	N	网络方式 -1：不限，1：wifi下发送，不填默认为-1
classification	int	N	消息类型 0：运营类消息，1：系统类消息。不填默认为0
clientCustomMap	JSON Object	N	客户端自定义键值对 自定义key和Value键值对个数不能超过10个，且长度不能超过1024字符, key和Value键值对总长度不能超过1024字符。
requestId	string	Y	用户请求唯一标识 最大64字符
auditReview	JSON Array	N	第三方审核结果，参见：基于第三方审核结果的消息推送

输出参数：

属性名字	类型	描述
result	int	接口调用是否成功的状态码 0成功，非0失败
desc	string	文字描述接口调用情况
taskId	string	任务编号

9.消息状态查询

9.1消息状态查询

接口说明

由于目前只返回审计相关信息，单推没有同步返回消息审计状态，其他类型的推送有同步返回。所以可通过调用此接口传递消息id，查询消息的状态。目前有调用频率限制，单个app 1次/s, 建议一批类似的消息体查询一次。

使用：

① 发送消息后查询消息的状态(延时在一分钟内)。

②‘审计通过’或 ‘审计不通过的状态还未入库’，返回 【消息状态未知】，审计不通过状态已入库，返回【消息包含敏感词】

访问方式

URL	编码方式	协议	method	Content-Type
https://api-push.vivo.com.cn/search/msgStatus	Utf-8	https/http	GET	application/json
Curl e.g.：   curl -X GET -H   ‘authToken:${your_auth_token}’ -H   ‘Content-Type:application/json’   -d     ‘${your_request_body}’ https://api-push.vivo.com.cn/search/msgStatus?appId=10004&taskIds=taskId1,taskId2Request body e.g.:{    “result”:   0,    “desc”:   “success”,    “data”: [          {                “taskId”: taskId1,                “desc”: “消息包含敏感词”          },          {                ” taskId “: taskId2,                “desc”: “消息状态未知”          }    ]}Response body e.g.:http status 200:http status 500：Internet server error!

接口定义

输入参数：

属性名字	类型	是否必填Y/N	描述
appId	int	Y	用户申请推送业务时生成的appId，用于与获取authToken时传递的appId校验，一致才可以推送
taskIds	string	Y	由多个taskId组成的字符串，多个taskId之间用逗号分隔，一次最多查询100个

10.查询失效id

10.1失效id查询

接口说明

由于用户卸载、客户端主动调用turnOffPush()解订阅、设备14天不联网还有一部分历史原因，可能造成推送的id无效。开发者可以根据推送时返回的InvalidUser对失效id做标记或者清除处理，或者单独查询本接口，将无效的id过滤，避免占用推送额度。

使用：

① 传递要查询的id，以及id的类型，后台根据保存的id，返回无效的id。

② 建议在推送低峰期，例如晚上或者凌晨调用，将保存的id一批批查询，避免影响应用的推送性能。勿高频调用。

访问方式

URL	编码方式	协议	method	Content-Type
/invalidUser/check	Utf-8	https/http	POST	application/json
Curl e.g.：   curl -X GET -H   ‘authToken:${your_auth_token}’ -H   ‘Content-Type:application/json’   -d     ‘${your_request_body}’ https://api-push.vivo.com.cn/invalidUser/check    Request body e.g.:{      “appId”:10004,      “userType”: 1,      “userIds”: [            “15547801220021000000000”,            “15547801220021000000001”    ]}Response body e.g.:http status 200:{      “invalidUsers”: [            “15547801220021000000000”,            “15547801220021000000001”    ]}http status 500：Internet server error!

接口定义

输入参数：

属性名字	类型	是否必填Y/N	描述
appId	int	Y	用户申请推送业务时生成的appId，用于与获取authToken时传递的appId校验，一致才可以推送
userIds	string[]	Y	用户id数组 ，单次最大100个
userType	int	Y	userId的类型1:regId,2:alias

11.消息回收

11.1 消息回收接口

接口说明

此接口用于回收已发送给用户的消息。通过传递推送的消息id和具体的用户id、用户类型进行消息回收，消息回收接口调用量和调用速度会占用推送量级和推送速度。

限制：由我司运营人员配置。

消息撤回功能是平台提供给开发者紧急处理运营事故的工具，切勿日常频繁使用，以免对用户体验不当影响。

对于推送内容、应用行为等存在违规的，平台将按《vivo推送运营规则》进行相应处罚。

访问方式

URL	编码方式	协议	method	Content-Type
/message/recycle	Utf-8	https	POST	application/json
Curl e.g.：curl -X POST -H ‘   authToken:${your_auth_token}’ -H ‘Content-Type:application/json’  -d ‘${your_request_body}’   https://host:port/message/recycleRequest body e.g.:{         “appId”:10004,         “taskId”:656079923690082304,         “userIds”:[“15762048080021000000007″,”15762048080021000000008″,”15762048080021000000009”],         “userType”:1}Response body e.g.:http status 200:业务成功：{         “result”:   0,         “desc”:   “请求成功”,”invalidUsers”: [         {            “status”: 1,            “userid”:   “15762048080021000000008”         },         {            “status”: 1,            “userid”:   “15762048080021000000008”         }      ]}业务异常：{         “result”:   xxx,”desc”: “xxx不合法”} http status 500：Internet server error!

接口定义

输入参数：

属性名字	类型	是否必填Y/N	描述
appId	int	Y	用户申请推送业务时生成的appId，用于与获取authToken时传递的appId校验，一致才可以推送
taskId	string	Y	单播或广播返回的taskId
userIds	string[]	Y	userId列表。个数大于等于1小于等于100
userType	int	Y	用户类型。1：regId；2：alias

输出参数：

属性名字	类型	描述
result	int	接口调用是否成功的状态码 0成功，非0失败
desc	string	文字描述接口调用情况
invalidUsers	JSON Array	非法用户信息，包括status和userid，userid为接入方传的regid或者alias，status有三种情况：1.userId不存在 2.卸载或者关闭了通知 3.七天不在线

12.应用配置信息查询 

12.1 应用配置信息查询接口

接口说明

此接口用于查询应用配置信息，系统消息总量、运营消息总量、群推消息体总量、配置速度等信息、SDK订阅数。此接口限制了调用频率，请勿频繁调用。

访问方式

URL	编码方式	协议	method	Content-Type
/report/getAppConfig	Utf-8	https	GET	application/json
Curl e.g.：curl -X GET -H ‘authToken:${your_auth_token}’   -H ‘Content-Type:application/json’  -d ‘${your_request_body}’     https://host:port/report/getAppConfig?appId=10004Response body e.g.:http status 200:业务成功：{      “result”: 0,      “desc”: “请求成功”,      “data”: {          “sysMsgCount”: 10000,          “marketMsgCount”: 100000,          “sdkSubCount”: 124,          “speed”: 3000,          “groupMsgBodyCount”: 12000，       “remainSysMsgCount”:1200，       “remainMarketMsgCount”:1300       }}业务异常：{           “result”:   xxx,”desc”:   “xxx不合法”} http status 500：Internet server error!

接口定义

输入参数：

属性名字	类型	是否必填Y/N	描述
appId	int	Y	用户申请推送业务时生成的appId，用于与获取authToken时传递的appId校验，一致才可以推送

输出参数：

属性名字	类型	描述
result	int	接口调用是否成功的状态码 0成功，非0失败
desc	string	文字描述接口调用情况
data	json object	详细内容

data：

属性名字	类型	描述
sysMsgCount	long	系统消息配置量
marketMsgCount	long	运营消息配置量
sdkSubCount	long	sdk订阅数
speed	long	速度配置
groupMsgBodyCount	long	群推消息体配置量
remainSysMsgCount	long	剩余可发送系统消息量级
remainMarketMsgCount	long	剩余可发送运营消息量级

全局公共返回码详解

result	desc
0	请求成功
10000	权限认证失败
10040	资源已达上限，稍后重试
10044	该接口未开放测试模式
10045	应用审核中不可发送正式消息
10050	alias和regId 不能都为空
10051	暂不支持该消息类型
10054	notifyType 不合法
10055	title 不能为空
10056	title 长度不能超过40个字符
10057	content 不能为空
10058	content 长度不能超过100个字符
10059	timeToLive 不合法
10060	skipType 不合法
10061	skipType = 2, skipContent 不能为空
10062	skipType = 2, skipContent 不能超过1000个字符
10063	skipType = 3, skipContent 不能为空
10064	skipType = 3, skipContent 不能超过1024个字符
10065	networkType 不合法
10066	自定义key和Value键值对个数不能超过10个
10067	自定义key和value键值对不合法
10068	skipType = 4, skipContent 不能为空
10069	skipType = 4, skipContent 不能超过1024个字符
10070	运营消息发送量总量超出限制
10071	超出发送时间允许范围
10072	推送速度过快，请稍后再试
10073	系统消息发送量总量超出限制。系统消息量级申请，请参见：系统消息量级说明
10082	系统消息未开通
10084	查询速度过快，请稍后再试
10085	title 或 content 不能为纯表情
10093	获取鉴权码速度过快
10094	鉴权码与请求体对应的appId不一致
10101	消息内容审核不通过
10102	服务器端未知异常
10103	推送内容含敏感信息
10104	请发送正式信息，请检查title、content，不要发送测试内容
10105	推必安内容审核不通过
10106	auditReview参数错误
10110	请配置商业化消息发送频率
10111	今天已发送商业化消息
10112	商业化消息发送超出周次数限制
10150	aliases 和 regIds 不能都为空
10151	taskId 不能为空
10152	taskId 不合法
10153	regIds 个数不在指定范围[2-1000]
10154	aliases 个数不在指定范围[2-1000]
10155	消息不存在或已过期
10200	appId 不能为空
10201	appKey 不能为空
10202	appKey 不合法
10203	timestamp 不能为空
10204	sign 不能为空
10205	appId 不存在
10206	sign 不正确
10207	timestamp 不合法
10250	认证接口超过调用次数限制
10252	批量发送创建消息体超出限制
10253	批量发送regId或alais超过总量限制
10254	全量发送超过次数限制
10301	alias 长度不能超过40个字符
10302	regId 不合法, regId为无效的regId, regId可能已经失效
10304	extra 包含不支持的key
10305	extra callback长度不能超过128个字符
10306	extra callback.param长度不能超过64个字符
10307	alias 不合法
10352	requestId 不能为空
10353	requestId 长度不能超过64个字符
10354	Internet server error
10471	taskIds 数量不能超过100个
10472	taskIds 格式错误
10473	taskIds 为空
10600	name参数不合法,只能使用中文、英文字母、阿拉伯数字和下划线命名,且不能以数字开头，且长度不超过50字符
10601	标签名字不能为空
10602	标签描述不能超过300字符
10603	oldName参数不能为空
10604	newName参数不能为空
10605	oldName参数不合法,只能使用中文、英文字母、阿拉伯数字和下划线命名, 且不能以数字开头，且长度不超过50字符
10606	newName参数不合法,只能使用中文、英文字母、阿拉伯数字和下划线命名, 且不能以数字开头，且长度不超过50字符
10607	id参数不能为空
10608	type参数不能为空
10609	ids参数不能为空
10610	标签名已经存在
10611	标签分类名已经存在
10612	标签组合名已经存在
10613	group参数不合法,只能使用中文、英文字母、阿拉伯数字和下划线命名, 且不能以数字开头，且长度不超过50字符
10614	ids数量不能超过1000
10615	tag数量不能超过100
10616	type参数不合法
10700	userids不能为空
10701	userid个数超过限制
10702	optionType错误
10703	register接口调用超频，稍后再试
10704	register调用过快，稍后再试
10705	app不支持
10706	userType错误
10800	registration_tokens个数不在指定范围
10801	notification不能为空
10802	original_source_name不能为空
10803	original_source_name长度非法
10804	original_source_ip不能为空
10806	click_action非法
10807	url长度超过限制
10808	intent长度超过限制
10255	全量推送接口未开放
10901	dyeKey长度不能超过限制
10900	dye设置个数超过限制
10811	超出限制
10810	clientId非法
10809	click_action不能为空
10805	notification_channel长度超过限制
10617	系统msgId生成异常
10500	订阅标签超出限制
10501	标签长度超出限制
10502	标签已经删除完成
10503	标签不能为空
10504	订阅标签超出限制
10505	标签长度超出限制
10506	标签已经删除完成
10507	标签不能为空
10508	标签个数超出限制
10550	标签操作类型无效
10551	标签列表不能为空
10552	标签个数超过限制
10553	标签组合名不能为空
10309	audienceId不合法,alias长度不超过40