Delete conversations and messages

Delete a conversation, clear chat history or delete messages for a user. Only what that user sees changes: the other side and other group members aren't affected, and the server still sees every message when fetching history. The result syncs to all of the user's devices.

Operation	Effect for this user	When a new message arrives
Delete a conversation	Removed from their conversation list, unread count reset, unpinned. Messages remain unless you also clear them	The conversation reappears in the list
Clear chat history	They can no longer see any earlier messages in the conversation; unread count reset; the conversation stays in the list	New messages show as usual
Delete messages	The given messages are hidden from them	Not affected

You can't delete the other side's messages

None of these delete messages on the other side's or other members' devices. To hide a message from everyone, recall it.

Deleting a conversation and clearing chat history both count as reading the earlier messages, the same as marking as read: the other side of a one-to-one chat sees the new read position, and group messages that asked for receipts count it as read. The other side isn't affected otherwise.

Delete a conversation

Remove a conversation from a user's conversation list.

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

After deleting: hidden in the user conversation object is true and hidden_seq is the last message at the time; the read position moves to it, the unread count resets, and pin and "marked unread" are cleared.
History is kept: without clear_messages the conversation is only hidden, and the user still sees earlier messages when reopening it. Add clear_messages=true to clear them too.
Deleting again: returns 200 OK with changed false.

Whether the conversation comes back to the list afterwards:

What happens next	Reappears?
A new message that counts as unread	Yes; the unread count only covers messages after the deletion
Your server sends as this user (with `sync_to_sender` at its default `true`, see Send messages)	Yes
The user marks the conversation unread in a client	Yes
Group notices (someone joins or leaves, and so on)	No
Messages with `exclude_from_unread` `true`	No
A group the user left	No, there are no new messages

Path parameters

For org_name and app_name, see the server overview.

Parameter	Type	Description
`username`	String	The username, case-insensitive
`conversation_id`	String	The conversation ID; for groups, the group ID

Query parameters

Parameter	Type	Required	Description
`clear_messages`	Boolean	No	Also clear chat history, like Clear chat history. `true` or `1` clears, `false` or `0` doesn't; default `false`

Request example

bash

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

Clearing chat history at the same time:

bash

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

Response

On success you get 200 OK:

Field	Type	Description
`conversation`	Object	The user conversation object after the operation
`changed`	Boolean	Whether anything changed; `false` when deleting again

json

{
  "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
}

Errors

HTTP status	`code`	Description
400	`invalid_argument`	`clear_messages` isn't `true`, `false`, `1` or `0`
404	`not_found`	The user doesn't exist or was deleted; the conversation doesn't exist; the user isn't part of the one-to-one chat; the group doesn't exist, or is private and the user never joined
403	`not_group_member`	A public group the user isn't in and has no record of leaving
403	`not_group_member`	`details.reason` `leave_pending`: the user just left and it hasn't finished processing; retry shortly

Clear chat history

Clear a conversation's history for a user: they can't see any earlier messages, and new messages show as usual.

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

After clearing: cleared_seq is the last message at the time and start_seq becomes the one after it (start_seq greater than max_seq means nothing is visible); the read position moves to it, the unread count resets, and mention reminders and "marked unread" go away.
The conversation stays: it remains in the conversation list, with its pin unchanged.
Can't be undone: applies to all of the user's devices.
Clearing again (with no new messages): returns 200 OK with changed false.

Path parameters

For org_name and app_name, see the server overview.

Parameter	Type	Description
`username`	String	The username, case-insensitive
`conversation_id`	String	The conversation ID; for groups, the group ID

Request example

bash

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

Response

On success you get 200 OK with the same fields as Delete a conversation. Here the conversation had 16 messages; after clearing, alice sees none, and bob is immediately told alice has read up to message 16:

json

{
  "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
}

Errors

HTTP status	`code`	Description
404	`not_found`	The user doesn't exist or was deleted; the conversation doesn't exist; the user isn't part of the one-to-one chat; the group doesn't exist, or is private and the user never joined
403	`not_group_member`	A public group the user isn't in and has no record of leaving
403	`not_group_member`	`details.reason` `leave_pending`: the user just left and it hasn't finished processing; retry shortly

Delete messages

Delete some messages in a conversation for a user, hiding them from that user only.

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

Invisible messages are ignored: nonexistent sequences, cleared messages, messages from before the user joined and expired messages are skipped without an error.
Unread counts don't change: deleted messages the user hasn't read still count as unread until the read position passes them. If needed, also mark as read.
Deleting again: returns 200 OK with changed false.

Path parameters

For org_name and app_name, see the server overview.

Parameter	Type	Description
`username`	String	The username, case-insensitive
`conversation_id`	String	The conversation ID; for groups, the group ID

Request body

Field	Type	Required	Description
`seqs`	Array<Number>	Yes	Sequences of the messages to delete, 1 to 100; duplicates count once

Request example

bash

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]
  }'

Response

On success you get 200 OK:

Field	Type	Description
`changed`	Boolean	Whether any message was newly deleted; `false` when all were already deleted or ignored
`version`	Number	The user's conversation-list version after the operation; client SDKs use it for incremental sync and servers usually don't need it

json

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

Errors

HTTP status	`code`	Description
400	`invalid_argument`	`seqs` is empty, missing or has more than 100 entries; `details.reason` is `too_many_items`, `details.field` is `seqs`, `details.max` is 100
400	`invalid_argument`	The body isn't a JSON object, or `seqs` isn't an array of numbers
404	`not_found`	The user doesn't exist or was deleted; the conversation doesn't exist; the user isn't part of the one-to-one chat; the group doesn't exist, or is private and the user never joined
403	`not_group_member`	A public group the user isn't in and has no record of leaving
403	`not_group_member`	`details.reason` `leave_pending`: the user just left and it hasn't finished processing; retry shortly

Delete conversations and messages ​

Delete a conversation ​

Path parameters ​

Query parameters ​

Request example ​

Response ​

Errors ​

Clear chat history ​

Path parameters ​

Request example ​

Response ​

Errors ​

Delete messages ​

Path parameters ​

Request body ​

Request example ​

Response ​

Errors ​

Delete conversations and messages

Delete a conversation

Path parameters

Query parameters

Request example

Response

Errors

Clear chat history

Path parameters

Request example

Response

Errors

Delete messages

Path parameters

Request body

Request example

Response

Errors