Update personal message flags for narrow

POST https://zulip.scsok.io/api/v1/messages/flags/narrow

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

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

Usage examples

curl

curl -sSX POST https://zulip.scsok.io/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"

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
}

Zulip homepage

API documentation home

Integrations

Interactive bots (beta)

REST API

Messages

Scheduled messages

Drafts

Channels

Users

Invitations

Server & organizations

Real-time events