From 6f6c761d80f60f4f6880e1fc24053293848d4da5 Mon Sep 17 00:00:00 2001 From: Tim Abbott Date: Mon, 16 Sep 2019 17:16:44 -0700 Subject: [PATCH] docs: Further expand documentation on using IDs in narrows. These docs had a number of typos, and also didn't fully clarify how to handle lists of integers for `pm-with`. Also makes some tweaks to the user docs to make this clearer as well. Fixes #13167. --- templates/zerver/api/construct-narrow.md | 28 +++++++++++++------- templates/zerver/help/search-for-messages.md | 8 +++--- 2 files changed, 23 insertions(+), 13 deletions(-) diff --git a/templates/zerver/api/construct-narrow.md b/templates/zerver/api/construct-narrow.md index aa24f67f86..e8e001053a 100644 --- a/templates/zerver/api/construct-narrow.md +++ b/templates/zerver/api/construct-narrow.md @@ -42,23 +42,31 @@ 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: -* `pm-with:1234`: Search 1-on-1 messages between you and user ID `1234`. -* `sender:1234`: Search 1-on-1 messages sent by user ID `1234`. -* `stream:1234`: Search 1-on-1 messages sent to the stream with ID `123`. -* `group-pm-with:1234`: Search private messages including the user with ID `1234`. +* `sender:1234`: Search messages sent by user ID `1234`. +* `stream:1234`: Search messages sent to the stream with ID `123`. +* `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`. -For example, to query messages sent by a user 1234 to stream 123, the -correct JSON-encoded query is: +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 +messages sent by a user 1234 to a PM thread with yourself, user 1234, +and user 5678, the correct JSON-encoded query is: ```json [ { - "operator": "sender", - "operand": 1234 + "operator": "pm-with", + "operand": [1234, 5678] }, { - "operator": "stream", - "operand": 123 + "operator": "sender", + "operand": 1234 } ] ``` diff --git a/templates/zerver/help/search-for-messages.md b/templates/zerver/help/search-for-messages.md index 2f0ce13d1d..7ffed051f9 100644 --- a/templates/zerver/help/search-for-messages.md +++ b/templates/zerver/help/search-for-messages.md @@ -26,9 +26,7 @@ Here is the **full list of search operators**. * `stream:design`: Search within the stream `#design`. * `stream:design topic:emoji+picker`: Search within the topic `emoji picker`. * `is:private`: Search all your private messages. -* `pm-with:ada@zulip.com`: Search 1-on-1 messages with Ada. -* `group-pm-with:ada@zulip.com`: Search group private messages that - include Ada. +* `pm-with:ada@zulip.com`: Search 1-on-1 private messages between you and Ada. * `sender:ada@zulip.com`: Search messages sent by Ada. * `sender:me`: Search sent messages. * `near:12345`: Show messages around the message with ID `12345`. @@ -43,6 +41,10 @@ Here is the **full list of search operators**. * `has:link` * `has:image` * `has:attachment` +* `pm-with:ada@zulip.com,bob@zulip.com`: Search private message conversation + between you, Bob, and Ada. +* `group-pm-with:ada@zulip.com,bob@zulip.com`: Search all group + private messages that include Ada and Bob. ## Words and phrases