api-docs: Document create/edit scheduled message endpoint and events.

Adds API changelog update for the new endpoint added for creating
or editing scheduled messages, for the events sent for scheduled
messages (add, update, delete), and for the `scheduled_messages`
field in the register response.

Adds a specific API markdown documentation file for the create
or update scheduled messages endpoint, so that the parameters in
the cURL examples are accurate for the type of message (direct or
stream) and action (create or edit).

Bumps the API feature level, adds Changes notes to API documentation
and adds the scheduled message endpoints to the API documentation
sidebar.

api_docs/changelog.md

@@ -20,6 +20,17 @@ format used by the Zulip server that they are interacting with.
 
 ## Changes in Zulip 7.0
 
+**Feature level 179**:
+
+* [`POST /scheduled_messages`](/api/create-or-update-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,
+  edits or deletes scheduled messages.
+* [`POST /register`](/api/register-queue):
+  Added an optional `scheduled_messages` field to that includes all
+  of the undelivered scheduled messages for the current user.
+
 **Feature level 178**
 
 * `POST users/me/presence`, [`POST /register`](/api/register-queue),

api_docs/create-or-update-scheduled-messages.md

@@ -0,0 +1,67 @@
+{generate_api_header(/scheduled_messages:post)}
+
+## Usage examples
+
+{start_tabs}
+
+{generate_code_example(python)|/scheduled_messages:post|example}
+
+{generate_code_example(javascript)|/scheduled_messages:post|example}
+
+{tab|curl}
+
+``` curl
+# Create 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=Hello \
+    --data-urlencode 'content=Thank you for' \
+    --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 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}
+
+## Parameters
+
+{generate_api_arguments_table|zulip.yaml|/scheduled_messages:post}
+
+{generate_parameter_description(/scheduled_messages:post)}
+
+## Response
+
+{generate_return_values_table|zulip.yaml|/scheduled_messages:post}
+
+{generate_response_description(/scheduled_messages:post)}
+
+#### Example response(s)
+
+{generate_code_example|/scheduled_messages:post|fixture}

api_docs/include/rest-endpoints.md

@@ -17,6 +17,12 @@
 * [Mark messages as read in bulk](/api/mark-all-as-read)
 * [Get a message's read receipts](/api/get-read-receipts)
 
+#### Scheduled messages
+
+* [Get scheduled messages](/api/get-scheduled-messages)
+* [Create or edit a scheduled message](/api/create-or-update-scheduled-message)
+* [Delete a scheduled message](/api/delete-scheduled-message)
+
 #### Drafts
 
 * [Get drafts](/api/get-drafts)

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 = 178
+API_FEATURE_LEVEL = 179
 
 # 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

zerver/openapi/zulip.yaml

@@ -4435,6 +4435,8 @@ paths:
                               description: |
                                 Event sent to a user's clients when scheduled messages
                                 are created.
+
+                                **Changes**: New in Zulip 7.0 (feature level 179).
                               properties:
                                 id:
                                   $ref: "#/components/schemas/EventIdSchema"
@@ -4475,6 +4477,8 @@ paths:
                               description: |
                                 Event sent to a user's clients when a scheduled message
                                 is edited.
+
+                                **Changes**: New in Zulip 7.0 (feature level 179).
                               properties:
                                 id:
                                   $ref: "#/components/schemas/EventIdSchema"
@@ -4508,6 +4512,8 @@ paths:
                               description: |
                                 Event sent to a user's clients when a scheduled message
                                 is deleted.
+
+                                **Changes**: New in Zulip 7.0 (feature level 179).
                               properties:
                                 id:
                                   $ref: "#/components/schemas/EventIdSchema"
@@ -5144,9 +5150,9 @@ paths:
                           ],
                       }
     post:
-      operationId: create-or-update-scheduled-messages
+      operationId: create-or-update-scheduled-message
       tags: ["scheduled_messages"]
-      summary: Create or edit scheduled messages
+      summary: Create or edit scheduled message
       description: |
         Create a new scheduled message or edit an existing scheduled message.
 
@@ -5155,6 +5161,8 @@ paths:
         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**: New in Zulip 7.0 (feature level 179).
       parameters:
         - name: type
           in: query
@@ -10857,6 +10865,8 @@ paths:
                           Present if `scheduled_messages` is present in `fetch_event_types`.
 
                           An array of all undelivered scheduled messages by the user.
+
+                          **Changes**: New in Zulip 7.0 (feature level 179).
                         items:
                           $ref: "#/components/schemas/ScheduledMessage"
                       muted_topics: