推送标签管理

大约 13 分钟

推送标签管理

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

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

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

公共参数

请求参数

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

响应参数

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

认证方式

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

Authorization:Bearer ${YourAppToken}

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

创建推送标签

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

HTTP 请求

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

路径参数

参数及说明详见 公共参数

请求 header

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

请求 body

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

HTTP 响应

响应 body

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

字段类型描述
dataJSON推送标签的数据。
nameString推送标签的名称。
descriptionString推送标签的描述。
createdAtLong推送标签的创建时间。该时间为 Unix 时间戳,单位为毫秒。

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

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

示例

请求示例

<YourAppToken> 替换为你在服务端生成的 App Token
curl -L -X POST 'localhost/hx/hxdemo/push/label' \
-H 'Authorization: Bearer <YourAppToken>' \
-H 'Content-Type: application/json' \
-d '{
    "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}

路径参数

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

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

请求 header

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

HTTP 响应

响应 body

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

字段类型描述
dataJSON推送标签的数据。
nameString推送标签的名称。
descriptionString推送标签的描述。
countInt该推送标签下的用户数量。
createdAtLong推送标签的创建时间。该时间为 Unix 时间戳,单位为毫秒。

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

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

示例

请求示例

<YourAppToken> 替换为你在服务端生成的 App Token
curl -L -X GET 'localhost/hx/hxdemo/push/label/90' \
-H 'Authorization: Bearer <YourAppToken>'

响应示例

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

分页查询推送标签

分页查询推送标签。

HTTP 请求

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

路径参数

参数及说明详见 公共参数

查询参数

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

请求 header

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

HTTP 响应

响应 body

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

字段类型描述
dataJSON推送标签的数据。
nameString推送标签的名称。
descriptionString推送标签的描述。
countInt该推送标签下的用户数量。
createdAtLong推送标签的创建时间。该时间为 Unix 时间戳,单位为毫秒。

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

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

示例

请求示例

<YourAppToken> 替换为你在服务端生成的 App Token
curl -L -X GET 'localhost/hx/hxdemo/push/label' \
-H 'Authorization: Bearer <YourAppToken>'

响应示例

{
    "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}

路径参数

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

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

请求 header

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

HTTP 响应

响应 body

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

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

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

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

示例

请求示例

<YourAppToken> 替换为你在服务端生成的 App Token
curl -L -X DELETE 'localhost/hx/hxdemo/push/label/post-90s' \
-H 'Authorization: Bearer <YourAppToken>'

响应示例

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

在推送标签下添加用户

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

HTTP 请求

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

路径参数

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

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

请求 header

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

请求 body

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

HTTP 响应

响应 body

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

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

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

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

示例

请求示例

<YourAppToken> 替换为你在服务端生成的 App Token
curl -L -X POST 'localhost/hx/hxdemo/push/label/post-90s/user' \
-H 'Authorization: Bearer <YourAppToken>' \
-H 'Content-Type: application/json' \
-d '{
    "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}

路径参数

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

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

请求 header

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

HTTP 响应

响应 body

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

字段类型描述
dataJSON用户数据。
usernameString要查询的用户 ID。
createdLong添加用户的 Unix 时间戳,单位为毫秒。

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

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

示例

请求示例

<YourAppToken> 替换为你在服务端生成的 App Token
curl -L -X GET 'localhost/hx/hxdemo/push/label/post-90s/user/hx1' \
-H 'Authorization: Bearer <YourAppToken>'

响应示例

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

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

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

HTTP 请求

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

路径参数

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

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

查询参数

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

请求 header

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

HTTP 响应

响应 body

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

字段类型描述
cursorString下次查询的起始位置。
dataJSON获得的用户的数据。
usernameString获得的该标签下的用户 ID。
createdLong添加用户的 Unix 时间戳,单位为毫秒。

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

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

示例

请求示例

<YourAppToken> 替换为你在服务端生成的 App Token
curl -L -X GET 'localhost/hx/hxdemo/push/label/post-90s/user?limit=1' \
-H 'Authorization: Bearer <YourAppToken>'

响应示例

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

批量移出指定推送标签下的用户

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

HTTP 请求

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

路径参数

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

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

请求 header

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

请求 body

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

HTTP 响应

响应 body

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

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

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

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

示例

请求示例

<YourAppToken> 替换为你在服务端生成的 App Token
curl -L -X DELETE 'localhost/hx/hxdemo/push/label/post-90s/user' \
-H 'Authorization: Bearer <YourAppToken>' \
-H 'Content-Type: application/json' \
-d '{
    "usernames":["hx1","hx2"]
}'

响应示例

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

常见错误码

调用推送标签管理相关的 REST API 时,若返回的 HTTP 状态码非 200,则请求失败,提示错误。本节列出这些接口的常见错误码。

HTTP 状态码错误类型错误提示可能原因处理建议
403ServiceNotOpenExceptionpush service not open即时推送功能未开通确认并开通即时推送功能。
403LimitExceptionlimit request因为数量或其他限制导致请求失败根据返回信息的限制原因处理。
400ResourceNotFoundExceptionpush label not exists of XXX即时推送标签不存在检查并修改,使用正确存在的标签名。
404请求路径不存在url is invalid请求路径错误检查并修改,使用正确的请求路径。
5xx服务器内部错误任意服务器在尝试处理请求时发生内部错误联系环信技术支持。

其他错误,你可以参考 错误码 了解可能的原因。