Check if messages match a narrow

Check whether a set of messages match a narrow.

GET https://chat.outreachy.org/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://chat.outreachy.org/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"}]'

Parameters

Response

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

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"
}