Delete a message

DELETE https://chat.zulip.org/api/v1/messages/{message_id}

Permanently delete a message.

This API corresponds to the delete a message completely feature documented in the Zulip help center.

A user must be able to access the content of a message in order to delete it. See channel permissions for more information about content access for channel messages. For direct messages, the user must have received or sent the direct message to have content access.

See restricting message deletion for documentation on when users are allowed to delete messages.

The relevant realm settings in the API that are related to the above linked documentation on when users are allowed to delete messages are:

  • realm_can_delete_any_message_group
  • realm_can_delete_own_message_group
  • realm_can_set_delete_message_policy_group
  • realm_message_content_delete_limit_seconds

The relevant per-channel permission settings in the API that are related to the above linked documentation on when users are allowed to delete messages in a specific channel are:

  • can_delete_any_message_group
  • can_delete_own_message_group

More details about these realm and channel settings can be found in the POST /register response.

Changes: Prior to Zulip 10.0 (feature level 281), only organization administrators had permission to permanently delete a message.

Usage examples

#!/usr/bin/env python3

import zulip

# Pass the path to your zuliprc file here.
client = zulip.Client(config_file="~/zuliprc")

# Delete a message, given the message's ID.
result = client.delete_message(message_id)
print(result)

curl -sSX DELETE https://chat.zulip.org/api/v1/messages/43 \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY

Parameters

message_id integer required in path

Example: 43

The target message's ID.


Response

Example response(s)

Changes: As of Zulip 7.0 (feature level 167), if any parameters sent in the request are not supported by this endpoint, a successful JSON response will include an ignored_parameters_unsupported array.

A typical successful JSON response may look like:

{
    "msg": "",
    "result": "success"
}

An example JSON response for when the specified message does not exist:

{
    "code": "BAD_REQUEST",
    "msg": "Invalid message(s)",
    "result": "error"
}

An example JSON response for when the user making the query does not have permission to delete the message:

{
    "code": "BAD_REQUEST",
    "msg": "You don't have permission to delete this message",
    "result": "error"
}