diff --git a/templates/zerver/api/update-subscription-properties.md b/templates/zerver/api/update-subscription-properties.md new file mode 100644 index 0000000000..2006781f85 --- /dev/null +++ b/templates/zerver/api/update-subscription-properties.md @@ -0,0 +1,71 @@ +# Update subscription properties + +This endpoint is used to update the user's personal settings for the +streams they are subscribed to, including muting, color, pinning, and +per-stream notification settings. + +`POST {{ api_url }}/v1/users/me/subscriptions/properties` + +## Usage examples + +
+ +
+ +
+ +``` +curl -X POST {{ api_url }}/v1/users/me/subscriptions/properties \ + -u BOT_EMAIL_ADDRESS:BOT_API_KEY \ + -d 'subscription_data=[{"stream_id": 1, \ + "property": "pin_to_top", \ + "value": true}, \ + {"stream_id": 3, \ + "property": "color", \ + "value": 'f00'}]' +``` + +
+ +
+ +{generate_code_example(python)|/users/me/subscriptions/properties:post|example} + +
+ +
+ +
+ +## Arguments + +{generate_api_arguments_table|zulip.yaml|/users/me/subscriptions/properties:post} + +The possible values for each `property` and `value` pairs are: + +* `color` (string): the hex value of the user's display color for the stream. +* `in_home_view` (boolean): whether the stream should be visible in the home + view (`true`) or muted and thus hidden from the home view (`false`). +* `pin_to_top` (boolean): whether to pin the stream at the top of the stream list. +* `desktop_notifications` (boolean): whether to show desktop notifications + for all messages sent to the stream. +* `audible_notifications` (boolean): whether to play a sound + notification for all messages sent to the stream. +* `push_notifications` (boolean): whether to trigger a mobile push + notification for all messages sent to the stream. + +## Response + +#### Return values + +* `subscription_data`: The same `subscription_data` object sent by the client + for the request, confirming the changes made. + +#### Example response + +A typical successful JSON response may look like: + +{generate_code_example|/users/me/subscriptions/properties:post|fixture(200)} diff --git a/templates/zerver/help/include/rest-endpoints.md b/templates/zerver/help/include/rest-endpoints.md index 3207ab701b..e3380e0a2d 100644 --- a/templates/zerver/help/include/rest-endpoints.md +++ b/templates/zerver/help/include/rest-endpoints.md @@ -17,6 +17,7 @@ * [Get all streams](/api/get-all-streams) * [Get subscribed streams](/api/get-subscribed-streams) * [Add subscriptions](/api/add-subscriptions) +* [Update subscription settings](/api/update-subscription-properties) * [Remove subscriptions](/api/remove-subscriptions) * [Get topics in a stream](/api/get-stream-topics) * [Topic muting](/api/mute-topics) diff --git a/zerver/lib/api_test_helpers.py b/zerver/lib/api_test_helpers.py index 44afc84c0f..1c8921d2cd 100644 --- a/zerver/lib/api_test_helpers.py +++ b/zerver/lib/api_test_helpers.py @@ -374,6 +374,28 @@ def mark_topic_as_read(client): validate_against_openapi_schema(result, '/mark_stream_as_read', 'post', '200') +def update_subscription_settings(client): + # type: (Client) -> None + + # {code_example|start} + # Update the user's subscription in stream #1 to pin it to the top of the + # stream list; and in stream #3 to have the hex color "f00" + request = [{ + 'stream_id': 1, + 'property': 'pin_to_top', + 'value': True + }, { + 'stream_id': 3, + 'property': 'color', + 'value': 'f00' + }] + result = client.update_subscription_settings(request) + # {code_example|end} + + validate_against_openapi_schema(result, + '/users/me/subscriptions/properties', + 'POST', '200') + def render_message(client): # type: (Client) -> None @@ -759,6 +781,7 @@ TEST_FUNCTIONS = { '/users/{email}/presence:get': get_user_presence, '/users/me/subscriptions:delete': remove_subscriptions, '/users/me/subscriptions/muted_topics:patch': toggle_mute_topic, + '/users/me/subscriptions/properties:post': update_subscription_settings, '/users:get': get_members, '/realm/emoji:get': get_realm_emoji, '/realm/filters:get': get_realm_filters, @@ -860,6 +883,7 @@ def test_streams(client, nonadmin_client): get_subscribers(client) remove_subscriptions(client) toggle_mute_topic(client) + update_subscription_settings(client) get_stream_topics(client, 1) test_user_not_authorized_error(nonadmin_client) diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml index c4b0d9ed6e..d2d48c8187 100644 --- a/zerver/openapi/zulip.yaml +++ b/zerver/openapi/zulip.yaml @@ -1384,6 +1384,58 @@ paths: } } } + /users/me/subscriptions/properties: + post: + description: Make bulk modifications of the subscription properties on + one or more streams the user is subscribed to. + parameters: + - name: subscription_data + in: query + description: A list of objects that describe the changes that should + be applied in each subscription. Each object represents a + subscription, and must have a `stream_id` key that identifies the + stream, as well as the `property` being modified and its new + `value`. + schema: + type: array + items: + type: object + example: [{"stream_id": 1, "property": "pin_to_top", "value": true}] + required: true + security: + - basicAuth: [] + responses: + '200': + description: Success. + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/JsonSuccess' + - properties: + subscription_data: + type: array + items: + type: object + description: The same `subscription_data` object sent + by the client for the request. + - example: + { + "subscription_data": [ + { + "property": "pin_to_top", + "value": true, + "stream_id": 1 + }, + { + "property": "color", + "value": 'f00', + "stream_id": 3 + } + ], + "result": "success", + "msg": "" + } /realm/filters: get: description: Fetch all the filters set up for the user's organization.