导航|地址|刷新
用户API-个推文档中心






文档中心开发者中心

，欢迎您！

您的优惠服务将于到期。





基本资料



安全设置



应用管理




退出登录
登录/注册SDK下载个推学堂请选择产品
消息推送

用户运营

OneID服务

AI应用工坊

统计分析

用户分析

标签管理

模型管理

短信服务

数字人外呼

一键认证

合规检测

点击提升







体验更多产品服务


欢迎登录开发者中心

立即登录

本月不再提醒





快速入门
快速接入指南

产品简介

开发者中心使用说明

进阶功能

名词解释

多厂商推送接入说明


客户端
Android
概述

3分钟演示

集成指南

API接口

进阶功能

AppLink集成

Maven集成视频


Android多厂商
厂商应用开通指南

厂商SDK集成指南

厂商消息报表补全

厂商SDK更新日志

厂商通道限额&QPS说明


iOS
概述

3分钟演示

集成指南

API接口

AppLink集成

iOS 证书配置指南

iOS集成视频

隐私清单说明


HarmonyOS
概述

集成指南

厂商应用开通指南

API接口


小程序

客户端插件

卓信ID
概述

使用指南

Android接口

iOS接口

服务端接口


Open Harmony
简介

使用入门

通知类型介绍

获取Push Token

推送场景化消息
发送通知消息

发送语音播报消息

推送后台消息


Push Kit常见问题



服务端
RestAPI V2 (推荐使用)
开发前必读

接口调用规范

进阶功能说明

公共参数

多厂商参数

鉴权API

推送API

统计API

用户API

返回码说明

服务端 SDK


老版文档
导航


个推回执文档

Open Harmony API
场景化消息
功能介绍

请求体结构说明

请求体参数说明

响应参数

请求示例


基于应用信息生成鉴权令牌



推送应用场景
三方账号打通

自定义通知铃声

消息分类

自定义通知图标

角标设置

通知大图、大文本

标签推送

emoji 表情推送

消息终止、覆盖和撤回

微信小程序推送

iOS 时效性通知（即时通知）

LiveActivity(灵动岛）文档说明


点击提升方案
文案圈人操作手册

流程画布操作手册

应用内弹窗操作手册

点击提升方案集成指南

到达率提升方案

点击率提升方案


常见问题
客户端推送常见问题

Android常见问题

iOS常见问题

服务端常见问题


SDK更新日志

购买指南
消息推送计费说明

消息推送购买指引


推送服务使用协议




当前位置：个推文档 > 服务端 > RestAPI V2 (推荐使用) > 用户API



用户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": "" } }

返回结构说明请参考公共返回结构



返回参数data说明

名称	类型	描述
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" ] } }

返回结构说明请参考公共返回结构



返回参数data说明

名称	类型	描述
cid	String Array	用户唯一标识，注：cid顺序和绑定顺序无关

请求示例
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" } }

返回结构说明请参考公共返回结构



返回参数data说明

名称	类型	描述
$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" } }

返回结构说明请参考公共返回结构



返回参数data说明

名称	类型	描述
$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" ] } }

返回结构说明请参考公共返回结构



返回参数data说明

名称	类型	描述
$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请求说明:


…(内容过长已截断)

------
导航页 打开网址