diff --git a/api_docs/changelog.md b/api_docs/changelog.md index 7af7179b7a..fb8ec78db2 100644 --- a/api_docs/changelog.md +++ b/api_docs/changelog.md @@ -20,6 +20,15 @@ format used by the Zulip server that they are interacting with. ## Changes in Zulip 7.0 +**Feature level 184** + +* [`PATCH /scheduled_messages/`](/api/update-scheduled-message): + Added new endpoint for editing an existing scheduled message. +* [`POST /scheduled_messages`](/api/create-scheduled-message): + Removed optional `scheduled_message_id` parameter, which had + been a previous way for clients to support editing an existing + scheduled message. + **Feature level 183** * [`POST /register`](/api/register-queue): Removed the @@ -56,7 +65,7 @@ format used by the Zulip server that they are interacting with. **Feature level 179** -* [`POST /scheduled_messages`](/api/create-or-update-scheduled-message): +* [`POST /scheduled_messages`](/api/create-scheduled-message): Added new endpoint to create and edit scheduled messages. * [`GET /events`](/api/get-events): Added `scheduled_messages` events sent to clients when a user creates, diff --git a/api_docs/create-or-update-scheduled-messages.md b/api_docs/create-scheduled-message.md similarity index 57% rename from api_docs/create-or-update-scheduled-messages.md rename to api_docs/create-scheduled-message.md index 32386958cc..6d89d34de1 100644 --- a/api_docs/create-or-update-scheduled-messages.md +++ b/api_docs/create-scheduled-message.md @@ -17,35 +17,17 @@ curl -X POST {{ api_url }}/v1/scheduled_messages \ --data-urlencode type=stream \ --data-urlencode to=9 \ --data-urlencode topic=Hello \ - --data-urlencode 'content=Thank you for' \ + --data-urlencode 'content=Nice to meet everyone!' \ --data-urlencode scheduled_delivery_timestamp=3165826990 -# Update a scheduled stream message -curl -X POST {{ api_url }}/v1/scheduled_messages \ - -u BOT_EMAIL_ADDRESS:BOT_API_KEY \ - --data-urlencode type=stream \ - --data-urlencode to=9 \ - --data-urlencode 'topic=Welcome aboard' \ - --data-urlencode 'content=Thank you for the help!' \ - --data-urlencode scheduled_delivery_timestamp=3165856990 \ - --data-urlencode scheduled_message_id=1 - # Create a scheduled direct message curl -X POST {{ api_url }}/v1/messages \ -u BOT_EMAIL_ADDRESS:BOT_API_KEY \ --data-urlencode type=direct \ --data-urlencode 'to=[9, 10]' \ - --data-urlencode 'content=Can we meet tomorrow?' \ + --data-urlencode 'content=Can we meet on Monday?' \ --data-urlencode scheduled_delivery_timestamp=3165826990 -# Update a scheduled direct message -curl -X POST {{ api_url }}/v1/messages \ - -u BOT_EMAIL_ADDRESS:BOT_API_KEY \ - --data-urlencode type=direct \ - --data-urlencode 'to=[9, 10, 11]' \ - --data-urlencode 'content=Can we meet tomorrow?' \ - --data-urlencode scheduled_delivery_timestamp=3165856990 \ - --data-urlencode scheduled_message_id=2 ``` {end_tabs} diff --git a/api_docs/include/rest-endpoints.md b/api_docs/include/rest-endpoints.md index 73b72b737f..49a631dd0f 100644 --- a/api_docs/include/rest-endpoints.md +++ b/api_docs/include/rest-endpoints.md @@ -20,7 +20,8 @@ #### Scheduled messages * [Get scheduled messages](/api/get-scheduled-messages) -* [Create or edit a scheduled message](/api/create-or-update-scheduled-message) +* [Create a scheduled message](/api/create-scheduled-message) +* [Edit a scheduled message](/api/update-scheduled-message) * [Delete a scheduled message](/api/delete-scheduled-message) #### Drafts diff --git a/version.py b/version.py index fdaa51fc6f..cee1817431 100644 --- a/version.py +++ b/version.py @@ -33,7 +33,7 @@ DESKTOP_WARNING_VERSION = "5.4.3" # Changes should be accompanied by documentation explaining what the # new level means in api_docs/changelog.md, as well as "**Changes**" # entries in the endpoint's documentation in `zulip.yaml`. -API_FEATURE_LEVEL = 183 +API_FEATURE_LEVEL = 184 # Bump the minor PROVISION_VERSION to indicate that folks should provision # only when going from an old version of the code to a newer version. Bump diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml index 7b25410e89..9c939212d3 100644 --- a/zerver/openapi/zulip.yaml +++ b/zerver/openapi/zulip.yaml @@ -5169,19 +5169,18 @@ paths: ], } post: - operationId: create-or-update-scheduled-message + operationId: create-scheduled-message tags: ["scheduled_messages"] - summary: Create or edit scheduled message + summary: Create a scheduled message description: | - Create a new scheduled message or edit an existing scheduled message. + Create a new [scheduled message](/help/schedule-a-message). - The `scheduled_message_id` parameter determines whether a scheduled - message is created or updated. When it is omitted, a new scheduled - message is created. When it is specified, the existing scheduled - message with that unique ID is updated for the values passed to the - other endpoint parameters. + **Changes**: In Zulip 7.0 (feature level 184), moved support for + [editing a scheduled message](/api/update-scheduled-message) to a + separate API endpoint, which removed the `scheduled_message_id` + parameter from this endpoint. - **Changes**: New in Zulip 7.0 (feature level 179). + New in Zulip 7.0 (feature level 179). parameters: - name: type in: query @@ -5235,16 +5234,6 @@ paths: type: string example: Castle allowEmptyValue: true - - name: scheduled_message_id - in: query - schema: - type: integer - description: | - The unique ID of the scheduled message to be updated. - - If omitted, a new scheduled message will be created. Otherwise, - the existing scheduled message with this unique ID will be updated. - example: 1 - name: scheduled_delivery_timestamp in: query schema: @@ -5281,6 +5270,134 @@ paths: "scheduled_message_id": 42, "result": "success", } + "400": + description: Bad request. + content: + application/json: + schema: + oneOf: + - allOf: + - $ref: "#/components/schemas/NonExistingStreamIdError" + - description: | + A typical failed JSON response for when a stream message is scheduled + to be sent to a stream that does not exist: + - allOf: + - $ref: "#/components/schemas/CodedError" + - example: + { + "code": "BAD_REQUEST", + "msg": "Invalid user ID 10", + "result": "error", + } + description: | + A typical failed JSON response for when a direct message is scheduled + to be sent to a user that does not exist: + /scheduled_messages/{scheduled_message_id}: + patch: + operationId: update-scheduled-message + tags: ["scheduled_messages"] + summary: Edit a scheduled message + description: | + Edit an existing [scheduled message](/help/schedule-a-message). + + **Changes**: New in Zulip 7.0 (feature level 184). + parameters: + - name: scheduled_message_id + in: path + schema: + type: integer + description: | + The ID of the scheduled message to update. + + This is different from the unique ID that the message would have + after being sent. + required: true + example: 2 + - name: type + in: query + description: | + The type of scheduled message to be sent. `"direct"` for a direct + message and `"stream"` for a stream message. + + When updating the type of the scheduled message, the `to` parameter + is required. And, if updating the type of the scheduled message to + `"stream"`, then the `topic` parameter is also required. + + In Zulip 7.0 (feature level 174), `"direct"` was added as the + preferred way to indicate the type of a direct message, deprecating + the original `"private"`. While `"private"` is supported for + scheduling direct messages, clients are encouraged to use to the + modern convention because support for `"private"` may eventually + be removed. + schema: + type: string + enum: + - direct + - stream + - private + example: stream + - name: to + in: query + description: | + The scheduled message's tentative target audience. + + For stream messages, the integer ID of the stream. + For direct messages, a list containing integer user IDs. + + Required when updating the `type` of the scheduled message. + content: + application/json: + schema: + oneOf: + - type: integer + - type: array + items: + type: integer + minLength: 1 + example: 8 + - name: content + in: query + description: | + The updated content of the scheduled message. + + Clients should use the `max_message_length` returned by the + [`POST /register`](/api/register-queue) endpoint to determine + the maximum message size. + schema: + type: string + example: Hello + - name: topic + in: query + description: | + The updated topic of the scheduled message. + + Required when updating the `type` of the scheduled message to + `"stream"`. Ignored when the existing or updated `type` of the + scheduled message is `"direct"` (or `"private"`). + + Clients should use the `max_topic_length` returned by the + [`POST /register`](/api/register-queue) endpoint to determine + the maximum topic length. + schema: + type: string + example: Castle + - name: scheduled_delivery_timestamp + in: query + schema: + type: integer + description: | + The UNIX timestamp for when the message will be sent, + in UTC seconds. + + Required when updating a scheduled message that the server + has already tried and failed to send. This state is indicated + with `"failed": true` in `scheduled_messages` objects; see + response description at + [`GET /scheduled_messages`](/api/get-scheduled-messages#response). + example: 3165826990 + responses: + "200": + $ref: "#/components/responses/SimpleSuccess" "400": description: Bad request. content: @@ -5313,7 +5430,6 @@ paths: "result": "error", "msg": "Scheduled message does not exist", } - /scheduled_messages/{scheduled_message_id}: delete: operationId: delete-scheduled-message tags: ["scheduled_messages"] @@ -5331,8 +5447,8 @@ paths: description: | The ID of the scheduled message to delete. - This is different from the unique ID that a message would have - after it was sent. + This is different from the unique ID that the message would have + after being sent. required: true example: 1 responses: