Update personal message flags for narrow
POST https://ppc2021.zulip.cs.aalto.fi/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://ppc2021.zulip.cs.aalto.fi/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).
-
ignored_because_not_subscribed_channels: (integer)[]
Only present if the flag is read and the operation is remove.
Zulip has an invariant that all unread messages must be in channels
the user is subscribed to. This field will contain a list of the
channels whose messages were skipped to mark as unread because the
user is not subscribed to them.
Changes: New in Zulip 10.0 (feature level 355).
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,
"ignored_because_not_subscribed_channels": [
12,
13,
9
],
"last_processed_id": 55,
"msg": "",
"processed_count": 11,
"result": "success",
"updated_count": 8
}