环信即时通讯 REST API 概览
大约 15 分钟
环信即时通讯 REST API 概览
环信即时通讯通过 REST 平台提供 REST API，你可以通过你的业务服务器向环信 REST 服务器发送 HTTP 请求，在服务端实现实时通信。
另外环信 Server SDK 提供了用户、消息、群组、聊天室等资源的操作管理能力，具体参见：Java Server SDK 和 PHP Server SDK。
REST 平台架构
环信即时通讯 REST 平台提供多租户架构，以集合（Collection）的形式管理资源，一个 Collection 包含如下子集：
- 数据库（database）
- 组织（orgs）
- 应用（apps）
- 用户（users）
- 群组（chatgroups）
- 消息（chatmessages）
- 文件（chatfiles）
不同 org 之间的用户数据相互隔离；同一个 org 下，不同 app 之间的用户数据也相互隔离。一个 org 的数据架构如下图：
前提条件
要调用环信即时通讯 RESTful API，请确保满足以下要求：
- 已在环信即时通讯控制台 开通配置环信即时通讯 IM 服务。
- 已从服务端获取 app token，详见 使用 App Token 鉴权。
请求结构
认证方式
环信即时通讯 REST API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时，都必须在请求头部填入如下 Authorization 字段：
Authorization: Bearer YourAppToken
为提高项目的安全性，环信即时通讯使用 Token（动态密钥）对即将登录即时通讯系统的用户进行鉴权。即时通讯 RESTful API 推荐使用 app token 的鉴权方式，详见 使用环信 App Token 鉴权。
请求域名
请参照私有化部署文档 5.2应用信息 章节获取REST API请求信息。
通信协议
环信即时通讯 REST API 支持 HTTP 和 HTTPS 协议。
数据格式
- 请求：请求的格式详见具体 API 中的示例。
- 响应：响应内容的格式为 JSON。
所有的请求 URL 和请求包体内容都是区分大小写的。
REST API 概览
用户体系管理
用户体系管理 功能，包括注册、获取、修改和删除用户等。
| 名称 | 方法 | 请求 | 描述 |
|---|---|---|---|
| 开放 和 授权注册单个用户 | POST | /{org_name}/{app_name}/users | 开放注册和授权注册一个用户。 |
| 批量注册用户 | POST | /{org_name}/{app_name}/users | 授权注册多个用户。 |
| 获取单个用户详情 | GET | /{org_name}/{app_name}/users/{username} | 获取单个用户的信息。 |
| 批量获取用户详情 | GET | /{org_name}/{app_name}/users | 获取多个用户的信息。 |
| 删除单个用户账号 | DELETE | /{org_name}/{app_name}/users/{username} | 删除单个用户。 |
| 批量删除用户账号 | DELETE | /{org_name}/{app_name}/users | 删除 app 下所有用户。 |
| 修改用户密码 | PUT | /{org_name}/{app_name}/users/{username}/password | 修改用户的密码。 |
| 获取单个用户在线状态（status） | GET | /{org_name}/{app_name}/users/{username}/status | 查看一个用户的在线状态。 |
| 批量获取用户在线状态（status） | GET | /{org_name}/{app_name}/users/batch/status | 批量查看用户的在线状态。 |
| 设置用户全局禁言 | POST | /{org_name}/{app_name}/mutes | 设置单个用户 ID 的单聊、群组、聊天室消息全局禁言。 |
| 查询单个用户 ID 全局禁言 | GET | /{org_name}/{app_name}/mutes/{username} | 查询单个用户的单聊、群聊和聊天室消息的全局禁言。 |
| 查询 app 下的所有全局禁言的用户 | POST | /{org_name}/{app_name}/users | 查询 app 下所有全局禁言的用户及其禁言剩余时间。 |
| 获取用户离线消息数量 | GET | /{org_name}/{app_name}/users/{owner_username}/offline_msg_count | 获取用户的离线消息数量。 |
| 获取某条离线消息状态 | GET | /{org_name}/{app_name}/users/{username}/offline_msg_status/{msg_id} | 获取用户的离线消息的状态，即查看该消息是否已投递。 |
| 用户账号封禁 | POST | /{org_name}/{app_name}/users/{username}/deactivate | 禁用用户账号，账号被禁用将立即下线并无法登录进入环信即时通讯 IM，直到被解禁后才能恢复登录。 |
| 用户账号解禁 | POST | /{org_name}/{app_name}/users/{username}/activate | 解禁用户账号。 |
| 强制下线 | GET | /{org_name}/{app_name}/users/{username}/disconnect | 强制用户即把用户状态改为离线，用户需要重新登录才能正常使用。 |
设置消息离线推送
设置推送消息 展示方式、显示昵称、免打扰模式等。
| 名称 | 方法 | 请求 | 描述 |
|---|---|---|---|
| 绑定和解绑推送信息 | PUT | /{org_name}/{app_name}/users/wzy/push/binding | 对用户设备与推送信息进行绑定和解绑。 |
| 查询当前用户的所有设备的推送绑定信息 | GET | /{org_name}/{app_name}/users/wzy/push/binding | 查询用户设备与推送信息进行绑定和解绑。 |
| 设置推送消息显示昵称 | PUT | /{org_name}/{app_name}/users/{username} | 设置用户离线推送消息显示的昵称。 |
| 设置推送消息展示方式 | PUT | /{org_name}/{app_name}/users/{username} | 设置用户离线推送消息展示为仅通知还是详情可见。 |
| 设置免打扰 | PUT | /{org_name}/{app_name}/users/{username} | 设置用户离线推送是否开启免打扰模式，以及开启/关闭免打扰的时间。 |
消息发送及文件下载
消息管理包括：从服务端发送文本、图片、语音、视频、透传、扩展、文件、自定义等各种类型的消息，以及上传和下载文件。
| 名称 | 方法 | 请求 | 描述 |
|---|---|---|---|
| 发送消息 | POST | 三种请求场景如下： - 单聊：/{org_name}/{app_name}/messages/users - 群聊：/{org_name}/{app_name}/messages/chatgroups - 聊天室：/{org_name}/{app_name}/messages/chatrooms | 聊天相关 API，一般是模拟系统管理员给用户、群组或聊天室发送消息，支持发送文本消息、图片消息、语音消息、视频消息，透传消息，扩展消息以及文件类型消息。 |
| 上传文件 | POST | /{org_name}/{app_name}/chatfiles | 上传语音和图片等文件。 |
| 下载文件 | GET | /{org_name}/{app_name}/chatfiles/{file_uuid} | 下载语音和图片等文件。 |
| 获取聊天记录文件 | GET | /{org_name}/{app_name}/chatmessages/${time} | 获取聊天记录文件。 |
用户属性
用户属性管理 包括：设置、获取和删除用户属性。
| 名称 | 方法 | 请求 | 描述 |
|---|---|---|---|
| 设置用户属性 | PUT | /{org_name}/{app_name}/metadata/user/{username} | 对指定的用户设置用户属性。 |
| 获取指定用户的所有用户属性 | GET | /{org_name}/{app_name}/metadata/user/{username} | 获取指定用户的所有用户属性。 |
| 批量获取用户属性 | POST | /{org_name}/{app_name}/metadata/user/get | 根据指定的用户名列表和属性列表查询用户属性。 |
| 删除用户属性 | DELETE | /{org_name}/{app_name}/metadata/user/{username} | 删除指定用户的所有用户属性。 |
| 获取 app 下的用户属性总大小 | GET | /{org_name}/{app_name}/metadata/user/capacity | 获取该 app 下所有用户的用户属性总大小。 |
用户关系管理
用户关系管理 包括：管理用户的好友列表和黑名单。
| 名称 | 方法 | 请求 | 描述 |
|---|---|---|---|
| 添加好友 | POST | /{org_name}/{app_name}/users/{owner_username}/contacts/users/{friend_username} | 添加为好友。 |
| 移除好友 | DELETE | /{org_name}/{app_name}/users/{owner_username}/contacts/users/{friend_username} | 移除好友列表中的用户。 |
| 获取好友列表 | GET | /{org_name}/{app_name}/users/{owner_username}/contacts/users | 获取好友列表。 |
| 获取黑名单列表 | GET | /{org_name}/{app_name}/users/{owner_username}/blocks/users | 获取黑名单。 |
| 添加用户至黑名单 | POST | /{org_name}/{app_name}/users/{owner_username}/blocks/users | 添加用户至黑名单。 |
| 将用户从黑名单移除 | DELETE | /{org_name}/{app_name}/users/{owner_username}/blocks/users/{blocked_username} | 移除黑名单中的用户。 |
群组管理
群组管理 包括创建、获取、修改和删除群组。
| 名称 | 方法 | 请求 | 描述 |
|---|---|---|---|
| 分页获取 app 中的群组 | GET | /{org_name}/{app_name}/chatgroups?limit={N}&cursor={cursor} | 分页获取应用下的群组信息。 |
| 获取一个用户参与的所有群组 | GET | /{org_name}/{app_name}/users/{username}/joined_chatgroups?pagesize={}&pagenum={} | 根据用户名称获取此用户加入的全部群组。 |
| 查看指定用户是否已加入群组 | POST | /{org_name}/{app_name}/chatgroups/{group_id}/user/{user_id}/is_joined | 查看指定的用户是否已加入群组。 |
| 获取群组详情 | GET | /{org_name}/{app_name}/chatgroups/{group_ids} | 根据群组 ID 获取群组的详情。 |
| 创建一个群组 | POST | /{org_name}/{app_name}/chatgroups | 创建一个群组。 |
| 修改群组信息 | PUT | /{org_name}/{app_name}/chatgroups/{group_id} | 修改群组信息。 |
| 删除群组 | DELETE | /{org_name}/{app_name}/chatgroups/{group_id} | 删除一个群组。 |
群组成员管理
管理群组成员，包括添加、移除群组成员关系列表，转让群主等。
| 名称 | 方法 | 请求 | 描述 |
|---|---|---|---|
| 分页获取群组成员 | GET | /{org_name}/{app_name}/chatgroups/{group_id}/users | 分页获取一个群组的群成员列表。 |
| 添加单个群组成员 | POST | /{org_name}/{app_name}/chatgroups/{group_id}/users/{username} | 添加用户至群组成员列表。 |
| 批量添加群组成员 | POST | /{org_name}/{app_name}/chatgroups/{group_id}/users | 批量添加用户至群组成员列表。 |
| 移除单个群组成员 | DELETE | /{org_name}/{app_name}/chatgroups/{group_id}/users/{username} | 从群组成员列表中移除用户。 |
| 批量移除群组成员 | DELETE | /{org_name}/{app_name}/chatgroups/{group_id}/users/{usernames} | 从群组成员列表中批量移除用户。 |
| 获取群管理员列表 | GET | /{org_name}/{app_name}/chatgroups/{group_id}/admin | 获取群组管理员列表。 |
| 添加群管理员 | POST | /{org_name}/{app_name}/chatgroups/{group_id}/admin | 添加用户至群组管理员列表。 |
| 移除群管理员 | DELETE | /{org_name}/{app_name}/chatgroups/{group_id}/admin/{oldadmin} | 从群组管理员列表中移除用户。 |
| 转让群组 | PUT | /{org_name}/{app_name}/chatgroups/{group_id} | 转让群主权限。 |
| 查询群组黑名单 | GET | /{org_name}/{app_name}/chatgroups/{group_id}/blocks/users | 查询群组的黑名单列表。 |
| 添加单个用户至群组黑名单 | POST | /{org_name}/{app_name}/chatgroups/{group_id}/blocks/users/{username} | 将用户添加至群组的黑名单列表。 |
| 批量添加用户至群组黑名单 | POST | /{org_name}/{app_name}/chatgroups/{group_id}/blocks/users | 将用户批量添加至群组的黑名单列表。 |
| 从群组黑名单移除单个用户 | DELETE | /{org_name}/{app_name}/chatgroups/{group_id}/blocks/users/{username} | 将用户从黑名单列表中移除。 |
| 批量从群组黑名单移除用户 | DELETE | /{org_name}/{app_name}/chatgroups/{group_id}/blocks/users/{usernames} | 批量将用户从黑名单列表中移除。 |
| 查询群组白名单 | GET | /{org_name}/{app_name}/chatgroups/{group_id}/white/users | 查询群组白名单中的用户列表。 |
| 添加单个用户至群组白名单 | POST | /{org_name}/{app_name}/chatgroups/{group_id}/white/users/{username} | 将指定的单个用户添加至群组白名单。 |
| 批量添加用户至群组白名单 | POST | /{org_name}/{app_name}/chatgroups/{group_id}/blocks/users | 添加多个用户至群组白名单。 |
| 将用户移除群组白名单 | DELETE | {org_name}/{app_name}/chatgroups/{group_id}/white/users/{username} | 将指定用户从群组白名单中移除。 |
| 获取禁言列表 | GET | /{org_name}/{app_name}/chatgroups/{group_id}/{mute} | 获得指定群组的禁言列表。 |
| 禁言指定群成员 | POST | /{org_name}/{app_name}/chatgroups/{group_id}/mute | 将指定群成员禁言。 |
| 禁言全体成员 | POST | /{org_name}/{app_name}/chatgroups/{group_id}/ban | 对所有群组成员一键禁言。 |
| 解除指定成员禁言 | POST | /{org_name}/{app_name}/chatgroups/{group_id}/mute/{member1}(,{member2},…) | 将一个或多个群成员移除禁言列表。 |
| 解除全员禁言 | PUT | /{org_name}/{app_name}/chatgroups/{group_id}/ban | 一键取消对群组全体成员的禁言。 |
管理子区
子区管理 包括子区的创建、获取、修改、删除等。
| 名称 | 方法 | 请求 | 描述 |
|---|---|---|---|
| 分页获取 app 中的子区 | GET | /{org_name}/{app_name}/thread?limit={limit}&cursor={cursor}&sort={sort} | 分页获取应用下的子区列表。 |
| 获取一个用户加入的所有子区（分页获取） | GET | /{org_name}/{app_name}/threads/user/{username} | 根据用户 ID 获取用户加入的所有的子区。 |
| 获取一个用户某个群组下加入的所有子区（分页获取） | GET | /{org_name}/{app_name}/threads/chatgroups/{group_id}user/{username} | 根据用户 ID 和群组 ID 获取用户加入的所有子区。 |
| 创建子区 | POST | /{org_name}/{app_name}/thread | 创建一个新子区。 |
| 修改子区 | PUT | /{org_name}/{app_name}/thread/{thread_id} | 修改子区的部分信息。 |
| 删除子区 | DELETE | /{org_name}/{app_name}/thread/{thread_id} | 删除一个子区。 |
管理子区成员
子区成员管理，包括对子区的加入和踢出等管理功能。
| 名称 | 方法 | 请求 | 描述 |
|---|---|---|---|
| 查询子区成员(分页) | GET | /{org_name}/{app_name}/thread/{thread_id}/users | 获取子区下成员列表。 |
| 批量加入子区 | POST | /{org_name}/{app_name}/thread/{thread_id}/users | 批量往子区添加成员。 |
| 批量踢出子区成员 | DELETE | /{org_name}/{app_name}/threads/{thread_id}/users | 批量踢出子区成员。 |
聊天室管理
聊天室管理 包括创建、获取、修改、删除聊天室。
| 名称 | 方法 | 请求 | 描述 |
|---|---|---|---|
| 分页获取 app 中的聊天室 | GET | /{org_name}/{app_name}/chatrooms?limit={N}&cursor={cursor} | 分页获取应用下的聊天室信息。 |
| 获取用户加入的聊天室 | GET | /{org_name}/{app_name}/users/{username}/joined_chatrooms | 根据用户名称获取此用户加入的全部聊天室。 |
| 获取聊天室详情 | GET | /{org_name}/{app_name}/chatrooms/{chatroom_id} | 根据聊天室 ID 获取此聊天室的详情 |
| 创建一个聊天室 | POST | /{org_name}/{app_name}/chatrooms | 创建一个新聊天室。 |
| 修改聊天室信息 | PUT | /{org_name}/{app_name}/chatrooms/{chatroom_id} | 修改聊天室信息。 |
| 删除聊天室 | DELETE | /{org_name}/{app_name}/chatrooms/{chatroom_id} | 删除一个聊天室。 |
| 获取聊天室公告 | GET | /{org_name}/{app_name}/chatrooms/{chatroom_id}/announcement | 获取指定聊天室 ID 的聊天室公告。 |
| 修改聊天室公告 | PUT | /{org_name}/{app_name}/chatrooms/{chatroom_id}/announcement | 修改指定聊天室 ID 的聊天室公告。 |
| 获取聊天室自定义属性 | POST | /{org_name}/{app_name}/chatrooms/{chatroom_id}/announcement | 获取聊天室指定或所有自定义属性。 |
| 设置聊天室自定义属性 | PUT | /{org_name}/{app_name}/metadata/chatroom/{chatroom_id}/user/{username} | 设置聊天室单个或多个自定义属性。 |
| 强制设置聊天室自定义属性 | PUT | /{org_name}/{app_name}/metadata/chatroom/{chatroom_id}/user/{username}/forced | 强制设置聊天室单个或多个自定义属性。 |
| 删除聊天室自定义属性 | DELETE | /{org_name}/{app_name}/metadata/chatroom/{chatroom_id}/user/{username} | 删除单个或多个聊天室自定义属性。 |
| 强制删除聊天室自定义属性 | DELETE | /{org_name}/{app_name}/metadata/chatroom/{chatroom_id}/user/{username}/forced | 强制删除单个或多个聊天室自定义属性。 |
聊天室成员管理
聊天室成员管理 包括：添加、获取、修改和删除聊天室中的成员。
| 名称 | 方法 | 请求 | 描述 |
|---|---|---|---|
| 分页获取聊天室成员 | GET | /{org_name}/{app_name}/chatrooms/{chatroom_id}/users | 分页获取一个聊天室的成员列表。 |
| 添加单个聊天室成员 | POST | /{org_name}/{app_name}/chatrooms/{chatroom_id}/users/{username} | 添加用户至聊天室成员列表。 |
| 批量添加聊天室成员 | POST | /{org_name}/{app_name}/chatrooms/{chatroom_id}/users | 批量添加用户至聊天室成员列表。 |
| 删除单个聊天室成员 | DELETE | /{org_name}/{app_name}/chatrooms/{chatroom_id}/users/{username} | 从聊天室成员列表中删除用户。 |
| 批量删除聊天室成员 | DELETE | /{org_name}/{app_name}/chatrooms/{chatroom_id}/users/{usernames} | 从聊天室成员列表中批量删除用户。 |
| 获取聊天室管理员列表 | GET | /{org_name}/{app_name}/chatrooms/{chatroom_id}/admin | 获取聊天室管理员列表。 |
| 添加聊天室管理员 | POST | /{org_name}/{app_name}/chatrooms/{chatroom_id}/admin | 添加用户至聊天室管理员列表。 |
| 移除聊天室管理员 | DELETE | /{org_name}/{app_name}/chatrooms/{chatroom_id}/admin/{oldadmin} | 从聊天室管理员列表中移除用户。 |
| 查询聊天室黑名单 | GET | /{org_name}/{app_name}/chatrooms/{chatroom_id}/blocks/users | 查看聊天室的黑名单列表。 |
| 添加单个用户至聊天室黑名单 | POST | /{org_name}/{app_name}/chatrooms/{chatroom_id}/blocks/users/{username} | 将用户添加至聊天室的黑名单。 |
| 批量添加用户至聊天室黑名单 | POST | /{org_name}/{app_name}/chatrooms/{chatroom_id}/blocks/users | 将单个用户批量添加至聊天室的黑名单。 |
| 从聊天室黑名单移除单个用户 | DELETE | /{org_name}/{app_name}/chatrooms/{chatroom_id}/blocks/users/{username} | 将用户从聊天室黑名单中移除。 |
| 批量从聊天室黑名单移除用户 | DELETE | /{org_name}/{app_name}/chatrooms/{chatroom_id}/blocks/users/{usernames} | 批量将用户从黑名单列表中移除。 |
| 查询聊天室白名单 | GET | /{org_name}/{app_name}/chatrooms/{chatroom_id}/white/users | 查询一个聊天室白名单中的用户列表。 |
| 添加单个用户至聊天室白名单 | POST | /{org_name}/{app_name}/chatrooms/{chatroom_id}/white/users/{username} | 将指定的单个用户添加至聊天室白名单。 |
| 批量添加用户至聊天室白名单 | POST | /{org_name}/{app_name}/chatrooms/{chatroom_id}/white/users | 添加多个用户至聊天室白名单。 |
| 将用户移除聊天室白名单 | DELETE | /{org_name}/{app_name}/chatrooms/{chatroom_id}/white/users/{username} | 将指定用户从聊天室白名单移除。 |
| 获取聊天室的禁言列表 | GET | /{org_name}/{app_name}/chatrooms/{chatroom_id}/mute | 获取当前聊天室的禁言用户列表。 |
| 禁言聊天室成员 | POST | /{org_name}/{app_name}/chatrooms/{chatroom_id}/mute | 将聊天室成员禁言。 |
| 禁言聊天室全体成员 | POST | /{org_name}/{app_name}/chatrooms/{chatroom_id}/ban | 对所有聊天室成员一键禁言。 |
| 解除聊天室禁言成员 | DELETE | /{org_name}/{app_name}/chatrooms/{chatroom_id}/mute/{member1}(,{member2},…) | 将指定用户从禁言列表中移除。 |
| 解除聊天室全员禁言 | PUT | /{org_name}/{app_name}/chatrooms/{chatroom_id}/ban | 一键取消对聊天室全体成员的禁言。 |
用户在线状态管理
| 名称 | 方法 | 请求 | 描述 |
|---|---|---|---|
| 设置用户在线状态信息 | POST | /{org_name}/{app_name}/users/{uid}/presence/{resource}/{status} | 设置用户在线状态信息。 |
| 批量订阅在线状态 | POST | /{org_name}/{app_name}/users/{uid}/presence/{expiry} | 批量订阅在线状态。 |
| 批量获取在线状态信息 | POST | /{org_name}/{app_name}/users/{uid}/presence | 批量获取在线状态信息。 |
| 查询单个群组的在线成员数量 | GET | /{org_name}/{app_name}/presence/online/{group_id}/type/{query_type} | 查询单个群组的在线成员数量。 |
| 取消订阅多个用户的在线状态 | DELETE | /{org_name}/{app_name}/users/{uid}/presence | 取消订阅多个用户的在线状态。 |
| 查询订阅列表 | GET | /{org_name}/{app_name}/users/{uid}/presence/sublist?pageNum=1&pageSize=100 | 查询订阅列表。 |