Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

api-docs: Update 'construct-narrow' article. 

Fixes small error in the example at the top of the article, and
adds a short statement about narrows searching the current user's
personal message history with a link to the help center article.

Gives the final section a subheader and adds the two other narrow
operators that take an ID.
This commit is contained in:
Lauryn Menard 2022-10-28 19:42:37 +02:00 committed by Tim Abbott
parent 81f3307da0
commit c4d407e992
1 changed files with 29 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
templates/zerver/api/construct-narrow.md
View File

@ -7,9 +7,9 @@ API (most importantly, in the API for fetching messages).
It is simplest to explain the algorithm for encoding a search as a
narrow using a single example. Consider the following search query
(written as it would be entered in the Zulip web app's search box). It
filters for messages sent on stream `announce`, not sent by
`iago@zulip.com`, and containing the phrase `cool sunglasses`:
(written as it would be entered in the Zulip web app's search box).
It filters for messages sent to stream `announce`, not sent by
`iago@zulip.com`, and containing the words `cool` and `sunglasses`:
```
stream:announce -sender:iago@zulip.com cool sunglasses
@ -36,22 +36,35 @@ as a list of simple objects, as follows:
]
```
The full set of search/narrowing options supported by the Zulip API is
documented in [the Zulip Help Center article on
search](/help/search-for-messages). There are a few additional
options, new in Zulip 2.1, that we don't document there because they
are primarily useful to API clients:
The Zulip help center article on [searching for messages](/help/search-for-messages)
documents the majority of the search/narrow options supported by the
Zulip API.
Note that many narrows, including all that lack a `stream` or `streams`
operator, search the current user's personal message history. See
[searching shared history](/help/search-for-messages#searching-shared-history)
for details.
## Narrows that use IDs
The `near` and `id` operators, documented in the help center, use message
IDs for their operands.
* `near:12345`: Search messages around the message with ID `12345`.
* `id:12345`: Search for only message with ID `12345`.
There are a few additional narrow/search options (new in Zulip 2.1)
that use either stream IDs or user IDs that are not documented in the
help center because they are primarily useful to API clients:
* `sender:1234`: Search messages sent by user ID `1234`.
* `stream:1234`: Search messages sent to the stream with ID `1234`.
* `sender:1234`: Search messages sent by user ID `1234`.
* `pm-with:1234`: Search the private message conversation between
you and user ID `1234`.
* `pm-with:1234,5678`: Search the private message conversation between
you, user ID `1234`, and user ID `5678`.
* `group-pm-with:1234`: Search all (group) private messages that
include user ID `1234`.
* `pm-with:1234,5678`: Search all (group) private messages that
include user ID `1234` and user ID `5678`.
* `group-pm-with:1234`: Search all group private messages that
include you and user ID `1234`.
The operands for these search options must be encoded either as an
integer ID or a JSON list of integer IDs. For example, to query