文档中心

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

#前提条件

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

• 已在环信即时通讯控制台 开通配置环信即时通讯 IM 服务。
• 了解环信 IM REST API 的调用频率限制，详见 接口频率限制。

#认证方式

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

Authorization: Bearer YourAppToken

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

#公共参数

#请求参数

#响应参数

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

#添加好友

添加好友，好友必须是和当前用户在一个 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}

#路径参数

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

#请求 header

#HTTP 响应

#响应 body

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

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

如果返回的 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": "htt

ps://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}

#路径参数

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

#请求 header

#HTTP 响应

#响应 body

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

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

如果返回的 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

#路径参数

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

#请求 header

#HTTP 响应

#响应 body

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

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

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

#示例

#请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token curl -X GET 'https://XXXX/XXXX/XXXX/use

rs/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

#路径参数

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

#请求 header

#请求 body

#HTTP 响应

#响应 body

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

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

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

#示例

#请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token curl -X POST -H 'Content-Type: applicati

on/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

#路径参数

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

#请求 header

#HTTP 响应

#响应 body

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

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

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

#示例

#请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token curl -X GET -H 'Accept: application/json' 

-H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/users/user1/blocks/users' 

#响应示例

{ "action": "get", "uri": "https://XXXX/XXXX/XXXX/users/user1/blocks/users", "entities": [], "data

": ["user2"], "timestamp": 1542599978751, "duration": 4, "count": 1 } 

#从黑名单中移除用户

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

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

#HTTP 请求

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

#路径参数

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

#请求 header

#HTTP 响应

#响应 body

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

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

如果返回的 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" }