删除会话与消息

本页的接口代用户删除会话、清空聊天记录、删除消息。它们都只影响这个用户自己的视图：单聊的对方和群里的其他成员看到的会话和消息不变，服务端拉取历史消息时仍能看到全部消息。操作结果同步到这个用户的所有设备：在线的设备实时收到通知，离线的设备在下次同步时更新。

操作	对这个用户的效果	之后有新消息时
删除会话	会话从他的会话列表中移除，未读数清零，取消置顶。消息仍在，可以选择同时清空	会话重新出现在列表中
清空聊天记录	他看不到这个会话中此前的全部消息，未读数清零；会话仍在列表中	新消息照常显示
删除消息	指定的消息对他不可见	不受影响

不能删除对方的消息

这些接口都不会删除对方或其他成员设备上的消息。要让所有人都看不到一条消息，请撤回它。

删除会话和清空聊天记录都视为读过了此前的消息：已读位置前进到当时的最后一条，单聊的对方会看到新的已读位置，群里要求已读回执的消息计入已读，与标记已读相同。除此之外不影响对方。

删除会话

代用户把一个会话从他的会话列表中删除。

DELETE/{org_name}/{app_name}/users/{username}/conversations/{conversation_id}

• 删除后，用户会话对象的 hidden 为 true，hidden_seq 为删除时的最后一条消息；已读位置前进到这条消息，未读数清零；同时取消置顶和“标记为未读”。
• 不带 clear_messages 时只是隐藏会话，聊天记录仍在：用户再打开这个会话时仍能看到之前的消息。
• 会话重新出现：之后会话中有计入未读的新消息时，hidden 变为 false，会话重新出现在列表中，未读数只计算删除之后的消息。以这个用户的身份发送消息（sync_to_sender 为默认的 true，见发送消息），或用户在客户端把会话标记为未读，也会让它重新出现。群提示（如有人加入或退出群）和 exclude_from_unread 为 true 的消息不会让会话重新出现。
• 已离开的群也可以删除，删除后不会再收到新消息，因而不再出现。
• 重复删除返回 200 OK，changed 为 false。

路径参数

org_name、app_name 见接入概述。

参数	类型	说明
username	String	用户名，不区分大小写
conversation_id	String	会话 ID；群会话的 ID 就是群 ID

查询参数

参数	类型	必填	说明
clear_messages	Boolean	否	是否同时清空聊天记录，效果与清空聊天记录相同。true 或 1 表示清空，false 或 0 表示不清空，默认 false

请求示例

curl -X DELETE "$IM_API/$ORG/$APP/users/bob/conversations/99582660229201920" \
  -H "Authorization: Bearer $APP_TOKEN"

同时清空聊天记录：

curl -X DELETE "$IM_API/$ORG/$APP/users/bob/conversations/99582660229201920?clear_messages=true" \
  -H "Authorization: Bearer $APP_TOKEN"

响应

成功返回 200 OK：

字段	类型	说明
conversation	Object	操作之后的用户会话对象
changed	Boolean	是否有变化，重复删除时为 false

{
  "conversation": {
    "conversation_id": "99582660229201920",
    "conversation_type": "single",
    "peer": "alice",
    "group_id": null,
    "membership": null,
    "start_seq": 1,
    "max_seq": 13,
    "read_seq": 13,
    "unread_count": 0,
    "marked_unread": false,
    "peer_read_seq": 10,
    "mention_seq": null,
    "cleared_seq": 0,
    "hidden_seq": 13,
    "hidden": true,
    "pinned_at": null,
    "joined_at": null,
    "left_at": null,
    "message_version": 0,
    "last_message_at": "2026-10-02T19:10:21.991Z",
    "version": 25
  },
  "changed": true
}

错误

HTTP 状态码	code	说明
400	invalid_argument	clear_messages 不是 true、false、1、0 之一
404	not_found	用户不存在或已删除；会话不存在；单聊中用户不是会话的一方；群不存在，或者是私有群而用户从未入群
403	not_group_member	公开群，用户不是成员，也没有离开之前的记录；details.reason 为 leave_pending 时是用户刚离开群、离开的处理还没完成，稍后重试

清空聊天记录

代用户清空一个会话的聊天记录：他看不到这个会话中此前的全部消息，之后的新消息照常显示。

POST/{org_name}/{app_name}/users/{username}/conversations/{conversation_id}/clear

• 清空后，cleared_seq 为清空时的最后一条消息，start_seq 变为它的下一条（start_seq 大于 max_seq 表示没有可见的消息）；已读位置前进到这条消息，未读数清零，@ 提醒和“标记为未读”随之消失。
• 会话仍在会话列表中，置顶不变。
• 清空的消息不能恢复，对这个用户的所有设备生效。
• 重复清空（期间没有新消息）返回 200 OK，changed 为 false。

路径参数

org_name、app_name 见接入概述。

参数	类型	说明
username	String	用户名，不区分大小写
conversation_id	String	会话 ID；群会话的 ID 就是群 ID

请求示例

curl -X POST "$IM_API/$ORG/$APP/users/alice/conversations/99582660229201920/clear" \
  -H "Authorization: Bearer $APP_TOKEN"

响应

成功返回 200 OK，字段与删除会话的响应相同。下例中会话共 16 条消息，清空后 alice 看不到任何消息，对方 bob 随即收到 alice 已读到第 16 条的通知：

{
  "conversation": {
    "conversation_id": "99582660229201920",
    "conversation_type": "single",
    "peer": "bob",
    "group_id": null,
    "membership": null,
    "start_seq": 17,
    "max_seq": 16,
    "read_seq": 16,
    "unread_count": 0,
    "marked_unread": false,
    "peer_read_seq": 15,
    "mention_seq": null,
    "cleared_seq": 16,
    "hidden_seq": 0,
    "hidden": false,
    "pinned_at": null,
    "joined_at": null,
    "left_at": null,
    "message_version": 0,
    "last_message_at": "2026-10-02T19:11:49.764Z",
    "version": 26
  },
  "changed": true
}

错误

HTTP 状态码	code	说明
404	not_found	用户不存在或已删除；会话不存在；单聊中用户不是会话的一方；群不存在，或者是私有群而用户从未入群
403	not_group_member	公开群，用户不是成员，也没有离开之前的记录；details.reason 为 leave_pending 时是用户刚离开群、离开的处理还没完成，稍后重试

删除消息

代用户删除会话中的几条消息，这些消息只对他不可见。

POST/{org_name}/{app_name}/users/{username}/conversations/{conversation_id}/messages/delete

• 只处理这个用户能看到的消息；不存在的序号、已清空的消息、群里他入群之前的消息、已过期的消息直接忽略，不报错。
• 他的在线设备实时收到删除通知，从本地移除这些消息；离线设备在下次同步时移除。
• 删除的消息如果他还没读，仍计入未读数，直到已读位置越过它。需要时请同时标记已读。
• 重复删除已删除的消息返回 200 OK，changed 为 false。

路径参数

org_name、app_name 见接入概述。

参数	类型	说明
username	String	用户名，不区分大小写
conversation_id	String	会话 ID；群会话的 ID 就是群 ID

请求体

字段	类型	必填	说明
seqs	Array<Number>	是	要删除的消息的序号，1 到 100 个，重复的只算一次

请求示例

curl -X POST "$IM_API/$ORG/$APP/users/bob/conversations/99582660229201920/messages/delete" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "seqs": [17, 18]
  }'

响应

成功返回 200 OK：

字段	类型	说明
changed	Boolean	是否有新删除的消息。全部已删除过或都被忽略时为 false
version	Number	操作之后这个用户的会话列表版本号，客户端 SDK 用它增量同步，服务端通常不需要使用

{
  "changed": true,
  "version": 34
}

错误

HTTP 状态码	code	说明
400	invalid_argument	seqs 为空、缺失或超过 100 个，details.reason 为 too_many_items，details.field 为 seqs，details.max 为 100
400	invalid_argument	请求体不是 JSON 对象，或 seqs 不是数字数组
404	not_found	用户不存在或已删除；会话不存在；单聊中用户不是会话的一方；群不存在，或者是私有群而用户从未入群
403	not_group_member	公开群，用户不是成员，也没有离开之前的记录；details.reason 为 leave_pending 时是用户刚离开群、离开的处理还没完成，稍后重试