Create a scheduled message

POST https://vercre.zulipchat.com/api/v1/scheduled_messages

Create a new scheduled message.

Changes: In Zulip 7.0 (feature level 184), moved support for editing a scheduled message to a separate API endpoint, which removed the scheduled_message_id parameter from this endpoint.

New in Zulip 7.0 (feature level 179).

Usage examples

# Create a scheduled channel message
curl -X POST https://vercre.zulipchat.com/api/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=Nice to meet everyone!' \
    --data-urlencode scheduled_delivery_timestamp=3165826990

# Create a scheduled direct message
curl -X POST https://vercre.zulipchat.com/api/v1/messages \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode type=direct \
    --data-urlencode 'to=[9, 10]' \
    --data-urlencode 'content=Can we meet on Monday?' \
    --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" or "channel" for a channel message.

Note that, while "private" is supported for scheduling direct messages, clients are encouraged to use to the modern convention of "direct" to indicate this message type, because support for "private" may eventually be removed.

Changes: In Zulip 9.0 (feature level 248), "channel" was added as an additional value for this parameter to indicate the type of a channel message.

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


to integer | (integer)[] required

Example: [9, 10]

The scheduled message's tentative target audience.

For channel messages, the integer ID of the channel. 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 channel messages ("type": "stream" or "type": "channel"), ignored otherwise.

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


scheduled_delivery_timestamp integer required

Example: 3165826990

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


read_by_sender boolean optional

Example: true

Whether the message should be initially marked read by its sender. If unspecified, the server uses a heuristic based on the client name and the recipient.

Changes: New in Zulip 8.0 (feature level 236).


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 channel message is scheduled to be sent to a channel that does not exist:

{
    "code": "STREAM_DOES_NOT_EXIST",
    "msg": "Channel 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"
}