用户关系管理 REST API

更新时间:2022-05-19

用户关系管理是用来管理用户之间关系的服务,环信即时通讯 IM REST API 提供以下方法支持管理用户之间的关系:

名称 请求 描述
添加好友 /{org_name}/{app_name}/users/{owner_username}/contacts/users/{friend_username} 添加为好友。
移除好友 /{org_name}/{app_name}/users/{owner_username}/contacts/users/{friend_username} 移除好友列表中的用户。
获取好友列表 /{org_name}/{app_name}/users/{owner_username}/contacts/users 获取好友列表以及信息。
获取黑名单 /{org_name}/{app_name}/users/{owner_username}/blocks/users 获取黑名单以及信息。
添加黑名单 /{org_name}/{app_name}/users/{owner_username}/blocks/users 拉黑用户,添加至黑名单。
移除黑名单 /{org_name}/{app_name}/users/{owner_username}/blocks/users/{blocked_username} 移除黑名单中的用户。

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

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

Authorization:Bearer ${YourAppToken}

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

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

添加好友

接口描述

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

免费版 App Key 下的每个用户的好友数量上限为 1000,不同版本 App Key 上限不同,具体可参考:版本功能介绍

基本信息

方法:POST

接入点:https://{host}/{org_name}/{app_name}/users/{owner_username}/contacts/users/{friend_username}

路径参数

参数 类型 是否必需 描述
host String 必需 你在环信即时通讯云控制台注册项目时所在的集群服务器地址。
org_name String 必需 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。
app_name String 必需 你在环信即时通讯云控制台注册项目时填入的应用名称。
owner_username String 必需 你的用户名。
friend_username String 必需 要添加的用户名。

请求头

参数 类型 是否必需 描述
Content-Type string 必需 内容类型:application/json
Authorization string 必需 Bearer ${token} Bearer 是固定字符,后面加英文空格,再加上获取到的 token 的值。该用户或管理员的 token,详见 使用 Token 鉴权

响应体参数

API 在响应体中返回一下参数:

参数 描述
action 请求方式,即接口方法名。
organization org_name,即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。
application 系统内为应用生成的唯一标识,开发者无需关心。
applicationName app_name,你在环信即时通讯云控制台注册项目时填入的应用名称。
path 请求路径,属于请求 URL 的一部分,开发者无需关注。
entities 用户详情。
uuid 系统内为用户生成的系统内唯一标识,开发者无需关心。
type 接口类型,分为 user 和 group 两种。
created 用户创建时间,Unix 时间戳,单位为毫秒。
modified 用户信息如密码或者昵称等最后修改时间,Unix 时间戳,单位为毫秒。
username 被添加的用户名。
activated 用户是否被封禁:
true 该用户没有被封禁。
false 该用户已经被封禁。
nickname 用户昵称。
timestamp 请求响应的时间,Unix 时间戳,单位为毫秒。
data 返回结果的数据,例如获取好友列表,返回好友列表数据。
duration 处理请求的用时时间, 单位为毫秒。

请求示例

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/contacts/users/user2'

响应示例

{
  "action": "post",
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",
  "path": "/users/4759aa70-eba5-11e8-925f-6fa0510823ba/contacts",
  "uri": "https://a1.easemob.com/easemob-demo/testapp/users/4759aa70-eba5-11e8-925f-6fa0510823ba/contacts",
  "entities": [
    {
      "uuid": "b2aade90-e978-11e8-a974-f3368f82e4f1",
      "type": "user",
      "created": 1542356523769,
      "modified": 1542597334500,
      "username": "user2",
      "activated": true,
      "nickname": "testuser"
    }
  ],
  "timestamp": 1542598913819,
  "duration": 63,
  "organization": "easemob-demo",
  "applicationName": "testapp"
}

响应状态码

状态码 描述
200 请求成功。
401 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。
404 添加人或者被添加人不存在。
429,503 或者其他 5xx 单位时间内请求过多,请稍后重试。
500 服务器内部错误,一般是 mysql 错误。 如果问题持续存在,请联系我们的技术支持团队。

移除好友

接口描述

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

基本信息

方法:DELETE

接入点:https://{host}/{org_name}/{app_name}/users/{owner_username}/contacts/users/{friend_username}

路径参数

参数 类型 是否必需 描述
host String 必需 你在环信即时通讯云控制台注册项目时所在的集群服务器地址。
org_name String 必需 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。
app_name String 必需 你在环信即时通讯云控制台注册项目时填入的应用名称。
owner_username String 必需 发起操作的用户名。
friend_username String 必需 被移除好友的用户名。

请求头

参数 类型 是否必需 描述
Content-Type string 必需 内容类型:application/json
Authorization string 必需 Bearer ${token} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。详见 使用 app token 鉴权

响应体

参数 描述
action 请求方式,即接口方法名。
organization org_name,即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。
application 系统内为应用生成的唯一标识,开发者无需关心。
applicationName app_name,你在环信即时通讯云控制台注册项目时填入的应用名称。
path 请求路径,属于请求 URL 的一部分,开发者无需关注。
entities 用户详情。
uuid 系统内为用户生成的系统内唯一标识,开发者无需关心。
type 接口类型,分为 user 和 group 两种。
created 用户创建时间,Unix 时间戳,单位为毫秒。
modified 用户信息如密码或者昵称等最后修改时间,Unix 时间戳,单位为毫秒。
username 被添加的用户名。
activated 用户是否被封禁:
true 该用户没有被封禁。
false 该用户已经被封禁。
nickname 用户昵称。
timestamp Unix 时间戳,单位为毫秒。
data 返回结果的数据,例如获取好友列表,返回好友列表数据。
duration 请求响应时间, 单位为毫秒。

请求示例

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/contacts/users/user2'

响应示例

{
  "action": "delete",
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",
  "path": "/users/4759aa70-eba5-11e8-925f-6fa0510823ba/contacts",
  "uri": "https://a1.easemob.com/easemob-demo/testapp/users/4759aa70-eba5-11e8-925f-6fa0510823ba/contacts",
  "entities": [
    {
      "uuid": "b2aade90-e978-11e8-a974-f3368f82e4f1",
      "type": "user",
      "created": 1542356523769,
      "modified": 1542597334500,
      "username": "user2",
      "activated": true,
      "nickname": "testuser"
    }
  ],
  "timestamp": 1542599266616,
  "duration": 350,
  "organization": "easemob-demo",
  "applicationName": "testapp"
}

响应状态码

状态码 描述
200 请求成功。
401 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。
404 添加人或者被删除用户不存在。
429,503 或者其他 5xx 单位时间内请求过多。请稍后重试。
500 服务器内部错误,一般是 mysql 错误。 如果问题持续存在,请联系我们的技术支持团队。

获取好友列表

接口描述

获取用户的好友列表。

基本信息

方法:GET

接入点:https://{host}/{org_name}/{app_name}/users/{owner_username}/contacts/users

路径参数

参数 类型 是否必需 描述
host String 必需 你在环信即时通讯云控制台注册项目时所在的集群服务器地址。
org_name String 必需 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。
app_name String 必需 你在环信即时通讯云控制台注册项目时填入的应用名称。
owner_username String 必需 好友列表所有者的用户名。

请求头

参数 类型 是否必需 描述
Content-Type string 必需 内容类型:application/json
Authorization string 必需 Bearer ${token} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。详见 使用 app token 鉴权

响应体

参数 说明
username “user1”, “user2”,获取到的好友列表。
action 请求方式,即接口方法名。
uri 发起请求的 URL。
entities 被添加好友的用户详情。
data 返回的好友列表数据。
timestamp Unix 时间戳,单位为毫秒。
duration 请求响应时间, 单位为毫秒。
count 计数,好友数量。

请求示例

curl -X GET 'http://a1.easemob.com/easemob-demo/testapp/users/user1/contacts/users' \
-H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw'

响应示例

{
  "action": "get",
  "uri": "http://a1.easemob.com/easemob-demo/testapp/users/user1/contacts/users",
  "entities": [],
  "data": [
    "user3",
    "user2"
  ],
  "timestamp": 1543819826513,
  "duration": 12,
  "count": 2
}

响应状态码

状态码 描述
200 请求成功。
401 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。
404 查询的用户不存在。
429,503 或者其他 5xx 单位时间内请求过多。请稍后重试。
500 服务器内部错误,一般是 mysql 错误。如果问题持续存在,请联系我们的技术支持团队。

添加黑名单

接口描述

向用户的黑名单列表中添加一个或者多个用户,黑名单中的用户无法给该用户发送消息,每个用户的黑名单人数上限为 500。

基本信息

方法:POST

接入点:https://{host}/{org_name}/{app_name}/users/{owner_username}/blocks/users

路径参数

参数 类型 是否必需 描述
host String 必需 你在环信即时通讯云控制台注册项目时所在的集群服务器地址。
org_name String 必需 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。
app_name String 必需 你在环信即时通讯云控制台注册项目时填入的应用名称。
owner_username String 必需 你的用户名。

请求头

参数 类型 是否必需 描述
Content-Type string 必需 内容类型:application/json
Authorization string 必需 Bearer ${token} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。详见 使用 app token 鉴权

请求体

参数 类型 是否必需 描述
usernames 用户名数组 必需 [“user1”, “user2”] 需要加入到黑名单中的用户名以数组方式提交。

响应体

参数 说明
action 请求方式,即接口方法名。
uri 发起请求的 URL。
entities 用户详情。
data 返回的数据。
user2 添加至黑名单的用户名。
timestamp Unix 时间戳,单位为毫秒。
duration 请求响应时间, 单位为毫秒。
organization org_name,即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。
applicationName app_name,你在环信即时通讯云控制台注册项目时填入的应用名称。

请求示例

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' -d '{  
   "usernames": [  
     "user2"  
   ]  
 }' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/blocks/users'

响应示例

{
  "action": "post",
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",
  "uri": "https://a1.easemob.com/easemob-demo/testapp",
  "entities": [],
  "data": [
    "user2"
  ],
  "timestamp": 1542600372046,
  "duration": 11,
  "organization": "easemob-demo",
  "applicationName": "testapp"
}

响应状态码

状态码 描述
200 请求成功。
401 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。
404 查询的用户不存在。
429,503 或者其他 5xx 单位时间内请求过多,请稍后重试。
500 服务器内部错误,一般是 mysql 错误。如果问题持续存在,请联系我们的技术支持团队。

获取黑名单

接口描述

获取黑名单列表。

基本信息

方法:GET

接入点:https://{host}/{org_name}/{app_name}/users/{owner_username}/blocks/users

路径参数

参数 类型 是否必需 描述
host String 必需 你在环信即时通讯云控制台注册项目时所在的集群服务器地址。
org_name String 必需 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。
app_name String 必需 你在环信即时通讯云控制台注册项目时填入的应用名称。
owner_username String 必需 你的用户名。

请求头

参数 类型 是否必需 描述
Content-Type string 必需 内容类型:application/json
Authorization string 必需 Bearer ${token} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。详见 使用 app token 鉴权

响应体

参数 说明
username “user1”, “user2”,获取到的黑名单列表。
action 请求方式,即接口方法名。
uri 发起请求的 URL。
entities 黑名单用户的详情。
data 返回的黑名单列表。
timestamp Unix 时间戳,单位为毫秒。
duration 请求响应时间, 单位为毫秒。
count 计数,好友数量。

请求示例

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/blocks/users'

响应示例

{
  "action": "get",
  "uri": "http://a1.easemob.com/easemob-demo/testapp/users/user1/blocks/users",
  "entities": [],
  "data": [
    "user2"
  ],
  "timestamp": 1542599978751,
  "duration": 4,
  "count": 1
}

响应状态码

状态码 描述
200 请求成功。
401 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。
404 查询的用户不存在。
429,503 或者其他 5xx 单位时间内请求过多,请稍后重试。
500 服务器内部错误,一般是 mysql 错误。如果问题持续存在,请联系我们的技术支持团队。

移除黑名单

接口描述

从用户的黑名单中移除用户。将用户从黑名单移除后,恢复到好友,或者未添加好友的用户关系。可以正常的进行消息收发。

基本信息

方法:DELETE

接入点:https://{host}/{org_name}/{app_name}/users/{owner_username}/blocks/users/{blocked_username}

路径参数

参数 类型 是否必需 描述
host String 必需 你在环信即时通讯云控制台注册项目时所在的集群服务器地址。
org_name String 必需 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。
app_name String 必需 你在环信即时通讯云控制台注册项目时填入的应用名称。
owner_username String 必需 你的用户名。
blocked_username String 必需 需移除的黑名单用户。

请求头

参数 类型 是否必需 描述
Content-Type string 必需 内容类型:application/json
Authorization string 必需 Bearer ${token} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。详见使用 app token 鉴权

响应体

参数 描述
action 请求方式,即接口方法名。
organization org_name,即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。
application 系统内为应用生成的唯一标识,开发者无需关心。
applicationName app_name,你在环信即时通讯云控制台注册项目时填入的应用名称。
path 请求路径,属于请求 URL 的一部分,开发者无需关注。
entities 从黑名单中移除的用户的详细信息。
uuid 用户在系统内的唯一标识。系统自动生成,开发者无需关心。
type 接口类型,分为 user 和 group 两种。
created 用户创建时间,Unix 时间戳,单位为毫秒。
modified 用户信息如密码或者昵称等最后修改时间,Unix 时间戳,单位为毫秒。
username 添加的用户名。
activated 用户是否被封禁:
true 该用户正常。
false 该用户被封禁。
nickname 用户昵称。
timestamp Unix 时间戳,单位为毫秒。
duration 请求响应时间,单位为毫秒。

请求示例

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/blocks/users/user2'

响应示例

{
  "action": "delete",
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",
  "path": "/users/4759aa70-eba5-11e8-925f-6fa0510823ba/blocks",
  "uri": "https://a1.easemob.com/easemob-demo/testapp/users/4759aa70-eba5-11e8-925f-6fa0510823ba/blocks",
  "entities": [
    {
      "uuid": "b2aade90-e978-11e8-a974-f3368f82e4f1",
      "type": "user",
      "created": 1542356523769,
      "modified": 1542597334500,
      "username": "user2",
      "activated": true,
      "nickname": "testuser"
    }
  ],
  "timestamp": 1542600712985,
  "duration": 20,
  "organization": "easemob-demo",
  "applicationName": "testapp"
}

响应状态码

状态码 描述
200 请求成功。
401 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。
404 查询的用户不存在或者要取消拉黑的用户不存在。
429,503 或者其他 5xx 单位时间内请求过多。请稍后重试。
500 服务器内部错误,一般是 mysql 错误。 如果问题持续存在,请联系我们的技术支持团队。