Check messages match narrow

Check whether a set of messages match a narrow.

GET https://zulip.dioco.io/api/v1/messages/matches_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 of GET /messages, 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 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
)
print(result)

curl -sSX GET -G https://zulip.dioco.io/api/v1/messages/matches_narrow \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode msg_ids='[31, 32]' \
    --data-urlencode narrow='[{"operand": "link", "operator": "has"}]'

Arguments

Response

Return values

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

  • 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: 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: 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

A typical successful JSON response may look like:

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