Create or edit scheduled message

POST https://mylog.connect.xfel.eu/api/v1/scheduled_messages

Create a new scheduled message or edit an existing scheduled 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: New in Zulip 7.0 (feature level 179).

Usage examples

curl -sSX POST https://mylog.connect.xfel.eu/api/v1/scheduled_messages \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode type=direct \
    --data-urlencode 'to=[9, 10]' \
    --data-urlencode content=Hello \
    --data-urlencode topic=Castle \
    --data-urlencode scheduled_message_id=1 \
    --data-urlencode scheduled_delivery_timestamp=3165826990

Parameters

type string required

Example: "direct"

The type of scheduled message to be sent. "direct" for a direct message and "stream" for a stream message.

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.

Must be one of: "direct", "stream", "private".


to integer | (integer)[] required

Example: [9, 10]

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.


content string required

Example: "Hello"

The content of the message.

Clients should use the max_message_length returned by the POST /register endpoint to determine the maximum message size.


topic string optional

Example: "Castle"

The topic of the message. Only required for stream messages ("type": "stream"), ignored otherwise.

Clients should use the max_topic_length returned by the POST /register endpoint to determine the maximum topic length.


scheduled_message_id integer optional

Example: 1

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.


scheduled_delivery_timestamp integer required

Example: 3165826990

The UNIX timestamp for when the message will be sent, in UTC seconds.


Response

Return values

  • scheduled_message_id: integer

    The unique ID of the scheduled message.

    This is different from the unique ID that the message will have after it is sent.

Example response(s)

Changes: As of Zulip 7.0 (feature level 167), if any parameters sent in the request are not supported by this endpoint, a successful JSON response will include an ignored_parameters_unsupported array.

A typical successful JSON response may look like:

{
    "msg": "",
    "result": "success",
    "scheduled_message_id": 42
}

A typical failed JSON response for when a stream message is scheduled to be sent to a stream that does not exist:

{
    "code": "STREAM_DOES_NOT_EXIST",
    "msg": "Stream with ID '9' does not exist",
    "result": "error",
    "stream_id": 9
}

A typical failed JSON response for when a direct message is scheduled to be sent to a user that does not exist:

{
    "code": "BAD_REQUEST",
    "msg": "Invalid user ID 10",
    "result": "error"
}

Example response for when no scheduled message exists with the provided ID.

{
    "code": "BAD_REQUEST",
    "msg": "Scheduled message does not exist",
    "result": "error"
}