管理用户关系

大约 12 分钟

管理用户关系

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

前提条件

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

认证方式

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

Authorization: Bearer YourAppToken

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

公共参数

请求参数

参数类型是否必需描述
hostString是访问 RESTful API 的域名或服务器信息。
-公有云集成为 环信即时通讯控制台的 即时通讯->服务概览页面下的 域名配置- Rest Api。
-私有化集成为部署后 服务器地址:端口。
org_nameString是每个公司（组织）分配的唯一标识。详见 环信即时通讯控制台的 应用概览->应用详情页面下的 应用信息-Orgname。
app_nameString是创建应用时填入的应用名称。详见 环信即时通讯控制台的 应用概览->应用详情页面下的 应用信息-Appname。
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，私有部署用户好友数无上限。

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。
AuthorizationString是App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

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

字段类型描述
entitiesJSON Array添加的好友的详情。
entities.uuidString系统内为好友生成的系统内唯一标识，开发者无需关心。
entities.typeString对象类型，值为 user 或 group。
entities.createdLong用户创建时间，Unix 时间戳，单位为毫秒。
entities.modifiedLong好友的用户信息如密码或者昵称等最新修改时间，Unix 时间戳，单位为毫秒。
entities.usernameString添加的好友的用户 ID。
entities.activatedBool好友是否为正常状态：
• true 正常状态。
• false 已被封禁。
entities.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。
AuthorizationString是App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

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

字段类型描述
entitiesJSON Array被移除的好友的详情。
entities.uuidString系统内为好友生成的系统内唯一标识，开发者无需关心。
entities.typeString对象类型，值为 user 或 group。
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"
}

获取好友列表

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

HTTP 请求

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

路径参数

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

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

请求 header

参数类型是否必需描述
Content-TypeString是内容类型。请填 application/json。
AcceptString是内容类型。请填 application/json。
AuthorizationString是App 管理员的鉴权 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。
AuthorizationString是App 管理员的鉴权 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否数据查询的起始位置。该参数仅在分页获取时为必需。

提示

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

请求 header

参数类型是否必需
描述
AcceptString是内容类型。请填 application/json。
AuthorizationString是App 管理员的鉴权 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://a1.easemob.com/easemob-demo/wang/users/tst/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。
AuthorizationString是App 管理员的鉴权 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"
}
上次编辑于:
环信私有化部署