用户API

用户API

简述

开发者可对用户设定别名与标签,推送时可直接根据别名、标签进行推送,方便对用户的管理。

  • 别名:

    别名是开发者根据自身需求为每个用户设定的标识,建议对不同用户设定不同别名,保证可通过别名来唯一确认某特定用户。

    例子:可将用户的邮箱、昵称、手机号等设为别名,即可通过邮箱、昵称、手机号指定目标用户下发推送。

  • 标签:

    标签是用户的一种属性,每个用户(通过CID来标识 )可以打上100个标签。

    例子:“喜爱足球”,“喜爱动漫”

  • 黑名单用户

    黑名单用户无法收到推送消息

【别名】绑定别名

一个cid只能绑定一个别名,若已绑定过别名的cid再次绑定新别名,则前一个别名会自动解绑,并绑定新别名。

  • 接口地址: BaseUrl/user/alias
  • 请求方式: POST

Request请求说明:

Header参数说明

名称 类型 是否必须 默认值 说明
token String 接口访问凭据,获取方式请参考获取鉴权token

body参数说明

  • content-type:application/json;charset=utf-8

  • 参数示例

{
    "data_list":[
        {
            "cid":"",
            "alias":""
        },
        {
            "cid":"",
            "alias":""
        }
    ]
}
  • 请求参数说明
名称 类型 是否必须 默认值 描述
data_list Json Array 数据列表,数组长度不大于1000

data_list说明

名称 类型 是否必须 默认值 描述
cid String cid,用户标识
alias String 别名,有效的别名组成:
字母(区分大小写)、数字、下划线、汉字;
长度<40字;
一个别名最多允许绑定10个cid。

Response响应说明

成功响应数据格式:

  • content-type: application/json;charset=utf-8

  • http code: 200(http code码说明)

  • 返回值示例

{
    "code": 0,
    "msg": "success"
}

请求示例

curl $BaseUrl/user/alias -X POST -H "Content-Type: application/json;charset=utf-8" -H "token: xxx" -d '{
    "data_list":[
        {
            "cid":"",
            "alias":""
        },
        {
            "cid":"",
            "alias":""
        }
    ]
}'

【别名】根据cid查询别名

通过传入的cid查询对应的别名信息

  • 接口地址: BaseUrl/user/alias/cid/$cid
  • 请求方式: GET

Request请求说明:

路径参数说明(路径中$开头的参数)

名称 类型 是否必须 默认值 说明
cid String 用户唯一标识

Header参数说明

名称 类型 是否必须 默认值 说明
token String 接口访问凭据,获取方式请参考获取鉴权token

Response响应说明

成功响应数据格式:

  • content-type: application/json;charset=utf-8

  • http code: 200(http code码说明)

  • 返回值示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "alias": ""
    }
}
名称 类型 描述
alias String 别名

请求示例

curl $BaseUrl/user/alias/cid/$cid -H "token: xxx"

【别名】根据别名查询cid

通过传入的别名查询对应的cid信息

  • 接口地址: BaseUrl/user/cid/alias/$alias
  • 请求方式: GET

Request请求说明:

路径参数说明(路径中$开头的参数)

名称 类型 是否必须 默认值 说明
alias String 别名

Header参数说明

名称 类型 是否必须 默认值 说明
token String 接口访问凭据,获取方式请参考获取鉴权token

Response响应说明

成功响应数据格式:

  • content-type: application/json;charset=utf-8

  • http code: 200(http code码说明)

  • 返回值示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "cid": ["xxx","xxx"]
    }
}
名称 类型 描述
cid String Array 用户唯一标识

请求示例

curl $BaseUrl/user/cid/alias/$alias -H "token: xxx"

【别名】批量解绑别名

批量解除别名与cid的关系

  • 接口地址: BaseUrl/user/alias
  • 请求方式: DELETE

Request请求说明:

Header参数说明

名称 类型 是否必须 默认值 说明
token String 接口访问凭据,获取方式请参考获取鉴权token

body参数说明

  • content-type:application/json;charset=utf-8

  • 参数示例

{
    "data_list":[
        {
            "cid":"",
            "alias":""
        },
        {
            "cid":"",
            "alias":""
        }
    ]
}
  • 请求参数说明
名称 类型 是否必须 默认值 描述
data_list Json Array 数据列表,数组长度不大于1000

data_list

名称 类型 是否必须 默认值 描述
cid String 用户标识
alias String 别名

Response响应说明

成功响应数据格式:

  • content-type: application/json;charset=utf-8

  • http code: 200(http code码说明)

  • 返回值示例

{
    "code": 0,
    "msg": "success"
}

请求示例

curl $BaseUrl/user/alias -X DELETE -H "Content-Type: application/json;charset=utf-8" -H "token: xxx" -d '{
    "data_list":[
        {
            "cid":"",
            "alias":""
        },
        {
            "cid":"",
            "alias":""
        }
    ]
}'

【别名】解绑所有别名

解绑所有与该别名绑定的cid

  • 接口地址: BaseUrl/user/alias/$alias
  • 请求方式: DELETE

Request请求说明:

路径参数说明(路径中$开头的参数)

名称 类型 是否必须 默认值 说明
alias String 用户别名

Header参数说明

名称 类型 是否必须 默认值 说明
token String 接口访问凭据,获取方式请参考获取鉴权token

Response响应说明

成功响应数据格式:

  • content-type: application/json;charset=utf-8

  • http code: 200(http code码说明)

  • 返回值示例

{
    "code": 0,
    "msg": "success"
}

请求示例

curl $BaseUrl/user/alias/$alias -X DELETE -H "token: xxx"

【标签】一个用户绑定一批标签

一个用户绑定一批标签,此操作为覆盖操作,会删除历史绑定的标签;
此接口对单个cid有频控限制,每天只能修改一次,最多设置100个标签;单个标签长度最大为32字符,标签总长度最大为512个字符,申请修改请点击右侧“技术咨询”了解详情 。

  • 接口地址: BaseUrl/user/custom_tag/cid/$cid
  • 请求方式: POST

Request请求说明:

路径参数说明(路径中$开头的参数)

名称 类型 是否必须 默认值 说明
cid String 用户标识

Header参数说明

名称 类型 是否必须 默认值 说明
token String 接口访问凭据,获取方式请参考获取鉴权token

body参数说明

  • content-type:application/json;charset=utf-8

  • 参数示例

{
    "custom_tag": [
        "tag1",
        "tag2"
    ]
}
  • 请求参数说明
名称 类型 是否必须 默认值 描述
custom_tag String Array 标签列表,标签中不能包含空格

Response响应说明

成功响应数据格式:

  • content-type: application/json;charset=utf-8

  • http code: 200(http code码说明)

  • 返回值示例

{
    "code": 0,
    "msg": "success"
}

请求示例

curl $BaseUrl/user/custom_tag/cid/$cid -X POST -H "Content-Type: application/json;charset=utf-8" -H "token: xxx" -d '{
    "custom_tag": [
        "tag1",
        "tag2"
    ]
}'

【标签】一批用户绑定一个标签

一批用户绑定一个标签,此接口为增量
此接口有频次控制(每分钟最多100次,每天最多10000次),且频次和“【标签】一批用户解绑一个标签”接口共用,申请修改请点击右侧“技术咨询”了解详情
此接口是异步的,会有延迟

  • 接口地址: BaseUrl/user/custom_tag/batch/$custom_tag
  • 请求方式: PUT

Request请求说明:

路径参数说明(路径中$开头的参数)

名称 类型 是否必须 默认值 说明
custom_tag String 用户标签,标签中不能包含空格,单个标签最大长度为32字符,如果含有中文字符需要编码(UrlEncode)

Header参数说明

名称 类型 是否必须 默认值 说明
token String 接口访问凭据,获取方式请参考获取鉴权token

body参数说明

  • content-type:application/json;charset=utf-8

  • 参数示例

{
    "cid": [
        "xxx"
    ]
}
  • 请求参数说明
名称 类型 是否必须 默认值 描述
cid String Array 要修改标签属性的cid列表,数组长度不大于1000

Response响应说明

成功响应数据格式:

  • content-type: application/json;charset=utf-8

  • http code: 200(http code码说明)

  • 返回值示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "$cid": "true"
    }
}
名称 类型 描述
$cid String key为cid,value为结果,true表示成功,否则失败

请求示例

curl $BaseUrl/user/custom_tag/batch/$custom_tag -X PUT -H "Content-Type: application/json;charset=utf-8" -H "token: xxx" -d '{
    "cid": [
        "xxx"
    ]
}'

【标签】一批用户解绑一个标签

解绑用户的某个标签属性,不影响其它标签
此接口有频次控制(每分钟最多100次,每天最多10000次),且频次和“【标签】一批用户绑定一个标签”接口共用,申请修改请点击右侧“技术咨询”了解详情

  • 接口地址: BaseUrl/user/custom_tag/batch/$custom_tag
  • 请求方式: DELETE

Request请求说明:

路径参数说明(路径中$开头的参数)

名称 类型 是否必须 默认值 说明
custom_tag String 用户标签,标签中不能包含空格,如果含有中文字符需要编码(UrlEncode)

Header参数说明

名称 类型 是否必须 默认值 说明
token String 接口访问凭据,获取方式请参考获取鉴权token

body参数说明

  • content-type:application/json;charset=utf-8

  • 参数示例

{
    "cid": [
        "xxx"
    ]
}
  • 请求参数说明
名称 类型 是否必须 默认值 描述
cid String Array 要删除标签属性的cid列表,数组长度不大于1000

Response响应说明

成功响应数据格式:

  • content-type: application/json;charset=utf-8

  • http code: 200(http code码说明)

  • 返回值示例

{
    "msg": "success",
    "code": 0,
    "data": {
        "$cid": "true"
    }
}
名称 类型 描述
$cid String key为cid,value为结果,true表示成功,否则失败

请求示例

curl $BaseUrl/user/custom_tag/batch/$custom_tag -X DELETE -H "Content-Type: application/json;charset=utf-8" -H "token: xxx" -d '{
    "cid": [
        "xxx"
    ]
}'

【标签】查询用户标签

根据cid查询用户标签列表

  • 接口地址: BaseUrl/user/custom_tag/cid/$cid
  • 请求方式: GET

Request请求说明:

路径参数说明(路径中$开头的参数)

名称 类型 是否必须 默认值 说明
cid String 用户标识

Header参数说明

名称 类型 是否必须 默认值 说明
token String 接口访问凭据,获取方式请参考获取鉴权token

Response响应说明

成功响应数据格式:

  • content-type: application/json;charset=utf-8

  • http code: 200(http code码说明)

  • 返回值示例

{
    "msg": "success",
    "code": 0,
    "data": {
        "$cid": [
            "custom_tag1 custom_tag2"
        ]
    }
}
名称 类型 描述
$cid Json key: cid,value: 标签列表,列表中只会有一个元素,多个以空格隔开

请求示例

curl $BaseUrl/user/custom_tag/cid/$cid -H "token: xxx"

【用户】添加黑名单用户

将单个或多个用户加入黑名单,对于黑名单用户在推送过程中会被过滤掉。

  • 接口地址: BaseUrl/user/black/cid/$cid,$cid
  • 请求方式: POST

Request请求说明:

路径参数说明(路径中$开头的参数)

名称 类型 是否必须 默认值 说明
cid String 用户标识,多个以英文逗号隔开,一次最多传200个

Header参数说明

名称 类型 是否必须 默认值 说明
token String 接口访问凭据,获取方式请参考获取鉴权token

Response响应说明

成功响应数据格式:

  • content-type: application/json;charset=utf-8

  • http code: 200(http code码说明)

  • 返回值示例

{
    "code": 0,
    "msg": "success"
}

请求示例

curl $BaseUrl/user/black/cid/$cid,$cid -X POST -H "Content-Type: application/json;charset=utf-8" -H "token: xxx"

【用户】移除黑名单用户

将单个cid或多个cid用户移出黑名单,对于黑名单用户在推送过程中会被过滤掉的,不会给黑名单用户推送消息

  • 接口地址: BaseUrl/user/black/cid/$cid,$cid
  • 请求方式: DELETE

Request请求说明:

路径参数说明(路径中$开头的参数)

名称 类型 是否必须 默认值 说明
cid String 用户标识,多个以英文逗号隔开,一次最多传200个

Header参数说明

名称 类型 是否必须 默认值 说明
token String 接口访问凭据,获取方式请参考获取鉴权token

Response响应说明

成功响应数据格式:

  • content-type: application/json;charset=utf-8

  • http code: 200(http code码说明)

  • 返回值示例

{
    "code": 0,
    "msg": "success"
}

请求示例

curl $BaseUrl/user/black/cid/$cid,$cid -X DELETE -H "Content-Type: application/json;charset=utf-8" -H "token: xxx"

【用户】查询用户状态

查询用户的状态

  • 接口地址: BaseUrl/user/status/$cid,$cid
  • 请求方式: GET

Request请求说明:

路径参数说明(路径中$开头的参数)

名称 类型 是否必须 默认值 说明
cid String 用户标识,多个以英文逗号隔开,一次最多传1000个

Header参数说明

名称 类型 是否必须 默认值 说明
token String 接口访问凭据,获取方式请参考获取鉴权token

Response响应说明

成功响应数据格式:

  • content-type: application/json;charset=utf-8

  • http code: 200(http code码说明)

  • 返回值示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "$cid": {
            "last_login_time":"1484018265935",
            "status":"offline"
        }
    }
}
名称 类型 描述
$cid Json key: cid,value: 用户状态信息
last_login_time String 毫秒时间戳
status String 状态,online在线 offline离线

请求示例

curl $BaseUrl/user/status/$cid,$cid -H "token: xxx"

【用户】查询设备状态

查询设备的状态

注意:
1.该接口返回设备在线时,仅表示存在集成了个推SDK的应用在线
2.该接口返回设备不在线时,仅表示不存在集成了个推SDK的应用在线
3.该接口需要开通权限,如需开通,请联系右侧技术咨询

  • 接口地址: BaseUrl/user/deviceStatus/$cid,$cid
  • 请求方式: GET

Request请求说明:

路径参数说明(路径中$开头的参数)

名称 类型 是否必须 默认值 说明
cid String 用户标识,多个以英文逗号隔开,一次最多传100个

Header参数说明

名称 类型 是否必须 默认值 说明
token String 接口访问凭据,获取方式请参考获取鉴权token

Response响应说明

成功响应数据格式:

  • content-type: application/json;charset=utf-8

  • http code: 200(http code码说明)

  • 返回值示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "$cid": {
            "msg":"success",
            "code": 0,
            "data": {
                "cid_status":"offline",
                "device_status":"online"
            }  
        }
    }
}
名称 类型 描述
$cid Json key: cid,value: 用户状态信息
cid_status String cid在线状态,online在线 offline离线
device_status String 设备在线状态,online在线 offline离线

请求示例

curl $BaseUrl/user/deviceStatus/$cid,$cid -H "token: xxx"

【用户】查询用户信息

查询用户的信息

  • 接口地址: BaseUrl/user/detail/$cid,$cid
  • 请求方式: GET

Request请求说明:

路径参数说明(路径中$开头的参数)

名称 类型 是否必须 默认值 说明
cid String 用户标识,多个以英文逗号隔开,一次最多传1000个

Header参数说明

名称 类型 是否必须 默认值 说明
token String 接口访问凭据,获取方式请参考获取鉴权token

Response响应说明

成功响应数据格式:

  • content-type: application/json;charset=utf-8

  • http code: 200(http code码说明)

  • 返回值示例

{
    "code":0,
    "msg":"success",
    "data":{
        "invalidCids":[
            "invalidCid1",
            "invalidCid2",
            "invalidCid3"
        ],
        "validCids":{
            "${cid1}":{
                "client_app_id":"client_app_id",
                "package_name":"com.getui.demo",
                "device_token":"device_token",
                "phone_type":1,
                "phone_model":"vv",
                "notification_switch":true,
                "create_time":"2021-06-30 00:00:00",
                "login_freq":10,
                "brand":"hw"
            }
        }
    }
}
名称 类型 描述
validCids Json Array 用户信息列表
invalidCids String Array 无效cid列表

validCids中的${cid}

名称 类型 描述
client_app_id String 应用id
package_name String 包名
device_token String 厂商token
phone_type Number 手机系统 1-安卓 2-ios
phone_model String 机型
notification_switch Boolean 系统通知栏开关,true-打开,false-关闭
create_time String 首次登录时间
login_freq Number 登录频次为100天内的登陆次数,如果当天多次登陆,只算一次
brand String brand是返回的厂商devicetoken前缀,比如:华为-hw、小米-xm、魅族-mz、OPPO-op、VIVO-vv、苹果-iphone,没有token的就是unknown,可以用来区分厂商渠道

请求示例

curl $BaseUrl/user/detail/$cid,$cid -H "token: xxx"

【用户】设置角标(仅支持IOS)

通过cid通知个推服务器当前iOS设备的角标情况。

  • 接口地址: BaseUrl/user/badge/cid/$cid,$cid
  • 请求方式: POST

Request请求说明:

路径参数说明(路径中$开头的参数)

名称 类型 是否必须 默认值 说明
cid String 用户标识,多个以英文逗号隔开,一次最多传200个

Header参数说明

名称 类型 是否必须 默认值 说明
token String 接口访问凭据,获取方式请参考获取鉴权token

body参数说明

  • content-type:application/json;charset=utf-8

  • 参数示例

{
    "badge": "-8"
}
  • 请求参数说明
名称 类型 是否必须 默认值 描述
badge String 用户应用icon上显示的数字
+N: 在原有badge上+N
-N: 在原有badge上-N
N: 直接设置badge(数字,会覆盖原有的badge值)

Response响应说明

成功响应数据格式:

  • content-type: application/json;charset=utf-8

  • http code: 200(http code码说明)

  • 返回值示例

{
    "code": 0,
    "msg": "success"
}

请求示例

curl $BaseUrl/user/badge/cid/$cid,$cid -X POST -H "Content-Type: application/json;charset=utf-8" -H "token: xxx" -d '{
    "badge": -8
}'

【用户】查询用户总量

通过指定查询条件来查询满足条件的用户数量

  • 接口地址: BaseUrl/user/count
  • 请求方式: POST

Request请求说明:

Header参数说明

名称 类型 是否必须 默认值 说明
token String 接口访问凭据,获取方式请参考获取鉴权token

body参数说明

  • content-type:application/json;charset=utf-8

  • 参数示例

{
    "tag": [
         {
            "key":"phone_type",
            "values": [
                "android"
            ],
            "opt_type":"and"
        },
        {
            "key":"region",
            "values": [
                "11000000"
            ],
            "opt_type":"not"
        },
         {
            "key":"custom_tag",
            "values": [
                "tag1",
                "tag2"
            ],
            "opt_type":"or"
        }
    ]
}
  • 请求参数说明
名称 类型 是否必须 默认值 描述
key String 查询条件(phone_type 手机类型,region 省市,custom_tag 用户标签,设置标签请见接口)
values String Array 查询条件值列表,其中
手机型号使用如下参数androidios
省市使用编号,点击下载文件region_code.data
opt_type String or(或),and(与),not(非),values间的交并补操作
  • 不同key之间是交集,同一个key之间是根据opt_type操作
  • 需要发送给城市在A,B,C里面,没有设置tagtest标签,手机型号为android的用户,用条件交并补功能可以实现,city(A|B|C) && !tag(tagtest) && phonetype(android)

Response响应说明

成功响应数据格式:

  • content-type: application/json;charset=utf-8

  • http code: 200(http code码说明)

  • 返回值示例

{
    "code": 0,
    "msg": "success",
    "data":{
        "user_count": 0
    }
}
名称 类型 描述
user_count Number 符合条件的用户数量

请求示例

curl $BaseUrl/user/count -X POST -H "Content-Type: application/json;charset=utf-8" -H "token: xxx" -d '{
    "tag": [
         {
            "key":"phone_type",
            "values": [
                "android"
            ],
            "opt_type":"or"
        },
         {
            "key":"region",
            "values": [
                "11000000",
                "12000000"
            ],
            "opt_type":"or"
        },
         {
            "key":"custom_tag",
            "values": [
                "aaa"
            ],
            "opt_type":"not"
        }
    ]
}'

【用户】批量绑定或解绑cid和deviceToken

批量绑定或解绑cid和deviceToken的关系;
默认仅支持小程序通道用户。若有其他厂商通道需要使用,请点击右侧“技术咨询”了解详情。
此接口有全局频控限制,每分钟最多调用1000次。

  • 接口地址: BaseUrl/user/bind_dt/$type
  • 请求方式: POST

Request请求说明:

路径参数说明(路径中$开头的参数)

名称 类型 是否必须 默认值 说明
type String 小程序通道:
wx:微信小程序
厂商通道(需联系技术支持开通):
hw:华为;hwq:华为快应用;ho:荣耀;xm:小米;
op:OPPO;opg:OPPO海外;vv:VIVO;mz:魅族;
fcm:谷歌;st:坚果;sn:索尼;ios:苹果;

Header参数说明

名称 类型 是否必须 默认值 说明
token String 接口访问凭据,获取方式请参考获取鉴权token

body参数说明

  • content-type:application/json;charset=utf-8

  • 参数示例

{
  "dt_list": [
    {
      "cid": "cid1",
      "device_token": "device_token1"
    },
    {
      "cid": "cid2",
      "device_token": "device_token2"
    }
  ]
}
  • 请求参数说明
名称 类型 是否必须 默认值 描述
dt_list Json Array 数据列表,数组长度不大于1000

dt_list说明

名称 类型 是否必须 默认值 描述
cid String cid,用户标识
device_token String deviceToken(传值表示绑定,不传或传空表示解绑):
微信小程序:对应微信小程序用户的openid

Response响应说明

成功响应数据格式:

  • content-type: application/json;charset=utf-8

  • http code: 200(http code码说明)

  • 返回值示例

{
  "msg": "success",
  "code": 0,
  "data": {
    "errorList": [
      {
        "cid": "f5fc768b8f3d0ac24d6b7df65e0221b0",
        "device_token": "WX_oX-Yr4ICsWkJaydB8mdRD3DMahkA",
        "error_code": 24002
      },
      {
        "cid": "9497869031e1fa74adaa84458f73cc62",
        "device_token": "WX_oX-BfgICsWkJurdB3odRDcDjyskB",
        "error_code": 24003
      }
    ]
  }
}
  • 返回结构说明请参考公共返回结构

  • 返回参数data说明(如果全部操作成功将不返回data

名称 类型 描述
errorList Json Array 操作失败的用户列表

errorList说明

名称 类型 描述
cid String 操作失败的cid
device_token String 操作失败的deviceToken
error_code Number 操作失败的错误码

error_code说明

error_code 错误描述 解决措施
24001 cid为空 请检查参数
24002 cid不存在 请检查参数
24003 cid和appId不匹配 请检查参数
24004 cid对应的类型不是小程序 请检查参数

请求示例

curl $BaseUrl/user/bind_dt/wx -X POST -H "Content-Type: application/json;charset=utf-8" -H "token: xxx" -d '{
        "dt_list": [
        {
            "cid": "f5fc768b8f3d0ac24d6b7df65e0221b0",
            "device_token": "oX-Yr4ICsWkJaydB8mdRD3DMahkA"
        },
        {
            "cid": "9497869031e1fa74adaa84458f73cc62",
            "device_token": "oX-BfgICsWkJurdB3odRDcDjyskB"
        }
    ]
}'

开发者中心 SDK 下载

文档中心搜索

技术
咨询

微信扫一扫

随时联系技术支持

在线
咨询