Update personal message flags

POST https://chat-dev.phy.cam.ac.uk/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

Python
JavaScript
curl

#!/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 messages, given the messages' IDs.
request = {
    "messages": message_ids,
    "op": "add",
    "flag": "read",
}
result = client.update_message_flags(request)
# Remove the "starred" flag from messages, given the messages' 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://chat-dev.phy.cam.ac.uk/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.
`stream_wildcard_mentioned`	Whether this message contained a channel wildcard mention (like @all). Cannot be changed by the user directly, but can change if the message is edited to add/remove a channel 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 channel before they subscribed to that channel). Cannot be changed by the user directly.
`wildcard_mentioned`	Whether this message contained either a channel 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 channel and/or topic wildcard mention. Changes: Deprecated in Zulip 8.0 (feature level 224), 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 supporting older server versions should treat this field as a previous name for the `stream_wildcard_mentioned` flag as topic wildcard mentions were not available prior to this feature level.

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

Zulip homepage

API documentation home

Integrations

Interactive bots (beta)

REST API

Messages

Scheduled messages

Drafts

Channels

Users

Invitations

Server & organizations

Real-time events

Specialty endpoints