管理用户关系

大约 15 分钟

管理用户关系

环信即时通讯 IM 支持通过 RESTful API 管理用户之间的关系,包括添加和移除联系人以及将用户添加至或移除黑名单。

前提条件

要调用环信即时通讯 RESTful API,请确保满足以下要求:

认证方式

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

Authorization: Bearer YourAppToken

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

公共参数

请求参数

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

响应参数

参数类型描述
entitiesObject响应实体。
dataObject实际获取的数据详情。
uuidString用户在系统内的唯一标识。该标识由系统生成,开发者无需关心。
usernameString用户 ID。
actionString请求方法。
organizationString环信即时通讯 IM 为每个公司(组织)分配的唯一标识,与请求参数 org_name 相同。
applicationString应用在系统内的唯一标识。该标识由系统生成,开发者无需关心。
applicationNameString你在环信即时通讯云控制台创建应用时填入的应用名称,与请求参数 app_name 相同。
uriString请求 URL。
pathString请求路径,属于请求 URL 的一部分,开发者无需关注。
usernameString用户 ID。
nicknameString用户昵称。
timestampLongUnix 时间戳,单位为毫秒。
durationString请求响应时间,单位为毫秒。

用户关系管理的主要接口如下:

添加好友

添加好友,好友必须是和当前用户在一个 App Key 下的用户。

对于免费版即时通讯服务,单个 App Key 下的每个用户的好友数量上限为 1000,不同服务版本的 App Key 的该数量上限不同,具体可参考版本功能介绍open in new window

HTTP 请求

POST https://{host}/{org_name}/{app_name}/users/{owner_username}/contacts/users/{friend_username}

路径参数

参数类型是否必需描述
owner_usernameString当前用户的用户 ID。
friend_usernameString要添加的用户 ID。

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

请求 header

参数类型是否必需
描述
Content-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

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

字段类型描述
entitiesJSON Array添加的好友的详情。
- uuidString系统内为好友生成的系统内唯一标识,开发者无需关心。
- typeString对象类型,值为 usergroup
- createdLong用户创建时间,Unix 时间戳,单位为毫秒。
- modifiedLong好友的用户信息如密码或者昵称等最新修改时间,Unix 时间戳,单位为毫秒。
- usernameString添加的好友的用户 ID。
- activatedBool好友是否为正常状态:
true 正常状态。
false 已被封禁。
- nicknameString好友的用户昵称。

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

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

示例

请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/users/user1/contacts/users/user2'

响应示例

{
  "action": "post",
  "application": "8bXXXX402",
  "path": "/users/475XXXXba/contacts",
  "uri": "https://XXXX/XXXX/XXXX/users/475XXXXba/contacts",
  "entities": [
    {
      "uuid": "b2aXXXXf1",
      "type": "user",
      "created": 1542356523769,
      "modified": 1542597334500,
      "username": "user2",
      "activated": true,
      "nickname": "testuser"
    }
  ],
  "timestamp": 1542598913819,
  "duration": 63,
  "organization": "XXXX",
  "applicationName": "testapp"
}

移除好友

从用户的好友列表中移除一个用户。

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/users/{owner_username}/contacts/users/{friend_username}

路径参数

参数类型是否必需描述
owner_usernameString发起操作的用户 ID。
friend_usernameString被移除好友的用户 ID。

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

请求 header

参数类型是否必需
描述
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

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

字段类型描述
entitiesJSON Array被移除的好友的详情。
entities.uuidString系统内为好友生成的系统内唯一标识,开发者无需关心。
entities.typeString对象类型,值为 usergroup
entities.createdLong用户创建时间,Unix 时间戳,单位为毫秒。
entities.modifiedLong好友的用户信息如密码或者昵称等最近一次修改时间,Unix 时间戳,单位为毫秒。
entities.usernameString被移除好友的用户 ID。
entities.activatedBool好友是否为正常状态:
  • true 正常状态。
  • false 已被封禁。
entities.nicknameString好友的用户昵称。

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

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

示例

请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/users/user1/contacts/users/user2'

响应示例

{
  "action": "delete",
  "application": "8bXXXX402",
  "path": "/users/475XXXXba/contacts",
  "uri": "https://XXXX/XXXX/XXXX/users/475XXXXba/contacts",
  "entities": [
    {
      "uuid": "b2aXXXXf1",
      "type": "user",
      "created": 1542356523769,
      "modified": 1542597334500,
      "username": "user2",
      "activated": true,
      "nickname": "testuser"
    }
  ],
  "timestamp": 1542599266616,
  "duration": 350,
  "organization": "XXXX",
  "applicationName": "testapp"
}

设置好友备注

你可以调用该接口设置你在当前 app 下的好友的备注,即你和要设置备注的好友需在同一个 App Key 下。

对于免费版即时通讯服务,单个 App Key 下的每个用户的好友数量上限为 100,不同服务套餐包的 App Key 的该数量上限不同,详见套餐包功能详情

HTTP 请求

PUT https://{host}/{org_name}/{app_name}/user/{owner_username}/contacts/users/{friend_username}

路径参数

参数类型是否必需描述
owner_usernameString当前用户的用户 ID。
friend_usernameString要设置备注的用户 ID。

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

请求 header

参数类型是否必需
描述
Content-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

请求 body

参数类型是否必需描述
remarkString好友备注。好友备注的长度不能超过 100 个字符。

HTTP 响应

响应 body

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

字段类型描述
actionString请求方法。
statusString好友备注是否设置成功,ok 表示设置成功。
timestampLongHTTP 响应的 UNIX 时间戳,单位为毫秒。
uriLong请求 URL。

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

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

示例

请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X PUT 'https://{host}/{org_name}/{app_name}/user/{owner_username}/contacts/users/{friend_username}' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
  "remark": <remark>
}'

响应示例

{
  "action": "put",
  "duration": 22,
  "status": "ok",
  "timestamp": 1700633088329,
  "uri": "https://{host}/{org_name}/{app_name}/user/{owner_username}/contacts/users/{friend_username}"
}

分页获取好友列表

分页获取指定用户的好友列表。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/user/{username}/contacts?limit={N}&cursor={cursor}&needReturnRemark={true/false} 

路径参数

参数类型是否必需描述
usernameString当前用户的用户 ID。

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

查询参数

参数类型是否必需描述
limitInt每次期望返回的好友的数量。取值范围为 [1,50]。该参数仅在分页获取时为必需,默认为 10
cursorString数据查询的起始位置。该参数仅在分页获取时为必需。第一次调用该接口不传 cursor,获取 limit 指定的好友数量。
needReturnRemarkBoolean是否需要返回好友备注:
- true:返回;
- (默认)false:不返回。

请求 header

参数类型是否必需
描述
Content-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

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

字段类型描述
countInt当前页的好友数量。
dataObject返回的好友列表对象。
data.contactsArray返回的好友列表数据。
data.contacts.remarkString好友备注。
data.contacts.usernameString好友的用户 ID。

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

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

示例

请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -L -X GET 'https://XXXX/XXXX/XXXX/user/XXXX/contacts?limit=10&needReturnRemark=true' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer  <YourAppToken>'

响应示例

{
  "uri": "http://XXXX/XXXX/XXXX/users/XXXX/rostersByPage",  
  "timestamp": 1706238297509,
  "entities": [],
  "count": 1,
  "action": "get",
  "data": {
    "contacts": [
      {
        "remark": null,
        "username": "username"
      }
    ]
  },
  "duration": 27
}

一次性获取好友列表

一次性获取指定用户的好友列表。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/users/{owner_username}/contacts/users

路径参数

参数类型是否必需描述
owner_usernameString好友列表所有者的用户 ID。

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

请求 header

参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

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

字段类型描述
dataArray获取的好友列表,例如 "user1", "user2"。
countInt好友数量。

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

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

示例

请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X GET 'https://XXXX/XXXX/XXXX/users/user1/contacts/users' \
-H 'Authorization: Bearer <YourAppToken>'

响应示例

{
  "action": "get",
  "uri": "https://XXXX/XXXX/XXXX/users/user1/contacts/users",
  "entities": [],
  "data": ["user3", "user2"],
  "timestamp": 1543819826513,
  "duration": 12,
  "count": 2
}

添加用户至黑名单

将一个或多个用户添加用户到黑名单。用户被加入黑名单后,无法向你发送消息,也无法发送好友申请。

用户可以将任何其他用户添加到黑名单列表,无论该用户是否是好友。好友被加入黑名单后仍在好友列表上显示。

每个用户的黑名单人数上限为 500。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/users/{owner_username}/blocks/users

路径参数

参数类型是否必需描述
owner_usernameString当前用户的用户 ID。

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

请求 header

参数类型是否必需
描述
Content-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

请求 body

参数类型是否必需描述
usernamesArray要加入黑名单的用户 ID,例如 ["user1", "user2"]。

HTTP 响应

响应 body

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

字段类型描述
dataArray添加至黑名单的用户 ID。

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

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

示例

请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' -d '{
   "usernames": [
     "user2"
   ]
 }' 'https://XXXX/XXXX/XXXX/users/user1/blocks/users'

响应示例

{
  "action": "post",
  "application": "8bXXXX402",
  "uri": "https://XXXX.com/XXXX/testapp",
  "entities": [],
  "data": ["user2"],
  "timestamp": 1542600372046,
  "duration": 11,
  "organization": "XXXX",
  "applicationName": "testapp"
}

获取黑名单列表

获取加入黑名单的用户列表。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/users/{owner_username}/blocks/users?pageSize={N}&cursor={cursor}

路径参数

参数类型是否必需描述
owner_usernameString当前用户的用户 ID。

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

查询参数
参数类型是否必需描述
pageSizeInt每次期望返回的黑名单用户的数量。取值范围为 [1,50]。该参数仅在分页获取时为必需。
cursorString数据查询的起始位置。该参数仅在分页获取时为必需。

提示

如果 pageSizecursor 参数均不传,获取最新加入黑名单的 500 个用户。若只传 pageSize 而不传 cursor,服务器返回第一页黑名单用户列表,即最新加入黑名单的用户,最多不超过 50 个。

请求 header

参数类型是否必需
描述
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

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

字段类型描述
dataArray获取的黑名单列表,例如 ["user1", "user2"]。
countInt黑名单上用户的数量。

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

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

示例

请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/users/user1/blocks/users?pageSize=2'

响应示例

{
    "uri": "https://XXXX/XXXX/XXXX/users/XXXX/blocks/users",
    "timestamp": 1682064422108,
    "entities": [],
    "cursor": "MTA5OTAwMzMwNDUzNTA2ODY1NA==",
    "count": 2,
    "action": "get",
    "data": [
        "tst05",
        "tst04"
    ],
    "duration": 52
}

从黑名单中移除用户

从用户的黑名单中移除用户:

  • 将好友从黑名单中移除后,恢复好友关系,可以正常收发消息;
  • 将非好友从黑名单中移除后,恢复到未添加好友的状态。

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/users/{owner_username}/blocks/users/{blocked_username}

路径参数

参数类型是否必需描述
owner_usernameString当前用户的用户 ID。
blocked_usernameString要移出黑名单的用户 ID。

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

请求 header

参数类型是否必需
描述
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

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

参数类型描述
entitiesJSON Array从黑名单中移除的用户的详细信息。
entities.uuidString用户在系统内的唯一标识。系统自动生成,开发者无需关心。
entities.typeString对象类型,值为 user
entities.createdLong用户创建时间,Unix 时间戳,单位为毫秒。
entities.modifiedLong用户信息如密码或昵称等的最新修改时间,Unix 时间戳,单位为毫秒。
entities.usernameString被移出黑名单的用户 ID。
entities.activatedBool用户是否为正常状态:
true 该用户为正常状态。
false 该用户为封禁状态。
entities.nicknameString被移出黑名单的用户的昵称。

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

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

示例

请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/users/user1/blocks/users/user2'

响应示例

{
  "action": "delete",
  "application": "8bXXXX402",
  "path": "/users/475XXXXba/blocks",
  "uri": "https://XXXX/XXXX/XXXX/users/475XXXXba/blocks",
  "entities": [
    {
      "uuid": "b2aXXXXf1",
      "type": "user",
      "created": 1542356523769,
      "modified": 1542597334500,
      "username": "user2",
      "activated": true,
      "nickname": "testuser"
    }
  ],
  "timestamp": 1542600712985,
  "duration": 20,
  "organization": "XXXX",
  "applicationName": "testapp"
}