Update personal message flags for narrow

POST https://yourZulipDomain.zulipchat.com/api/v1/messages/flags/narrow

Add or remove personal message flags like read and starred on a range of messages within a narrow.

See also the endpoint for updating flags on specific message IDs.

Changes: New in Zulip 6.0 (feature level 155).

Usage examples

curl -sSX POST https://yourZulipDomain.zulipchat.com/api/v1/messages/flags/narrow \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode anchor=43 \
    --data-urlencode num_before=4 \
    --data-urlencode num_after=8 \
    --data-urlencode 'narrow=[{"operand": "Denmark", "operator": "channel"}]' \
    --data-urlencode op=add \
    --data-urlencode flag=read

Parameters

anchor string required

Example: "43"

Integer message ID to anchor updating of flags. Supports special string values for when the client wants the server to compute the anchor to use:

  • newest: The most recent message.
  • oldest: The oldest message.
  • first_unread: The oldest unread message matching the query, if any; otherwise, the most recent message.

include_anchor boolean optional

Example: false

Whether a message with the specified ID matching the narrow should be included in the update range.

Defaults to true.


num_before integer required

Example: 4

Limit the number of messages preceding the anchor in the update range. The server may decrease this to bound transaction sizes.


num_after integer required

Example: 8

Limit the number of messages following the anchor in the update range. The server may decrease this to bound transaction sizes.


narrow (object | (string)[])[] required

Example: [{"operand": "Denmark", "operator": "channel"}]

The narrow you want update flags within. See how to construct a narrow.

Note that, when adding the read flag to messages, clients should consider including a narrow with the is:unread filter as an optimization. Including that filter takes advantage of the fact that the server has a database index for unread messages.

Changes: In Zulip 9.0 (feature level 250), narrows gained support for two new filters related to channel messages: channel and channels; which are aliases for (and return the same results as) the stream and streams filters respectively.

In Zulip 9.0 (feature level 249), narrows gained support for a new filter, has:reaction, which returns messages with at least one emoji reaction.

In Zulip 7.0 (feature level 177), narrows gained support for three new filters related to direct messages: is:dm, dm and dm-including; replacing and deprecating is:private, pm-with and group-pm-with respectively.

Defaults to [].


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. See available flags.


Response

Return values

  • processed_count: integer

    The number of messages that were within the update range (at most num_before + 1 + num_after).

  • updated_count: integer

    The number of messages where the flag's value was changed (at most processed_count).

  • first_processed_id: integer | null

    The ID of the oldest message within the update range, or null if the range was empty.

  • last_processed_id: integer | null

    The ID of the newest message within the update range, or null if the range was empty.

  • found_oldest: boolean

    Whether the update range reached backward far enough to include very oldest message matching the narrow (used by clients doing a bulk update to decide whether to issue another request anchored at first_processed_id).

  • found_newest: boolean

    Whether the update range reached forward far enough to include very oldest message matching the narrow (used by clients doing a bulk update to decide whether to issue another request anchored at last_processed_id).

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:

{
    "first_processed_id": 35,
    "found_newest": true,
    "found_oldest": false,
    "last_processed_id": 55,
    "msg": "",
    "processed_count": 11,
    "result": "success",
    "updated_count": 8
}