单向删除漫游消息

大约 15 分钟

单向删除漫游消息

本文介绍如何根据消息 ID 单向删除单聊和群聊的漫游消息以及如何单向清空环信服务端的漫游消息，包含以下五个 REST API：

根据消息 ID 单向删除单聊漫游消息
根据消息 ID 单向删除群聊漫游消息
单向清空指定用户的漫游消息
单向清空单聊会话某个时间点及之前的漫游消息
单向清空群组或聊天室会话某个时间点及之前的漫游消息

前提条件

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

已在环信即时通讯控制台开通配置环信即时通讯 IM 服务。

公共参数

请求参数

参数	类型	是否必需	描述
`host`	String	是	访问 RESTful API 的域名或服务器信息。 -公有云集成为环信即时通讯控制台的 `即时通讯->服务概览`页面下的 `域名配置- Rest Api`。 -私有化集成为部署后 `服务器地址:端口`。
`org_name`	String	是	每个公司（组织）分配的唯一标识。详见环信即时通讯控制台的 `应用概览->应用详情`页面下的 `应用信息-Orgname`。
`app_name`	String	是	创建应用时填入的应用名称。详见环信即时通讯控制台的 `应用概览->应用详情`页面下的 `应用信息-Appname`。

响应参数

参数	类型	描述
`action`	String	请求方法。
`organization`	String	环信即时通讯 IM 为每个公司（组织）分配的唯一标识，与请求参数 `org_name` 相同。
`application`	String	应用在系统内的唯一标识。该标识由系统生成，开发者无需关心。
`applicationName`	String	你在环信即时通讯云控制台创建应用时填入的应用名称，与请求参数 `app_name` 相同。
`uri`	String	请求 URL。
`path`	String	请求路径，属于请求 URL 的一部分，开发者无需关注。
`timestamp`	Long	HTTP 响应的 Unix 时间戳，单位为毫秒。
`duration`	Int	从发送 HTTP 请求到响应的时长，单位为毫秒。

认证方式

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

Authorization: Bearer YourAppToken

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

根据消息 ID 单向删除单聊漫游消息

功能说明

根据消息 ID 单向删除指定用户的单聊会话的一条或多条（每次最多 50 条）漫游消息。
只能单向删除消息：
- 该用户的指定漫游消息会从服务器和本地删除，该用户无法在客户端拉取到这些消息。若该会话的全部漫游消息均被删除了，该用户的会话在服务端也会被清除，在客户端拉取会话列表时拉不到该会话。
- 会话的对端用户不受影响，仍然可以拉取与该用户的漫游消息和会话。
调用该接口前，可通过获取历史消息记录获取要删除的消息 ID。如果客户使用消息回调功能的话，也可以从自己的服务器上获取，因为消息回调给你的服务器时包含消息 ID。

调用频率上限：100 次/秒/App Key

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/rest/message/roaming/chat/user/{userId}?userId={userId}&msgIdList={msgIdList}&isNotify={isNotify}

路径参数

参数	类型	是否必需	描述
`userId`	String	是	要删除的单聊漫游消息的所属用户 ID。

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

查询参数

参数	类型	是否必需	描述
`userId`	String	是	单聊会话中的对端用户 ID。
`msgIdList`	String	是	要删除的消息的消息 ID。每次最多可传入 50 个消息 ID，消息 ID 之间以英文逗号分隔，例如 message ID 1,message ID 2。
`isNotify`	Boolean	否	消息删除后，是否同步到消息所属用户的所有在线设备。 - （默认）`true`：是 - `false`：否

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

HTTP 响应

响应 body

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

字段	类型	描述
`requestStatusCode`	String	返回 `ok` 表示消息成功删除。
`timestamp`	Number	HTTP 响应的 Unix 时间戳，单位为毫秒。

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

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

示例

请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -L -X DELETE 'https://XXXX/XXXX/XXXX/rest/message/roaming/chat/user/XXXX?userId=XXXX&msgIdList=XXXX&isNotify=false' \
-H 'Authorization: Bearer <YourAppToken>' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'

响应示例

{
  "requestStatusCode": "ok",
  "timestamp": 1710309184114
}

错误码

如果返回的 HTTP 状态码非 200，表示请求失败，可能提示以下错误码：

HTTP 状态码	错误类型	错误提示	可能原因	处理建议
400	service open exception	this appKey not open message roaming	消息漫游服务未开通。	联系商务开通。
400	param exception	delete msg list limit can not greater than 50	一次删除的消息 ID 数量超过限制（50）。	减少一次删除的消息 ID 数量。
400	Bad Request	Bad Request	缺少必填参数，例如查询参数 `userId` 或 `msgIdList`。	校验参数是否传入正确。

关于其他错误，你可以参考响应状态码了解可能的原因。

根据消息 ID 单向删除群聊漫游消息

功能说明

根据消息 ID 单向删除指定用户的某个群聊会话的一条或多条（每次最多 50 条）漫游消息。
只能单向删除消息：
- 该用户的指定漫游消息会从服务器和本地删除，该用户无法从环信服务端拉取到这些消息。若删除了该群聊会话的全部漫游消息，该用户的这个会话在服务端也会被清除，拉取会话列表时拉不到该会话。
- 群组内其他用户不受影响，仍然可以拉取这些漫游消息和会话。
调用该接口前，可通过获取历史消息记录获取要删除的消息 ID。如果客户使用消息回调功能的话，也可以从自己的服务器上获取，因为消息回调给你的服务器时包含消息 ID。

调用频率上限：100 次/秒/App Key

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/rest/message/roaming/group/user/{userId}?groupId={groupId}&msgIdList={msgIdList}&isNotify={isNotify}

路径参数

参数	类型	是否必需	描述
`userId`	String	是	要删除的群聊漫游消息的所属用户 ID。

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

查询参数

参数	类型	是否必需	描述
`groupId`	String	是	群组 ID。
`msgIdList`	String	是	要删除的消息的消息 ID。每次最多可传入 50 个消息 ID，消息 ID 之间以英文逗号分隔，例如 message ID 1,message ID 2。
`isNotify`	Boolean	否	消息删除后，是否同步到消息所属用户的所有在线设备。 - （默认）`true`：是 - `false`：否

请求 header

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

HTTP 响应

响应 body

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

字段	类型	描述
`requestStatusCode`	String	返回 `ok` 表示消息成功删除。
`timestamp`	Number	HTTP 响应的 Unix 时间戳，单位为毫秒。

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

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

示例

请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -L -X DELETE 'https://XXXX/XXXX/XXXX/rest/message/roaming/group/user/XXXX?groupId=XXXX&msgIdList=XXXXisNotify=false' \
-H 'Authorization: Bearer <YourAppToken>' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'

响应示例

{
  "requestStatusCode": "ok",
  "timestamp": 1710309184114
}

错误码

如果返回的 HTTP 状态码非 200，表示请求失败，可能提示以下错误码：

HTTP 状态码	错误类型	错误提示	可能原因	处理建议
400	service open exception	this appKey not open message roaming	消息漫游服务未开通。	联系商务开通。
400	param exception	delete msg list limit can not greater than 50	一次删除的消息 ID 数量超过限制（50）。	减少一次删除的消息 ID 数量。

关于其他错误，你可以参考响应状态码了解可能的原因。

单向清空指定用户的漫游消息

功能说明

清空单个用户当前时间及之前的所有漫游消息。
单向删除消息：
- 调用该接口后，该用户的漫游消息会从服务器和本地清空，该用户无法从服务端拉取到漫游消息，而且该用户的所有会话也会被清除，也拉不到会话列表。不过，
- 会话中的其他用户不受影响，仍然可以拉取与该用户的漫游消息和会话。

调用频率上限：100 次/秒/App Key

HTTP 请求

POST https://{host}/{org_name}/{app_name}/rest/message/roaming/user/{userId}/delete/all

路径参数

参数	类型	是否必需	描述
`userId`	String	是	要清空该用户 ID 的漫游消息。

请求 header

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

HTTP 响应

响应 body

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

字段	类型	描述
`requestStatusCode`	String	操作结果，返回 `ok` 表示该用户的漫游消息清除成功。
`timestamp`	Long	HTTP 响应的 Unix 时间戳，单位为毫秒。

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

示例

请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -L -X POST 'https://XXXX/XXXX/XXXX/rest/message/roaming/user/XXXX/delete/all' \
-H 'Authorization: Bearer <YourAppToken>' \
-H 'Content-Type: Content-Type: application/json' \
-H 'Accept: Accept: application/json'

响应示例

{
  "requestStatusCode": "ok",
  "timestamp": 1710309184114
}

错误码

如果返回的 HTTP 状态码非 200，表示请求失败，可能提示以下错误码：

HTTP 状态码	错误类型	错误提示	可能原因	处理建议
400	service open exception	this appKey not open message roaming	消息漫游服务未开通。	联系商务开通。

关于其他错误，你可以参考响应状态码了解可能的原因。

单向清空单聊会话某个时间点及之前的漫游消息

功能说明

清空单个用户的某个单聊会话在某个时间点及之前的漫游消息。
单向删除消息：
- 调用该接口后，该用户的漫游消息会从服务器和本地清空，该用户无法从环信服务端拉取到这些漫游消息。若清除了该会话的全部漫游消息，该用户的这个会话在服务端也会被清除，拉取会话列表时拉不到该会话。
- 会话中的其他用户不受影响，仍然可以拉取与该用户的漫游消息和会话。

调用频率上限：100 次/秒/App Key

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/rest/message/roaming/chat/user/{userId}/time?userId={peer_userId}&delTime={delTime}&isNotify={isNotify}

路径参数

参数	类型	是否必需	描述
`userId`	String	是	要清空的单聊漫游消息的所属用户 ID。

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

查询参数

参数	类型	是否必需	描述
`peer_userId`	String	是	单聊会话中的对端用户，即要清空和哪个用户之间的漫游消息。需传入该用户 ID。
`delTime`	Long	是	要清空哪个时间点及之前的单聊漫游消息。该时间为 Unix 时间戳，单位为毫秒。
`isNotify`	Boolean	否	消息删除后，是否同步到消息所属用户的所有在线设备。 - （默认）`true`：是 - `false`：否

请求 header

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

HTTP 响应

响应 body

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

字段	类型	描述
`requestStatusCode`	String	操作结果，返回 `ok` 表示漫游消息清除成功。
`timestamp`	Number	HTTP 响应的 Unix 时间戳，单位为毫秒。

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

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

示例

请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -L -X DELETE 'http://XXXX/XXXX/XXXX/rest/message/roaming/chat/user/XXXX/time?userId=XXXX&delTime=1659014868000&isNotify=false' \
-H 'Authorization: Bearer <YourAppToken>'

响应示例

{
  "requestStatusCode": "ok",
  "timestamp": 1710309184114
}

错误码

如果返回的 HTTP 状态码非 200，表示请求失败，可能提示以下错误码：

HTTP 状态码	错误类型	错误提示	可能原因	处理建议
400	service open exception	this appKey not open message roaming	消息漫游服务未开通。	联系商务开通。

关于其他错误，你可以参考响应状态码了解可能的原因。

单向清空群组或聊天室会话某个时间点及之前的漫游消息

功能说明

清空指定用户的某个群组或聊天室会话在某个时间点及之前的的漫游消息。
单向删除消息：
- 调用该接口后，该用户的漫游消息会从服务器和本地清空，该用户无法从环信服务端拉取到这些漫游消息。若清除了该会话的全部漫游消息，该用户的这个会话在服务端也会被清除，拉取会话列表时拉不到该会话。
- 会话中的其他用户不受影响，仍然可以拉取这些漫游消息和会话。

调用频率上限：100 次/秒/App Key

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/rest/message/roaming/group/user/{userId}/time?groupId={groupId}&delTime={delTime}&isNotify={isNotify}

路径参数

参数	类型	是否必需	描述
`userId`	String	是	要清空的漫游消息的所属用户 ID。

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

查询参数

参数	类型	是否必需	描述
`groupId`	String	是	要清空该群组或聊天室的漫游消息。你可以传入群组 ID 或聊天室 ID。
`delTime`	Long	是	要清空指定的时间点及之前的群组或聊天室的漫游消息。该时间为 Unix 时间戳，单位为毫秒。
`isNotify`	Boolean	否	消息删除后，是否同步到消息所属用户的所有在线设备。 - （默认）`true`：是 - `false`：否

请求 header

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

HTTP 响应

响应 body

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

字段	类型	描述
`requestStatusCode`	String	操作结果，返回 `ok` 表示漫游消息清除成功。
`timestamp`	Number	HTTP 响应的 Unix 时间戳，单位为毫秒。

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

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

示例

请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -L -X DELETE 'http://XXXX/XXXX/XXXX/rest/message/roaming/group/user/XXXX/time?groupId=XXXX&delTime=1659014868000&isNotify=false' \
-H 'Authorization: Bearer <YourAppToken>'

响应示例

{
  "requestStatusCode": "ok",
  "timestamp": 1710309184114
}

错误码

如果返回的 HTTP 状态码非 200，表示请求失败，可能提示以下错误码：

HTTP 状态码	错误类型	错误提示	可能原因	处理建议
400	service open exception	this appKey not open message roaming	消息漫游服务未开通。	联系商务开通。

关于其他错误，你可以参考响应状态码了解可能的原因。

单向删除漫游消息

# 单向删除漫游消息

# 前提条件

# 公共参数

# 请求参数

# 响应参数

# 认证方式

# 根据消息 ID 单向删除单聊漫游消息

# 功能说明

# HTTP 请求

# 路径参数

# 查询参数

# 请求 header

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

# 错误码

# 根据消息 ID 单向删除群聊漫游消息

# 功能说明

# HTTP 请求

# 路径参数

# 查询参数

# 请求 header

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

# 错误码

# 单向清空指定用户的漫游消息

# 功能说明

# HTTP 请求

# 路径参数

# 请求 header

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

# 错误码

# 单向清空单聊会话某个时间点及之前的漫游消息

# 功能说明

# HTTP 请求

# 路径参数

# 查询参数

# 请求 header

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

# 错误码

# 单向清空群组或聊天室会话某个时间点及之前的漫游消息

# 功能说明

# HTTP 请求

# 路径参数

# 查询参数

# 请求 header

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

# 错误码

单向删除漫游消息

前提条件

公共参数

请求参数

响应参数

认证方式

根据消息 ID 单向删除单聊漫游消息

功能说明

HTTP 请求

路径参数

查询参数

请求 header

HTTP 响应

响应 body

示例

请求示例

响应示例

错误码

根据消息 ID 单向删除群聊漫游消息

功能说明

HTTP 请求

路径参数

查询参数

请求 header

HTTP 响应

响应 body

示例

请求示例

响应示例

错误码

单向清空指定用户的漫游消息

功能说明

HTTP 请求

路径参数

请求 header

HTTP 响应

响应 body

示例

请求示例

响应示例

错误码

单向清空单聊会话某个时间点及之前的漫游消息

功能说明

HTTP 请求

路径参数

查询参数

请求 header

HTTP 响应

响应 body

示例

请求示例

响应示例

错误码

单向清空群组或聊天室会话某个时间点及之前的漫游消息

功能说明

HTTP 请求

路径参数

查询参数

请求 header

HTTP 响应

响应 body

示例

请求示例

响应示例

错误码