Update personal message flags

POST https://phys-a3131.zulip.cs.aalto.fi/api/v1/messages/flags

Add or remove personal message flags like read and starred on a collection of message IDs.

See also the endpoint for updating flags on a range of messages within a narrow.

Usage examples

#!/usr/bin/env python3

import zulip

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

# Add the "read" flag to the messages with IDs in "message_ids"
request = {
    "messages": message_ids,
    "op": "add",
    "flag": "read",
}
result = client.update_message_flags(request)
# Remove the "starred" flag from the messages with IDs in "message_ids"
request = {
    "messages": message_ids,
    "op": "remove",
    "flag": "starred",
}
result = client.update_message_flags(request)
print(result)

More examples and documentation can be found here.

const zulipInit = require("zulip-js");

// Pass the path to your zuliprc file here.
const config = { zuliprc: "zuliprc" };

(async () => {
    const client = await zulipInit(config);

    // Add the "read" flag to the messages with IDs in "message_ids"
    const addflag = {
        messages: message_ids,
        flag: "read",
    };
    console.log(await client.messages.flags.add(addflag));

    // Remove the "starred" flag from the messages with IDs in "message_ids"
    const removeflag = {
        messages: message_ids,
        flag: "starred",
    };
    console.log(await client.messages.flags.remove(removeflag));
})();

curl -sSX POST https://phys-a3131.zulip.cs.aalto.fi/api/v1/messages/flags \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode 'messages=[4, 8, 15]' \
    --data-urlencode op=add \
    --data-urlencode flag=read

Parameters

messages (integer)[] required

Example: [4, 8, 15]

An array containing the IDs of the target messages.


op string required

Example: "add"

Whether to add the flag or remove it.

Must be one of: "add", "remove".


flag string required

Example: "read"

The flag that should be added/removed.


Available flags

Flag Purpose
read Whether the user has read the message. Messages start out unread (except for messages the user themself sent using a non-API client) and can later be marked as read.
starred Whether the user has starred this message.
collapsed Whether the user has collapsed this message.
mentioned Whether the current user was mentioned by this message, either directly or via a user group. Cannot be changed by the user directly, but can change if the message is edited to add/remove a mention of the current user.
wildcard_mentioned Whether this message contained either a stream wildcard mention like @**all** or a topic wildcard mention (@**topic**). Cannot be changed by the user directly, but can change if the message is edited to add/remove a stream or/and topic wildcard mention. **Changes**: In Zulip 8.0 (feature level 224), the `wildcard_mentioned` flag was deprecated in favor of the `stream_wildcard_mentioned` and `topic_wildcard_mentioned` flags. The `wildcard_mentioned` flag exists for backwards compatibility with older clients and equals `stream_wildcard_mentioned` || `topic_wildcard_mentioned`. Clients interacting with older servers should treat this field as an old name for `stream_wildcard_mentioned`. @topic mentions were not available prior to this feature level.
stream_wildcard_mentioned Whether this message contained a stream wildcard mention like @**all**. Cannot be changed by the user directly, but can change if the message is edited to add/remove a stream wildcard mention. **Changes**: New in Zulip 8.0 (feature level 224).
topic_wildcard_mentioned Whether this message contained a topic wildcard mention (@**topic**). Cannot be changed by the user directly, but can change if the message is edited to add/remove a topic wildcard mention. **Changes**: New in Zulip 8.0 (feature level 224).
has_alert_word Whether the message contains any of the current user's configured alert words. Cannot be changed by the user directly, but can change if the message is edited to add/remove one of the current user's alert words.
historical Is `true` for messages that the user did not receive at the time they were sent but later was added to the user's history (E.g. because they starred or reacted to a message sent to a public stream before they subscribed to that stream). Cannot be changed by the user directly.

Response

Return values

  • messages: (integer)[]

    An array with the IDs of the modified messages.

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:

{
    "messages": [
        4,
        18,
        15
    ],
    "msg": "",
    "result": "success"
}