Zulip scheduled_messages API
The scheduled_messages API from Zulip — 2 operation(s) for scheduled_messages.
OpenAPI Specification
openapi: 3.0.1
info:
version: 1.0.0
title: Zulip REST authentication scheduled_messages API
description: 'Powerful open source group chat
'
contact:
url: https://zulip.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://{subdomain}.zulipchat.com/api/v1
variables:
subdomain:
default: example
- url: '{server}/api/v1'
variables:
server:
default: https://
- url: https://chat.zulip.org/api/v1
- url: http://localhost:9991/api/v1
- url: http://{subdomain}.testserver/json
security:
- basicAuth: []
tags:
- name: scheduled_messages
paths:
/scheduled_messages:
get:
operationId: get-scheduled-messages
tags:
- scheduled_messages
summary: Get scheduled messages
description: 'Fetch all [scheduled messages](/help/schedule-a-message) for
the current user.
Scheduled messages are messages the user has scheduled to be
sent in the future via the send later feature.
**Changes**: New in Zulip 7.0 (feature level 173).
'
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccessBase'
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
scheduled_messages:
type: array
description: 'Returns all of the current user''s undelivered scheduled
messages, ordered by `scheduled_delivery_timestamp`
(ascending).
'
items:
$ref: '#/components/schemas/ScheduledMessage'
example:
result: success
msg: ''
scheduled_messages:
- scheduled_message_id: 27
to: 14
type: stream
content: Hi
rendered_content: <p>Hi</p>
topic: Introduction
scheduled_delivery_timestamp: 1681662420
failed: false
post:
operationId: create-scheduled-message
tags:
- scheduled_messages
summary: Create a scheduled message
description: 'Create a new [scheduled message](/help/schedule-a-message).
**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.
New in Zulip 7.0 (feature level 179).
'
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
type:
description: '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.
'
type: string
enum:
- direct
- channel
- stream
- private
example: direct
to:
description: '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.
'
oneOf:
- type: integer
- type: array
items:
type: integer
minLength: 1
example:
- 9
- 10
content:
$ref: '#/components/schemas/RequiredContent'
topic:
description: '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`](/api/register-queue) endpoint to determine
the maximum topic length.
Note: When `"(no topic)"` or the value of `realm_empty_topic_display_name`
found in the [POST /register](/api/register-queue) response is used for this
parameter, it is interpreted as an empty string.
When [topics are required](/help/require-topics), this parameter can''t
be `"(no topic)"`, an empty string, or the value of `realm_empty_topic_display_name`.
**Changes**: Before Zulip 10.0 (feature level 370), `"(no topic)"`
was not interpreted as an empty string.
Before Zulip 10.0 (feature level 334), empty string
was not a valid topic name for channel messages.
'
type: string
example: Castle
scheduled_delivery_timestamp:
type: integer
description: 'The UNIX timestamp for when the message will be sent,
in UTC seconds.
'
example: 3165826990
read_by_sender:
type: boolean
description: '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).
'
example: true
required:
- type
- to
- content
- scheduled_delivery_timestamp
encoding:
to:
contentType: application/json
scheduled_delivery_timestamp:
contentType: application/json
read_by_sender:
contentType: application/json
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccessBase'
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
scheduled_message_id:
type: integer
description: 'The unique ID of the scheduled message.
This is different from the unique ID that the message will have
after it is sent.
'
example:
msg: ''
scheduled_message_id: 42
result: success
'400':
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: '#/components/schemas/NonExistingChannelIdError'
- description: 'A typical failed JSON response for when a channel message is scheduled
to be sent to a channel 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
requestBody:
required: false
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
type:
description: 'The type of scheduled message to be sent. `"direct"` for a direct
message and `"stream"` or `"channel"` for a channel 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"`/`"channel"`, then the `topic` parameter is also required.
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.
'
type: string
enum:
- direct
- channel
- stream
- private
example: stream
to:
description: '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.
Required when updating the `type` of the scheduled message.
'
oneOf:
- type: integer
- type: array
items:
type: integer
minLength: 1
example: 11
content:
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.
'
type: string
example: Hello
topic:
description: 'The updated topic of the scheduled message.
Required when updating the `type` of the scheduled message to
`"stream"` or `"channel"`. 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.
Note: When `"(no topic)"` or the value of `realm_empty_topic_display_name`
found in the [POST /register](/api/register-queue) response is used for this
parameter, it is interpreted as an empty string.
When [topics are required](/help/require-topics), this parameter can''t
be `"(no topic)"`, an empty string, or the value of `realm_empty_topic_display_name`.
**Changes**: Before Zulip 10.0 (feature level 370), `"(no topic)"`
was not interpreted as an empty string.
Before Zulip 10.0 (feature level 334), empty string
was not a valid topic name for channel messages.
'
type: string
example: Castle
scheduled_delivery_timestamp:
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
encoding:
to:
contentType: application/json
scheduled_delivery_timestamp:
contentType: application/json
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccessBase'
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
example:
result: success
msg: ''
'400':
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: '#/components/schemas/NonExistingChannelIdError'
- description: 'A typical failed JSON response for when a channel message is scheduled
to be sent to a channel 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:
'
'404':
description: Not Found.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CodedError'
- description: 'A typical failed JSON response for when no scheduled message exists
with the provided ID:
'
example:
code: BAD_REQUEST
result: error
msg: Scheduled message does not exist
delete:
operationId: delete-scheduled-message
tags:
- scheduled_messages
summary: Delete a scheduled message
description: 'Delete, and therefore cancel sending, a previously [scheduled
message](/help/schedule-a-message).
**Changes**: New in Zulip 7.0 (feature level 173).
'
parameters:
- name: scheduled_message_id
in: path
schema:
type: integer
description: 'The ID of the scheduled message to delete.
This is different from the unique ID that the message would have
after being sent.
'
required: true
example: 1
responses:
'200':
$ref: '#/components/responses/SimpleSuccess'
'404':
description: Not Found.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CodedError'
- description: 'A typical failed JSON response for when no scheduled message exists
with the provided ID:
'
example:
code: BAD_REQUEST
result: error
msg: Scheduled message does not exist
components:
schemas:
JsonSuccessBase:
description: '**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`][ignored_params] array.
A typical successful JSON response may look like:
[ignored_params]: /api/rest-error-handling#ignored-parameters
'
allOf:
- $ref: '#/components/schemas/JsonResponseBase'
- required:
- result
- msg
properties:
result:
enum:
- success
msg:
type: string
ignored_parameters_unsupported:
$ref: '#/components/schemas/IgnoredParametersUnsupported'
NonExistingChannelIdError:
allOf:
- $ref: '#/components/schemas/CodedErrorBase'
- additionalProperties: false
properties:
result: {}
msg: {}
code: {}
stream_id:
type: integer
description: 'The channel ID that could not be found.
'
example:
code: STREAM_DOES_NOT_EXIST
msg: Channel with ID '9' does not exist
result: error
stream_id: 9
RequiredContent:
description: 'The content of the message.
Clients should use the `max_message_length` returned by the
[`POST /register`](/api/register-queue) endpoint to determine
the maximum message size.
'
type: string
example: Hello
JsonSuccess:
allOf:
- $ref: '#/components/schemas/JsonSuccessBase'
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
example:
msg: ''
result: success
ScheduledMessageBase:
type: object
description: 'Object containing details of the scheduled message.
'
properties:
scheduled_message_id:
type: integer
description: 'The unique ID of the scheduled message, which can be used to
modify or delete the scheduled message.
This is different from the unique ID that the message will have
after it is sent.
'
type:
type: string
description: 'The type of the scheduled message. Either `"stream"` or `"private"`.
'
enum:
- stream
- private
to:
oneOf:
- type: integer
- type: array
items:
type: integer
description: 'The scheduled message''s tentative target audience.
For channel messages, it will be the unique ID of the target
channel. For direct messages, it will be an array with the
target users'' IDs.
'
topic:
type: string
description: 'Only present if `type` is `"stream"`.
The topic for the channel message.
'
content:
type: string
description: 'The content/body of the scheduled message, in [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format.
See [Markdown message formatting](/api/message-formatting) for details on Zulip''s HTML format.
'
rendered_content:
type: string
description: 'The content/body of the scheduled message rendered in HTML.
'
scheduled_delivery_timestamp:
type: integer
description: 'The UNIX timestamp for when the message will be sent
by the server, in UTC seconds.
'
example: 1595479019
failed:
type: boolean
description: 'Whether the server has tried to send the scheduled message
and it failed to successfully send.
Clients that support unscheduling and editing scheduled messages
should display scheduled messages with `"failed": true` with an
indicator that the server failed to send the message at the
scheduled time, so that the user is aware of the failure and can
get the content of the scheduled message.
**Changes**: New in Zulip 7.0 (feature level 181).
'
additionalProperties: false
required:
- scheduled_message_id
- type
- to
- content
- rendered_content
- scheduled_delivery_timestamp
- failed
IgnoredParametersUnsupported:
type: array
items:
type: string
description: 'An array of any parameters sent in the request that are not
supported by the endpoint.
See [error handling](/api/rest-error-handling#ignored-parameters) documentation
for details on this and its change history.
'
JsonResponseBase:
type: object
properties:
result:
type: string
ScheduledMessage:
allOf:
- $ref: '#/components/schemas/ScheduledMessageBase'
- additionalProperties: false
properties:
scheduled_message_id: {}
type: {}
to: {}
topic: {}
content: {}
rendered_content: {}
scheduled_delivery_timestamp: {}
failed: {}
CodedError:
allOf:
- $ref: '#/components/schemas/CodedErrorBase'
- additionalProperties: false
properties:
result: {}
msg: {}
code: {}
CodedErrorBase:
allOf:
- $ref: '#/components/schemas/JsonResponseBase'
- required:
- result
- msg
- code
properties:
result:
enum:
- error
msg:
type: string
code:
type: string
description: 'A string that identifies the error.
'
responses:
SimpleSuccess:
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/JsonSuccess'
securitySchemes:
BasicAuth:
type: http
scheme: basic
description: 'Basic authentication, with the user''s email as the username, and the API
key as the password. The API key can be fetched using the
`/fetch_api_key` or `/dev_fetch_api_key` endpoints.
'