Check if messages match a narrow


Check whether a set of messages match a narrow.

For many common narrows (e.g. a topic), clients can write an efficient client-side check to determine whether a newly arrived message belongs in the view.

This endpoint is designed to allow clients to handle more complex narrows for which the client does not (or in the case of full-text search, cannot) implement this check.

The format of the match_subject and match_content objects is designed to match those returned by the GET /messages endpoint, so that a client can splice these fields into a message object received from GET /events and end up with an extended message object identical to how a GET /messages request for the current narrow would have returned the message.

Usage examples

#!/usr/bin/env python3

import zulip

# Pass the path to your zuliprc file here.
client = zulip.Client(config_file="~/zuliprc")

# Check which messages within an array match a narrow.
request = {
    "msg_ids": msg_ids,
    "narrow": [{"operator": "has", "operand": "link"}],

result = client.call_endpoint(url="messages/matches_narrow", method="GET", request=request)

curl -sSX GET -G \
    --data-urlencode 'msg_ids=[31, 32]' \
    --data-urlencode 'narrow=[{"operand": "link", "operator": "has"}]'


msg_ids (integer)[] required

Example: [31, 32]

List of IDs for the messages to check.

narrow (object)[] required

Example: [{"operator": "has", "operand": "link"}]

A structure defining the narrow to check against. See how to construct a narrow.

Changes: In Zulip 9.0 (feature level 250), narrows gained support for two new filters related to stream 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.


Return values

  • messages: object

    A dictionary with a key for each queried message that matches the narrow, with message IDs as keys and search rendering data as values.

    • message_id: object

      The ID of the message that matches the narrow. No record will be returned for queried messages that do not match the narrow.

      • match_content: string

        HTML content of a queried message that matches the narrow. If the narrow is a search narrow, <span class="highlight"> elements will be included, wrapping the matches for the search keywords.

      • match_subject: string

        HTML-escaped topic of a queried message that matches the narrow. If the narrow is a search narrow, <span class="highlight"> elements will be included wrapping the matches for the search keywords.

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:

    "messages": {
        "31": {
            "match_content": "<p><a href=\"\" target=\"_blank\" title=\"\"></a></p>",
            "match_subject": "test_topic"
    "msg": "",
    "result": "success"