Update personal message flags for narrow
POST https://math187awinter2024.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://math187awinter2024.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: See changes section
of search/narrow filter documentation.
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"
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
}