mirror of
https://github.com/zulip/zulip.git
synced 2025-10-22 20:42:14 +00:00
api-docs: Update descriptive uses of "stream" for channel rename.
Updates `.md` files in api_docs/ to use "stream" instead of "channel" for descriptive text, with the exception of the API changelog file. Part of stream to channel rename project.
This commit is contained in:
Lauryn Menard
committed by
Tim Abbott
Tim Abbott
parent
acec5108c5
commit
388c6b2412
@@ -1,18 +1,18 @@
|
||||
# Construct a narrow
|
||||
|
||||
A **narrow** is a set of filters for Zulip messages, that can be based
|
||||
on many different factors (like sender, stream, topic, search
|
||||
on many different factors (like sender, channel, topic, search
|
||||
keywords, etc.). Narrows are used in various places in the the Zulip
|
||||
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 to stream `announce`, not sent by
|
||||
It filters for messages sent to channel `announce`, not sent by
|
||||
`iago@zulip.com`, and containing the words `cool` and `sunglasses`:
|
||||
|
||||
```
|
||||
stream:announce -sender:iago@zulip.com cool sunglasses
|
||||
channel:announce -sender:iago@zulip.com cool sunglasses
|
||||
```
|
||||
|
||||
This query would be JSON-encoded for use in the Zulip API using JSON
|
||||
@@ -21,7 +21,7 @@ as a list of simple objects, as follows:
|
||||
```json
|
||||
[
|
||||
{
|
||||
"operator": "stream",
|
||||
"operator": "channel",
|
||||
"operand": "announce"
|
||||
},
|
||||
{
|
||||
@@ -40,7 +40,7 @@ The Zulip help center article on [searching for messages](/help/search-for-messa
|
||||
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`
|
||||
Note that many narrows, including all that lack a `channel` or `channels`
|
||||
operator, search the current user's personal message history. See
|
||||
[searching shared history](/help/search-for-messages#searching-shared-history)
|
||||
for details.
|
||||
@@ -52,7 +52,7 @@ when [adding the `read` flag to a user's personal
|
||||
messages](/api/update-message-flags-for-narrow)).
|
||||
|
||||
**Changes**: In Zulip 9.0 (feature level 250), support was added for
|
||||
two filters related to stream messages: `channel` and `channels`. The
|
||||
two filters related to channel messages: `channel` and `channels`. The
|
||||
`channel` operator is an alias for the `stream` operator. The `channels`
|
||||
operator is an alias for the `streams` operator. Both `channel` and
|
||||
`channels` return the same exact results as `stream` and `streams`
|
||||
@@ -107,13 +107,13 @@ operand for the `id` operator needed to be encoded as a string.
|
||||
]
|
||||
```
|
||||
|
||||
### Stream and user IDs
|
||||
### Channel and user IDs
|
||||
|
||||
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
|
||||
that use either channel IDs or user IDs that are not documented in the
|
||||
help center because they are primarily useful to API clients:
|
||||
|
||||
* `stream:1234`: Search messages sent to the stream with ID `1234`.
|
||||
* `channel:1234`: Search messages sent to the channel with ID `1234`.
|
||||
* `sender:1234`: Search messages sent by user ID `1234`.
|
||||
* `dm:1234`: Search the direct message conversation between
|
||||
you and user ID `1234`.
|
||||
@@ -125,8 +125,8 @@ help center because they are primarily useful to API clients:
|
||||
!!! tip ""
|
||||
|
||||
A user ID can be found by [viewing a user's profile][view-profile]
|
||||
in the web or desktop apps. A stream ID can be found when [browsing
|
||||
streams][browse-streams] in the web or desktop apps.
|
||||
in the web or desktop apps. A channel ID can be found when [browsing
|
||||
channels][browse-channels] in the web or desktop apps.
|
||||
|
||||
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
|
||||
@@ -147,4 +147,4 @@ user 1234, and user 5678, the correct JSON-encoded query is:
|
||||
```
|
||||
|
||||
[view-profile]: /help/view-someones-profile
|
||||
[browse-streams]: /help/introduction-to-channels#browse-and-subscribe-to-channels
|
||||
[browse-channels]: /help/introduction-to-channels#browse-and-subscribe-to-channels
|
||||
|
||||
@@ -11,7 +11,7 @@
|
||||
{tab|curl}
|
||||
|
||||
``` curl
|
||||
# Create a scheduled stream message
|
||||
# Create a scheduled channel message
|
||||
curl -X POST {{ api_url }}/v1/scheduled_messages \
|
||||
-u BOT_EMAIL_ADDRESS:BOT_API_KEY \
|
||||
--data-urlencode type=stream \
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Create a stream
|
||||
# Create a channel
|
||||
|
||||
You can create a stream using Zulip's REST API by submitting a
|
||||
[subscribe](/api/subscribe) request with a stream name that
|
||||
You can create a channel using Zulip's REST API by submitting a
|
||||
[subscribe](/api/subscribe) request with a channel name that
|
||||
doesn't yet exist and passing appropriate parameters to define
|
||||
the initial configuration of the new stream.
|
||||
the initial configuration of the new channel.
|
||||
|
||||
@@ -15,7 +15,7 @@
|
||||
* [Update personal message flags](/api/update-message-flags)
|
||||
* [Update personal message flags for narrow](/api/update-message-flags-for-narrow)
|
||||
* [Mark all messages as read](/api/mark-all-as-read)
|
||||
* [Mark messages in a stream as read](/api/mark-stream-as-read)
|
||||
* [Mark messages in a channel as read](/api/mark-stream-as-read)
|
||||
* [Mark messages in a topic as read](/api/mark-topic-as-read)
|
||||
* [Get a message's read receipts](/api/get-read-receipts)
|
||||
|
||||
@@ -33,27 +33,27 @@
|
||||
* [Edit a draft](/api/edit-draft)
|
||||
* [Delete a draft](/api/delete-draft)
|
||||
|
||||
#### Streams
|
||||
#### Channels
|
||||
|
||||
* [Get subscribed streams](/api/get-subscriptions)
|
||||
* [Subscribe to a stream](/api/subscribe)
|
||||
* [Unsubscribe from a stream](/api/unsubscribe)
|
||||
* [Get subscribed channels](/api/get-subscriptions)
|
||||
* [Subscribe to a channel](/api/subscribe)
|
||||
* [Unsubscribe from a channel](/api/unsubscribe)
|
||||
* [Get subscription status](/api/get-subscription-status)
|
||||
* [Get all subscribers](/api/get-subscribers)
|
||||
* [Update subscription settings](/api/update-subscription-settings)
|
||||
* [Get all streams](/api/get-streams)
|
||||
* [Get a stream by ID](/api/get-stream-by-id)
|
||||
* [Get stream ID](/api/get-stream-id)
|
||||
* [Create a stream](/api/create-stream)
|
||||
* [Update a stream](/api/update-stream)
|
||||
* [Archive a stream](/api/archive-stream)
|
||||
* [Get stream's email address](/api/get-stream-email-address)
|
||||
* [Get topics in a stream](/api/get-stream-topics)
|
||||
* [Get all channels](/api/get-streams)
|
||||
* [Get a channel by ID](/api/get-stream-by-id)
|
||||
* [Get channel ID](/api/get-stream-id)
|
||||
* [Create a channel](/api/create-stream)
|
||||
* [Update a channel](/api/update-stream)
|
||||
* [Archive a channel](/api/archive-stream)
|
||||
* [Get channel's email address](/api/get-stream-email-address)
|
||||
* [Get topics in a channel](/api/get-stream-topics)
|
||||
* [Topic muting](/api/mute-topic)
|
||||
* [Update personal preferences for a topic](/api/update-user-topic)
|
||||
* [Delete a topic](/api/delete-topic)
|
||||
* [Add a default stream](/api/add-default-stream)
|
||||
* [Remove a default stream](/api/remove-default-stream)
|
||||
* [Add a default channel](/api/add-default-stream)
|
||||
* [Remove a default channel](/api/remove-default-stream)
|
||||
|
||||
#### Users
|
||||
|
||||
|
||||
@@ -137,7 +137,7 @@ below are for a webhook named `MyWebHook`.
|
||||
* Integrations that don't match a team's workflow can often be
|
||||
uselessly spammy. Give careful thought to providing options for
|
||||
triggering Zulip messages only for certain message types, certain
|
||||
projects, or sending different messages to different streams/topics,
|
||||
projects, or sending different messages to different channels/topics,
|
||||
to make it easy for teams to configure the integration to support
|
||||
their workflow.
|
||||
|
||||
@@ -180,20 +180,20 @@ bot's API key, see the [API keys](/api/api-keys) documentation.
|
||||
|
||||
### stream
|
||||
|
||||
The stream for the integration to send notifications to. Can be either
|
||||
the stream ID or the [URL-encoded][url-encoder] stream name. By default
|
||||
The channel for the integration to send notifications to. Can be either
|
||||
the channel ID or the [URL-encoded][url-encoder] channel name. By default
|
||||
the integration will send direct messages to the bot's owner.
|
||||
|
||||
!!! tip ""
|
||||
|
||||
A stream ID can be found when [browsing streams][browse-streams]
|
||||
A channel ID can be found when [browsing channels][browse-channels]
|
||||
in the web or desktop apps.
|
||||
|
||||
### topic
|
||||
|
||||
The topic in the specified stream for the integration to send
|
||||
The topic in the specified channel for the integration to send
|
||||
notifications to. The topic should also be [URL-encoded][url-encoder].
|
||||
By default the integration will have a topic configured for stream
|
||||
By default the integration will have a topic configured for channel
|
||||
messages.
|
||||
|
||||
### only_events, exclude_events
|
||||
@@ -212,7 +212,7 @@ For example, `test*` matches every event that starts with `test`.
|
||||
For a list of supported events, see a specific [integration's
|
||||
documentation](/integrations) page.
|
||||
|
||||
[browse-streams]: /help/introduction-to-channels#browse-and-subscribe-to-channels
|
||||
[browse-channels]: /help/introduction-to-channels#browse-and-subscribe-to-channels
|
||||
[add-bot]: /help/add-a-bot-or-integration
|
||||
[url-encoder]: https://www.urlencoder.org/
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
Below, we explain each part of a simple incoming webhook integration,
|
||||
called **Hello World**. This integration sends a "hello" message to the `test`
|
||||
stream and includes a link to the Wikipedia article of the day, which
|
||||
channel and includes a link to the Wikipedia article of the day, which
|
||||
it formats from json data it receives in the http request.
|
||||
|
||||
Use this walkthrough to learn how to write your first webhook
|
||||
@@ -151,7 +151,7 @@ define additional parameters using the `REQ` object.
|
||||
In the example above, we have defined `payload` which is populated
|
||||
from the body of the http request, `stream` with a default of `test`
|
||||
(available by default in the Zulip development environment), and
|
||||
`topic` with a default of `Hello World`. If your webhook uses a custom stream,
|
||||
`topic` with a default of `Hello World`. If your webhook uses a custom channel,
|
||||
it must exist before a message can be created in it. (See
|
||||
[Step 4: Create automated tests](#step-5-create-automated-tests) for how to handle this in tests.)
|
||||
|
||||
@@ -170,7 +170,7 @@ link to the Wikipedia article of the day as provided by the json payload.
|
||||
Then we send a message with `check_send_webhook_message`, which will
|
||||
validate the message and do the following:
|
||||
|
||||
* Send a public (stream) message if the `stream` query parameter is
|
||||
* Send a public (channel) message if the `stream` query parameter is
|
||||
specified in the webhook URL.
|
||||
* If the `stream` query parameter isn't specified, it will send a direct
|
||||
message to the owner of the webhook bot.
|
||||
@@ -350,12 +350,12 @@ class HelloWorldHookTests(WebhookTestCase):
|
||||
In the above example, `CHANNEL_NAME`, `URL_TEMPLATE`, and `WEBHOOK_DIR_NAME` refer
|
||||
to class attributes from the base class, `WebhookTestCase`. These are needed by
|
||||
the helper function `check_webhook` to determine how to execute
|
||||
your test. `CHANNEL_NAME` should be set to your default stream. If it doesn't exist,
|
||||
your test. `CHANNEL_NAME` should be set to your default channel. If it doesn't exist,
|
||||
`check_webhook` will create it while executing your test.
|
||||
|
||||
If your test expects a stream name from a test fixture, the value in the fixture
|
||||
If your test expects a channel name from a test fixture, the value in the fixture
|
||||
and the value you set for `CHANNEL_NAME` must match. The test helpers use `CHANNEL_NAME`
|
||||
to create the destination stream, and then create the message to send using the
|
||||
to create the destination channel, and then create the message to send using the
|
||||
value from the fixture. If these don't match, the test will fail.
|
||||
|
||||
`URL_TEMPLATE` defines how the test runner will call your incoming webhook, in the same way
|
||||
@@ -438,9 +438,9 @@ Second, you need to write the actual documentation content in
|
||||
```md
|
||||
Learn how Zulip integrations work with this simple Hello World example!
|
||||
|
||||
1. The Hello World webhook will use the `test` stream, which is created
|
||||
1. The Hello World webhook will use the `test` channel, which is created
|
||||
by default in the Zulip development environment. If you are running
|
||||
Zulip in production, you should make sure that this stream exists.
|
||||
Zulip in production, you should make sure that this channel exists.
|
||||
|
||||
1. {!create-an-incoming-webhook.md!}
|
||||
|
||||
@@ -531,7 +531,7 @@ def test_unknown_action_no_data(self) -> None:
|
||||
# we are testing. The value of result is the error message the webhook should
|
||||
# return if no params are sent. The fixture for this test is an empty file.
|
||||
|
||||
# subscribe to the target stream
|
||||
# subscribe to the target channel
|
||||
self.subscribe(self.test_user, self.CHANNEL_NAME)
|
||||
|
||||
# post to the webhook url
|
||||
@@ -550,7 +550,7 @@ setup it would have done, and check the result yourself.
|
||||
|
||||
Here, `subscribe_to_stream` is a test helper that uses `TEST_USER_EMAIL` and
|
||||
`CHANNEL_NAME` (attributes from the base class) to register the user to receive
|
||||
messages in the given stream. If the stream doesn't exist, it creates it.
|
||||
messages in the given channel. If the channel doesn't exist, it creates it.
|
||||
|
||||
`client_post`, another helper, performs the HTTP POST that calls the incoming
|
||||
webhook. As long as `self.url` is correct, you don't need to construct the webhook
|
||||
|
||||
@@ -34,7 +34,7 @@ Zulip.
|
||||
[Slack-compatible webhook API](/integrations/slack/slack_incoming).
|
||||
|
||||
* If the product can send email notifications, you can
|
||||
[send those emails to a stream](/help/message-a-channel-by-email).
|
||||
[send those emails to a channel](/help/message-a-channel-by-email).
|
||||
|
||||
## Write your own integration
|
||||
|
||||
|
||||
@@ -52,4 +52,4 @@ inconsistent syntax, were removed.
|
||||
[help-spoilers]: /help/spoilers
|
||||
[help-global-time]: /help/global-times
|
||||
[help-mentions]: /help/mention-a-user-or-group
|
||||
[help-mention-all]: /help/mention-a-user-or-group#mention-everyone-on-a-stream
|
||||
[help-mention-all]: /help/mention-a-user-or-group#mention-everyone-on-a-channel
|
||||
|
||||
@@ -29,8 +29,8 @@ To register an outgoing webhook:
|
||||
|
||||
There are currently two ways to trigger an outgoing webhook:
|
||||
|
||||
* **@-mention** the bot user in a stream. If the bot replies, its
|
||||
reply will be sent to that stream and topic.
|
||||
* **@-mention** the bot user in a channel. If the bot replies, its
|
||||
reply will be sent to that channel and topic.
|
||||
* **Send a direct message** with the bot as one of the recipients.
|
||||
If the bot replies, its reply will be sent to that thread.
|
||||
|
||||
@@ -124,11 +124,11 @@ Here's how we fill in the fields that a Slack-format webhook expects:
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>channel_id</code></td>
|
||||
<td>Stream ID prefixed by "C"</td>
|
||||
<td>Channel ID prefixed by "C"</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>channel_name</code></td>
|
||||
<td>Stream name</td>
|
||||
<td>Channel name</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>thread_ts</code></td>
|
||||
|
||||
@@ -4,7 +4,7 @@ Zulip's real-time events API lets you write software that reacts
|
||||
immediately to events happening in Zulip. This API is what powers the
|
||||
real-time updates in the Zulip web and mobile apps. As a result, the
|
||||
events available via this API cover all changes to data displayed in
|
||||
the Zulip product, from new messages to stream descriptions to
|
||||
the Zulip product, from new messages to channel descriptions to
|
||||
emoji reactions to changes in user or organization-level settings.
|
||||
|
||||
## Using the events API
|
||||
|
||||
@@ -76,7 +76,7 @@ event](/api/get-events#realm_user-add), and the
|
||||
Many areas of Zulip are customizable by the roles
|
||||
above, such as (but not limited to) [restricting message editing and
|
||||
deletion](/help/restrict-message-editing-and-deletion) and
|
||||
[streams permissions](/help/channel-permissions). The potential
|
||||
[channels permissions](/help/channel-permissions). The potential
|
||||
permission levels are:
|
||||
|
||||
* Everyone / Any user including Guests (least restrictive)
|
||||
|
||||
@@ -43,7 +43,7 @@ You'll need:
|
||||
INFO:root:starting message handling...
|
||||
|
||||
1. Test your setup by [starting a new direct message](/help/starting-a-new-direct-message)
|
||||
with the bot or [mentioning](/help/mention-a-user-or-group) the bot on a stream.
|
||||
with the bot or [mentioning](/help/mention-a-user-or-group) the bot on a channel.
|
||||
|
||||
!!! tip ""
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@
|
||||
{tab|curl}
|
||||
|
||||
``` curl
|
||||
# For stream messages
|
||||
# For channel messages
|
||||
curl -X POST {{ api_url }}/v1/messages \
|
||||
-u BOT_EMAIL_ADDRESS:BOT_API_KEY \
|
||||
--data-urlencode type=stream \
|
||||
@@ -34,7 +34,7 @@ You can use `zulip-send`
|
||||
the command-line, providing the message content via STDIN.
|
||||
|
||||
```bash
|
||||
# For stream messages
|
||||
# For channel messages
|
||||
zulip-send --stream Denmark --subject Castle \
|
||||
--user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5
|
||||
|
||||
|
||||
@@ -191,7 +191,7 @@ def usage(self):
|
||||
This plugin will allow users to flag messages
|
||||
as being follow-up items. Users should preface
|
||||
messages with "@followup".
|
||||
Before running this, make sure to create a stream
|
||||
Before running this, make sure to create a channel
|
||||
called "followup" that your API user can send to.
|
||||
'''
|
||||
```
|
||||
@@ -247,7 +247,7 @@ about where the message is sent to.
|
||||
```python
|
||||
bot_handler.send_message(dict(
|
||||
type='stream', # can be 'stream' or 'private'
|
||||
to=stream_name, # either the stream name or user's email
|
||||
to=channel_name, # either the channel name or user's email
|
||||
subject=subject, # message subject
|
||||
content=message, # content of the sent message
|
||||
))
|
||||
|
||||
Reference in New Issue
Block a user