用户收藏

大约 11 分钟

用户收藏

即时通讯 IM 支持你收藏聊天过程中发送成功的各类消息或你的其他自定义内容。这些收藏的内容永久保存，你可以随时查看。例如，你若收藏指定的消息附件，可将消息附件设置为永久存储，然后再收藏，即可随时查看这些附件内容。

公共参数

以下表格列举了即时通讯 IM 的 RESTful 接口的公共请求参数：

参数类型是否必需描述
hostString是即时通讯 IM 分配的用于访问 RESTful API 的域名。
app_idString是声网为每个项目自动分配的 App ID，作为项目唯一标识。

前提条件

要调用即时通讯 IM 的 RESTful API，请确保满足以下要求：

认证方式

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

Authorization: Bearer YourAppToken

为提高项目的安全性，声网使用 Token（动态密钥）对即将登录即时通讯系统的用户进行鉴权。即时通讯 IM RESTful API 推荐使用 app token 的 鉴权方式，详见 使用 Token 鉴权。

分页获取用户收藏

调用该接口获取指定用户的收藏。

调用频率上限：100 次/秒/App ID

HTTP 请求

GET https://{host}/app-id/{app_id}/users/{username}/collections
路径参数
参数类型是否必需描述
usernameString是要获取哪个用户的收藏。

其它参数及说明详见 公共参数。

查询参数

用户收藏可通过两种方式查询，如下所示。除了 type 和 limit 字段的设置，这两种方式的设置如下：

  1. 按时间段：时间段字段和 direction 字段配合使用。这种方式下，你必须传入 begin_time 和 end_time 字段，direction 字段的默认值为 desc。
  2. 从指定的收藏 ID 开始查询：collection_id 和 direction 字段配合使用。这种方式下，你必须传入 collection_id。

注意：第二种查询方式的优先级高于第一种方式。也就是说，若你传入了 collection_id 字段，则设置的 begin_time 和 end_time 字段无效。

参数类型是否必需描述
begin_timeNumber否查询开始时间，UNIX 时间戳。默认值为 0。该字段必须小于等于 end_time。单位为毫秒。
end_timeNumber否查询结束时间，UNIX 时间戳。
- 该字段必须大于等于 begin_time，默认为系统当前时间。单位为毫秒。
- 若 end_time 等于 begin_time，服务器查询该时间点的收藏。
directionString否查询方向：
- （默认）desc ：按照收藏时间的降序排列；
- asc： 按照收藏时间的升序排列。
typeInt否收藏类型。若该参数不传，则不限制收藏类型，返回满足查询条件的所有类型的收藏。
limitInt否请求查询的收藏数量。取值范围为 [1,200]，默认值为 100。超过 200 则返回参数错误。
collection_idString否收藏 ID。参数不为空的情况下：
- direction 为 desc 时，服务器会将当前收藏的时间戳作为查询结束时间，查询当前收藏及其添加时间之前的所有收藏，按收藏时间的倒序返回。
- direction 为 asc 时，服务器会将当前收藏的创建时间戳设置为查询开始时间，查询当前收藏及其创建时间之后的所有收藏，按收藏时间的正序返回。
请求 Header
参数类型是否必需描述
AcceptString是内容类型。请填 application/json。
AuthorizationString是App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

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

字段类型描述
collectionsJSON Array获取的用户收藏的详情。
- idString收藏 ID。
- typeInt收藏类型。
- dataString收藏内容。
- extString收藏的扩展信息
- createdAtLong收藏创建时间。
- updatedAtLong收藏更新时间。

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

示例

请求示例
将 <YourAppToken> 替换为你在服务端生成的 App Token 
curl -X GET -H 'Accept: application/json' \
-H 'Authorization: Bearer <YourAppToken>' https://XXXX/app-id/XXXX/users/{username}/collections
响应示例
{
    "collections": [
    {
    "id": "string",
    "type": 0,
    "data": "string",
    "ext": "string",
    "createdAt": 0,
    "updatedAt": 0 
    }
  ]
}

错误码

如果返回的 HTTP 状态码非 200，表示请求失败，可能提示以下错误码：

HTTP 状态码错误类型错误提示可能原因处理建议
400illegal_argumentusername XXX is not legal用户 ID 不合法。查看注册用户名规范。
400illegal_argumentlimit should be less than 200传入的每页查询的收藏数量 limit 不能超过 200。将 limit 的值控制在 200 以内。
400illegal_argumentdirection should be desc or ascdirection 参数传错。direction 参数只能是 desc 或者 asc。
400user collection not found用户收藏找不到。对 collection_id 参数传入存在的用户收藏 ID。

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

添加一条收藏

调用该接口对指定用户添加一条收藏。

调用频率上限：100 次/秒/App ID

HTTP 请求

POST https://{host}/app-id/{app_id}/users/{username}/collections
路径参数
参数类型是否必需描述
usernameString是要对哪个用户添加收藏。

其它参数及说明详见 公共参数。

请求 Header
参数类型是否必需描述
Content-TypeString是内容类型。请填 application/json。
AcceptString是内容类型。请填 application/json。
AuthorizationString是App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。
请求 body
参数类型是否必需描述
idString否收藏 ID，收藏的唯一标识。若不传，声网服务器会设置随机的 UUID。
dataString是收藏内容。
typeInt是收藏类型。
extString否收藏的扩展信息。默认为 NULL，即无扩展信息。

HTTP 响应

响应 body

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

字段类型描述
idString收藏 ID。
typeInt收藏类型。
dataString收藏内容。
extString收藏的扩展信息。
createdAtLong收藏创建时间。
updatedAtLong收藏更新时间。

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

示例

请求示例
将 <YourAppToken> 替换为你在服务端生成的 App Token 
curl -X POST https://XXXX/app-id/XXXX/users/{username}/collections
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <YourAppToken>' 
-d '{
  "id": "string",
  "data": "string",
  "type": 0,
  "ext": "info"
}'
响应示例
{
  "collection": {
    "id": "string",
    "type": 0,
    "data": "string",
    "ext": "string",
    "createdAt": 0,
    "updatedAt": 0
  } 
}

错误码

如果返回的 HTTP 状态码非 200，表示请求失败，可能提示以下错误码：

HTTP 状态码错误类型错误提示可能原因处理建议
400illegal_argumentusername XXX is not legal用户 ID 不合法。查看注册用户名规范。

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

批量添加用户收藏

调用该接口对指定用户添加多条收藏。

调用频率上限：100 次/秒/App ID

HTTP 请求

POST https://{host}/app-id/{app_id}/collections
路径参数

参数及说明详见 公共参数。

请求 Header
参数类型是否必需描述
Content-TypeString是内容类型。请填 application/json。
AcceptString是内容类型。请填 application/json。
AuthorizationString是App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。
请求 body
参数类型是否必需描述
collectionsArray是要添加的收藏详情。最多可添加 20 个收藏。
- idString是收藏 ID。
- dataString是收藏内容。
- typeInt是收藏类型。
- extString是收藏的扩展信息。
- createdAtLong是收藏的添加时间。
usernameString是为哪个用户添加收藏。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200，表示请求成功。

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

示例

请求示例
将 <YourAppToken> 替换为你在服务端生成的 App Token 
curl -X POST https://XXXX/app-id/XXXX/collections
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <YourAppToken>'  \
-d '{
  "collections": [
    {
      "id": "string",
      "type": 0,
      "data": "string",
      "ext": "string",
      "createdAt": 0
    }
  ],
  "username": "string"
}'
响应示例
{
  "collections": [ 
    {
    "id": "id1",
    "type": 0,
    "data": "string",
    "ext": "string",
    "createdAt": 0,
    "updatedAt": 0
    }
    {
    "id": "id2",
    "type": 1,
    "data": "string",
    "ext": "string",
    "createdAt": 0,
    "updatedAt": 0
    }  
  ] 
}

错误码

如果返回的 HTTP 状态码非 200，表示请求失败，可能提示以下错误码：

HTTP 状态码错误类型错误提示可能原因处理建议
400illegal_argumentusername XXX is not legal用户 ID 不合法。查看注册用户名规范。

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

修改用户收藏的扩展信息

调用该接口修改指定用户的一条收藏的扩展信息。

调用频率上限：100 次/秒/App ID

HTTP 请求

PUT https://{host}/app-id/{app_id}/users/{username}/collections/{collectionId}
路径参数
参数类型是否必需描述
usernameString是要修改哪个用户的收藏。
collectionIdString是收藏 ID。

其它参数及说明详见 公共参数。

请求 Header
参数类型是否必需描述
Content-TypeString是内容类型。请填 application/json。
AcceptString是内容类型。请填 application/json。
AuthorizationString是App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。
请求 body
参数类型是否必需描述
extString是收藏的扩展信息。如果设置为空，则表示取消现有的扩展字段。

HTTP 响应

响应 body

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

字段类型描述
idString收藏 ID。
typeInt收藏类型。
dataString收藏内容。
extString收藏的扩展信息。
createdAtLong收藏创建时间。
updatedAtLong收藏更新时间。

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

示例

请求示例
将 <YourAppToken> 替换为你在服务端生成的 App Token 
curl -X PUT https://XXXX/app-id/XXXX/users/{username}/collections/{collectionId} \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
  "ext": "string" 
}'
响应示例
{
  "collection": {
    "id": "string",
    "type": 0,
    "data": "string",
    "ext": "string",
    "createdAt": 0,
    "updatedAt": 0
  } 
}

错误码

如果返回的 HTTP 状态码非 200，表示请求失败，可能提示以下错误码：

HTTP 状态码错误类型错误提示可能原因处理建议
400illegal_argumentusername XXX is not legal用户 ID 不合法。查看注册用户名规范。

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

删除用户收藏

调用该接口删除指定用户的收藏。

调用频率上限：100 次/秒/App ID

HTTP 请求

DELETE https://{host}/app-id/{app_id}/users/{username}/collections
路径参数
参数类型是否必需描述
usernameString是要删除哪个用户的收藏。

其它参数及说明详见 公共参数。

请求 Header
参数类型是否必需描述
Content-TypeString是内容类型。请填 application/json。
AcceptString是内容类型。请填 application/json。
AuthorizationString是App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。
请求 body
参数类型是否必需描述
collection_idsString是收藏 ID。最多可传入 20 个收藏 ID。

HTTP 响应

响应 body

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

字段类型描述
resultString是否成功删除收藏：
- true：成功；
- false：失败。

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

示例

请求示例
将 <YourAppToken> 替换为你在服务端生成的 App Token 
curl -X DELETE https://XXXX/app-id/XXXX/users/{username}/collections \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <YourAppToken>'  \
-d '{
  "collection_ids": [
  "string"
  ]
}'
响应示例
{
  "result": true
}

错误码

如果返回的 HTTP 状态码非 200，表示请求失败，可能提示以下错误码：

HTTP 状态码错误类型错误提示可能原因处理建议
400illegal_argumentusername XXX is not legal用户 ID 不合法。查看注册用户名规范。
400user collection not found用户收藏找不到。对 collection_ids 参数传入存在的用户收藏 ID。

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

上次编辑于: