推送标签管理

即时通讯服务支持通过设置标签自定义推送用户,实现精准推送。标签用于描述用户的生活习惯、兴趣爱好、行为特征等信息。对用户设置标签后,推送消息时,指定某一推送标签,即可向该标签下的用户发送消息。例如,可以为一些用户打上“时尚弄潮儿”标签后,可定期向该人群推送国内外潮流品牌的相关信息。

你可以通过环信即时通讯控制台创建和管理标签,也可以通过 REST API 进行标签管理。用户与标签是多对多的关系,即一个用户可以对应多个标签,一个标签也可以对应多个用户。

本文档主要介绍如何调用即时推送 REST API 实现创建及管理推送标签。调用以下方法前,请先参考 接口频率限制了解即时通讯 RESTful API 的调用频率限制。

请求参数

参数 类型 是否必需 描述
host String 环信即时通讯 IM 分配的用于访问 RESTful API 的域名。
org_name String 环信即时通讯 IM 为每个公司(组织)分配的唯一标识。
app_name String 你在环信即时通讯云控制台创建应用时填入的应用名称。
username String 用户 ID。

响应参数

参数 类型 描述
timestamp Long 响应的 Unix 时间戳,单位为毫秒。
duration Long 从发送请求到响应的时长,单位为毫秒。

环信即时通讯 RESTful API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时,都必须在请求头部填入如下 Authorization 字段:

Authorization:Bearer ${YourToken}

为提高项目的安全性,环信使用 Token(动态密钥)对即将登录即时通讯系统的用户进行鉴权。即时通讯 RESTful API 推荐使用 app token 的鉴权方式,详见 使用 token 鉴权

为推送的目标用户添加标签,对用户进行分组,实现精细化推送。当前最多可创建 100 个推送标签。如需提升该上限,请联系商务。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/push/label

路径参数

参数及说明详见 公共参数

请求 header

参数 类型 描述 是否必需
Content-Type String 内容类型。请填 application/json
Authorization String Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。

请求 body

字段 类型 描述 是否必需
name String 要创建的推送标签的名称,不能超过 64 个字符。支持以下字符集:
- 26 个小写英文字母 a-z
- 26 个大写英文字母 A-Z
- 10 个数字 0-9
- “_“,”-“,”.”
标签名称区分大小写,因此 Aaaa 为两个标签名称 。
同一个 app 下,标签名称必须唯一。
description String 推送标签的描述,不能超过 255 个字符。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段 类型 描述
data JSON 推送标签的数据。
name String 推送标签的名称。
description String 推送标签的描述。
createdAt Long 推送标签的创建时间。该时间为 Unix 时间戳,单位为毫秒。

其他参数及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例

curl -L -X POST 'localhost/hx/hxdemo/push/label' \
-H 'Authorization: Bearer YWMt5lyAUJnNEeyHUS2MdMYkPAAAAAAAAAAAAAAAAAAAAAEHMpqy501HZr2ms92z-Hz9AQMAAAF_SGRs1QBPGgBOIAaoCYWXntKF-h0vuvlyUCNB-IXTM4eEpSVqIdei9A' \
-H 'Content-Type: application/json' \
--data-raw '{
    "name":"post-90s",
    "description":"hah"
}'

响应示例

{
    "timestamp": 1648720341157,
    "data": {
        "name": "post-90s",
        "description": "hah",
        "createdAt": 1648720341118
    },
    "duration": 13
}

查询指定的推送标签。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/push/label/{labelname}

路径参数

参数 类型 描述 是否必需
labelname String 要查询的推送标签的名称。

其他参数及描述详见 公共参数

请求 header

参数 类型 描述 是否必需
Authorization String Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段 类型 描述
data JSON 推送标签的数据。
name String 推送标签的名称。
description String 推送标签的描述。
count Int 该推送标签下的用户数量。
createdAt Long 推送标签的创建时间。该时间为 Unix 时间戳,单位为毫秒。

其他参数及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码了解可能的原因。

示例

请求示例

curl -L -X GET 'localhost/hx/hxdemo/push/label/90' \
-H 'Authorization: Bearer YWMt5lyAUJnNEeyHUS2MdMYkPAAAAAAAAAAAAAAAAAAAAAEHMpqy501HZr2ms92z-Hz9AQMAAAF_SGRs1QBPGgBOIAaoCYWXntKF-h0vuvlyUCNB-IXTM4eEpSVqIdei9A'

响应示例

{
    "timestamp": 1648720562644,
    "data": {
        "name": "90",
        "description": "hah",
        "count": 0,
        "createdAt": 1648720341118
    },
    "duration": 0
}

分页查询推送标签。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/push/label

路径参数

参数及说明详见 公共参数

查询参数

字段 类型 描述 是否必需
limit Int 每页显示的推送标签的数量,取值范围为 [1,100],默认为 100。
cursor String 数据查询的起始位置。

请求 header

参数 类型 描述 是否必需
Authorization String Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段 类型 描述
data JSON 推送标签的数据。
name String 推送标签的名称。
description String 推送标签的描述。
count Int 该推送标签下的用户数量。
createdAt Long 推送标签的创建时间。该时间为 Unix 时间戳,单位为毫秒。

其他参数及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例

curl -L -X GET 'localhost/hx/hxdemo/push/label' \
-H 'Authorization: Bearer YWMt5lyAUJnNEeyHUS2MdMYkPAAAAAAAAAAAAAAAAAAAAAEHMpqy501HZr2ms92z-Hz9AQMAAAF_SGRs1QBPGgBOIAaoCYWXntKF-h0vuvlyUCNB-IXTM4eEpSVqIdei9A'

响应示例

{
    "timestamp": 1648720425599,
    "data": [
        {
            "name": "post-90s",
            "description": "hah",
            "count": 0,
            "createdAt": 1648720341118
        },
        {
            "name": "post-80s",
            "description": "post-80s generation",
            "count": 0,
            "createdAt": 1647512525642
        }
    ],
    "duration": 1
}

删除指定的推送标签。每次只能删除单个推送标签。

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/push/label/{labelname}

路径参数

参数 类型 描述 是否必需
labelname String 要删除的推送标签的名称。

其他参数及描述详见 公共参数

请求 header

参数 类型 描述 是否必需
Authorization String Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段 类型 描述
data JSON 推送标签成功删除的结果。

其他参数及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例

curl -L -X DELETE 'localhost/hx/hxdemo/push/label/post-90s' \
-H 'Authorization: Bearer YWMt5lyAUJnNEeyHUS2MdMYkPAAAAAAAAAAAAAAAAAAAAAEHMpqy501HZr2ms92z-Hz9AQMAAAF_SGRs1QBPGgBOIAaoCYWXntKF-h0vuvlyUCNB-IXTM4eEpSVqIdei9A'

响应示例

{
    "timestamp": 1648721097405,
    "data": "success",
    "duration": 0
}

为用户分配指定的推送标签。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/push/label/{labelname}/user

路径参数

参数 类型 描述 是否必需
labelname String 推送标签的名称。

其他参数及描述详见 公共参数

请求 header

参数 类型 描述 是否必需
Content-Type String 内容类型。请填 application/json
Authorization String Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。

请求 body

字段 类型 描述 是否必需
usernames List 推送标签下的用户 ID 列表,最多可传 100 个用户 ID。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段 类型 描述
data JSON 用户添加结果。
success List 列明成功添加的用户 ID。
fail JSON 返回的用户添加失败的结果,为键值对格式,其中 key 为添加失败的用户 ID,value 为失败原因。

其他参数及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例

curl -L -X POST 'localhost/hx/hxdemo/push/label/post-90s/user' \
-H 'Authorization: Bearer YWMt5lyAUJnNEeyHUS2MdMYkPAAAAAAAAAAAAAAAAAAAAAEHMpqy501HZr2ms92z-Hz9AQMAAAF_SGRs1QBPGgBOIAaoCYWXntKF-h0vuvlyUCNB-IXTM4eEpSVqIdei9A' \
-H 'Content-Type: application/json' \
--data-raw '{
    "usernames":["hx1","hx2"]
}'

响应示例

{
    "timestamp": 1648721496345,
    "data": {
        "success": [
            "hx1",
            "hx2"
        ],
        "fail": {}
    },
    "duration": 18
}

查询推送标签是否存在指定用户。若存在,返回该用户的用户 ID 以及为该用户添加标签的时间;若不存在则不返回这些信息。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/push/label/{labelname}/user/{username}

路径参数

参数 类型 描述 是否必需
labelname String 推送标签的名称。
username String 要查询的用户 ID。

其他参数及描述详见 公共参数

请求 header

参数 类型 描述 是否必需
Content-Type String 内容类型。请填 application/json
Authorization String Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段 类型 描述
data JSON 用户数据。
username String 要查询的用户 ID。
created Long 添加用户的 Unix 时间戳,单位为毫秒。

其他参数及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例

curl -L -X GET 'localhost/hx/hxdemo/push/label/post-90s/user/hx1' \
-H 'Authorization: Bearer YWMt5lyAUJnNEeyHUS2MdMYkPAAAAAAAAAAAAAAAAAAAAAEHMpqy501HZr2ms92z-Hz9AQMAAAF_SGRs1QBPGgBOIAaoCYWXntKF-h0vuvlyUCNB-IXTM4eEpSVqIdei9A'

响应示例

{
    "timestamp": 1648721589676,
    "data": {
        "username": "hx1",
        "created": 1648721496324
    },
    "duration": 1
}

分页查询指定标签下包含的用户。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/push/label/{labelname}/user

路径参数

参数 类型 描述 是否必需
labelname String 推送标签的名称。

其他参数及描述详见 公共参数

查询参数

字段 类型 描述 是否必需
limit String 每次获取的用户数量,取值范围为 [1,100],默认为 100。
cursor String 数据查询的起始位置。

请求 header

参数 类型 描述 是否必需
Content-Type String 内容类型。请填 application/json
Authorization String Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段 类型 描述
cursor String 下次查询的起始位置。
data JSON 获得的用户的数据。
username String 获得的该标签下的用户 ID。
created Long 添加用户的 Unix 时间戳,单位为毫秒。

其他参数及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例

curl -L -X GET 'localhost/hx/hxdemo/push/label/post-90s/user?limit=1' \
-H 'Authorization: Bearer YWMt5lyAUJnNEeyHUS2MdMYkPAAAAAAAAAAAAAAAAAAAAAEHMpqy501HZr2ms92z-Hz9AQMAAAF_SGRs1QBPGgBOIAaoCYWXntKF-h0vuvlyUCNB-IXTM4eEpSVqIdei9A'

响应示例

{
    "timestamp": 1648721736670,
    "cursor": "ZWFzZW1vYjpwdXNoOmxhYmVsOmN1cnNvcjo5NTkxNTMwMDM4ODQxMzgwMjc",
    "data": [
        {
            "username": "hx1",
            "created": 1648721496324
        }
    ],
    "duration": 1
}

一次移除指定推送标签下的单个或多个用户。

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/push/label/{labelname}/user

路径参数

参数 类型 描述 是否必需
labelname String 推送标签的名称。

其他参数及说明详见公共参数

请求 header

参数 类型 描述 是否必需
Content-Type String 内容类型。请填 application/json
Authorization String Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。

请求 body

字段 类型 描述 是否必需
usernames List 要移出标签的用户 ID 列表,最多可传 100 个用户 ID。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

字段 类型 描述
data JSON 用户移出标签的结果。
Success List 被移出标签的用户 ID。
fail JSON 返回的用户移出标签的结果,为键值对格式,其中 key 为移出失败的用户 ID,value 为失败原因。

其他参数及描述详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例

curl -L -X DELETE 'localhost/hx/hxdemo/push/label/post-90s/user' \
-H 'Authorization: Bearer YWMt5lyAUJnNEeyHUS2MdMYkPAAAAAAAAAAAAAAAAAAAAAEHMpqy501HZr2ms92z-Hz9AQMAAAF_SGRs1QBPGgBOIAaoCYWXntKF-h0vuvlyUCNB-IXTM4eEpSVqIdei9A' \
-H 'Content-Type: application/json' \
--data-raw '{
    "usernames":["hx1","hx2"]
}'

响应示例

{
    "timestamp": 1648722018636,
    "data": {
        "success": [
            "hx1",
            "hx2"
        ],
        "fail": {}
    },
    "duration": 1
}