刪除會話與訊息

代使用者刪除會話、清空聊天記錄或刪除訊息。隻影響這個使用者自己看到的：對方和其他群成員不受影響，服務端拉取歷史訊息時也仍能看到全部訊息。結果同步到這個使用者的所有裝置。

操作	對這個使用者的效果	之後有新訊息時
刪除會話	會話從他的會話列表中移除，未讀數清零，取消置頂。訊息仍在，可以選擇同時清空	會話重新出現在列表中
清空聊天記錄	他看不到這個會話中此前的全部訊息，未讀數清零；會話仍在列表中	新訊息照常顯示
刪除訊息	指定的訊息對他不可見	不受影響

不能刪除對方的訊息

這些介面都不會刪除對方或其他成員裝置上的訊息。要讓所有人都看不到一條訊息，請撤回它。

刪除會話和清空聊天記錄都算讀過了此前的訊息，和標記已讀一樣：單聊對方會看到新的已讀位置，要求了回執的群訊息計入已讀。除此之外不影響對方。

刪除會話

代使用者把一個會話從他的會話列表中刪除。

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

• 刪除後：使用者會話物件的 hidden 為 true，hidden_seq 為當時的最後一條；已讀位置前進到這條，未讀數清零，取消置頂和“標記為未讀”。
• 聊天記錄還在：不帶 clear_messages 時只是隱藏會話，使用者再開啟時仍能看到之前的訊息。要一起清空，加 clear_messages=true。
• 重複刪除：返回 200 OK，changed 為 false。

刪除後會話會不會重新出現在列表中：

之後發生	重新出現？
有計入未讀的新訊息	是，未讀數只算刪除之後的訊息
服務端以這個使用者的身份發訊息（sync_to_sender 為預設的 true，見傳送訊息）	是
使用者在客戶端把會話標記為未讀	是
群提示（有人加入、退出群等）	否
exclude_from_unread 為 true 的訊息	否
已離開的群	否，不會再有新訊息

路徑引數

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	公開群，使用者不是成員，也沒有離開之前的記錄
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	公開群，使用者不是成員，也沒有離開之前的記錄
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	公開群，使用者不是成員，也沒有離開之前的記錄
403	not_group_member	details.reason 為 leave_pending：使用者剛離開群，處理還沒完成，稍後重試