Check if messages match a narrow
GET https://chat.h2t.iar.kit.edu/api/v1/messages/matches_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)
print(result)
curl -sSX GET -G https://chat.h2t.iar.kit.edu/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
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 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.
Response
Return values
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=\"http://foo.com\" target=\"_blank\" title=\"http://foo.com\">http://foo.com</a></p>",
"match_subject": "test_topic"
}
},
"msg": "",
"result": "success"
}