Update personal message flags for narrow
POST https://lampo-dev.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://lampo-dev.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
}