mirror of
https://github.com/zulip/zulip.git
synced 2025-10-23 04:52:12 +00:00
6e119842bd
This commit adds new API endpoint to get stream email which is used by the web-app as well to get the email when a user tries to open the stream email modal. The stream email is returned only to the users who have access to it. Specifically for private streams only subscribed users have access to its email. And for public streams, all non-guest users and only subscribed guests have access to its email. All users can access email of web-public streams.
19033 lines
873 KiB
YAML
19033 lines
873 KiB
YAML
# This file contains the API definitions for the Zulip REST API.
|
|
#
|
|
# For details on the OpenAPI specification, see https://swagger.io/specification
|
|
#
|
|
# Our own documentation lives at
|
|
#
|
|
# https://zulip.readthedocs.io/en/latest/documentation/openapi.html
|
|
#
|
|
|
|
openapi: 3.0.1
|
|
info:
|
|
version: 1.0.0
|
|
title: Zulip REST 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:
|
|
# Zulip Cloud
|
|
- url: "https://{subdomain}.zulipchat.com/api/v1"
|
|
variables:
|
|
subdomain:
|
|
default: example
|
|
# Self-hosted
|
|
- url: "{server}/api/v1"
|
|
variables:
|
|
server:
|
|
default: https://
|
|
# chat.zulip.org
|
|
- url: "https://chat.zulip.org/api/v1"
|
|
# Development server
|
|
- url: "http://localhost:9991/api/v1"
|
|
security:
|
|
- basicAuth: []
|
|
#######################
|
|
# Endpoint definitions
|
|
#######################
|
|
paths:
|
|
/fetch_api_key:
|
|
post:
|
|
operationId: fetch-api-key
|
|
summary: Fetch an API key (production)
|
|
tags: ["authentication"]
|
|
description: |
|
|
This API endpoint is used by clients such as the Zulip mobile and
|
|
terminal apps to implement password-based authentication. Given the
|
|
user's Zulip login credentials, it returns a Zulip API key that the client
|
|
can use to make requests as the user.
|
|
|
|
This endpoint is only useful for Zulip servers/organizations with
|
|
EmailAuthBackend or LDAPAuthBackend enabled.
|
|
|
|
The Zulip mobile apps also support SSO/social authentication (GitHub
|
|
auth, Google auth, SAML, etc.) that does not use this endpoint. Instead,
|
|
the mobile apps reuse the web login flow passing the `mobile_flow_otp` in
|
|
a webview, and the credentials are returned to the app (encrypted) via a redirect
|
|
to a `zulip://` URL.
|
|
|
|
!!! warn ""
|
|
|
|
**Note:** If you signed up using passwordless authentication and
|
|
never had a password, you can [reset your password](/help/change-your-password).
|
|
|
|
See the [API keys](/api/api-keys) documentation for more details
|
|
on how to download an API key manually.
|
|
|
|
In a [Zulip development environment](https://zulip.readthedocs.io/en/latest/development/overview.html),
|
|
see also [the unauthenticated variant](/api/dev-fetch-api-key).
|
|
parameters:
|
|
- name: username
|
|
in: query
|
|
description: |
|
|
The username to be used for authentication (typically, the email
|
|
address, but depending on configuration, it could be an LDAP username).
|
|
|
|
See the `require_email_format_usernames` parameter documented in
|
|
[GET /server_settings](/api/get-server-settings) for details.
|
|
schema:
|
|
type: string
|
|
example: iago@zulip.com
|
|
required: true
|
|
- name: password
|
|
in: query
|
|
schema:
|
|
type: string
|
|
example: abcd1234
|
|
description: |
|
|
The user's Zulip password (or LDAP password, if LDAP authentication is in use).
|
|
required: true
|
|
security: []
|
|
responses:
|
|
"200":
|
|
description: |
|
|
Valid credentials the client can use to access the Zulip API:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/ApiKeyResponse"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
/dev_fetch_api_key:
|
|
post:
|
|
operationId: dev-fetch-api-key
|
|
summary: Fetch an API key (development only)
|
|
tags: ["authentication"]
|
|
description: |
|
|
For easy testing of mobile apps and other clients and against Zulip
|
|
development servers, we support fetching a Zulip API key for any user
|
|
on the development server without authentication (so that they can
|
|
implement analogues of the one-click login process available for Zulip
|
|
development servers on the web).
|
|
|
|
!!! warn ""
|
|
|
|
**Note:** This endpoint is only available on Zulip development
|
|
servers; for obvious security reasons it will always return an error
|
|
in a Zulip production server.
|
|
parameters:
|
|
- name: username
|
|
in: query
|
|
description: |
|
|
The email address for the user that owns the API key.
|
|
schema:
|
|
type: string
|
|
example: iago@zulip.com
|
|
required: true
|
|
security: []
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/ApiKeyResponse"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
/events:
|
|
get:
|
|
operationId: get-events
|
|
summary: Get events from an event queue
|
|
tags: ["real_time_events"]
|
|
description: |
|
|
This endpoint allows you to receive new events from
|
|
[a registered event queue](/api/register-queue).
|
|
|
|
Long-lived clients should use the
|
|
`event_queue_longpoll_timeout_seconds` property returned by
|
|
`POST /register` as the client-side HTTP request timeout for
|
|
calls to this endpoint. It is guaranteed to be higher than
|
|
heartbeat frequency and should be respected by clients to
|
|
avoid breaking when heartbeat frequency increases.
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: include
|
|
parameters:
|
|
enum:
|
|
- queue_id
|
|
- last_event_id
|
|
x-parameter-description: |
|
|
!!! warn ""
|
|
|
|
**Note**: The parameters documented above are optional in the sense that
|
|
even if you haven't registered a queue by explicitly requesting the
|
|
`POST /register` endpoint, you could pass the parameters for
|
|
[the `POST /register` endpoint](/api/register-queue) to this
|
|
endpoint and a queue would be registered in the absence of a `queue_id`.
|
|
x-python-examples-extra-imports: ["sys"]
|
|
parameters:
|
|
- $ref: "#/components/parameters/QueueId"
|
|
- name: last_event_id
|
|
in: query
|
|
description: |
|
|
The highest event ID in this queue that you've received and
|
|
wish to acknowledge. See the [code for
|
|
`call_on_each_event`](https://github.com/zulip/python-zulip-api/blob/main/zulip/zulip/__init__.py)
|
|
in the [zulip Python
|
|
module](https://github.com/zulip/python-zulip-api) for an
|
|
example implementation of correctly processing each event
|
|
exactly once.
|
|
schema:
|
|
type: integer
|
|
example: -1
|
|
- name: dont_block
|
|
in: query
|
|
description: |
|
|
Set to `true` if the client is requesting a nonblocking reply. If not
|
|
specified, the request will block until either a new event is available
|
|
or a few minutes have passed, in which case the server will send the
|
|
client a heartbeat event.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
events:
|
|
type: array
|
|
description: |
|
|
An array of `event` objects (possibly zero-length if `dont_block` is
|
|
set) with IDs newer than `last_event_id`. Event IDs are
|
|
guaranteed to be increasing, but they are not guaranteed to be
|
|
consecutive.
|
|
items:
|
|
oneOf:
|
|
- type: object
|
|
description: |
|
|
Event sent to a user's clients when that user's set of configured
|
|
[alert words](/help/dm-mention-alert-notifications#alert-words) have changed.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- alert_words
|
|
alert_words:
|
|
type: array
|
|
description: |
|
|
An array of strings, where each string is an alert word (or phrase)
|
|
configured by the user.
|
|
items:
|
|
type: string
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "alert_words",
|
|
"alert_words": ["alert_word"],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to clients that have requested the
|
|
`update_display_settings` event type and did not include
|
|
`user_settings_object` in their `client_capabilities` when
|
|
registering the event queue.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and process the `user_settings` event type instead.
|
|
deprecated: true
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- update_display_settings
|
|
setting_name:
|
|
type: string
|
|
description: |
|
|
Name of the changed display setting.
|
|
setting:
|
|
description: |
|
|
New value of the changed setting.
|
|
oneOf:
|
|
- type: boolean
|
|
- type: integer
|
|
- type: string
|
|
language_name:
|
|
description: |
|
|
Present only if the setting to be changed is
|
|
`default_language`. Contains the name of the
|
|
new default language in English.
|
|
type: string
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "update_display_settings",
|
|
"setting_name": "high_contrast_mode",
|
|
"setting": false,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to a user's clients when that user's [notification
|
|
settings](/api/update-settings) have changed with an additional
|
|
rule that it is only sent to clients that did not include
|
|
`user_settings_object` in their `client_capabilities` when
|
|
registering the event queue.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and process the `user_settings` event type instead.
|
|
deprecated: true
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- update_global_notifications
|
|
notification_name:
|
|
type: string
|
|
description: |
|
|
Name of the changed notification setting.
|
|
setting:
|
|
description: |
|
|
New value of the changed setting.
|
|
oneOf:
|
|
- type: boolean
|
|
- type: integer
|
|
- type: string
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "update_global_notifications",
|
|
"notification_name": "enable_sounds",
|
|
"setting": true,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to a user's clients when that user's settings
|
|
have changed.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 89), replacing the
|
|
previous `update_display_settings` and `update_global_notifications`
|
|
event types, which are still present for backwards compatibility reasons.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- user_settings
|
|
op:
|
|
type: string
|
|
enum:
|
|
- update
|
|
property:
|
|
type: string
|
|
description: |
|
|
Name of the changed setting.
|
|
value:
|
|
description: |
|
|
New value of the changed setting.
|
|
oneOf:
|
|
- type: boolean
|
|
- type: integer
|
|
- type: string
|
|
language_name:
|
|
description: |
|
|
Present only if the setting to be changed is
|
|
`default_language`. Contains the name of the
|
|
new default language in English.
|
|
type: string
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "user_settings",
|
|
"op": "update",
|
|
"property": "high_contrast_mode",
|
|
"value": false,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent generally to all users in an organization for changes
|
|
in the set of users or those users metadata.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_user
|
|
op:
|
|
type: string
|
|
enum:
|
|
- update
|
|
person:
|
|
description: |
|
|
Object containing the changed details of the user.
|
|
It has multiple forms depending on the value changed.
|
|
oneOf:
|
|
- type: object
|
|
description: |
|
|
When a user changes their full name.
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of modified user.
|
|
full_name:
|
|
type: string
|
|
description: |
|
|
The new full name for the user.
|
|
additionalProperties: false
|
|
- type: object
|
|
description: |
|
|
When a user changes their avatar.
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user who is affected by this change.
|
|
avatar_url:
|
|
type: string
|
|
description: |
|
|
The URL of the new avatar for the user.
|
|
avatar_source:
|
|
type: string
|
|
description: |
|
|
The new avatar data source type for the user.
|
|
|
|
Value values are `G` (gravatar) and `U` (uploaded by user).
|
|
avatar_url_medium:
|
|
type: string
|
|
description: |
|
|
The new medium-size avatar URL for user.
|
|
avatar_version:
|
|
type: integer
|
|
description: |
|
|
The version number for the user's avatar. This is useful
|
|
for cache-busting.
|
|
additionalProperties: false
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
When a user changes their time zone setting.
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of modified user.
|
|
email:
|
|
type: string
|
|
description: |
|
|
The Zulip API email of the user.
|
|
|
|
**Deprecated**: This field will be removed in a future
|
|
release as it is redundant with the `user_id`.
|
|
deprecated: true
|
|
timezone:
|
|
type: string
|
|
description: |
|
|
The new time zone of the user.
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
When the owner of a bot changes.
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user/bot whose owner has changed.
|
|
bot_owner_id:
|
|
type: integer
|
|
description: |
|
|
The user ID of the new bot owner.
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
When the [role](/help/roles-and-permissions) of a user changes.
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user affected by this change.
|
|
role:
|
|
type: integer
|
|
description: |
|
|
The new [role](/api/roles-and-permissions) of the user.
|
|
enum:
|
|
- 100
|
|
- 200
|
|
- 300
|
|
- 400
|
|
- 600
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
When billing role of a user changes.
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user affected by this change.
|
|
is_billing_admin:
|
|
type: boolean
|
|
description: |
|
|
A boolean specifying whether the user is now a billing administrator.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 73).
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
When the value of a user's delivery email as visible to you changes,
|
|
either due to the email address changing or your access to the user's
|
|
email changing via an update to their `email_address_visibility`
|
|
setting.
|
|
|
|
**Changes**: Prior to Zulip 7.0 (feature level 163), this event was
|
|
sent only to the affected user, and this event would only be triggered
|
|
by changing the affected user's delivery email.
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user affected by this change.
|
|
delivery_email:
|
|
type: string
|
|
nullable: true
|
|
description: |
|
|
The new delivery email of the user.
|
|
|
|
This value can be `null` if the affected user
|
|
changed their `email_address_visibility` setting
|
|
such that you cannot access their real email.
|
|
|
|
**Changes**: Before Zulip 7.0 (feature level 163),
|
|
`null` was not a possible value for this event as
|
|
it was only sent to the affected user when their
|
|
email address was changed.
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
When the user updates one of their custom profile
|
|
fields.
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user affected by this change.
|
|
custom_profile_field:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Object containing details about the custom
|
|
profile data change.
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the custom profile field which user updated.
|
|
value:
|
|
type: string
|
|
nullable: true
|
|
description: |
|
|
User's personal value for this custom profile field,
|
|
or `null` if unset.
|
|
rendered_value:
|
|
type: string
|
|
description: |
|
|
The `value` rendered in HTML. Will only be present for
|
|
custom profile field types that support Markdown rendering.
|
|
|
|
This user-generated HTML content should be rendered
|
|
using the same CSS and client-side security protections
|
|
as are used for message content.
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
When the Zulip API email address of a user changes,
|
|
either due to the user's email address changing, or
|
|
due to changes in the user's
|
|
[email address visibility][help-email-visibility].
|
|
|
|
[help-email-visibility]: /help/configure-email-visibility
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user affected by this change.
|
|
new_email:
|
|
type: string
|
|
description: |
|
|
The new value of `email` for the user. The client
|
|
should update any data structures associated
|
|
with this user to use this new value as the
|
|
user's Zulip API email address.
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "realm_user",
|
|
"op": "update",
|
|
"person":
|
|
{
|
|
"avatar_source": "G",
|
|
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=3",
|
|
"avatar_url_medium": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&s=500&version=3",
|
|
"avatar_version": 3,
|
|
"user_id": 10,
|
|
},
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to a user's clients when that user's stream subscriptions
|
|
have changed (either the set of subscriptions or their properties).
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- subscription
|
|
op:
|
|
type: string
|
|
enum:
|
|
- add
|
|
subscriptions:
|
|
type: array
|
|
description: |
|
|
A list of dictionaries where each dictionary contains
|
|
information about one of the subscribed streams.
|
|
|
|
**Changes**: Removed `email_address` field from the dictionary
|
|
in Zulip 7.5 (feature level 186).
|
|
|
|
**Changes**: Removed `role` field from the dictionary
|
|
in Zulip 6.0 (feature level 133).
|
|
items:
|
|
$ref: "#/components/schemas/Subscriptions"
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "subscription",
|
|
"op": "add",
|
|
"subscriptions":
|
|
[
|
|
{
|
|
"name": "test_stream",
|
|
"stream_id": 9,
|
|
"description": "",
|
|
"rendered_description": "",
|
|
"invite_only": false,
|
|
"is_web_public": false,
|
|
"stream_post_policy": 1,
|
|
"history_public_to_subscribers": true,
|
|
"first_message_id": null,
|
|
"message_retention_days": null,
|
|
"is_announcement_only": false,
|
|
"color": "#76ce90",
|
|
"is_muted": false,
|
|
"pin_to_top": false,
|
|
"audible_notifications": null,
|
|
"desktop_notifications": null,
|
|
"email_notifications": null,
|
|
"push_notifications": null,
|
|
"wildcard_mentions_notify": null,
|
|
"in_home_view": true,
|
|
"stream_weekly_traffic": null,
|
|
"can_remove_subscribers_group_id": 2,
|
|
"subscribers": [10],
|
|
},
|
|
],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to a user's clients when that user has been unsubscribed
|
|
from one or more streams.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- subscription
|
|
op:
|
|
type: string
|
|
enum:
|
|
- remove
|
|
subscriptions:
|
|
type: array
|
|
description: |
|
|
A list of dictionaries, where each dictionary contains
|
|
information about one of the newly unsubscribed streams.
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Dictionary containing details about the unsubscribed stream.
|
|
properties:
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the stream.
|
|
name:
|
|
type: string
|
|
description: |
|
|
The name of the stream.
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "subscription",
|
|
"op": "remove",
|
|
"subscriptions":
|
|
[{"name": "test_stream", "stream_id": 9}],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to a user's clients when a property of the user's
|
|
subscription to a stream has been updated. This event is used
|
|
only for personal properties like `is_muted` or `pin_to_top`.
|
|
See the [stream update event](/api/get-events#stream-update)
|
|
for updates to global properties of a stream.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- subscription
|
|
op:
|
|
type: string
|
|
enum:
|
|
- update
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the stream whose subscription details have changed.
|
|
property:
|
|
type: string
|
|
description: |
|
|
The property of the subscription which has changed. For details on the
|
|
various subscription properties that a user can change, see
|
|
[POST /users/me/subscriptions/properties](/api/update-subscription-settings).
|
|
|
|
Clients should generally handle an unknown property received here without
|
|
crashing, since that will naturally happen when connecting to a Zulip
|
|
server running a new version that adds a new subscription property.
|
|
|
|
**Changes**: As of Zulip 6.0 (feature level 139), updates to the `is_muted`
|
|
property or the deprecated `in_home_view` property will send two `subscription`
|
|
update events, one for each property, to support clients fully migrating to
|
|
use the `is_muted` property. Prior to this feature level, updates to either
|
|
property only sent one event with the deprecated `in_home_view` property.
|
|
value:
|
|
description: |
|
|
The new value of the changed property.
|
|
oneOf:
|
|
- type: integer
|
|
- type: boolean
|
|
- type: string
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"op": "update",
|
|
"type": "subscription",
|
|
"property": "pin_to_top",
|
|
"value": true,
|
|
"stream_id": 11,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to other users when users have been subscribed to
|
|
streams. Sent to all users if the stream is public or to only
|
|
the existing subscribers if the stream is private.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- subscription
|
|
op:
|
|
type: string
|
|
enum:
|
|
- peer_add
|
|
stream_ids:
|
|
type: array
|
|
description: |
|
|
The IDs of the streams to which the user has subscribed.
|
|
items:
|
|
type: integer
|
|
user_ids:
|
|
type: array
|
|
description: |
|
|
The IDs of the users who subscribed.
|
|
items:
|
|
type: integer
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "subscription",
|
|
"op": "peer_add",
|
|
"stream_id": 9,
|
|
"user_id": 12,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to other users when users have been unsubscribed
|
|
from streams. Sent to all users if the stream is public or to only
|
|
the existing subscribers if the stream is private.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- subscription
|
|
op:
|
|
type: string
|
|
enum:
|
|
- peer_remove
|
|
stream_ids:
|
|
type: array
|
|
description: |
|
|
The IDs of the streams from which the users have been
|
|
unsubscribed from.
|
|
items:
|
|
type: integer
|
|
user_ids:
|
|
type: array
|
|
description: |
|
|
The IDs of the users who have been unsubscribed.
|
|
items:
|
|
type: integer
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "subscription",
|
|
"op": "peer_remove",
|
|
"stream_id": 9,
|
|
"user_id": 12,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event type for messages.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- message
|
|
message:
|
|
$ref: "#/components/schemas/MessagesEvent"
|
|
flags:
|
|
type: array
|
|
description: |
|
|
The user's [message flags][message-flags] for the message.
|
|
|
|
Clients should inspect the flags field rather than assuming that
|
|
new messages are unread; [muted users](/api/mute-user), messages
|
|
sent by the current user, and more subtle scenarios can result
|
|
in a new message that the server has already marked as read for
|
|
the user.
|
|
|
|
[message-flags]: /api/update-message-flags#available-flags
|
|
items:
|
|
type: string
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "message",
|
|
"message":
|
|
{
|
|
"id": 31,
|
|
"sender_id": 10,
|
|
"content": '<p>First message ...<a href="user_uploads/2/ce/2Xpnnwgh8JWKxBXtTfD6BHKV/zulip.txt">zulip.txt</a></p>',
|
|
"recipient_id": 23,
|
|
"timestamp": 1594825416,
|
|
"client": "test suite",
|
|
"subject": "test",
|
|
"topic_links": [],
|
|
"is_me_message": false,
|
|
"reactions": [],
|
|
"submessages": [],
|
|
"sender_full_name": "King Hamlet",
|
|
"sender_short_name": "hamlet",
|
|
"sender_email": "user10@zulip.testserver",
|
|
"sender_realm_str": "zulip",
|
|
"display_recipient": "Denmark",
|
|
"type": "stream",
|
|
"stream_id": 1,
|
|
"avatar_url": null,
|
|
"content_type": "text/html",
|
|
},
|
|
"flags": [],
|
|
"id": 1,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to a user's clients when the user completes the
|
|
OAuth flow for the [Zoom integration](/help/start-a-call). Clients need
|
|
to know whether initiating Zoom OAuth is required before creating a Zoom call.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- has_zoom_token
|
|
value:
|
|
type: boolean
|
|
description: |
|
|
A boolean specifying whether the user has zoom
|
|
token or not.
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "has_zoom_token",
|
|
"value": true,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
A simple event sent to organization administrators when the
|
|
set of invitations changes; this tells clients they need to refetch
|
|
data from `GET /invites` if they are displaying UI containing active
|
|
invitations.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- invites_changed
|
|
additionalProperties: false
|
|
example: {"type": "invites_changed", "id": 0}
|
|
- type: object
|
|
description: |
|
|
Event sent to all users in a Zulip organization when a new
|
|
user joins. Processing this event is important to being able
|
|
to display basic details on other users given only their ID.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_user
|
|
op:
|
|
type: string
|
|
enum:
|
|
- add
|
|
person:
|
|
$ref: "#/components/schemas/User"
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "realm_user",
|
|
"op": "add",
|
|
"person":
|
|
{
|
|
"email": "foo@zulip.com",
|
|
"delivery_email": null,
|
|
"user_id": 38,
|
|
"avatar_version": 1,
|
|
"is_admin": false,
|
|
"is_owner": false,
|
|
"is_guest": false,
|
|
"is_billing_admin": false,
|
|
"role": 400,
|
|
"is_bot": false,
|
|
"full_name": "full name",
|
|
"timezone": "",
|
|
"is_active": true,
|
|
"date_joined": "2020-07-15T15:04:02.030833+00:00",
|
|
"avatar_url": "https://secure.gravatar.com/avatar/c6b5578d4964bd9c5fae593c6868912a?d=identicon&version=1",
|
|
"profile_data": {},
|
|
},
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to all users in a Zulip organization when
|
|
a user is deactivated.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_user
|
|
op:
|
|
type: string
|
|
enum:
|
|
- remove
|
|
person:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Object containing details of the deactivated user.
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the deactivated user.
|
|
full_name:
|
|
type: string
|
|
deprecated: true
|
|
description: |
|
|
The full name of the user.
|
|
|
|
**Deprecated**: We expect to remove this field in the future.
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "realm_user",
|
|
"op": "remove",
|
|
"person":
|
|
{"user_id": 35, "full_name": "Foo Bot"},
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to all users in an organization when a user comes
|
|
back online after being offline for a while. While most presence
|
|
updates are done via polling the [main presence
|
|
endpoint](/api/get-presence), this event is important to avoid
|
|
confusing users when someone comes online and immediately sends
|
|
a message (one wouldn't want them to still appear offline at
|
|
that point!).
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- presence
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the modified user.
|
|
email:
|
|
type: string
|
|
description: |
|
|
The Zulip API email of the user.
|
|
|
|
**Deprecated**: This field will be removed in a future
|
|
release as it is redundant with the `user_id`.
|
|
deprecated: true
|
|
server_timestamp:
|
|
type: number
|
|
description: |
|
|
The timestamp of when the Zulip server received the user's
|
|
presence as a UNIX timestamp.
|
|
presence:
|
|
type: object
|
|
description: |
|
|
Object containing the details of the user's most recent presence.
|
|
additionalProperties:
|
|
type: object
|
|
description: |
|
|
`{client_name}`: Object containing the details of the user's
|
|
presence.
|
|
|
|
**Changes**: Starting with Zulip 7.0 (feature level 178), this
|
|
will always be `"website"` as the server no longer stores which
|
|
client submitted presence updates.
|
|
|
|
Previously, the object key was the client's platform name, for
|
|
example `website` or `ZulipDesktop`.
|
|
additionalProperties: false
|
|
properties:
|
|
client:
|
|
type: string
|
|
description: |
|
|
The client's platform name.
|
|
|
|
**Changes**: Starting with Zulip 7.0 (feature level 178), this
|
|
will always be `"website"` as the server no longer stores which
|
|
client submitted presence updates.
|
|
status:
|
|
type: string
|
|
enum:
|
|
- idle
|
|
- active
|
|
description: |
|
|
The status of the user on this client. Will be either `idle`
|
|
or `active`.
|
|
timestamp:
|
|
type: integer
|
|
description: |
|
|
The UNIX timestamp of when this client sent the user's presence
|
|
to the server with the precision of a second.
|
|
pushable:
|
|
type: boolean
|
|
description: |
|
|
Whether the client is capable of showing mobile/push notifications
|
|
to the user.
|
|
|
|
**Changes**: Starting with Zulip 7.0 (feature level 178), this
|
|
will always be `false` as the server no longer stores which
|
|
client submitted presence updates.
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "presence",
|
|
"user_id": 10,
|
|
"email": "user10@zulip.testserver",
|
|
"server_timestamp": 1594825445.320078373,
|
|
"presence":
|
|
{
|
|
"website":
|
|
{
|
|
"client": "website",
|
|
"status": "idle",
|
|
"timestamp": 1594825445,
|
|
"pushable": false,
|
|
},
|
|
},
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent when a new stream is created to users who can see
|
|
the new stream exists (for private streams, only subscribers and
|
|
organization administrators will receive this event).
|
|
|
|
Note that organization administrators who are not subscribed will
|
|
not be able to see content on the stream; just that it exists.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- stream
|
|
op:
|
|
type: string
|
|
enum:
|
|
- create
|
|
streams:
|
|
type: array
|
|
description: |
|
|
Array of stream objects, each containing
|
|
details about the newly added stream(s).
|
|
items:
|
|
$ref: "#/components/schemas/BasicStream"
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "stream",
|
|
"op": "create",
|
|
"streams":
|
|
[
|
|
{
|
|
"name": "private",
|
|
"stream_id": 12,
|
|
"description": "",
|
|
"rendered_description": "",
|
|
"invite_only": true,
|
|
"is_web_public": false,
|
|
"stream_post_policy": 1,
|
|
"history_public_to_subscribers": false,
|
|
"first_message_id": null,
|
|
"message_retention_days": null,
|
|
"is_announcement_only": false,
|
|
"can_remove_subscribers_group_id": 2,
|
|
},
|
|
],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to all users who can see a stream when it is deactivated.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- stream
|
|
op:
|
|
type: string
|
|
enum:
|
|
- delete
|
|
streams:
|
|
type: array
|
|
description: |
|
|
Array of stream objects, each containing
|
|
details about a stream that was deleted.
|
|
items:
|
|
$ref: "#/components/schemas/BasicStream"
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "stream",
|
|
"op": "delete",
|
|
"streams":
|
|
[
|
|
{
|
|
"name": "private",
|
|
"stream_id": 12,
|
|
"description": "",
|
|
"rendered_description": "",
|
|
"invite_only": true,
|
|
"is_web_public": false,
|
|
"stream_post_policy": 1,
|
|
"history_public_to_subscribers": false,
|
|
"first_message_id": null,
|
|
"message_retention_days": null,
|
|
"is_announcement_only": false,
|
|
"can_remove_subscribers_group_id": 2,
|
|
},
|
|
],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to all users who can see that a stream exists
|
|
when a property of that stream changes.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- stream
|
|
op:
|
|
type: string
|
|
enum:
|
|
- update
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the stream whose details have changed.
|
|
name:
|
|
type: string
|
|
description: |
|
|
The name of the stream whose details have changed.
|
|
property:
|
|
type: string
|
|
description: |
|
|
The property of the stream which has changed. See
|
|
[/stream GET](/api/get-streams) for details on the various
|
|
properties of a stream.
|
|
|
|
Clients should handle an "unknown" property received here without
|
|
crashing, since that can happen when connecting to a server running a
|
|
newer version of Zulip with new features.
|
|
value:
|
|
description: |
|
|
The new value of the changed property.
|
|
oneOf:
|
|
- type: integer
|
|
- type: boolean
|
|
- type: string
|
|
rendered_description:
|
|
type: string
|
|
description: |
|
|
Note: Only present if the changed property was `description`.
|
|
|
|
The short description of the stream rendered as HTML, intended to
|
|
be used when displaying the stream description in a UI.
|
|
|
|
One should use the standard Zulip rendered_markdown CSS when
|
|
displaying this content so that emoji, LaTeX, and other syntax
|
|
work correctly. And any client-side security logic for
|
|
user-generated message content should be applied when displaying
|
|
this HTML as though it were the body of a Zulip message.
|
|
history_public_to_subscribers:
|
|
type: boolean
|
|
description: |
|
|
Note: Only present if the changed property was `invite_only`.
|
|
|
|
Whether the history of the stream is public to its subscribers.
|
|
|
|
Currently always true for public streams (i.e. `"invite_only": false` implies
|
|
`"history_public_to_subscribers": true`), but clients should not make that
|
|
assumption, as we may change that behavior in the future.
|
|
is_web_public:
|
|
type: boolean
|
|
description: |
|
|
Note: Only present if the changed property was `invite_only`.
|
|
|
|
Whether the stream's history is now readable by web-public spectators.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 71).
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"op": "update",
|
|
"type": "stream",
|
|
"property": "invite_only",
|
|
"value": true,
|
|
"history_public_to_subscribers": true,
|
|
"is_web_public": false,
|
|
"stream_id": 11,
|
|
"name": "test_stream",
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent when a reaction is added to a message.
|
|
Sent to all users who were recipients of the message.
|
|
allOf:
|
|
- $ref: "#/components/schemas/EmojiReactionBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- reaction
|
|
op:
|
|
type: string
|
|
enum:
|
|
- add
|
|
message_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the message to which a reaction was
|
|
added.
|
|
emoji_code: {}
|
|
emoji_name: {}
|
|
reaction_type: {}
|
|
user_id: {}
|
|
user: {}
|
|
example:
|
|
{
|
|
"type": "reaction",
|
|
"op": "add",
|
|
"user_id": 10,
|
|
"user":
|
|
{
|
|
"user_id": 10,
|
|
"email": "user10@zulip.testserver",
|
|
"full_name": "King Hamlet",
|
|
},
|
|
"message_id": 32,
|
|
"emoji_name": "tada",
|
|
"emoji_code": "1f389",
|
|
"reaction_type": "unicode_emoji",
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent when a reaction is removed from a message.
|
|
Sent to all users who were recipients of the message.
|
|
allOf:
|
|
- $ref: "#/components/schemas/EmojiReactionBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- reaction
|
|
op:
|
|
type: string
|
|
enum:
|
|
- remove
|
|
message_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the message from which the reaction was
|
|
removed.
|
|
emoji_code: {}
|
|
emoji_name: {}
|
|
reaction_type: {}
|
|
user_id: {}
|
|
user: {}
|
|
example:
|
|
{
|
|
"type": "reaction",
|
|
"op": "remove",
|
|
"user_id": 10,
|
|
"user":
|
|
{
|
|
"user_id": 10,
|
|
"email": "user10@zulip.testserver",
|
|
"full_name": "King Hamlet",
|
|
},
|
|
"message_id": 52,
|
|
"emoji_name": "tada",
|
|
"emoji_code": "1f389",
|
|
"reaction_type": "unicode_emoji",
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to a user's clients when the user uploads a new file
|
|
in a Zulip message. Useful to implement live update in UI showing all files
|
|
the current user has uploaded.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- attachment
|
|
op:
|
|
type: string
|
|
enum:
|
|
- add
|
|
attachment:
|
|
$ref: "#/components/schemas/Attachments"
|
|
upload_space_used:
|
|
type: integer
|
|
description: |
|
|
The total size of all files uploaded by in the organization,
|
|
in bytes.
|
|
example:
|
|
{
|
|
"type": "attachment",
|
|
"op": "add",
|
|
"attachment":
|
|
{
|
|
"id": 1,
|
|
"name": "zulip.txt",
|
|
"path_id": "2/ce/2Xpnnwgh8JWKxBXtTfD6BHKV/zulip.txt",
|
|
"size": 6,
|
|
"create_time": 1594825414000,
|
|
"messages": [],
|
|
},
|
|
"upload_space_used": 6,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to a user's clients when details of a file that user
|
|
uploaded are changed. Most updates will be changes in the list of
|
|
messages that reference the uploaded file.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- attachment
|
|
op:
|
|
type: string
|
|
enum:
|
|
- update
|
|
attachment:
|
|
$ref: "#/components/schemas/Attachments"
|
|
upload_space_used:
|
|
type: integer
|
|
description: |
|
|
The total size of all files uploaded by in the organization,
|
|
in bytes.
|
|
example:
|
|
{
|
|
"type": "attachment",
|
|
"op": "update",
|
|
"attachment":
|
|
{
|
|
"id": 1,
|
|
"name": "zulip.txt",
|
|
"path_id": "2/ce/2Xpnnwgh8JWKxBXtTfD6BHKV/zulip.txt",
|
|
"size": 6,
|
|
"create_time": 1594825414000,
|
|
"messages": [],
|
|
},
|
|
"upload_space_used": 6,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to a user's clients when the user deletes a file
|
|
they had uploaded. Useful primarily for UI showing all the files
|
|
the current user has uploaded.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- attachment
|
|
op:
|
|
type: string
|
|
enum:
|
|
- remove
|
|
attachment:
|
|
type: object
|
|
description: |
|
|
Dictionary containing the ID of the deleted attachment.
|
|
additionalProperties: false
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the deleted attachment.
|
|
upload_space_used:
|
|
type: integer
|
|
description: |
|
|
The total size of all files uploaded by in the organization,
|
|
in bytes.
|
|
example:
|
|
{
|
|
"type": "attachment",
|
|
"op": "remove",
|
|
"attachment": {"id": 1},
|
|
"upload_space_used": 0,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent when a submessage is added to a message.
|
|
|
|
Submessages are an **experimental** API used for widgets such as the
|
|
`/poll` widget in Zulip.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- submessage
|
|
msg_type:
|
|
type: string
|
|
description: |
|
|
The type of the message.
|
|
content:
|
|
type: string
|
|
description: |
|
|
The new content of the submessage.
|
|
message_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the message to which the submessage has been added.
|
|
sender_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user who sent the message.
|
|
submessage_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the submessage.
|
|
example:
|
|
{
|
|
"type": "submessage",
|
|
"msg_type": "widget",
|
|
"message_id": 970461,
|
|
"submessage_id": 4737,
|
|
"sender_id": 58,
|
|
"content": '{"type":"vote","key":"58,1","vote":1}',
|
|
"id": 28,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users in a Zulip organization when the
|
|
status of a user changes.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- user_status
|
|
away:
|
|
type: boolean
|
|
deprecated: true
|
|
description: |
|
|
Whether the user has marked themself "away" with this status.
|
|
|
|
**Changes**: Deprecated in Zulip 6.0 (feature level 148);
|
|
starting with that feature level, `away` is a legacy way to
|
|
access the user's `presence_enabled` setting, with
|
|
`away = !presence_enabled`. To be removed in a future release.
|
|
status_text:
|
|
type: string
|
|
description: |
|
|
The text content of the status message.
|
|
|
|
This will be `""` for users who set a status without selecting
|
|
or writing a message.
|
|
emoji_name:
|
|
type: string
|
|
description: |
|
|
The [emoji name](/api/update-status#parameter-emoji_name) for
|
|
the emoji the user selected for their new status.
|
|
|
|
This will be `""` for users who set a status without selecting
|
|
an emoji.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 86).
|
|
emoji_code:
|
|
type: string
|
|
description: |
|
|
The [emoji code](/api/update-status#parameter-emoji_code) for
|
|
the emoji the user selected for their new status.
|
|
|
|
This will be `""` for users who set a status without selecting
|
|
an emoji.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 86).
|
|
reaction_type:
|
|
type: string
|
|
description: |
|
|
The [emoji type](/api/update-status#parameter-reaction_type) for
|
|
the emoji the user selected for their new status.
|
|
|
|
This will be `""` for users who set a status without selecting
|
|
an emoji.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 86).
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user whose status changed.
|
|
example:
|
|
{
|
|
"type": "user_status",
|
|
"user_id": 10,
|
|
"away": true,
|
|
"status_text": "out to lunch",
|
|
"emoji_name": "car",
|
|
"emoji_code": "1f697",
|
|
"reaction_type": "unicode_emoji",
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users in a Zulip organization when new custom
|
|
profile field types are configured for that Zulip organization.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- custom_profile_fields
|
|
fields:
|
|
type: array
|
|
description: |
|
|
An array of dictionaries where each dictionary contains
|
|
details of a single new custom profile field for the Zulip
|
|
organization.
|
|
items:
|
|
$ref: "#/components/schemas/CustomProfileField"
|
|
example:
|
|
{
|
|
"type": "custom_profile_fields",
|
|
"fields":
|
|
[
|
|
{
|
|
"id": 1,
|
|
"name": "Phone number",
|
|
"type": 1,
|
|
"hint": "",
|
|
"field_data": "",
|
|
"order": 1,
|
|
},
|
|
{
|
|
"id": 2,
|
|
"name": "Biography",
|
|
"type": 2,
|
|
"hint": "What are you known for?",
|
|
"field_data": "",
|
|
"order": 2,
|
|
},
|
|
{
|
|
"id": 3,
|
|
"name": "Favorite food",
|
|
"type": 1,
|
|
"hint": "Or drink, if you'd prefer",
|
|
"field_data": "",
|
|
"order": 3,
|
|
},
|
|
{
|
|
"id": 4,
|
|
"name": "Favorite editor",
|
|
"type": 3,
|
|
"hint": "",
|
|
"field_data": '{"0":{"text":"Vim","order":"1"},"1":{"text":"Emacs","order":"2"}}',
|
|
"order": 4,
|
|
"display_in_profile_summary": true,
|
|
},
|
|
{
|
|
"id": 5,
|
|
"name": "Birthday",
|
|
"type": 4,
|
|
"hint": "",
|
|
"field_data": "",
|
|
"order": 5,
|
|
},
|
|
{
|
|
"id": 6,
|
|
"name": "Favorite website",
|
|
"type": 5,
|
|
"hint": "Or your personal blog's URL",
|
|
"field_data": "",
|
|
"order": 6,
|
|
"display_in_profile_summary": true,
|
|
},
|
|
{
|
|
"id": 7,
|
|
"name": "Mentor",
|
|
"type": 6,
|
|
"hint": "",
|
|
"field_data": "",
|
|
"order": 7,
|
|
},
|
|
{
|
|
"id": 8,
|
|
"name": "GitHub",
|
|
"type": 7,
|
|
"hint": "Enter your GitHub username",
|
|
"field_data": '{"subtype":"github"}',
|
|
"order": 8,
|
|
},
|
|
],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users in a Zulip organization when an organization
|
|
administrator changes the organization's configured default stream groups.
|
|
|
|
Default stream groups are an **experimental** feature that is not yet
|
|
stabilized.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- default_stream_groups
|
|
default_stream_groups:
|
|
type: array
|
|
description: |
|
|
An array of dictionaries where each dictionary
|
|
contains details about a single default stream group.
|
|
items:
|
|
$ref: "#/components/schemas/DefaultStreamGroup"
|
|
example:
|
|
{
|
|
"type": "default_stream_groups",
|
|
"default_stream_groups":
|
|
[
|
|
{
|
|
"name": "group1",
|
|
"id": 2,
|
|
"description": "New description",
|
|
"streams":
|
|
[
|
|
{
|
|
"name": "Scotland",
|
|
"stream_id": 3,
|
|
"description": "Located in the United Kingdom",
|
|
"rendered_description": "<p>Located in the United Kingdom</p>",
|
|
"invite_only": false,
|
|
"is_web_public": false,
|
|
"stream_post_policy": 1,
|
|
"history_public_to_subscribers": true,
|
|
"first_message_id": 1,
|
|
"message_retention_days": null,
|
|
"is_announcement_only": false,
|
|
"can_remove_subscribers_group_id": 2,
|
|
},
|
|
{
|
|
"name": "Denmark",
|
|
"stream_id": 1,
|
|
"description": "A Scandinavian country",
|
|
"rendered_description": "<p>A Scandinavian country</p>",
|
|
"invite_only": false,
|
|
"is_web_public": false,
|
|
"stream_post_policy": 1,
|
|
"history_public_to_subscribers": true,
|
|
"first_message_id": 4,
|
|
"message_retention_days": null,
|
|
"is_announcement_only": false,
|
|
"can_remove_subscribers_group_id": 2,
|
|
},
|
|
{
|
|
"name": "Verona",
|
|
"stream_id": 5,
|
|
"description": "A city in Italy",
|
|
"rendered_description": "<p>A city in Italy</p>",
|
|
"invite_only": false,
|
|
"is_web_public": false,
|
|
"stream_post_policy": 1,
|
|
"history_public_to_subscribers": true,
|
|
"first_message_id": 6,
|
|
"message_retention_days": null,
|
|
"is_announcement_only": false,
|
|
"can_remove_subscribers_group_id": 2,
|
|
},
|
|
],
|
|
},
|
|
],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users in a Zulip organization when the
|
|
default streams in the organization are changed by an
|
|
organization administrator.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- default_streams
|
|
default_streams:
|
|
type: array
|
|
description: |
|
|
An array of dictionaries where each dictionary
|
|
contains details about a single default stream.
|
|
items:
|
|
$ref: "#/components/schemas/BasicStream"
|
|
example:
|
|
{
|
|
"type": "default_streams",
|
|
"default_streams":
|
|
[
|
|
{
|
|
"name": "Scotland",
|
|
"stream_id": 3,
|
|
"description": "Located in the United Kingdom",
|
|
"rendered_description": "<p>Located in the United Kingdom</p>",
|
|
"invite_only": false,
|
|
"is_web_public": false,
|
|
"stream_post_policy": 1,
|
|
"history_public_to_subscribers": true,
|
|
"first_message_id": 1,
|
|
"message_retention_days": null,
|
|
"is_announcement_only": false,
|
|
"can_remove_subscribers_group_id": 2,
|
|
},
|
|
],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent when a message has been deleted.
|
|
Sent to all users who received the message.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 77), events
|
|
for private messages contained additional `sender_id` and
|
|
`recipient_id` fields.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- delete_message
|
|
message_ids:
|
|
type: array
|
|
description: |
|
|
Only present for clients that support the `bulk_message_deletion`
|
|
[client capability][client-capabilities].
|
|
|
|
A list containing the IDs of the newly deleted messages.
|
|
|
|
[client-capabilities]: /api/register-queue#parameter-client_capabilities
|
|
items:
|
|
type: integer
|
|
message_id:
|
|
type: integer
|
|
description: |
|
|
Only present for clients that do not support the `bulk_message_deletion`
|
|
[client capability][client-capabilities].
|
|
|
|
The ID of the newly deleted message.
|
|
|
|
[client-capabilities]: /api/register-queue#parameter-client_capabilities
|
|
message_type:
|
|
type: string
|
|
description: |
|
|
The type of message. Either `"stream"` or `"private"`.
|
|
enum:
|
|
- private
|
|
- stream
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
Only present if `message_type` is `"stream"`.
|
|
|
|
The ID of the stream to which the message was sent.
|
|
topic:
|
|
type: string
|
|
description: |
|
|
Only present if `message_type` is `"stream"`.
|
|
|
|
The topic to which the message was sent.
|
|
example:
|
|
{
|
|
"type": "delete_message",
|
|
"message_type": "private",
|
|
"message_id": 37,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to a user's clients when that user's set of
|
|
configured muted topics have changed.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- muted_topics
|
|
muted_topics:
|
|
type: array
|
|
deprecated: true
|
|
description: |
|
|
Array of tuples, where each tuple describes a muted topic.
|
|
The first element of the tuple is the stream name in which the topic
|
|
has to be muted, the second element is the topic name to be muted
|
|
and the third element is an integer UNIX timestamp representing
|
|
when the topic was muted.
|
|
|
|
**Changes**: Deprecated in Zulip 6.0 (feature level
|
|
134). Starting with this version, clients that explicitly
|
|
requested the replacement `user_topic` event type when
|
|
registering their event queue will not receive this legacy
|
|
event type.
|
|
|
|
**Changes**: Before Zulip 3.0 (feature level 1), the `muted_topics`
|
|
array objects were 2-item tuples and did not include the timestamp
|
|
information for when the topic was muted.
|
|
items:
|
|
type: array
|
|
items:
|
|
oneOf:
|
|
- type: string
|
|
- type: integer
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "muted_topics",
|
|
"muted_topics":
|
|
[["Denmark", "topic", 1594825442]],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to a user's clients when the user mutes/unmutes
|
|
a topic, or otherwise modifies their personal per-topic
|
|
configuration.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 134). Previously,
|
|
clients were notified about changes in muted topic
|
|
configuration via the `muted_topics` event type.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- user_topic
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the stream to which the topic belongs.
|
|
topic_name:
|
|
type: string
|
|
description: |
|
|
The name of the topic.
|
|
last_updated:
|
|
type: integer
|
|
description: |
|
|
An integer UNIX timestamp representing when the user-topic
|
|
relationship was last changed.
|
|
visibility_policy:
|
|
type: integer
|
|
description: |
|
|
An integer indicating the user's visibility
|
|
preferences for the topic, such as whether the topic
|
|
is muted.
|
|
|
|
- 0 = None. Used to indicate that the user no
|
|
longer has a special visibility policy for this topic.
|
|
- 1 = Muted. Used to record muted topics.
|
|
- 2 = Unmuted. Used to record unmuted topics.
|
|
|
|
**Changes**: In Zulip 7.0 (feature level 170), added unmuted as
|
|
a visibility policy option.
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"id": 1,
|
|
"type": "user_topic",
|
|
"stream_id": 1,
|
|
"topic_name": "topic",
|
|
"last_updated": 1594825442,
|
|
"visibility_policy": 1,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to a user's clients when that user's set of
|
|
configured [muted users](/api/mute-user) have changed.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 48).
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- muted_users
|
|
muted_users:
|
|
type: array
|
|
description: |
|
|
A list of dictionaries where each dictionary describes
|
|
a muted user.
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Object containing the user ID and timestamp of a muted user.
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the muted user.
|
|
timestamp:
|
|
type: integer
|
|
description: |
|
|
An integer UNIX timestamp representing when the user was muted.
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "muted_users",
|
|
"muted_users":
|
|
[
|
|
{"id": 1, "timestamp": 1594825442},
|
|
{"id": 22, "timestamp": 1654865392},
|
|
],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Heartbeat events are sent by the server to avoid
|
|
longpolling connections being affected by networks that
|
|
kill idle HTTP connections.
|
|
|
|
Clients do not need to do anything to process these
|
|
events, beyond the common `last_event_id` accounting.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- heartbeat
|
|
example: {"type": "heartbeat", "id": 0}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent when the set of onboarding "hotspots" to show for
|
|
the current user have changed (E.g. because the user dismissed one).
|
|
|
|
Clients that feature a similar tutorial experience to the Zulip
|
|
web app may want to handle these events.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- hotspots
|
|
hotspots:
|
|
type: array
|
|
description: |
|
|
An array of dictionaries where each
|
|
dictionary contains details about a single hotspot.
|
|
items:
|
|
$ref: "#/components/schemas/Hotspot"
|
|
example:
|
|
{
|
|
"type": "hotspots",
|
|
"hotspots":
|
|
[
|
|
{
|
|
"name": "intro_streams",
|
|
"title": "Catch up on a stream",
|
|
"description": "Messages sent to a stream are seen by everyone subscribed to that stream. Try clicking on one of the stream links below.",
|
|
"delay": 0.5,
|
|
},
|
|
],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent when a message's content, topic and/or
|
|
stream has been edited or when a message's content
|
|
has a rendering update, such as for an
|
|
[inline URL preview][inline-url-previews].
|
|
Sent to all users who had received the original
|
|
message.
|
|
|
|
[inline-url-previews]: https://zulip.readthedocs.io/en/latest/subsystems/sending-messages.html#inline-url-previews
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- update_message
|
|
user_id:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
The ID of the user who sent the message.
|
|
|
|
Is `null` when event is for a rendering update of the original message,
|
|
such as for an [inline URL preview][inline-url-previews].
|
|
|
|
**Changes**: As of Zulip 5.0 (feature level 114), this field
|
|
is present for all `update_message` events. Previously, this
|
|
field was omitted for [inline URL preview][inline-url-previews]
|
|
updates.
|
|
rendering_only:
|
|
type: boolean
|
|
description: |
|
|
Whether the event only updates the rendered content of the message.
|
|
|
|
This field should be used by clients to determine if the event
|
|
only provides a rendering update to the message content,
|
|
such as for an [inline URL preview][inline-url-previews].
|
|
When `true`, the event does not reflect a user-generated edit
|
|
and does not modify the message history.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 114). Clients can
|
|
correctly identify these rendering update event with earlier
|
|
Zulip versions by checking whether the `user_id` field was omitted.
|
|
message_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the message which was edited or updated.
|
|
|
|
This field should be used to apply content edits to the client's
|
|
cached message history, or to apply rendered content updates.
|
|
|
|
If the stream or topic was changed, the set of moved messages is
|
|
encoded in the separate `message_ids` field, which is guaranteed
|
|
to include `message_id`.
|
|
message_ids:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
The list of IDs of messages to which any stream or topic changes
|
|
encoded in this event should be applied.
|
|
|
|
These messages are guaranteed to have all been previously sent
|
|
to stream `stream_id` with topic `orig_subject`, and have been
|
|
moved to `new_stream_id` with topic `subject` (if those fields
|
|
are present in the event).
|
|
|
|
Clients processing these events should update all cached message
|
|
history associated with the moved messages (including adjusting
|
|
`unread_msgs` data structures, where the client may not have the
|
|
message itself in its history) to reflect the new stream and
|
|
topic.
|
|
|
|
Content changes should be applied only to the single message
|
|
indicated by `message_id`.
|
|
flags:
|
|
type: array
|
|
description: |
|
|
The user's personal [message flags][message-flags] for the
|
|
message with ID `message_id` following the edit.
|
|
|
|
A client application should compare these to the original flags
|
|
to identify cases where a mention or alert word was added by the
|
|
edit.
|
|
|
|
[message-flags]: /api/update-message-flags#available-flags
|
|
items:
|
|
type: string
|
|
edit_timestamp:
|
|
type: integer
|
|
description: |
|
|
The time when this message edit operation was processed by the
|
|
server.
|
|
|
|
**Changes**: As of Zulip 5.0 (feature level 114), this field
|
|
is present for all `update_message` events. Previously, this
|
|
field was omitted for [inline URL preview][inline-url-previews]
|
|
updates.
|
|
stream_name:
|
|
type: string
|
|
description: |
|
|
Only present if the message was edited and originally sent to a stream.
|
|
|
|
The name of the stream that the message was sent to. Clients
|
|
are recommended to use the `stream_id` field instead.
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
Only present if the message was edited and originally sent to a stream.
|
|
|
|
The pre-edit stream for all of the messages with IDs in
|
|
`message_ids`.
|
|
|
|
**Changes**: As of Zulip 5.0 (feature level 112), this field
|
|
is present for all edits to a stream message. Previously, it
|
|
was not present when only the content of the stream message was
|
|
edited.
|
|
new_stream_id:
|
|
type: integer
|
|
description: |
|
|
Only present if message(s) were moved to a different stream.
|
|
|
|
The post-edit stream for all of the messages with IDs in
|
|
`message_ids`.
|
|
propagate_mode:
|
|
type: string
|
|
description: |
|
|
Only present if this event moved messages to a different
|
|
topic and/or stream.
|
|
|
|
The choice the editing user made about which messages should be
|
|
affected by a stream/topic edit:
|
|
|
|
- `"change_one"`: Just change the one indicated in `message_id`.
|
|
- `"change_later"`: Change messages in the same topic that had
|
|
been sent after this one.
|
|
- `"change_all"`: Change all messages in that topic.
|
|
|
|
This parameter should be used to decide whether to change
|
|
navigation and compose box state in response to the edit. For
|
|
example, if the user was previously in topic narrow, and the
|
|
topic was edited with `"change_later"` or `"change_all"`, the Zulip
|
|
web app will automatically navigate to the new topic narrow.
|
|
Similarly, a message being composed to the old topic should
|
|
have its recipient changed to the new topic.
|
|
|
|
This navigation makes it much more convenient to move content
|
|
between topics without disruption or messages continuing
|
|
to be sent to the pre-edit topic by accident.
|
|
enum:
|
|
- change_one
|
|
- change_later
|
|
- change_all
|
|
orig_subject:
|
|
type: string
|
|
description: |
|
|
Only present if this event moved messages to a different
|
|
topic and/or stream.
|
|
|
|
The pre-edit topic for all of the messages with IDs in
|
|
`message_ids`.
|
|
subject:
|
|
type: string
|
|
description: |
|
|
Only present if this event moved messages to a different
|
|
topic.
|
|
|
|
The post-edit topic for all of the messages with IDs in
|
|
`message_ids`.
|
|
topic_links:
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
text:
|
|
type: string
|
|
description: |
|
|
The original link text present in the topic.
|
|
url:
|
|
type: string
|
|
description: |
|
|
The expanded target url which the link points to.
|
|
description: |
|
|
Only present if this event moved messages to a different
|
|
topic.
|
|
|
|
Data on any links to be included in the `topic`
|
|
line (these are generated by
|
|
[custom linkification filter](/help/add-a-custom-linkifier)
|
|
that match content in the message's topic.), corresponding
|
|
to the post-edit topic.
|
|
|
|
**Changes**: This field contained a list of urls before
|
|
Zulip 4.0 (feature level 46).
|
|
|
|
New in Zulip 3.0 (feature level 1). Previously, this field
|
|
was called `subject_links`; clients are recommended to
|
|
rename `subject_links` to `topic_links` if present for
|
|
compatibility with older Zulip servers.
|
|
orig_content:
|
|
type: string
|
|
description: |
|
|
Only present if this event changed the message content.
|
|
|
|
The original content of the message with ID `message_id`
|
|
immediately prior to this edit, in the original markdown.
|
|
orig_rendered_content:
|
|
type: string
|
|
description: |
|
|
Only present if this event changed the message content.
|
|
|
|
The original content of the message with ID `message_id`
|
|
immediately prior to this edit, rendered as HTML.
|
|
prev_rendered_content_version:
|
|
type: integer
|
|
description: |
|
|
Only present if this event changed the message content.
|
|
|
|
The Markdown processor version number for the pre-edit message.
|
|
|
|
Clients should ignore this field.
|
|
content:
|
|
type: string
|
|
description: |
|
|
Only present if this event changed the message content or
|
|
updated the message content for an
|
|
[inline URL preview][inline-url-previews].
|
|
|
|
The new content of the message with ID `message_id`, in the
|
|
original Markdown.
|
|
rendered_content:
|
|
type: string
|
|
description: |
|
|
Only present if this event changed the message content or
|
|
updated the message content for an
|
|
[inline URL preview][inline-url-previews].
|
|
|
|
The new content of the message with ID `message_id`,
|
|
rendered in HTML.
|
|
is_me_message:
|
|
type: boolean
|
|
description: |
|
|
Only present if this event changed the message content.
|
|
|
|
Whether the message with ID `message_id` is now a
|
|
[/me status message][status-messages].
|
|
|
|
[status-messages]: /help/format-your-message-using-markdown#status-messages
|
|
required:
|
|
- type
|
|
- id
|
|
- user_id
|
|
- message_id
|
|
- message_ids
|
|
- flags
|
|
- edit_timestamp
|
|
- rendering_only
|
|
example:
|
|
{
|
|
"type": "update_message",
|
|
"user_id": 10,
|
|
"edit_timestamp": 1594825451,
|
|
"message_id": 58,
|
|
"stream_name": "Verona",
|
|
"orig_content": "hello",
|
|
"orig_rendered_content": "<p>hello</p>",
|
|
"content": "new content",
|
|
"rendered_content": "<p>new content</p>",
|
|
"prev_rendered_content_version": 1,
|
|
"is_me_message": false,
|
|
"propagate_mode": "change_all",
|
|
"stream_id": 5,
|
|
"orig_subject": "test",
|
|
"subject": "new_topic",
|
|
"topic_links": [],
|
|
"message_ids": [58, 57],
|
|
"flags": [],
|
|
"rendering_only": false,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent when a user starts typing a message.
|
|
|
|
Sent to all clients for users who would receive the
|
|
message being typed, with the additional rule that typing
|
|
notifications for stream messages are only sent to clients
|
|
that included `stream_typing_notifications` in their
|
|
[client capabilities][client-capabilities] when registering
|
|
the event queue.
|
|
|
|
See [POST /typing](/api/set-typing-status) endpoint for more details.
|
|
|
|
**Changes**: Typing notifications for stream messages are new in
|
|
Zulip 4.0 (feature level 58).
|
|
|
|
[client-capabilities]: /api/register-queue#parameter-client_capabilities
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- typing
|
|
op:
|
|
type: string
|
|
enum:
|
|
- start
|
|
message_type:
|
|
type: string
|
|
description: |
|
|
Type of message being composed. Must be `"stream"` or `"private"`.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 58). Previously,
|
|
all typing notifications were implicitly private messages.
|
|
enum:
|
|
- private
|
|
- stream
|
|
sender:
|
|
additionalProperties: false
|
|
type: object
|
|
description: |
|
|
Object describing the user who is typing the message.
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The user's ID.
|
|
email:
|
|
type: string
|
|
description: |
|
|
The Zulip API email address for the user.
|
|
recipients:
|
|
type: array
|
|
description: |
|
|
Only present if `message_type` is `"private"`.
|
|
|
|
Array of dictionaries describing the set of users who would be
|
|
recipients of the message being typed. Each dictionary contains
|
|
details about one of the recipients. The sending user is guaranteed
|
|
to appear among the recipients.
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Object containing the user ID and Zulip API email of a recipient.
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user.
|
|
email:
|
|
type: string
|
|
description: |
|
|
The Zulip API email address for the user.
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
Only present if `message_type` is `"stream"`.
|
|
|
|
The unique ID of the stream to which message is being typed.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 58). Previously,
|
|
typing notifications were only for private messages.
|
|
topic:
|
|
type: string
|
|
description: |
|
|
Only present if `message_type` is `"stream"`.
|
|
|
|
Topic within the stream where the message is being typed.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 58). Previously,
|
|
typing notifications were only for private messages.
|
|
example:
|
|
{
|
|
"type": "typing",
|
|
"op": "start",
|
|
"message_type": "private",
|
|
"sender":
|
|
{
|
|
"user_id": 10,
|
|
"email": "user10@zulip.testserver",
|
|
},
|
|
"recipients":
|
|
[
|
|
{
|
|
"user_id": 8,
|
|
"email": "user8@zulip.testserver",
|
|
},
|
|
{
|
|
"user_id": 10,
|
|
"email": "user10@zulip.testserver",
|
|
},
|
|
],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent when a user stops typing a message.
|
|
|
|
Sent to all clients for users who would receive the message
|
|
that was previously being typed, with the additional rule
|
|
that typing notifications for stream messages are only sent to
|
|
clients that included `stream_typing_notifications` in their
|
|
[client capabilities][client-capabilities] when registering
|
|
the event queue.
|
|
|
|
See [POST /typing](/api/set-typing-status) endpoint for more details.
|
|
|
|
**Changes**: Typing notifications for stream messages are new in
|
|
Zulip 4.0 (feature level 58).
|
|
|
|
[client-capabilities]: /api/register-queue#parameter-client_capabilities
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- typing
|
|
op:
|
|
type: string
|
|
enum:
|
|
- stop
|
|
message_type:
|
|
type: string
|
|
description: |
|
|
Type of message being composed. Must be `"stream"` or `"private"`.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 58). Previously,
|
|
all typing notifications were implicitly private messages.
|
|
enum:
|
|
- private
|
|
- stream
|
|
sender:
|
|
additionalProperties: false
|
|
type: object
|
|
description: |
|
|
Object describing the user who was previously typing the message.
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The user's ID.
|
|
email:
|
|
type: string
|
|
description: |
|
|
The Zulip API email address for the user.
|
|
recipients:
|
|
type: array
|
|
description: |
|
|
Only present if `message_type` is `"private"`.
|
|
|
|
Array of dictionaries describing the set of users who would be
|
|
recipients of the message that was previously being typed. Each
|
|
dictionary contains details about one of the recipients. The
|
|
sending user is guaranteed to appear among the recipients.
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Object containing the user ID and email of a recipient.
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user.
|
|
email:
|
|
type: string
|
|
description: |
|
|
The Zulip API email address for the user.
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
Only present if `message_type` is `"stream"`.
|
|
|
|
The unique ID of the stream to which message is being typed.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 58). Previously,
|
|
typing notifications were only for private messages.
|
|
topic:
|
|
type: string
|
|
description: |
|
|
Only present if `message_type` is `"stream"`.
|
|
|
|
Topic within the stream where the message is being typed.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 58). Previously,
|
|
typing notifications were only for private messages.
|
|
example:
|
|
{
|
|
"type": "typing",
|
|
"op": "stop",
|
|
"message_type": "private",
|
|
"sender":
|
|
{
|
|
"user_id": 10,
|
|
"email": "user10@zulip.testserver",
|
|
},
|
|
"recipients":
|
|
[
|
|
{
|
|
"user_id": 8,
|
|
"email": "user8@zulip.testserver",
|
|
},
|
|
{
|
|
"user_id": 10,
|
|
"email": "user10@zulip.testserver",
|
|
},
|
|
],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to a user when [message flags][message-flags] are added
|
|
to a message.
|
|
|
|
[message-flags]: /api/update-message-flags#available-flags
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- update_message_flags
|
|
op:
|
|
type: string
|
|
enum:
|
|
- add
|
|
operation:
|
|
deprecated: true
|
|
description: |
|
|
Old name for `op` for this event type.
|
|
|
|
**Deprecated**: This is deprecated; please use `op` instead
|
|
starting with Zulip 4.0 (feature level 32).
|
|
type: string
|
|
enum:
|
|
- add
|
|
flag:
|
|
type: string
|
|
description: |
|
|
The flag that was added.
|
|
messages:
|
|
type: array
|
|
description: |
|
|
Array containing the IDs of all messages to which
|
|
the flag was added.
|
|
items:
|
|
type: integer
|
|
all:
|
|
type: boolean
|
|
description: |
|
|
Whether the flag was added to all messages (E.g. all messages
|
|
were marked as read).
|
|
If this is true, then the `messages` array will be empty.
|
|
example:
|
|
{
|
|
"type": "update_message_flags",
|
|
"op": "add",
|
|
"operation": "add",
|
|
"flag": "starred",
|
|
"messages": [63],
|
|
"all": false,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to a user when [message flags][message-flags] are
|
|
removed from a message.
|
|
|
|
[message-flags]: /api/update-message-flags#available-flags
|
|
required:
|
|
[
|
|
"id",
|
|
"type",
|
|
"op",
|
|
"operation",
|
|
"flag",
|
|
"messages",
|
|
"all",
|
|
]
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- update_message_flags
|
|
op:
|
|
type: string
|
|
enum:
|
|
- remove
|
|
operation:
|
|
deprecated: true
|
|
type: string
|
|
description: |
|
|
Old name for `op` for this event type.
|
|
|
|
**Deprecated**: This is deprecated; please use `op` instead
|
|
starting with Zulip 4.0 (feature level 32).
|
|
enum:
|
|
- remove
|
|
flag:
|
|
type: string
|
|
description: |
|
|
The flag to be removed.
|
|
enum:
|
|
- starred
|
|
- read
|
|
messages:
|
|
type: array
|
|
description: |
|
|
Array containing the IDs of the messages from which the flag
|
|
was removed.
|
|
items:
|
|
type: integer
|
|
all:
|
|
type: boolean
|
|
description: |
|
|
Whether the flag was removed from all messages.
|
|
If this is true then the `messages` array will be empty.
|
|
message_details:
|
|
description: |
|
|
Present if `message` and `update_message_flags` are both present in
|
|
`event_types` and the `flag` is `read` and the `op` is `remove`.
|
|
|
|
A set of data structures describing the messages that
|
|
are being marked as unread with additional details to
|
|
allow a client to update the `unread_msgs` data
|
|
structure for these messages (which may not be
|
|
otherwise known to the client).
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 121). Previously,
|
|
marking already read messages as unread was not
|
|
supported by the Zulip API.
|
|
type: object
|
|
additionalProperties:
|
|
type: object
|
|
description: |
|
|
Additional properties.
|
|
additionalProperties: false
|
|
required: ["type"]
|
|
properties:
|
|
type:
|
|
type: string
|
|
description: |
|
|
The type of this message.
|
|
enum:
|
|
- private
|
|
- stream
|
|
mentioned:
|
|
type: boolean
|
|
description: |
|
|
A flag which indicates whether the message contains a mention
|
|
of the user.
|
|
|
|
Present only if the message mentions the current user.
|
|
user_ids:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
Present only if `type` is `private`.
|
|
|
|
The user IDs of every recipient of this private message, excluding yourself.
|
|
Will be the empty list for a message you had sent to only yourself.
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
Present only if `type` is `stream`.
|
|
|
|
The ID of the stream where the message was sent.
|
|
topic:
|
|
type: string
|
|
description: |
|
|
Present only if `type` is `stream`.
|
|
|
|
Name of the topic where the message was sent.
|
|
unmuted_stream_msg:
|
|
type: boolean
|
|
deprecated: true
|
|
description: |
|
|
**Deprecated**
|
|
Internal implementation detail. Clients should
|
|
ignore this field as it will be removed in the future.
|
|
example:
|
|
{
|
|
"type": "update_message_flags",
|
|
"op": "remove",
|
|
"operation": "remove",
|
|
"flag": "starred",
|
|
"messages": [63],
|
|
"message_details":
|
|
{
|
|
63:
|
|
{
|
|
"type": "stream",
|
|
"stream_id": 22,
|
|
"topic": "lunch",
|
|
},
|
|
},
|
|
"all": false,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to users in an organization when a [user group](/help/user-groups) is created.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- user_group
|
|
op:
|
|
type: string
|
|
enum:
|
|
- add
|
|
group:
|
|
$ref: "#/components/schemas/UserGroup"
|
|
example:
|
|
{
|
|
"type": "user_group",
|
|
"op": "add",
|
|
"group":
|
|
{
|
|
"name": "backend",
|
|
"members": [12],
|
|
"description": "Backend team",
|
|
"id": 2,
|
|
"is_system_group": false,
|
|
},
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users in a Zulip organization
|
|
when a property of a user group is changed.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- user_group
|
|
op:
|
|
type: string
|
|
enum:
|
|
- update
|
|
group_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user group whose details have changed.
|
|
data:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Dictionary containing the changed details of the user group.
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: |
|
|
The new name of the user group. Only present if the group's name changed.
|
|
description:
|
|
type: string
|
|
description: |
|
|
The new description of the group. Only present if the description
|
|
changed.
|
|
example:
|
|
{
|
|
"type": "user_group",
|
|
"op": "update",
|
|
"group_id": 2,
|
|
"data":
|
|
{
|
|
"description": "Mention this group to get the security team's attention.",
|
|
},
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users when users have been added to a user group.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- user_group
|
|
op:
|
|
type: string
|
|
enum:
|
|
- add_members
|
|
group_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user group with new members.
|
|
user_ids:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
Array containing the IDs of the users who have been added
|
|
to the user group.
|
|
example:
|
|
{
|
|
"type": "user_group",
|
|
"op": "add_members",
|
|
"group_id": 2,
|
|
"user_ids": [10],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users when users have been removed from
|
|
a user group.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- user_group
|
|
op:
|
|
type: string
|
|
enum:
|
|
- remove_members
|
|
group_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user group whose details have changed.
|
|
user_ids:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
Array containing the IDs of the users who have been removed
|
|
from the user group.
|
|
example:
|
|
{
|
|
"type": "user_group",
|
|
"op": "remove_members",
|
|
"group_id": 2,
|
|
"user_ids": [10],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users when subgroups have been added to
|
|
a user group.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 127).
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- user_group
|
|
op:
|
|
type: string
|
|
enum:
|
|
- add_subgroups
|
|
group_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user group whose details have changed.
|
|
direct_subgroup_ids:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
Array containing the IDs of the subgroups that have been added
|
|
to the user group.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 131).
|
|
Previously, this was called `subgroup_ids`, but
|
|
clients can ignore older events as this feature level
|
|
predates subgroups being fully implemented.
|
|
example:
|
|
{
|
|
"type": "user_group",
|
|
"op": "add_subgroups",
|
|
"group_id": 2,
|
|
"direct_subgroup_ids": [10],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users when subgroups have been removed from
|
|
a user group.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 127).
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- user_group
|
|
op:
|
|
type: string
|
|
enum:
|
|
- remove_subgroups
|
|
group_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user group whose details have changed.
|
|
direct_subgroup_ids:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
Array containing the IDs of the subgroups that have been
|
|
removed from the user group.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 131).
|
|
Previously, this was called `subgroup_ids`, but
|
|
clients can ignore older events as this feature level
|
|
predates subgroups being fully implemented.
|
|
example:
|
|
{
|
|
"type": "user_group",
|
|
"op": "remove_subgroups",
|
|
"group_id": 2,
|
|
"direct_subgroup_ids": [10],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users when a user group has been deleted.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- user_group
|
|
op:
|
|
type: string
|
|
enum:
|
|
- remove
|
|
group_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the group which has been deleted.
|
|
example:
|
|
{
|
|
"type": "user_group",
|
|
"op": "remove",
|
|
"group_id": 2,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users in a Zulip organization when the
|
|
set of configured [linkifiers](/help/add-a-custom-linkifier)
|
|
for the organization has changed.
|
|
|
|
Processing this event is important for doing Markdown local echo
|
|
correctly.
|
|
|
|
Clients will not receive this event unless the event queue is
|
|
registered with the client capability
|
|
`{"linkifier_url_template": true}`.
|
|
See [`POST /register`](/api/register-queue#parameter-client_capabilities)
|
|
for how client capabilities can be specified.
|
|
|
|
**Changes**: Before Zulip 7.0 (feature level 176), the
|
|
`linkifier_url_template` client capability was not required. The
|
|
requirement was added because linkifiers were updated to contain
|
|
a URL template instead of a URL format string, which was not a
|
|
backwards-compatible change.
|
|
|
|
New in Zulip 4.0 (feature level 54), replacing the deprecated
|
|
`realm_filters` event type.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_linkifiers
|
|
realm_linkifiers:
|
|
type: array
|
|
description: |
|
|
Array of dictionaries where each dictionary contains details about
|
|
a single realm linkifier.
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
pattern:
|
|
type: string
|
|
description: |
|
|
The [Python regular expression](https://docs.python.org/3/howto/regex.html)
|
|
that represents the pattern that should be linkified by this linkifier.
|
|
url_template:
|
|
type: string
|
|
description: |
|
|
The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html) compliant
|
|
URL template to be used for linkifying matches.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 176). This replaced `url_format`,
|
|
which contained a URL format string.
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the linkifier.
|
|
example:
|
|
{
|
|
"type": "realm_linkifiers",
|
|
"realm_linkifiers":
|
|
[
|
|
{
|
|
"pattern": "#(?P<id>[123])",
|
|
"url_template": "https://realm.com/my_realm_filter/{id}",
|
|
"id": 1,
|
|
},
|
|
],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
deprecated: true
|
|
description: |
|
|
Legacy event type that is no longer sent to clients. Previously, sent
|
|
to all users in a Zulip organization when the set of configured
|
|
[linkifiers](/help/add-a-custom-linkifier) for the organization was
|
|
changed.
|
|
|
|
**Changes**: Prior to Zulip 7.0 (feature level 176), this event type
|
|
was sent to clients.
|
|
|
|
**Deprecated** in Zulip 4.0 (feature level 54), and replaced by the
|
|
`realm_linkifiers` event type, which has a clearer name and format.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_filters
|
|
realm_filters:
|
|
type: array
|
|
items:
|
|
type: array
|
|
items:
|
|
oneOf:
|
|
- type: integer
|
|
- type: string
|
|
description: |
|
|
An array of tuples, where each tuple described a linkifier. The first
|
|
element of the tuple was a string regex pattern which represented the
|
|
pattern to be linkified on matching, for example `"#(?P<id>[123])"`.
|
|
The second element was the URL format string that the pattern should be
|
|
linkified with. A URL format string for the above example would be
|
|
`"https://realm.com/my_realm_filter/%(id)s"`. And the third element
|
|
was the ID of the realm filter.
|
|
example:
|
|
{
|
|
"type": "realm_filters",
|
|
"realm_filters": [],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users in a Zulip organization when the
|
|
set of configured [code playgrounds](/help/code-blocks#code-playgrounds)
|
|
for the organization has changed.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 49).
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_playgrounds
|
|
realm_playgrounds:
|
|
type: array
|
|
description: |
|
|
An array of dictionaries where each dictionary contains
|
|
data about a single playground entry.
|
|
items:
|
|
$ref: "#/components/schemas/RealmPlayground"
|
|
example:
|
|
{
|
|
"type": "realm_playgrounds",
|
|
"realm_playgrounds":
|
|
[
|
|
{
|
|
"id": 1,
|
|
"name": "Python playground",
|
|
"pygments_language": "Python",
|
|
"url_prefix": "https://python.example.com",
|
|
},
|
|
],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users in a Zulip organization when
|
|
a [custom emoji](/help/custom-emoji) has been updated,
|
|
typically when a new emoji has been added or an old one
|
|
has been deactivated. The event contains all custom emoji
|
|
configured for the organization, not just the updated
|
|
custom emoji.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_emoji
|
|
op:
|
|
type: string
|
|
enum:
|
|
- update
|
|
realm_emoji:
|
|
type: object
|
|
description: |
|
|
An object in which each key describes a realm emoji.
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/RealmEmoji"
|
|
example:
|
|
{
|
|
"type": "realm_emoji",
|
|
"op": "update",
|
|
"realm_emoji":
|
|
{
|
|
"2":
|
|
{
|
|
"id": "2",
|
|
"name": "my_emoji",
|
|
"source_url": "/user_avatars/2/emoji/images/2.png",
|
|
"deactivated": true,
|
|
"author_id": 11,
|
|
},
|
|
"1":
|
|
{
|
|
"id": "1",
|
|
"name": "green_tick",
|
|
"source_url": "/user_avatars/2/emoji/images/1.png",
|
|
"deactivated": false,
|
|
"author_id": 11,
|
|
},
|
|
},
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users in a Zulip organization when the set of
|
|
[allowed domains for new users](/help/restrict-account-creation#configuring-email-domain-restrictions)
|
|
has changed.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_domains
|
|
op:
|
|
type: string
|
|
enum:
|
|
- add
|
|
realm_domain:
|
|
$ref: "#/components/schemas/RealmDomain"
|
|
example:
|
|
{
|
|
"type": "realm_domains",
|
|
"op": "add",
|
|
"realm_domain":
|
|
{
|
|
"domain": "zulip.org",
|
|
"allow_subdomains": false,
|
|
},
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users in a Zulip organization when the set of
|
|
[allowed domains for new users](/help/restrict-account-creation#configuring-email-domain-restrictions)
|
|
has changed.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_domains
|
|
op:
|
|
type: string
|
|
enum:
|
|
- change
|
|
realm_domain:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Object containing details of the edited domain.
|
|
properties:
|
|
domain:
|
|
type: string
|
|
description: |
|
|
The domain whose settings have changed.
|
|
allow_subdomains:
|
|
type: boolean
|
|
description: |
|
|
Whether subdomains are allowed for this domain.
|
|
example:
|
|
{
|
|
"type": "realm_domains",
|
|
"op": "change",
|
|
"realm_domain":
|
|
{
|
|
"domain": "zulip.org",
|
|
"allow_subdomains": true,
|
|
},
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users in a Zulip organization when the set of
|
|
[allowed domains for new users](/help/restrict-account-creation#configuring-email-domain-restrictions)
|
|
has changed.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_domains
|
|
op:
|
|
type: string
|
|
enum:
|
|
- remove
|
|
domain:
|
|
type: string
|
|
description: |
|
|
The domain to be removed.
|
|
example:
|
|
{
|
|
"type": "realm_domains",
|
|
"op": "remove",
|
|
"domain": "zulip.org",
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to the user who requested a [data export](/help/export-your-organization)
|
|
when the status of the export changes.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_export
|
|
exports:
|
|
type: array
|
|
description: |
|
|
An array of dictionaries where each dictionary contains
|
|
data about a single organization export request.
|
|
items:
|
|
$ref: "#/components/schemas/RealmExport"
|
|
example:
|
|
{
|
|
"type": "realm_export",
|
|
"exports":
|
|
[
|
|
{
|
|
"id": 107,
|
|
"export_time": 1594825443.6567969322,
|
|
"acting_user_id": 10,
|
|
"export_url": null,
|
|
"deleted_timestamp": null,
|
|
"failed_timestamp": 1594825444.4363360405,
|
|
"pending": false,
|
|
},
|
|
],
|
|
"id": 1,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to users who can administer a newly created bot
|
|
user. Clients will also receive a `realm_user` event that
|
|
contains basic details (but not the API key).
|
|
|
|
The `realm_user` events are sufficient for clients that
|
|
only need to interact with the bot; this `realm_bot` event
|
|
type is relevant only for administering bots.
|
|
|
|
Only organization administrators and the user who owns the bot will
|
|
receive this event.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_bot
|
|
op:
|
|
type: string
|
|
enum:
|
|
- add
|
|
bot:
|
|
$ref: "#/components/schemas/Bot"
|
|
example:
|
|
{
|
|
"type": "realm_bot",
|
|
"op": "add",
|
|
"bot":
|
|
{
|
|
"email": "test-bot@zulip.testserver",
|
|
"user_id": 36,
|
|
"full_name": "Foo Bot",
|
|
"bot_type": 1,
|
|
"is_active": true,
|
|
"api_key": "6hc6MC9mpNFvoo0gSOWnZEq4aJEn8UNK",
|
|
"default_sending_stream": null,
|
|
"default_events_register_stream": null,
|
|
"default_all_public_streams": false,
|
|
"avatar_url": "https://secure.gravatar.com/avatar/af8abc2537d283b212a6bd4d1289956d?d=identicon&version=1",
|
|
"services": [],
|
|
"owner_id": 10,
|
|
},
|
|
"id": 1,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to users who can administer a bot user when the bot is
|
|
configured. Clients may also receive a `realm_user` event that
|
|
for changes in public data about the bot (name, etc.).
|
|
|
|
The `realm_user` events are sufficient for clients that
|
|
only need to interact with the bot; this `realm_bot` event
|
|
type is relevant only for administering bots.
|
|
|
|
Only organization administrators and the user who owns the bot will
|
|
receive this event.
|
|
additionalProperties: false
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_bot
|
|
op:
|
|
type: string
|
|
enum:
|
|
- update
|
|
bot:
|
|
allOf:
|
|
- description: |
|
|
Object containing details about the changed bot.
|
|
It contains two properties: the user ID of the bot and
|
|
the property to be changed. The changed property is one
|
|
of the remaining properties listed below.
|
|
- $ref: "#/components/schemas/BasicBot"
|
|
example:
|
|
{
|
|
"type": "realm_bot",
|
|
"op": "update",
|
|
"bot":
|
|
{
|
|
"user_id": 37,
|
|
"services":
|
|
[
|
|
{
|
|
"base_url": "http://hostname.domain2.com",
|
|
"interface": 2,
|
|
"token": "grr8I2APXRmVL0FRTMRYAE4DRPQ5Wlaw",
|
|
},
|
|
],
|
|
},
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users when a bot has been deactivated.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_bot
|
|
op:
|
|
type: string
|
|
enum:
|
|
- remove
|
|
bot:
|
|
type: object
|
|
description: |
|
|
Object containing details about the deactivated bot.
|
|
additionalProperties: false
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The user ID of the deactivated bot.
|
|
full_name:
|
|
type: string
|
|
description: |
|
|
The full name of the deactivated bot.
|
|
example:
|
|
{
|
|
"type": "realm_bot",
|
|
"op": "remove",
|
|
"bot":
|
|
{"user_id": 35, "full_name": "Foo Bot"},
|
|
"id": 1,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users when a bot has been deactivated.
|
|
Note that this is very similar to the bot_remove event
|
|
and one of them will be removed soon.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_bot
|
|
op:
|
|
type: string
|
|
enum:
|
|
- delete
|
|
bot:
|
|
type: object
|
|
description: |
|
|
Object containing details about the deactivated bot.
|
|
additionalProperties: false
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The user ID of the deactivated bot.
|
|
example:
|
|
{
|
|
"type": "realm_bot",
|
|
"op": "delete",
|
|
"bot":
|
|
{"user_id": 35, "full_name": "Foo Bot"},
|
|
"id": 1,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
The simpler of two possible event types sent to all users
|
|
in a Zulip organization when the configuration of the
|
|
organization (realm) has changed.
|
|
|
|
Often individual settings are migrated from this format to
|
|
the [realm/update_dict](#realm-update_dict) event format when additional realm
|
|
settings are added whose values are coupled to each other
|
|
in some way. The specific values supported by this event
|
|
type are documented in the [realm/update_dict](#realm-update_dict)
|
|
documentation.
|
|
|
|
A correct client implementation should convert these
|
|
events into the corresponding [realm/update_dict](#realm-update_dict)
|
|
event and then process that.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm
|
|
op:
|
|
type: string
|
|
enum:
|
|
- update
|
|
property:
|
|
type: string
|
|
description: |
|
|
The name of the property that was changed.
|
|
value:
|
|
description: |
|
|
The new value of the property.
|
|
nullable: true
|
|
oneOf:
|
|
- type: string
|
|
- type: boolean
|
|
- type: integer
|
|
extra_data:
|
|
description: |
|
|
Object containing extra data related to the changed
|
|
property.
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
upload_quota:
|
|
type: integer
|
|
description: |
|
|
Note: Only present if changed property is `plan_type`.
|
|
|
|
The new upload quota for the Zulip organization.
|
|
example:
|
|
{
|
|
"type": "realm",
|
|
"op": "update",
|
|
"property": "disallow_disposable_email_addresses",
|
|
"value": false,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users in a Zulip organization when the
|
|
organization (realm) is deactivated. Its main purpose is to
|
|
flush active longpolling connections so clients can immediately
|
|
show the organization as deactivated.
|
|
|
|
Clients cannot rely on receiving this event, because they will
|
|
no longer be able to authenticate to the Zulip API due to the
|
|
deactivation, and thus can miss it if they did not have an active
|
|
longpolling connection at the moment of deactivation.
|
|
|
|
Correct handling of realm deactivations requires that clients
|
|
parse authentication errors from GET /events; if that is done
|
|
correctly, the client can ignore this event type and rely on its
|
|
handling of the `GET /events` request it will do immediately
|
|
after processing this batch of events.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm
|
|
op:
|
|
type: string
|
|
enum:
|
|
- deactivated
|
|
realm_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the deactivated realm.
|
|
example:
|
|
{
|
|
"type": "realm",
|
|
"op": "deactivated",
|
|
"realm_id": 2,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
description: |
|
|
Event sent to all the users whenever the Zulip server restarts.
|
|
|
|
Specifically, this event is sent whenever the Tornado process
|
|
for the user is restarted; in particular, this will always happen
|
|
when the Zulip server is upgraded.
|
|
|
|
Clients can use this event to know when they should get a new
|
|
event queue after a server upgrade. Clients doing so must implement
|
|
a random delay strategy to spread such restarts over 10 minutes or
|
|
more to avoid creating a synchronized thundering herd effect.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- restart
|
|
zulip_version:
|
|
type: string
|
|
description: |
|
|
The Zulip version number, in the format where this appears
|
|
in the [server_settings](/api/get-server-settings) and
|
|
[register](/api/register-queue) responses.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 59).
|
|
zulip_merge_base:
|
|
type: string
|
|
description: |
|
|
The Zulip merge base number, in the format where this appears
|
|
in the [server_settings](/api/get-server-settings) and
|
|
[register](/api/register-queue) responses.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 88).
|
|
zulip_feature_level:
|
|
type: integer
|
|
description: |
|
|
The [Zulip feature level](/api/changelog) of the server
|
|
after the restart.
|
|
|
|
Clients can safely avoid refetching their state and
|
|
creating a new event queue when the API feature level has not
|
|
changed, or when they know the specific feature level change
|
|
is not relevant to the client (E.g. it just adds a new endpoint
|
|
that the client doesn't use).
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 59).
|
|
immediate:
|
|
type: boolean
|
|
description: |
|
|
Whether the client should fetch a new event queue immediately,
|
|
rather than using a backoff strategy to avoid thundering herds.
|
|
A Zulip development server uses this parameter to reload
|
|
clients immediately.
|
|
server_generation:
|
|
type: integer
|
|
description: |
|
|
The timestamp at which the server started.
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"id": 0,
|
|
"immediate": true,
|
|
"server_generation": 1619334181,
|
|
"type": "restart",
|
|
"zulip_feature_level": 57,
|
|
"zulip_version": "5.0-dev-1650-gc3fd37755f",
|
|
"zulip_merge_base": "5.0-dev-1646-gea6b21cd8c",
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
The more general of two event types that may be used when
|
|
sending an event to all users in a Zulip organization when
|
|
the configuration of the organization (realm) has changed.
|
|
|
|
Unlike the simpler [realm/update](#realm-update) event format, this
|
|
event type supports multiple properties being changed in a
|
|
single event.
|
|
|
|
**Changes**: In Zulip 7.0 (feature level 163), the realm setting
|
|
`email_address_visibility` was removed. It was replaced by a [user
|
|
setting](/api/update-settings#parameter-email_address_visibility) with
|
|
a [realm user default][user-defaults], with the encoding of different
|
|
values preserved. Clients can support all versions by supporting the
|
|
current API and treating every user as having the realm's
|
|
`email_address_visibility` value.
|
|
|
|
[user-defaults]: /api/update-realm-user-settings-defaults#parameter-email_address_visibility
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm
|
|
op:
|
|
type: string
|
|
enum:
|
|
- update_dict
|
|
property:
|
|
type: string
|
|
deprecated: true
|
|
description: |
|
|
Always `"default"`. Present for backwards-compatibility with older
|
|
clients that predate the `update_dict` event style.
|
|
|
|
**Deprecated** and will be removed in a future release.
|
|
data:
|
|
type: object
|
|
description: |
|
|
An object containing the properties that have changed.
|
|
|
|
**Changes**: In Zulip 7.0 (feature level 183), the
|
|
`community_topic_editing_limit_seconds` property was removed.
|
|
It was documented as potentially returned as a changed property
|
|
in this event, but in fact it was only ever returned in the
|
|
[`POST /register`](/api/register-queue) response.
|
|
|
|
Before Zulip 6.0 (feature level 150), on changing any of
|
|
`allow_message_editing`, `message_content_edit_limit_seconds`, or
|
|
`edit_topic_policy` settings, this object included all the three settings
|
|
irrespective of which of these settings were changed. Now, a separate event
|
|
is sent for each changed setting.
|
|
properties:
|
|
add_custom_emoji_policy:
|
|
type: integer
|
|
description: |
|
|
The [policy](/api/roles-and-permissions#permission-levels)
|
|
for which users can add custom emoji in this organization.
|
|
allow_edit_history:
|
|
type: boolean
|
|
description: |
|
|
Whether this organization is configured to allow users to access
|
|
[message edit history](/help/view-a-messages-edit-history).
|
|
allow_message_editing:
|
|
type: boolean
|
|
description: |
|
|
Whether this organizations [message edit policy](/help/restrict-message-editing-and-deletion)
|
|
allows editing the content of messages.
|
|
authentication_methods:
|
|
type: object
|
|
additionalProperties:
|
|
description: |
|
|
Boolean describing whether the authentication method (i.e its key)
|
|
is enabled in this organization.
|
|
type: boolean
|
|
description: |
|
|
Dictionary of 'authentication_method_name': 'boolean' with each
|
|
entry describing whether the authentication name can be used for
|
|
authenticating into the organization.
|
|
bot_creation_policy:
|
|
type: integer
|
|
description: |
|
|
The [policy](/api/roles-and-permissions#permission-levels)
|
|
for which users can create bot users in this organization.
|
|
create_public_stream_policy:
|
|
type: integer
|
|
description: |
|
|
The [policy](/api/roles-and-permissions#permission-levels)
|
|
for which users can create public streams in this organization.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 102), permission to
|
|
create streams was controlled by the `create_stream_policy` setting.
|
|
create_private_stream_policy:
|
|
type: integer
|
|
description: |
|
|
The [policy](/api/roles-and-permissions#permission-levels)
|
|
for which users can create private streams in this organization.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 102), permission to
|
|
create streams was controlled by the `create_stream_policy` setting.
|
|
create_web_public_stream_policy:
|
|
type: integer
|
|
description: |
|
|
The [policy](/api/roles-and-permissions#permission-levels)
|
|
for which users can create web public streams in this organization.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 103).
|
|
default_code_block_language:
|
|
type: string
|
|
nullable: true
|
|
description: |
|
|
The default pygments language code to be used for a code blocks
|
|
in this organization. If `null`, no default has been set.
|
|
default_language:
|
|
type: string
|
|
description: |
|
|
The default language for the organization.
|
|
description:
|
|
type: string
|
|
description: |
|
|
The description of the organization, used on login and registration pages.
|
|
digest_emails_enabled:
|
|
type: boolean
|
|
description: |
|
|
Whether the organization has enabled [weekly digest emails](/help/digest-emails).
|
|
digest_weekday:
|
|
type: integer
|
|
description: |
|
|
The day of the week when the organization will send
|
|
its weekly digest email to inactive users.
|
|
disallow_disposable_email_addresses:
|
|
type: boolean
|
|
description: |
|
|
Whether the organization disallows disposable email
|
|
addresses.
|
|
edit_topic_policy:
|
|
type: integer
|
|
description: |
|
|
The [policy][permission-level] for which users can edit topics of any message.
|
|
|
|
- 1 = Members only
|
|
- 2 = Admins only
|
|
- 3 = [Full members][calc-full-member] only
|
|
- 4 = Moderators only
|
|
- 5 = Everyone
|
|
- 6 = Nobody
|
|
|
|
**Changes**: Nobody added as an option in Zulip 7.0 (feature level 159).
|
|
|
|
New in Zulip 5.0 (feature level 75), replacing the previous
|
|
`allow_community_topic_editing` boolean.
|
|
|
|
[permission-level]: /api/roles-and-permissions#permission-levels
|
|
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
|
|
email_changes_disabled:
|
|
type: boolean
|
|
description: |
|
|
Whether users are allowed to change their own email address in this
|
|
organization. This is typically disabled for organizations that
|
|
synchronize accounts from LDAP or a similar corporate database.
|
|
emails_restricted_to_domains:
|
|
type: boolean
|
|
description: |
|
|
Whether [new users joining](/help/restrict-account-creation#configuring-email-domain-restrictions)
|
|
this organization are required to have an email
|
|
address in one of the `realm_domains` configured for the organization.
|
|
enable_spectator_access:
|
|
type: boolean
|
|
description: |
|
|
Whether web-public streams are enabled in this organization.
|
|
|
|
Can only be enabled if the `WEB_PUBLIC_STREAMS_ENABLED`
|
|
[server setting][server-settings] is enabled on the Zulip
|
|
server. See also the `create_web_public_stream_policy` realm
|
|
setting.
|
|
|
|
[server-settings]: https://zulip.readthedocs.io/en/stable/production/settings.html
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 109).
|
|
giphy_rating:
|
|
type: integer
|
|
description: |
|
|
Maximum rating of the GIFs that will be retrieved from GIPHY.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 55).
|
|
icon_source:
|
|
type: string
|
|
description: |
|
|
String indicating whether the organization's
|
|
[profile icon](/help/create-your-organization-profile) was uploaded
|
|
by a user or is the default. Useful for UI allowing editing the organization's icon.
|
|
|
|
- "G" means generated by Gravatar (the default).
|
|
- "U" means uploaded by an organization administrator.
|
|
icon_url:
|
|
type: string
|
|
description: |
|
|
The URL of the organization's [profile icon](/help/create-your-organization-profile).
|
|
inline_image_preview:
|
|
type: boolean
|
|
description: |
|
|
Whether this organization has been configured to enable
|
|
[previews of linked images](/help/allow-image-link-previews).
|
|
inline_url_embed_preview:
|
|
type: boolean
|
|
description: |
|
|
Whether this organization has been configured to enable
|
|
[previews of linked websites](/help/allow-image-link-previews).
|
|
invite_required:
|
|
type: boolean
|
|
description: |
|
|
Whether an invitation is required to join this organization.
|
|
invite_to_realm_policy:
|
|
type: integer
|
|
description: |
|
|
The [policy](/api/roles-and-permissions#permission-levels)
|
|
for which users can invite other users to join the organization.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 50) replacing the
|
|
previous `invite_by_admins_only` boolean.
|
|
invite_to_stream_policy:
|
|
type: integer
|
|
description: |
|
|
The [policy](/api/roles-and-permissions#permission-levels)
|
|
for which users can add other users to streams in this organization.
|
|
logo_source:
|
|
type: string
|
|
description: |
|
|
String indicating whether the organization's
|
|
[profile wide logo](/help/create-your-organization-profile) was uploaded
|
|
by a user or is the default. Useful for UI allowing editing the
|
|
organization's wide logo.
|
|
|
|
- "D" means the logo is the default Zulip logo.
|
|
- "U" means uploaded by an organization administrator.
|
|
logo_url:
|
|
type: string
|
|
description: |
|
|
The URL of the organization's wide logo configured in the
|
|
[organization profile](/help/create-your-organization-profile).
|
|
mandatory_topics:
|
|
type: boolean
|
|
description: |
|
|
Whether [topics are required](/help/require-topics) for messages in this organization.
|
|
message_content_allowed_in_email_notifications:
|
|
type: boolean
|
|
description: |
|
|
Whether notification emails in this organization are allowed to
|
|
contain Zulip the message content, or simply indicate that a new
|
|
message was sent.
|
|
message_content_delete_limit_seconds:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
Messages sent more than this many seconds ago cannot be deleted
|
|
with this organization's
|
|
[message deletion policy](/help/restrict-message-editing-and-deletion).
|
|
|
|
Will not be 0. A `null` value means no limit: messages can be deleted
|
|
regardless of how long ago they were sent.
|
|
|
|
**Changes**: No limit was represented using the
|
|
special value `0` before Zulip 5.0 (feature level 100).
|
|
message_content_edit_limit_seconds:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
Messages sent more than this many seconds ago cannot be edited
|
|
with this organization's
|
|
[message edit policy](/help/restrict-message-editing-and-deletion).
|
|
|
|
**Changes**: No limit was represented using the
|
|
special value `0` before Zulip 6.0 (feature level 138).
|
|
move_messages_within_stream_limit_seconds:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
Messages sent more than this many seconds ago cannot be moved within a
|
|
stream to another topic by users who have permission to do so based on this
|
|
organization's [topic edit policy](/help/restrict-moving-messages). This
|
|
setting does not affect moderators and administrators.
|
|
|
|
Will not be 0. A `null` value means no limit, so message topics can be
|
|
edited regardless of how long ago they were sent.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 162). Previously, this time
|
|
limit was always 72 hours for users who were not administrators or
|
|
moderators.
|
|
move_messages_between_streams_limit_seconds:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
Messages sent more than this many seconds ago cannot be moved between
|
|
streams by users who have permission to do so based on this organization's
|
|
[message move policy](/help/restrict-moving-messages). This setting does
|
|
not affect moderators and administrators.
|
|
|
|
Will not be 0. A `null` value means no limit, so messages can be moved
|
|
regardless of how long ago they were sent.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 162). Previously, there was
|
|
no time limit for moving messages between streams for users with permission
|
|
to do so.
|
|
move_messages_between_streams_policy:
|
|
type: integer
|
|
description: |
|
|
The [policy][permission-level] for which users can move messages from
|
|
one stream to another.
|
|
|
|
- 1 = Members only
|
|
- 2 = Administrators only
|
|
- 3 = [Full members][calc-full-member] only
|
|
- 4 = Moderators only
|
|
- 6 = Nobody
|
|
|
|
**Changes**: Nobody added as an option in Zulip 7.0 (feature level 159).
|
|
|
|
New in Zulip 4.0 (feature level 56).
|
|
|
|
[permission-level]: /api/roles-and-permissions#permission-levels
|
|
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
|
|
name:
|
|
type: string
|
|
description: |
|
|
The name of the organization, used in login pages etc.
|
|
name_changes_disabled:
|
|
type: boolean
|
|
description: |
|
|
Indicates whether users are
|
|
[allowed to change](/help/restrict-name-and-email-changes) their name
|
|
via the Zulip UI in this organization. Typically disabled
|
|
in organizations syncing this type of account information from
|
|
an external user database like LDAP.
|
|
night_logo_source:
|
|
type: string
|
|
description: |
|
|
String indicating whether the organization's dark theme
|
|
[profile wide logo](/help/create-your-organization-profile) was uploaded
|
|
by a user or is the default. Useful for UI allowing editing the
|
|
organization's wide logo.
|
|
|
|
- "D" means the logo is the default Zulip logo.
|
|
- "U" means uploaded by an organization administrator.
|
|
night_logo_url:
|
|
type: string
|
|
description: |
|
|
The URL of the organization's dark theme wide-format logo configured in the
|
|
[organization profile](/help/create-your-organization-profile).
|
|
notifications_stream_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the stream to which automated messages announcing the
|
|
[creation of new streams][new-stream-announce] are sent.
|
|
|
|
Will be `-1` if such automated messages are disabled.
|
|
|
|
Since these automated messages are sent by the server, this field is
|
|
primarily relevant to clients containing UI for changing it.
|
|
|
|
[new-stream-announce]: /help/configure-notification-bot#new-stream-announcements
|
|
org_type:
|
|
type: integer
|
|
description: |
|
|
The [organization type](/help/organization-type)
|
|
for the realm.
|
|
|
|
- 0 = Unspecified
|
|
- 10 = Business
|
|
- 20 = Open-source project
|
|
- 30 = Education (non-profit)
|
|
- 35 = Education (for-profit)
|
|
- 40 = Research
|
|
- 50 = Event or conference
|
|
- 60 = Non-profit (registered)
|
|
- 70 = Government
|
|
- 80 = Political group
|
|
- 90 = Community
|
|
- 100 = Personal
|
|
- 1000 = Other
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 128).
|
|
plan_type:
|
|
type: integer
|
|
description: |
|
|
The plan type of the organization.
|
|
|
|
- 1 = Self-hosted organization (SELF_HOSTED)
|
|
- 2 = Zulip Cloud free plan (LIMITED)
|
|
- 3 = Zulip Cloud Standard plan (STANDARD)
|
|
- 4 = Zulip Cloud Standard plan, sponsored for free (STANDARD_FREE)
|
|
presence_disabled:
|
|
type: boolean
|
|
description: |
|
|
Whether online presence of other users is shown in this
|
|
organization.
|
|
private_message_policy:
|
|
type: integer
|
|
description: |
|
|
[Policy](/api/roles-and-permissions#permission-levels)
|
|
for [who can send direct messages](/help/restrict-direct-messages)
|
|
in this organization.
|
|
|
|
- 1 = Everyone
|
|
- 2 = Nobody
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 1).
|
|
send_welcome_emails:
|
|
type: boolean
|
|
description: |
|
|
Whether or not this organization is configured to send the standard Zulip
|
|
[welcome emails](/help/disable-welcome-emails) to new users joining the organization.
|
|
signup_notifications_stream_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the stream to which automated messages announcing
|
|
that [new users have joined the organization][new-user-announce] are sent.
|
|
|
|
Will be `-1` if such automated messages are disabled.
|
|
|
|
Since these automated messages are sent by the server, this field is
|
|
primarily relevant to clients containing UI for changing it.
|
|
|
|
[new-user-announce]: /help/configure-notification-bot#new-user-announcements
|
|
user_group_edit_policy:
|
|
type: integer
|
|
description: |
|
|
The organization's [policy][permission-level] for
|
|
[who can manage user groups][user-group-permissions].
|
|
|
|
- 1 = All members can create and edit user groups
|
|
- 2 = Only organization administrators can create and edit user groups
|
|
- 3 = Only [full members][calc-full-member] can create and edit user groups
|
|
- 4 = Only organization administrators and moderators can create and edit user groups
|
|
|
|
[user-group-permissions]: /help/user-groups#configure-who-can-create-and-manage-user-groups
|
|
[permission-level]: /api/roles-and-permissions#permission-levels
|
|
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
|
|
video_chat_provider:
|
|
type: integer
|
|
description: |
|
|
The configured [video call provider](/help/start-a-call) for the
|
|
organization.
|
|
|
|
- 0 = None
|
|
- 1 = Jitsi Meet
|
|
- 3 = Zoom
|
|
- 4 = BigBlueButton
|
|
|
|
**Changes**: None added as an option in Zulip 3.0 (feature level 1)
|
|
to disable video call UI.
|
|
waiting_period_threshold:
|
|
type: integer
|
|
description: |
|
|
Members whose accounts have been created at least this many days ago
|
|
will be treated as [full members][calc-full-member]
|
|
for the purpose of settings that restrict access to new members.
|
|
|
|
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
|
|
want_advertise_in_communities_directory:
|
|
type: boolean
|
|
description: |
|
|
Whether the organization has given permission to be advertised in the
|
|
Zulip [communities directory](/help/communities-directory).
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 129).
|
|
wildcard_mention_policy:
|
|
type: integer
|
|
description: |
|
|
The [policy][permission-level] for who can use wildcard mentions in
|
|
large streams.
|
|
|
|
- 1 = Any user can use wildcard mentions in large streams.
|
|
- 2 = Only members can use wildcard mentions in large streams.
|
|
- 3 = Only [full members][calc-full-member] can use wildcard mentions in large streams.
|
|
- 5 = Only organization administrators can use wildcard mentions in large streams.
|
|
- 6 = Nobody can use wildcard mentions in large streams.
|
|
- 7 = Only organization administrators and moderators can use wildcard mentions in large streams.
|
|
|
|
All users will receive a warning/reminder when using
|
|
mentions in large streams, even when permitted to do so.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 33). Moderators option added in
|
|
Zulip 4.0 (feature level 62). Stream administrators option removed in
|
|
Zulip 6.0 (feature level 133).
|
|
|
|
[permission-level]: /api/roles-and-permissions#permission-levels
|
|
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
|
|
enable_read_receipts:
|
|
type: boolean
|
|
description: |
|
|
Whether read receipts is enabled in the organization or not.
|
|
|
|
If disabled, read receipt data will be unavailable to clients, regardless
|
|
of individual users' personal read receipt settings. See also the
|
|
`send_read_receipts` setting within `realm_user_settings_defaults`.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 137).
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "realm",
|
|
"op": "update_dict",
|
|
"property": "default",
|
|
"data":
|
|
{"message_content_edit_limit_seconds": 600},
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users in a Zulip organization when the
|
|
[default settings for new users][new-user-defaults]
|
|
of the organization (realm) have changed.
|
|
|
|
[new-user-defaults]: /help/configure-default-new-user-settings
|
|
|
|
See [PATCH /realm/user_settings_defaults](/api/update-realm-user-settings-defaults)
|
|
for details on possible properties.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 95).
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- realm_user_settings_defaults
|
|
op:
|
|
type: string
|
|
enum:
|
|
- update
|
|
property:
|
|
type: string
|
|
description: |
|
|
The name of the property that was changed.
|
|
value:
|
|
description: |
|
|
The new value of the property.
|
|
oneOf:
|
|
- type: boolean
|
|
- type: integer
|
|
- type: string
|
|
example:
|
|
{
|
|
"type": "realm_user_settings_defaults",
|
|
"op": "update",
|
|
"property": "left_side_userlist",
|
|
"value": false,
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event containing details of newly created drafts.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- drafts
|
|
op:
|
|
type: string
|
|
enum:
|
|
- add
|
|
drafts:
|
|
type: array
|
|
description: |
|
|
An array containing objects for the newly created drafts.
|
|
items:
|
|
$ref: "#/components/schemas/Draft"
|
|
example:
|
|
{
|
|
"type": "drafts",
|
|
"op": "add",
|
|
"drafts":
|
|
[
|
|
{
|
|
"id": 17,
|
|
"type": "private",
|
|
"to": [6],
|
|
"topic": "",
|
|
"content": "Hello there!",
|
|
"timestamp": 15954790200,
|
|
},
|
|
],
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event containing details for an edited draft.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- drafts
|
|
op:
|
|
type: string
|
|
enum:
|
|
- update
|
|
draft:
|
|
$ref: "#/components/schemas/Draft"
|
|
example:
|
|
{
|
|
"type": "drafts",
|
|
"op": "update",
|
|
"draft":
|
|
{
|
|
"id": 17,
|
|
"type": "private",
|
|
"to": [6, 7, 8, 9, 10],
|
|
"topic": "",
|
|
"content": "Hello everyone!",
|
|
"timestamp": 15954790200,
|
|
},
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event containing the ID of a deleted draft.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- drafts
|
|
op:
|
|
type: string
|
|
enum:
|
|
- remove
|
|
draft_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the draft that was just deleted.
|
|
example:
|
|
{
|
|
"type": "drafts",
|
|
"op": "update",
|
|
"draft_id": 17,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
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"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- scheduled_messages
|
|
op:
|
|
type: string
|
|
enum:
|
|
- add
|
|
scheduled_messages:
|
|
type: array
|
|
description: |
|
|
An array of objects containing details of the newly created
|
|
scheduled messages.
|
|
items:
|
|
$ref: "#/components/schemas/ScheduledMessage"
|
|
example:
|
|
{
|
|
"type": "scheduled_messages",
|
|
"op": "add",
|
|
"scheduled_messages":
|
|
[
|
|
{
|
|
"scheduled_message_id": 17,
|
|
"type": "private",
|
|
"to": [6],
|
|
"content": "Hello there!",
|
|
"rendered_content": "<p>Hello there!</p>",
|
|
"scheduled_delivery_timestamp": 1681662420,
|
|
"failed": false,
|
|
},
|
|
],
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
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"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- scheduled_messages
|
|
op:
|
|
type: string
|
|
enum:
|
|
- update
|
|
scheduled_message:
|
|
$ref: "#/components/schemas/ScheduledMessage"
|
|
example:
|
|
{
|
|
"type": "scheduled_messages",
|
|
"op": "update",
|
|
"scheduled_message":
|
|
{
|
|
"scheduled_message_id": 17,
|
|
"type": "private",
|
|
"to": [6],
|
|
"content": "Hello there!",
|
|
"rendered_content": "<p>Hello there!</p>",
|
|
"scheduled_delivery_timestamp": 1681662420,
|
|
"failed": false,
|
|
},
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
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"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- scheduled_messages
|
|
op:
|
|
type: string
|
|
enum:
|
|
- remove
|
|
scheduled_message_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the scheduled message that was deleted.
|
|
example:
|
|
{
|
|
"type": "scheduled_messages",
|
|
"op": "remove",
|
|
"scheduled_message_id": 17,
|
|
}
|
|
queue_id:
|
|
type: string
|
|
description: |
|
|
The ID of the registered queue.
|
|
example:
|
|
{
|
|
"queue_id": "fb67bf8a-c031-47cc-84cf-ed80accacda8",
|
|
"events":
|
|
[
|
|
{
|
|
"id": 0,
|
|
"message":
|
|
{
|
|
"avatar_url": "https://url/for/othello-bots/avatar",
|
|
"client": "website",
|
|
"content": "I come not, friends, to steal away your hearts.",
|
|
"content_type": "text/x-markdown",
|
|
"display_recipient": "Denmark",
|
|
"id": 12345678,
|
|
"recipient_id": 12314,
|
|
"sender_email": "othello-bot@example.com",
|
|
"sender_full_name": "Othello Bot",
|
|
"sender_id": 13215,
|
|
"sender_realm_str": "example",
|
|
"topic_links": [],
|
|
"timestamp": 1375978403,
|
|
"type": "stream",
|
|
},
|
|
"type": "message",
|
|
},
|
|
{
|
|
"id": 1,
|
|
"message":
|
|
{
|
|
"avatar_url": "https://url/for/othello-bots/avatar",
|
|
"client": "website",
|
|
"content": "With mirth and laughter let old wrinkles come.",
|
|
"content_type": "text/x-markdown",
|
|
"display_recipient":
|
|
[
|
|
{
|
|
"email": "hamlet@example.com",
|
|
"full_name": "Hamlet of Denmark",
|
|
"id": 31572,
|
|
},
|
|
],
|
|
"id": 12345679,
|
|
"recipient_id": 18391,
|
|
"sender_email": "othello-bot@example.com",
|
|
"sender_full_name": "Othello Bot",
|
|
"sender_id": 13215,
|
|
"sender_realm_str": "example",
|
|
"subject": "",
|
|
"topic_links": [],
|
|
"timestamp": 1375978404,
|
|
"type": "private",
|
|
},
|
|
"type": "message",
|
|
},
|
|
],
|
|
"msg": "",
|
|
"result": "success",
|
|
}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/BadEventQueueIdError"
|
|
- description: |
|
|
#### BAD_EVENT_QUEUE_ID errors
|
|
|
|
This error occurs if the target event queue has been garbage collected.
|
|
A compliant client will handle this error by re-initializing itself
|
|
(e.g. a Zulip web app browser window will reload in this case).
|
|
|
|
See [the /register endpoint docs](/api/register-queue) for details on how to
|
|
handle these correctly.
|
|
|
|
The following is the error response in such case:
|
|
delete:
|
|
operationId: delete-queue
|
|
summary: Delete an event queue
|
|
tags: ["real_time_events"]
|
|
description: |
|
|
Delete a previously registered queue.
|
|
parameters:
|
|
- $ref: "#/components/parameters/QueueId"
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/BadEventQueueIdError"
|
|
- description: |
|
|
A typical JSON response for when the `queue_id` is non-existent or the
|
|
associated queue has already been deleted:
|
|
/get_stream_id:
|
|
get:
|
|
operationId: get-stream-id
|
|
summary: Get stream ID
|
|
tags: ["streams"]
|
|
description: |
|
|
Get the unique ID of a given stream.
|
|
parameters:
|
|
- name: stream
|
|
in: query
|
|
description: |
|
|
The name of the stream to access.
|
|
schema:
|
|
type: string
|
|
example: Denmark
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the given stream.
|
|
example: {"msg": "", "result": "success", "stream_id": 15}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Invalid stream name 'nonexistent'",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON response for when the supplied stream does not exist:
|
|
/mark_all_as_read:
|
|
post:
|
|
operationId: mark-all-as-read
|
|
summary: Mark all messages as read
|
|
tags: ["messages"]
|
|
description: |
|
|
Marks all of the current user's unread messages as read.
|
|
|
|
**Changes**: Before Zulip 6.0 (feature level 153), this
|
|
request did a single atomic operation, which could time out
|
|
with 10,000s of unread messages to mark as read.
|
|
|
|
It now marks messages as read in batches, starting with the
|
|
newest messages, so that progress will be made even if the
|
|
request times out.
|
|
|
|
If the server's processing is interrupted by a timeout, it
|
|
will return an HTTP 200 success response with result
|
|
"partially_completed". A correct client should repeat the
|
|
request when handling such a response.
|
|
responses:
|
|
"200":
|
|
description: Success or partial success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/JsonSuccess"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- allOf:
|
|
- $ref: "#/components/schemas/PartiallyCompleted"
|
|
- example:
|
|
{
|
|
"code": "REQUEST_TIMEOUT",
|
|
"msg": "",
|
|
"result": "partially_completed",
|
|
}
|
|
description: |
|
|
If the request exceeds its processing time limit after having
|
|
successfully marked some messages as read, response code 200
|
|
with result "partially_completed" and code "REQUEST_TIMEOUT" will be returned like this:
|
|
/mark_stream_as_read:
|
|
post:
|
|
operationId: mark-stream-as-read
|
|
summary: Mark messages in a stream as read
|
|
tags: ["messages"]
|
|
description: |
|
|
Mark all the unread messages in a stream as read.
|
|
parameters:
|
|
- name: stream_id
|
|
in: query
|
|
description: |
|
|
The ID of the stream to access.
|
|
schema:
|
|
type: integer
|
|
example: 43
|
|
required: true
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
/mark_topic_as_read:
|
|
post:
|
|
operationId: mark-topic-as-read
|
|
summary: Mark messages in a topic as read
|
|
tags: ["messages"]
|
|
description: |
|
|
Mark all the unread messages in a topic as read.
|
|
parameters:
|
|
- name: stream_id
|
|
in: query
|
|
description: |
|
|
The ID of the stream to access.
|
|
schema:
|
|
type: integer
|
|
example: 43
|
|
required: true
|
|
- name: topic_name
|
|
in: query
|
|
description: |
|
|
The name of the topic whose messages should be marked as read.
|
|
schema:
|
|
type: string
|
|
example: new coffee machine
|
|
required: true
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
/attachments:
|
|
get:
|
|
operationId: get-attachments
|
|
summary: Get attachments
|
|
tags: ["users"]
|
|
description: |
|
|
Fetch metadata on files uploaded by the requesting user.
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
attachments:
|
|
type: array
|
|
description: |
|
|
A list of `attachment` objects, each containing
|
|
details about a file uploaded by the user.
|
|
items:
|
|
$ref: "#/components/schemas/Attachments"
|
|
upload_space_used:
|
|
type: integer
|
|
description: |
|
|
The total size of all files uploaded by users in the organization,
|
|
in bytes.
|
|
example:
|
|
{
|
|
"result": "success",
|
|
"msg": "",
|
|
"attachments":
|
|
[
|
|
{
|
|
"id": 1,
|
|
"name": "166050.jpg",
|
|
"path_id": "2/ce/DfOkzwdg_IwlrN3myw3KGtiJ/166050.jpg",
|
|
"size": 571946,
|
|
"create_time": 1588145417000,
|
|
"messages":
|
|
[
|
|
{"id": 102, "date_sent": 1588145424000},
|
|
{"id": 103, "date_sent": 1588145448000},
|
|
],
|
|
},
|
|
],
|
|
"upload_space_used": 571946,
|
|
}
|
|
/attachments/{attachment_id}:
|
|
delete:
|
|
operationId: remove-attachment
|
|
summary: Delete an attachment
|
|
tags: ["users"]
|
|
description: |
|
|
Delete an uploaded file given its attachment ID.
|
|
|
|
Note that uploaded files that have been referenced in at least
|
|
one message are automatically deleted once the last message
|
|
containing a link to them is deleted (whether directly or via
|
|
a [message retention policy](/help/message-retention-policy)).
|
|
|
|
Uploaded files that are never used in a message are
|
|
automatically deleted a few weeks after being uploaded.
|
|
|
|
Attachment IDs can be contained from [GET /attachments](/api/get-attachments).
|
|
parameters:
|
|
- name: attachment_id
|
|
in: path
|
|
description: |
|
|
The ID of the attachment to be deleted.
|
|
schema:
|
|
type: string
|
|
example: "1"
|
|
required: true
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Invalid attachment",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
description: |
|
|
A typical failed JSON response for when the `attachment_id` is invalid
|
|
"401":
|
|
description: Error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Not logged in: API authentication or user session required",
|
|
}
|
|
description: |
|
|
A typical failed JSON response for when the user is not logged in
|
|
/drafts:
|
|
get:
|
|
operationId: get-drafts
|
|
tags: ["drafts"]
|
|
summary: Get drafts
|
|
description: |
|
|
Fetch all drafts for the current user.
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
count:
|
|
type: integer
|
|
description: |
|
|
The number of drafts the user currently has. Also the
|
|
number of drafts returned under "drafts".
|
|
example: 3
|
|
drafts:
|
|
type: array
|
|
description: |
|
|
Returns all of the current user's drafts, in order of last edit time
|
|
(with the most recently edited draft appearing first).
|
|
items:
|
|
$ref: "#/components/schemas/Draft"
|
|
example:
|
|
{
|
|
"result": "success",
|
|
"msg": "",
|
|
"count": 3,
|
|
"drafts":
|
|
[
|
|
{
|
|
"id": 1,
|
|
"type": "stream",
|
|
"to": [3],
|
|
"topic": "sync drafts",
|
|
"content": "Let's add backend support for syncing drafts.",
|
|
"timestamp": 1595479019.43915,
|
|
},
|
|
{
|
|
"id": 2,
|
|
"type": "private",
|
|
"to": [4],
|
|
"topic": "",
|
|
"content": "What if we made it possible to sync drafts in Zulip?",
|
|
"timestamp": 1595479020.43916,
|
|
},
|
|
{
|
|
"id": 3,
|
|
"type": "private",
|
|
"to": [4, 10],
|
|
"topic": "",
|
|
"content": "What if we made it possible to sync drafts in Zulip?",
|
|
"timestamp": 1595479021.43916,
|
|
},
|
|
],
|
|
}
|
|
post:
|
|
operationId: create-drafts
|
|
tags: ["drafts"]
|
|
summary: Create drafts
|
|
description: |
|
|
Create one or more drafts on the server. These drafts will be automatically
|
|
synchronized to other clients via `drafts` events.
|
|
parameters:
|
|
- name: drafts
|
|
in: query
|
|
description: |
|
|
A JSON-encoded list of containing new draft objects.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Draft"
|
|
example:
|
|
[
|
|
{
|
|
"type": "stream",
|
|
"to": [1],
|
|
"topic": "questions",
|
|
"content": "What are the contribution guidelines for this project?",
|
|
"timestamp": 1595479019,
|
|
},
|
|
]
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
ids:
|
|
type: array
|
|
description: |
|
|
An array of the IDs for the drafts that were just created in the same
|
|
order as they were submitted.
|
|
items:
|
|
type: integer
|
|
example: {"result": "success", "msg": "", "ids": [1, 2, 3]}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- description: |
|
|
JSON response for when a draft targeted towards a stream does not specify
|
|
exactly one stream ID:
|
|
example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Must specify exactly 1 stream ID for stream messages",
|
|
"result": "error",
|
|
}
|
|
/drafts/{draft_id}:
|
|
patch:
|
|
operationId: edit-draft
|
|
tags: ["drafts"]
|
|
summary: Edit a draft
|
|
description: |
|
|
Edit a draft on the server. The edit will be automatically
|
|
synchronized to other clients via `drafts` events.
|
|
parameters:
|
|
- name: draft_id
|
|
in: path
|
|
schema:
|
|
type: integer
|
|
description: |
|
|
The ID of the draft to be edited.
|
|
required: true
|
|
example: 2
|
|
- name: draft
|
|
in: query
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Draft"
|
|
example:
|
|
{
|
|
"type": "stream",
|
|
"to": [1],
|
|
"topic": "questions",
|
|
"content": "how tough is a Lamy Safari?",
|
|
"timestamp": 1595479019,
|
|
}
|
|
description: |
|
|
A JSON-encoded object containing a replacement draft object for this ID.
|
|
required: true
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"404":
|
|
description: Not Found.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonError"
|
|
- description: |
|
|
JSON response for when no draft exists with the provided ID.
|
|
example: {"result": "error", "msg": "Draft does not exist"}
|
|
delete:
|
|
operationId: delete-draft
|
|
tags: ["drafts"]
|
|
summary: Delete a draft
|
|
description: |
|
|
Delete a single draft from the server. The deletion will be automatically
|
|
synchronized to other clients via a `drafts` event.
|
|
parameters:
|
|
- name: draft_id
|
|
in: path
|
|
schema:
|
|
type: integer
|
|
description: |
|
|
The ID of the draft you want to delete.
|
|
required: true
|
|
example: 1
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"404":
|
|
description: Not Found.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonError"
|
|
- description: |
|
|
JSON response for when no draft exists with the provided ID.
|
|
example: {"result": "error", "msg": "Draft does not exist"}
|
|
/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"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- 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).
|
|
parameters:
|
|
- name: type
|
|
in: query
|
|
description: |
|
|
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.
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- direct
|
|
- stream
|
|
- private
|
|
example: direct
|
|
required: true
|
|
- 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.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- type: integer
|
|
- type: array
|
|
items:
|
|
type: integer
|
|
minLength: 1
|
|
example: [9, 10]
|
|
required: true
|
|
- $ref: "#/components/parameters/RequiredContent"
|
|
- name: topic
|
|
in: query
|
|
description: |
|
|
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`](/api/register-queue) endpoint to determine
|
|
the maximum topic length.
|
|
schema:
|
|
type: string
|
|
example: Castle
|
|
allowEmptyValue: true
|
|
- name: scheduled_delivery_timestamp
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
description: |
|
|
The UNIX timestamp for when the message will be sent,
|
|
in UTC seconds.
|
|
required: true
|
|
example: 3165826990
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- 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/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:
|
|
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:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/JsonError"
|
|
- description: |
|
|
Example 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/JsonError"
|
|
- description: |
|
|
Example response for when no scheduled message exists with the provided ID.
|
|
example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"result": "error",
|
|
"msg": "Scheduled message does not exist",
|
|
}
|
|
/default_streams:
|
|
post:
|
|
operationId: add-default-stream
|
|
tags: ["streams"]
|
|
summary: Add a default stream
|
|
x-requires-administrator: true
|
|
description: |
|
|
Add a stream to the set of [default streams][default-streams]
|
|
for new users joining the organization.
|
|
|
|
[default-streams]: /help/set-default-streams-for-new-users
|
|
parameters:
|
|
- name: stream_id
|
|
in: query
|
|
description: |
|
|
The ID of the target stream.
|
|
schema:
|
|
type: integer
|
|
example: 7
|
|
required: true
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Invalid stream ID",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
A typical failed JSON response for when an invalid stream ID is passed:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Private streams cannot be made default.",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
A typical failed JSON response for when a user tries to add a private stream
|
|
to the default streams set:
|
|
delete:
|
|
operationId: remove-default-stream
|
|
summary: Remove a default stream
|
|
tags: ["streams"]
|
|
description: |
|
|
Remove a stream from the set of [default streams][default-streams]
|
|
for new users joining the organization.
|
|
|
|
[default-streams]: /help/set-default-streams-for-new-users
|
|
x-requires-administrator: true
|
|
parameters:
|
|
- name: stream_id
|
|
in: query
|
|
description: |
|
|
The ID of the target stream.
|
|
schema:
|
|
type: integer
|
|
example: 7
|
|
required: true
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- description: |
|
|
A typical failed JSON response for when an invalid stream ID is passed:
|
|
example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Invalid stream ID",
|
|
"result": "error",
|
|
}
|
|
/messages:
|
|
get:
|
|
operationId: get-messages
|
|
summary: Get messages
|
|
tags: ["messages"]
|
|
description: |
|
|
Fetch user's message history from a Zulip server.
|
|
|
|
This endpoint is the primary way to fetch a user's message history
|
|
from a Zulip server. It is useful both for Zulip clients (e.g. the
|
|
web, desktop, mobile, and terminal clients) as well as bots, API
|
|
clients, backup scripts, etc.
|
|
|
|
Note that a user's message history does not contain messages sent to
|
|
streams before they [subscribe](/api/subscribe), and newly created
|
|
bot users are not usually subscribed to any streams.
|
|
|
|
By specifying a [narrow filter](/api/get-messages#parameter-narrow),
|
|
you can use this endpoint to fetch the messages matching any search
|
|
query that is supported by Zulip's powerful full-text search backend.
|
|
|
|
In either case, you specify an `anchor` message (or ask the server to
|
|
calculate the first unread message for you and use that as the
|
|
anchor), as well as a number of messages before and after the anchor
|
|
message. The server returns those messages, sorted by message ID, as
|
|
well as some metadata that makes it easy for a client to determine
|
|
whether there are more messages matching the query that were not
|
|
returned due to the `num_before` and `num_after` limits.
|
|
|
|
We recommend setting `num_before` and `num_after` to no more than 1000, to
|
|
avoid generating very large HTTP responses. A maximum of 5000 messages
|
|
can be obtained per request; attempting to exceed this will result in an
|
|
error.
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: exclude
|
|
parameters:
|
|
enum:
|
|
- client_gravatar
|
|
- apply_markdown
|
|
- use_first_unread_anchor
|
|
- include_anchor
|
|
parameters:
|
|
- name: anchor
|
|
in: query
|
|
description: |
|
|
Integer message ID to anchor fetching of new messages. Supports special
|
|
string values for when the client wants the server to compute the anchor
|
|
to use:
|
|
|
|
- `newest`: The most recent message.
|
|
- `oldest`: The oldest message.
|
|
- `first_unread`: The oldest unread message matching the
|
|
query, if any; otherwise, the most recent message.
|
|
|
|
**Changes**: String values are new in Zulip 3.0 (feature level 1). The
|
|
`first_unread` functionality was supported in Zulip 2.1.x
|
|
and older by not sending `anchor` and using `use_first_unread_anchor`.
|
|
|
|
In Zulip 2.1.x and older, `oldest` can be emulated with
|
|
`"anchor": 0`, and `newest` with `"anchor": 10000000000000000`
|
|
(that specific large value works around a bug in Zulip
|
|
2.1.x and older in the `found_newest` return value).
|
|
schema:
|
|
oneOf:
|
|
- type: string
|
|
- type: integer
|
|
example: 43
|
|
- name: include_anchor
|
|
in: query
|
|
description: |
|
|
Whether a message with the specified ID matching the narrow
|
|
should be included.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 155).
|
|
schema:
|
|
type: boolean
|
|
default: true
|
|
example: false
|
|
- name: num_before
|
|
in: query
|
|
description: |
|
|
The number of messages with IDs less than the anchor to retrieve.
|
|
schema:
|
|
type: integer
|
|
minimum: 0
|
|
example: 4
|
|
required: true
|
|
- name: num_after
|
|
in: query
|
|
description: |
|
|
The number of messages with IDs greater than the anchor to retrieve.
|
|
schema:
|
|
type: integer
|
|
minimum: 0
|
|
example: 8
|
|
required: true
|
|
- name: narrow
|
|
in: query
|
|
description: |
|
|
The narrow where you want to fetch the messages from. See how to
|
|
[construct a narrow](/api/construct-narrow).
|
|
|
|
Note that many narrows, including all that lack a `stream`
|
|
or `streams` operator, search the user's personal message
|
|
history. See [searching shared
|
|
history](/help/search-for-messages#searching-shared-history)
|
|
for details.
|
|
|
|
For example, if you would like to fetch messages from all public streams instead
|
|
of only the user's message history, then a specific narrow for
|
|
messages sent to all public streams can be used:
|
|
`{"operator": "streams", "operand": "public"}`.
|
|
|
|
Newly created bot users are not usually subscribed to any
|
|
streams, so bots using this API should either be
|
|
subscribed to appropriate streams or use a shared history
|
|
search narrow with this endpoint.
|
|
|
|
**Changes**: In Zulip 7.0 (feature level 177), narrows gained support
|
|
for three new filters related to direct messages: `is:dm`, `dm` and
|
|
`dm-including`; replacing and deprecating `is:private`, `pm-with` and
|
|
`group-pm-with` respectively.
|
|
|
|
In Zulip 2.1.0, added support for using user/stream IDs when
|
|
constructing narrows for a message's sender, its stream and/or
|
|
its recipient(s).
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
oneOf:
|
|
- type: object
|
|
required:
|
|
- operator
|
|
- operand
|
|
additionalProperties: false
|
|
properties:
|
|
operator:
|
|
type: string
|
|
operand:
|
|
oneOf:
|
|
- type: string
|
|
- type: integer
|
|
- type: array
|
|
items:
|
|
type: integer
|
|
negated:
|
|
type: boolean
|
|
- type: array
|
|
items:
|
|
type: string
|
|
minItems: 2
|
|
maxItems: 2
|
|
default: []
|
|
example: [{"operand": "Denmark", "operator": "stream"}]
|
|
- $ref: "#/components/parameters/ClientGravatar"
|
|
- name: apply_markdown
|
|
in: query
|
|
description: |
|
|
If `true`, message content is returned in the rendered HTML
|
|
format. If `false`, message content is returned in the raw
|
|
Markdown-format text that user entered.
|
|
schema:
|
|
type: boolean
|
|
default: true
|
|
example: false
|
|
- name: use_first_unread_anchor
|
|
in: query
|
|
deprecated: true
|
|
description: |
|
|
Legacy way to specify `"anchor": "first_unread"` in Zulip 2.1.x and older.
|
|
|
|
Whether to use the (computed by the server) first unread message
|
|
matching the narrow as the `anchor`. Mutually exclusive with `anchor`.
|
|
|
|
**Changes**: Deprecated in Zulip 3.0 (feature level 1) and replaced by
|
|
`"anchor": "first_unread"`.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
anchor:
|
|
type: integer
|
|
description: |
|
|
The same `anchor` specified in the request (or the computed one, if
|
|
`use_first_unread_anchor` is `true`).
|
|
found_newest:
|
|
type: boolean
|
|
description: |
|
|
Whether the `messages` list includes the very newest messages matching
|
|
the narrow (used by clients that paginate their requests to decide
|
|
whether there are more messages to fetch).
|
|
found_oldest:
|
|
type: boolean
|
|
description: |
|
|
Whether the `messages` list includes the very oldest messages matching
|
|
the narrow (used by clients that paginate their requests to decide
|
|
whether there are more messages to fetch).
|
|
found_anchor:
|
|
type: boolean
|
|
description: |
|
|
Whether the anchor message is included in the
|
|
response. If the message with the ID specified
|
|
in the request does not exist, did not match
|
|
the narrow, or was excluded via
|
|
`"include_anchor": false`, this will be false.
|
|
history_limited:
|
|
type: boolean
|
|
description: |
|
|
Whether the message history was limited due to
|
|
plan restrictions. This flag is set to `true`
|
|
only when the oldest messages(`found_oldest`)
|
|
matching the narrow is fetched.
|
|
messages:
|
|
type: array
|
|
description: |
|
|
An array of `message` objects, each containing the following
|
|
fields:
|
|
items:
|
|
allOf:
|
|
- $ref: "#/components/schemas/MessagesBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
avatar_url:
|
|
nullable: true
|
|
client: {}
|
|
content: {}
|
|
content_type: {}
|
|
display_recipient: {}
|
|
edit_history: {}
|
|
id: {}
|
|
is_me_message: {}
|
|
last_edit_timestamp: {}
|
|
reactions: {}
|
|
recipient_id: {}
|
|
sender_email: {}
|
|
sender_full_name: {}
|
|
sender_id: {}
|
|
sender_realm_str: {}
|
|
stream_id: {}
|
|
subject: {}
|
|
submessages: {}
|
|
timestamp: {}
|
|
topic_links: {}
|
|
type: {}
|
|
flags:
|
|
type: array
|
|
description: |
|
|
The user's [message flags][message-flags] for the message.
|
|
|
|
[message-flags]: /api/update-message-flags#available-flags
|
|
items:
|
|
type: string
|
|
match_content:
|
|
type: string
|
|
description: |
|
|
Only present if keyword search was included among the narrow parameters.
|
|
|
|
HTML content of a queried message that matches the narrow, with
|
|
`<span class="highlight">` elements wrapping the matches for the
|
|
search keywords.
|
|
match_subject:
|
|
type: string
|
|
description: |
|
|
Only present if keyword search was included among the narrow parameters.
|
|
|
|
HTML-escaped topic of a queried message that matches the narrow, with
|
|
`<span class="highlight">` elements wrapping the matches for the
|
|
search keywords.
|
|
example:
|
|
{
|
|
"anchor": 21,
|
|
"found_newest": true,
|
|
"found_anchor": true,
|
|
"result": "success",
|
|
"msg": "",
|
|
"messages":
|
|
[
|
|
{
|
|
"subject": "",
|
|
"sender_realm_str": "zulip",
|
|
"type": "private",
|
|
"content": "<p>Security experts agree that relational algorithms are an interesting new topic in the field of networking, and scholars concur.</p>",
|
|
"flags": ["read"],
|
|
"id": 16,
|
|
"display_recipient":
|
|
[
|
|
{
|
|
"id": 4,
|
|
"is_mirror_dummy": false,
|
|
"email": "hamlet@zulip.com",
|
|
"full_name": "King Hamlet",
|
|
},
|
|
{
|
|
"id": 5,
|
|
"is_mirror_dummy": false,
|
|
"email": "iago@zulip.com",
|
|
"full_name": "Iago",
|
|
},
|
|
{
|
|
"id": 8,
|
|
"is_mirror_dummy": false,
|
|
"email": "prospero@zulip.com",
|
|
"full_name": "Prospero from The Tempest",
|
|
},
|
|
],
|
|
"content_type": "text/html",
|
|
"is_me_message": false,
|
|
"timestamp": 1527921326,
|
|
"sender_id": 4,
|
|
"sender_full_name": "King Hamlet",
|
|
"recipient_id": 27,
|
|
"topic_links": [],
|
|
"client": "populate_db",
|
|
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
|
|
"submessages": [],
|
|
"sender_email": "hamlet@zulip.com",
|
|
"reactions": [],
|
|
},
|
|
{
|
|
"subject": "Verona3",
|
|
"stream_id": 5,
|
|
"sender_realm_str": "zulip",
|
|
"type": "stream",
|
|
"content": "<p>Wait, is this from the frontend js code or backend python code</p>",
|
|
"flags": ["read"],
|
|
"id": 21,
|
|
"display_recipient": "Verona",
|
|
"content_type": "text/html",
|
|
"is_me_message": false,
|
|
"timestamp": 1527939746,
|
|
"sender_id": 4,
|
|
"sender_full_name": "King Hamlet",
|
|
"recipient_id": 20,
|
|
"topic_links": [],
|
|
"client": "populate_db",
|
|
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
|
|
"submessages": [],
|
|
"sender_email": "hamlet@zulip.com",
|
|
"reactions": [],
|
|
},
|
|
],
|
|
}
|
|
post:
|
|
operationId: send-message
|
|
summary: Send a message
|
|
tags: ["messages"]
|
|
description: |
|
|
Send a [stream message](/help/streams-and-topics) or a
|
|
[direct message](/help/direct-messages).
|
|
parameters:
|
|
- name: type
|
|
in: query
|
|
description: |
|
|
The type of message to be sent.
|
|
|
|
`"direct"` for a direct message and `"stream"` for a stream message.
|
|
|
|
**Changes**: In Zulip 7.0 (feature level 174), `"direct"` was added as
|
|
the preferred way to request a direct message, deprecating the original
|
|
`"private"`. While `"private"` is still supported for requesting direct
|
|
messages, clients are encouraged to use to the modern convention with
|
|
servers that support it, because support for `"private"` will eventually
|
|
be removed.
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- direct
|
|
- stream
|
|
- private
|
|
example: direct
|
|
required: true
|
|
- name: to
|
|
in: query
|
|
description: |
|
|
For stream messages, either the name or integer ID of the stream. For
|
|
direct messages, either a list containing integer user IDs or a list
|
|
containing string Zulip API email addresses.
|
|
|
|
**Changes**: Support for using user/stream IDs was added in Zulip 2.0.0.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- type: string
|
|
- type: integer
|
|
- type: array
|
|
items:
|
|
type: string
|
|
- type: array
|
|
items:
|
|
type: integer
|
|
minLength: 1
|
|
example: [9, 10]
|
|
required: true
|
|
- $ref: "#/components/parameters/RequiredContent"
|
|
- name: topic
|
|
in: query
|
|
description: |
|
|
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`](/api/register-queue) endpoint to determine
|
|
the maximum topic length.
|
|
|
|
**Changes**: New in Zulip 2.0.0. Previous Zulip releases encoded
|
|
this as `subject`, which is currently a deprecated alias.
|
|
schema:
|
|
type: string
|
|
example: Castle
|
|
- name: queue_id
|
|
in: query
|
|
schema:
|
|
type: string
|
|
description: |
|
|
For clients supporting
|
|
[local echo](https://zulip.readthedocs.io/en/latest/subsystems/sending-messages.html#local-echo),
|
|
the [event queue](/api/register-queue)
|
|
ID for the client. If passed, `local_id` is required. If the message is
|
|
successfully sent, the server will include `local_id` in the `message` event
|
|
that the client with this `queue_id` will receive notifying it of the new message
|
|
via [`GET /events`](/api/get-events). This lets the client know unambiguously
|
|
that it should replace the locally echoed message, rather than adding this new
|
|
message (which would be correct if the user had sent the new message from another
|
|
device).
|
|
example: "fb67bf8a-c031-47cc-84cf-ed80accacda8"
|
|
- name: local_id
|
|
in: query
|
|
schema:
|
|
type: string
|
|
description: |
|
|
For clients supporting local echo, a unique string-format identifier
|
|
chosen freely by the client; the server will pass it back to the client without
|
|
inspecting it, as described in the `queue_id` description.
|
|
example: "100.01"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The unique ID assigned to the sent message.
|
|
example: {"msg": "", "id": 42, "result": "success"}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/NonExistingStreamNameError"
|
|
- description: |
|
|
A typical failed JSON response for when a stream message is sent to a stream
|
|
that does not exist:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Invalid email 'eeshan@zulip.com'",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
A typical failed JSON response for when a direct message is sent to a user
|
|
that does not exist:
|
|
/messages/{message_id}/history:
|
|
get:
|
|
operationId: get-message-history
|
|
summary: Get a message's edit history
|
|
tags: ["messages"]
|
|
description: |
|
|
Fetch the message edit history of a previously edited message.
|
|
|
|
Note that edit history may be disabled in some organizations; see the
|
|
[Zulip Help Center documentation on editing messages][edit-settings].
|
|
|
|
[edit-settings]: /help/view-a-messages-edit-history
|
|
parameters:
|
|
- $ref: "#/components/parameters/MessageId"
|
|
x-response-description: |
|
|
Please note that the original message's snapshot only contains the fields
|
|
`topic`, `content`, `rendered_content`, `timestamp` and `user_id`. This
|
|
snapshot will be the only one present if the message has never been edited.
|
|
|
|
Also note that each snapshot object will only contain additional data for the
|
|
modified fields for that particular edit (e.g. if only the topic or stream
|
|
was edited, `prev_content`, `prev_rendered_content`, and
|
|
`content_html_diff` will not appear).
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
message_history:
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
topic:
|
|
type: string
|
|
description: |
|
|
The topic of the message immediately
|
|
after this edit event.
|
|
prev_topic:
|
|
type: string
|
|
description: |
|
|
Only present if message's topic was edited.
|
|
|
|
The topic of the message immediately
|
|
prior to this edit event.
|
|
stream:
|
|
type: integer
|
|
description: |
|
|
Only present if message's stream was edited.
|
|
|
|
The ID of the stream containing the message
|
|
immediately after this edit event.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 118).
|
|
prev_stream:
|
|
type: integer
|
|
description: |
|
|
Only present if message's stream was edited.
|
|
|
|
The ID of the stream containing the message immediately
|
|
prior to this edit event.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 1).
|
|
content:
|
|
type: string
|
|
description: |
|
|
The raw Markdown content of the message
|
|
immediately after this edit event.
|
|
rendered_content:
|
|
type: string
|
|
description: |
|
|
The rendered HTML representation of `content`.
|
|
prev_content:
|
|
type: string
|
|
description: |
|
|
Only present if message's content was edited.
|
|
|
|
The raw Markdown content of the message immediately
|
|
prior to this edit event.
|
|
prev_rendered_content:
|
|
type: string
|
|
description: |
|
|
Only present if message's content was edited.
|
|
|
|
The rendered HTML representation of `prev_content`.
|
|
user_id:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
The ID of the user that made the edit.
|
|
|
|
Will be `null` only for edit history
|
|
events predating March 2017.
|
|
|
|
Clients can display edit history events where this
|
|
is `null` as modified by either the sender (for content
|
|
edits) or an unknown user (for topic edits).
|
|
content_html_diff:
|
|
type: string
|
|
description: |
|
|
Only present if message's content was edited.
|
|
|
|
An HTML diff between this version of the message
|
|
and the previous one.
|
|
timestamp:
|
|
type: integer
|
|
description: |
|
|
The UNIX timestamp for this edit.
|
|
description: |
|
|
A chronologically sorted, oldest to newest, array
|
|
of `snapshot` objects, each one with the values of
|
|
the message after the edit.
|
|
example:
|
|
{
|
|
"message_history":
|
|
[
|
|
{
|
|
"content": "Hello!",
|
|
"topic": "party at my houz",
|
|
"rendered_content": "<p>Hello!</p>",
|
|
"timestamp": 1530129122,
|
|
"user_id": 5,
|
|
},
|
|
{
|
|
"topic": "party at my house",
|
|
"content": "Howdy!",
|
|
"prev_content": "Hello!",
|
|
"rendered_content": "<p>Howdy!</p>",
|
|
"user_id": 5,
|
|
"prev_rendered_content": "<p>Hello!</p>",
|
|
"content_html_diff": '<div><p><span class="highlight_text_inserted">Howdy!</span></p> <p><span class="highlight_text_deleted">Hello!</span></p></div>',
|
|
"prev_topic": "party at my houz",
|
|
"timestamp": 1530129134,
|
|
},
|
|
],
|
|
"msg": "",
|
|
"result": "success",
|
|
}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/InvalidMessageError"
|
|
- description: |
|
|
An example JSON response for when the specified message does not exist:
|
|
/messages/flags:
|
|
post:
|
|
operationId: update-message-flags
|
|
summary: Update personal message flags
|
|
tags: ["messages"]
|
|
description: |
|
|
Add or remove personal message flags like `read` and `starred`
|
|
on a collection of message IDs.
|
|
|
|
See also the endpoint for [updating flags on a range of
|
|
messages within a narrow](/api/update-message-flags-for-narrow).
|
|
For updating the `read` flag on common collections of messages, see also
|
|
the
|
|
[special endpoints for marking message as read in bulk](/api/mark-all-as-read).
|
|
x-parameter-description: |
|
|
## Available flags
|
|
<div>
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th style="width:30%">Flag</th>
|
|
<th style="width:70%">Purpose</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><code>read</code></td>
|
|
<td>
|
|
Whether the user has read the message. Messages
|
|
start out unread (except for messages the user
|
|
themself sent using a non-API client) and can
|
|
later be marked as read.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>starred</code></td>
|
|
<td>Whether the user has <a href="/help/star-a-message">starred this message</a>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>collapsed</code></td>
|
|
<td>Whether the user has <a href="/help/collapse-a-message">collapsed this message</a>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>mentioned</code></td>
|
|
<td>
|
|
Whether the current user
|
|
<a href="/help/mention-a-user-or-group">was mentioned</a>
|
|
by this message, either directly or via a user
|
|
group. Cannot be changed by the user directly, but
|
|
can change if the message is edited to add/remove
|
|
a mention of the current user.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>wildcard_mentioned</code></td>
|
|
<td>
|
|
Whether this message contained
|
|
<a href="/help/mention-a-user-or-group#mention-everyone-on-a-stream">wildcard mention</a>
|
|
like @**all**. Cannot be changed by the user directly, but
|
|
can change if the message is edited to add/remove
|
|
a wildcard mention.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>has_alert_word</code></td>
|
|
<td>
|
|
Whether the message contains any of the current user's
|
|
<a href="/help/dm-mention-alert-notifications#alert-words">configured alert words</a>.
|
|
Cannot be changed by the user directly, but
|
|
can change if the message is edited to add/remove
|
|
one of the current user's alert words.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>historical</code></td>
|
|
<td>
|
|
Is `true` for messages that the user did not receive
|
|
at the time they were sent but later was added to
|
|
the user's history (E.g. because they starred or
|
|
reacted to a message sent to a public stream
|
|
before they subscribed to that stream). Cannot be
|
|
changed by the user directly.
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
parameters:
|
|
- name: messages
|
|
in: query
|
|
description: |
|
|
An array containing the IDs of the target messages.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
example: [4, 8, 15]
|
|
required: true
|
|
- name: op
|
|
in: query
|
|
description: |
|
|
Whether to `add` the flag or `remove` it.
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- add
|
|
- remove
|
|
example: add
|
|
required: true
|
|
- name: flag
|
|
in: query
|
|
description: |
|
|
The flag that should be added/removed.
|
|
schema:
|
|
type: string
|
|
example: read
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
messages:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
An array with the IDs of the modified messages.
|
|
example:
|
|
{"msg": "", "messages": [4, 18, 15], "result": "success"}
|
|
/messages/flags/narrow:
|
|
post:
|
|
operationId: update-message-flags-for-narrow
|
|
summary: Update personal message flags for narrow
|
|
tags: ["messages"]
|
|
description: |
|
|
Add or remove personal message flags like `read` and `starred`
|
|
on a range of messages within a narrow.
|
|
|
|
See also [the endpoint for updating flags on specific message
|
|
IDs](/api/update-message-flags).
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 155).
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: exclude
|
|
parameters:
|
|
enum:
|
|
- include_anchor
|
|
parameters:
|
|
- name: anchor
|
|
in: query
|
|
description: |
|
|
Integer message ID to anchor updating of flags. Supports special
|
|
string values for when the client wants the server to compute the anchor
|
|
to use:
|
|
|
|
- `newest`: The most recent message.
|
|
- `oldest`: The oldest message.
|
|
- `first_unread`: The oldest unread message matching the
|
|
query, if any; otherwise, the most recent message.
|
|
schema:
|
|
oneOf:
|
|
- type: string
|
|
- type: integer
|
|
example: 43
|
|
required: true
|
|
- name: include_anchor
|
|
in: query
|
|
description: |
|
|
Whether a message with the specified ID matching the narrow
|
|
should be included in the update range.
|
|
schema:
|
|
type: boolean
|
|
default: true
|
|
example: false
|
|
- name: num_before
|
|
in: query
|
|
description: |
|
|
Limit the number of messages preceding the anchor in the
|
|
update range. The server may decrease this to bound
|
|
transaction sizes.
|
|
schema:
|
|
type: integer
|
|
minimum: 0
|
|
example: 4
|
|
required: true
|
|
- name: num_after
|
|
in: query
|
|
description: |
|
|
Limit the number of messages following the anchor in the
|
|
update range. The server may decrease this to bound
|
|
transaction sizes.
|
|
schema:
|
|
type: integer
|
|
minimum: 0
|
|
example: 8
|
|
required: true
|
|
- name: narrow
|
|
in: query
|
|
description: |
|
|
The narrow you want update flags within. See how to
|
|
[construct a narrow](/api/construct-narrow).
|
|
|
|
**Changes**: In Zulip 7.0 (feature level 177), narrows gained support
|
|
for three new filters related to direct messages: `is:dm`, `dm` and
|
|
`dm-including`; replacing and deprecating `is:private`, `pm-with` and
|
|
`group-pm-with` respectively.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
oneOf:
|
|
- type: object
|
|
required:
|
|
- operator
|
|
- operand
|
|
additionalProperties: false
|
|
properties:
|
|
operator:
|
|
type: string
|
|
operand:
|
|
oneOf:
|
|
- type: string
|
|
- type: integer
|
|
- type: array
|
|
items:
|
|
type: integer
|
|
negated:
|
|
type: boolean
|
|
- type: array
|
|
items:
|
|
type: string
|
|
minItems: 2
|
|
maxItems: 2
|
|
default: []
|
|
example: [{"operand": "Denmark", "operator": "stream"}]
|
|
required: true
|
|
- name: op
|
|
in: query
|
|
description: |
|
|
Whether to `add` the flag or `remove` it.
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- add
|
|
- remove
|
|
example: add
|
|
required: true
|
|
- name: flag
|
|
in: query
|
|
description: |
|
|
The flag that should be added/removed. See [available
|
|
flags](/api/update-message-flags#available-flags).
|
|
schema:
|
|
type: string
|
|
example: read
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
required:
|
|
- processed_count
|
|
- updated_count
|
|
- first_processed_id
|
|
- last_processed_id
|
|
- found_oldest
|
|
- found_newest
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
processed_count:
|
|
type: integer
|
|
description: |
|
|
The number of messages that were within the
|
|
update range (at most `num_before + 1 +
|
|
num_after`).
|
|
updated_count:
|
|
type: integer
|
|
description: |
|
|
The number of messages where the flag's
|
|
value was changed (at most
|
|
`processed_count`).
|
|
first_processed_id:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
The ID of the oldest message within the
|
|
update range, or `null` if the range was
|
|
empty.
|
|
last_processed_id:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
The ID of the newest message within the
|
|
update range, or `null` if the range was
|
|
empty.
|
|
found_oldest:
|
|
type: boolean
|
|
description: |
|
|
Whether the update range reached backward
|
|
far enough to include very oldest message
|
|
matching the narrow (used by clients doing a
|
|
bulk update to decide whether to issue
|
|
another request anchored at
|
|
`first_processed_id`).
|
|
found_newest:
|
|
type: boolean
|
|
description: |
|
|
Whether the update range reached forward far
|
|
enough to include very oldest message
|
|
matching the narrow (used by clients doing a
|
|
bulk update to decide whether to issue
|
|
another request anchored at
|
|
`last_processed_id`).
|
|
example:
|
|
{
|
|
"result": "success",
|
|
"msg": "",
|
|
"processed_count": 11,
|
|
"updated_count": 8,
|
|
"first_processed_id": 35,
|
|
"last_processed_id": 55,
|
|
"found_oldest": false,
|
|
"found_newest": true,
|
|
}
|
|
/messages/render:
|
|
post:
|
|
operationId: render-message
|
|
summary: Render message
|
|
tags: ["messages"]
|
|
description: |
|
|
Render a message to HTML.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RequiredContent"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
rendered:
|
|
type: string
|
|
description: |
|
|
The rendered HTML.
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"rendered": "<p><strong>foo</strong></p>",
|
|
"result": "success",
|
|
}
|
|
/messages/{message_id}/reactions:
|
|
post:
|
|
operationId: add-reaction
|
|
summary: Add an emoji reaction
|
|
tags: ["messages"]
|
|
description: |
|
|
Add an [emoji reaction](/help/emoji-reactions) to a message.
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: exclude
|
|
parameters:
|
|
enum:
|
|
- emoji_code
|
|
- reaction_type
|
|
parameters:
|
|
- $ref: "#/components/parameters/MessageId"
|
|
- name: emoji_name
|
|
in: query
|
|
description: |
|
|
The target emoji's human-readable name.
|
|
|
|
To find an emoji's name, hover over a message to reveal
|
|
three icons on the right, then click the smiley face icon.
|
|
Images of available reaction emojis appear. Hover over the
|
|
emoji you want, and note that emoji's text name.
|
|
schema:
|
|
type: string
|
|
example: "octopus"
|
|
required: true
|
|
- $ref: "#/components/parameters/EmojiCode"
|
|
- $ref: "#/components/parameters/ReactionType"
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Invalid emoji code",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
description: |
|
|
An example JSON error response for when the emoji code is invalid:
|
|
|
|
delete:
|
|
operationId: remove-reaction
|
|
summary: Remove an emoji reaction
|
|
tags: ["messages"]
|
|
description: |
|
|
Remove an [emoji reaction](/help/emoji-reactions) from a message.
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: exclude
|
|
parameters:
|
|
enum:
|
|
- emoji_code
|
|
- reaction_type
|
|
parameters:
|
|
- $ref: "#/components/parameters/MessageId"
|
|
- name: emoji_name
|
|
in: query
|
|
description: |
|
|
The target emoji's human-readable name.
|
|
|
|
To find an emoji's name, hover over a message to reveal
|
|
three icons on the right, then click the smiley face icon.
|
|
Images of available reaction emojis appear. Hover over the
|
|
emoji you want, and note that emoji's text name.
|
|
schema:
|
|
type: string
|
|
example: "octopus"
|
|
required: false
|
|
- $ref: "#/components/parameters/EmojiCode"
|
|
- $ref: "#/components/parameters/ReactionType"
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Invalid message(s)",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
description: |
|
|
An example JSON error response for when the emoji code is invalid:
|
|
|
|
/messages/{message_id}/read_receipts:
|
|
get:
|
|
operationId: get-read-receipts
|
|
summary: Get the list of IDs of users who have read a message.
|
|
tags: ["messages"]
|
|
description: |
|
|
Returns a list containing the IDs for all users who have
|
|
marked the message as read (and whose privacy settings allow
|
|
sharing that information).
|
|
|
|
The list of users IDs will include any bots who have marked
|
|
the message as read via the API (providing a way for bots to
|
|
indicate whether they have processed a message successfully in
|
|
a way that can be easily inspected in a Zulip client). Bots
|
|
for which this behavior is not desired may disable the
|
|
`send_read_receipts` setting via the API.
|
|
|
|
It will never contain the message's sender.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 137).
|
|
parameters:
|
|
- $ref: "#/components/parameters/MessageId"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
user_ids:
|
|
type: array
|
|
description: |
|
|
An array of IDs of users who have marked the target message as
|
|
read and whose read status is available to the current user.
|
|
|
|
The IDs of users who have disabled sending read receipts
|
|
(`"send_read_receipts": false`) will never appear in the response,
|
|
nor will the message's sender. Additionally, the IDs of any users
|
|
who have been muted by the current user or who have muted the
|
|
current user will not be included in the response.
|
|
|
|
The current user's ID will appear if they have marked the target
|
|
message as read.
|
|
|
|
**Changes**: Prior to Zulip 6.0 (feature level 143), the IDs of
|
|
users who have been muted by or have muted the current user were
|
|
included in the response.
|
|
items:
|
|
type: integer
|
|
example:
|
|
{"msg": "", "result": "success", "user_ids": [3, 7, 9]}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonError"
|
|
- example: {"msg": "Invalid message(s)", "result": "error"}
|
|
description: |
|
|
A typical JSON response when attempting to
|
|
access read receipts for a message ID that
|
|
either does not exist or is not accessible to
|
|
the current user.
|
|
|
|
/messages/matches_narrow:
|
|
get:
|
|
operationId: check-messages-match-narrow
|
|
summary: Check if messages match a narrow
|
|
tags: ["messages"]
|
|
description: |
|
|
Check whether a set of messages match a [narrow](/api/construct-narrow).
|
|
|
|
For many common narrows (e.g. a topic), clients can write an efficient
|
|
client-side check to determine whether a newly arrived message belongs
|
|
in the view.
|
|
|
|
This endpoint is designed to allow clients to handle more complex narrows
|
|
for which the client does not (or in the case of full-text search, cannot)
|
|
implement this check.
|
|
|
|
The format of the `match_subject` and `match_content` objects is designed
|
|
to match those returned by the [`GET /messages`](/api/get-messages#response)
|
|
endpoint, so that a client can splice these fields into a `message` object
|
|
received from [`GET /events`](/api/get-events#message) and end up with an
|
|
extended message object identical to how a [`GET /messages`](/api/get-messages)
|
|
request for the current narrow would have returned the message.
|
|
parameters:
|
|
- name: msg_ids
|
|
in: query
|
|
description: List of IDs for the messages to check.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
example: [31, 32]
|
|
required: true
|
|
- name: narrow
|
|
in: query
|
|
description: |
|
|
A structure defining the narrow to check against. See how to
|
|
[construct a narrow](/api/construct-narrow).
|
|
|
|
**Changes**: In Zulip 7.0 (feature level 177), narrows gained support
|
|
for three new filters related to direct messages: `is:dm`, `dm` and
|
|
`dm-including`; replacing and deprecating `is:private`, `pm-with` and
|
|
`group-pm-with` respectively.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
example: [{"operator": "has", "operand": "link"}]
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
messages:
|
|
type: object
|
|
description: |
|
|
A dictionary with a key for each queried message that matches the narrow,
|
|
with message IDs as keys and search rendering data as values.
|
|
additionalProperties:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
match_content:
|
|
type: string
|
|
description: |
|
|
HTML content of a queried message that matches the narrow. If the
|
|
narrow is a search narrow, `<span class="highlight">` elements
|
|
will be included, wrapping the matches for the search keywords.
|
|
match_subject:
|
|
type: string
|
|
description: |
|
|
HTML-escaped topic of a queried message that matches the narrow. If the
|
|
narrow is a search narrow, `<span class="highlight">` elements
|
|
will be included wrapping the matches for the search keywords.
|
|
description: |
|
|
`message_id`: The ID of the message that matches the narrow. No record will be returned
|
|
for queried messages that do not match the narrow.
|
|
example:
|
|
{
|
|
"result": "success",
|
|
"msg": "",
|
|
"messages":
|
|
{
|
|
"31":
|
|
{
|
|
"match_content": '<p><a href="http://foo.com" target="_blank" title="http://foo.com">http://foo.com</a></p>',
|
|
"match_subject": "test_topic",
|
|
},
|
|
},
|
|
}
|
|
/messages/{message_id}:
|
|
get:
|
|
operationId: get-message
|
|
summary: Fetch a single message.
|
|
tags: ["messages"]
|
|
description: |
|
|
Given a message ID, return the message object.
|
|
|
|
Additionally, a `raw_content` field is included. This field is
|
|
useful for clients that primarily work with HTML-rendered
|
|
messages but might need to occasionally fetch the message's
|
|
raw Markdown (e.g. for [view
|
|
source](/help/view-the-markdown-source-of-a-message) or
|
|
prefilling a message edit textarea).
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 120), this
|
|
endpoint only returned the `raw_content` field.
|
|
parameters:
|
|
- $ref: "#/components/parameters/MessageId"
|
|
- name: apply_markdown
|
|
in: query
|
|
description: |
|
|
If `true`, message content is returned in the rendered HTML
|
|
format. If `false`, message content is returned in the raw
|
|
Markdown-format text that user entered.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 120).
|
|
schema:
|
|
type: boolean
|
|
default: true
|
|
example: false
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
raw_content:
|
|
type: string
|
|
deprecated: true
|
|
description: |
|
|
The raw Markdown content of the message.
|
|
|
|
**Deprecated** and to be removed once no longer required for
|
|
legacy clients. Modern clients should prefer passing
|
|
`"apply_markdown": false` to request raw message content.
|
|
message:
|
|
description: |
|
|
An object containing details of the message.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 120).
|
|
allOf:
|
|
- $ref: "#/components/schemas/MessagesBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
avatar_url:
|
|
nullable: true
|
|
client: {}
|
|
content: {}
|
|
content_type: {}
|
|
display_recipient: {}
|
|
edit_history: {}
|
|
id: {}
|
|
is_me_message: {}
|
|
last_edit_timestamp: {}
|
|
reactions: {}
|
|
recipient_id: {}
|
|
sender_email: {}
|
|
sender_full_name: {}
|
|
sender_id: {}
|
|
sender_realm_str: {}
|
|
stream_id: {}
|
|
subject: {}
|
|
submessages: {}
|
|
timestamp: {}
|
|
topic_links: {}
|
|
type: {}
|
|
flags:
|
|
type: array
|
|
description: |
|
|
The user's [message flags][message-flags] for the message.
|
|
|
|
[message-flags]: /api/update-message-flags#available-flags
|
|
items:
|
|
type: string
|
|
example:
|
|
{
|
|
"raw_content": "**Don't** forget your towel!",
|
|
"result": "success",
|
|
"msg": "",
|
|
"message":
|
|
{
|
|
"subject": "",
|
|
"sender_realm_str": "zulip",
|
|
"type": "private",
|
|
"content": "<p>Security experts agree that relational algorithms are an interesting new topic in the field of networking, and scholars concur.</p>",
|
|
"flags": ["read"],
|
|
"id": 16,
|
|
"display_recipient":
|
|
[
|
|
{
|
|
"id": 4,
|
|
"is_mirror_dummy": false,
|
|
"email": "hamlet@zulip.com",
|
|
"full_name": "King Hamlet",
|
|
},
|
|
{
|
|
"id": 5,
|
|
"is_mirror_dummy": false,
|
|
"email": "iago@zulip.com",
|
|
"full_name": "Iago",
|
|
},
|
|
{
|
|
"id": 8,
|
|
"is_mirror_dummy": false,
|
|
"email": "prospero@zulip.com",
|
|
"full_name": "Prospero from The Tempest",
|
|
},
|
|
],
|
|
"content_type": "text/html",
|
|
"is_me_message": false,
|
|
"timestamp": 1527921326,
|
|
"sender_id": 4,
|
|
"sender_full_name": "King Hamlet",
|
|
"recipient_id": 27,
|
|
"topic_links": [],
|
|
"client": "populate_db",
|
|
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
|
|
"submessages": [],
|
|
"sender_email": "hamlet@zulip.com",
|
|
"reactions": [],
|
|
},
|
|
}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/InvalidMessageError"
|
|
- description: |
|
|
An example JSON response for when the specified message does not exist or it
|
|
is not visible to the user making the query (e.g. it was a PM between other
|
|
two users):
|
|
patch:
|
|
operationId: update-message
|
|
summary: Edit a message
|
|
tags: ["messages"]
|
|
description: |
|
|
Edit/update the content, topic, or stream of a message.
|
|
|
|
`{msg_id}` in the above URL should be replaced with the ID of the
|
|
message you wish you update.
|
|
|
|
You can [resolve topics](/help/resolve-a-topic) by editing the
|
|
topic to `✔ {original_topic}`.
|
|
|
|
See [configuring message editing][config-message-editing] for detailed
|
|
documentation on when users are allowed to edit message content and
|
|
[restricting moving messages][restrict-move-messages] for detailed
|
|
documentation on when users are allowed to change a message's topic
|
|
and/or stream.
|
|
|
|
The relevant realm settings in the API that are related to the above
|
|
linked documentation on when users are allowed to update messages are:
|
|
|
|
- `allow_message_editing`
|
|
- `edit_topic_policy`
|
|
- `move_messages_between_streams_policy`
|
|
- `message_content_edit_limit_seconds`
|
|
- `move_messages_within_stream_limit_seconds`
|
|
- `move_messages_between_streams_limit_seconds`
|
|
|
|
More details about these realm settings can be found in the
|
|
[`POST /register`](/api/register-queue) response or in the documentation
|
|
of the [`realm op: update_dict`](/api/get-events#realm-update_dict)
|
|
event in [`GET /events`](/api/get-events).
|
|
|
|
**Changes**: Prior to Zulip 7.0 (feature level 172), anyone could add a
|
|
topic to stream messages without a topic, regardless of the organization's
|
|
[topic editing permissions](/help/restrict-moving-messages). As of this
|
|
feature level, messages without topics have the same restrictions for
|
|
topic edits as messages with topics.
|
|
|
|
Before Zulip 7.0 (feature level 172), by using the `change_all` value for
|
|
the `propagate_mode` parameter, users could move messages after the
|
|
organization's configured time limits for changing a message's topic or
|
|
stream had passed. As of this feature level, the server will [return an
|
|
error](/api/update-message#response) with `"code":
|
|
"MOVE_MESSAGES_TIME_LIMIT_EXCEEDED"` if users, other than organization
|
|
administrators or moderators, try to move messages after these time
|
|
limits have passed.
|
|
|
|
Before Zulip 7.0 (feature level 162), users who were not administrators or
|
|
moderators could only edit topics if the target message was sent within the
|
|
last 3 days. As of this feature level, that time limit is now controlled by
|
|
the realm setting `move_messages_within_stream_limit_seconds`. Also at this
|
|
feature level, a similar time limit for moving messages between streams was
|
|
added, controlled by the realm setting
|
|
`move_messages_between_streams_limit_seconds`. Previously, all users who
|
|
had permission to move messages between streams did not have any time limit
|
|
restrictions when doing so.
|
|
|
|
Before Zulip 7.0 (feature level 159), editing streams and topics of messages
|
|
was forbidden if the realm setting for `allow_message_editing` was `false`,
|
|
regardless of an organization's configuration for the realm settings
|
|
`edit_topic_policy` or `move_messages_between_streams_policy`.
|
|
|
|
Before Zulip 7.0 (feature level 159), message senders were allowed to edit
|
|
the topic of their messages indefinitely.
|
|
|
|
[config-message-editing]: /help/restrict-message-editing-and-deletion
|
|
[restrict-move-messages]: /help/restrict-moving-messages
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: exclude
|
|
parameters:
|
|
enum:
|
|
- stream_id
|
|
parameters:
|
|
- $ref: "#/components/parameters/MessageId"
|
|
- name: topic
|
|
in: query
|
|
description: |
|
|
The topic to move the message(s) to, to request changing the topic.
|
|
|
|
Clients should use the `max_topic_length` returned by the
|
|
[`POST /register`](/api/register-queue) endpoint to determine
|
|
the maximum topic length
|
|
|
|
Should only be sent when changing the topic, and will throw an error
|
|
if the target message is not a stream message.
|
|
|
|
**Changes**: New in Zulip 2.0.0. Previous Zulip releases encoded
|
|
this as `subject`, which is currently a deprecated alias.
|
|
schema:
|
|
type: string
|
|
example: Castle
|
|
- name: propagate_mode
|
|
in: query
|
|
description: |
|
|
Which message(s) should be edited:
|
|
|
|
- `"change_later"`: The target message and all following messages.
|
|
- `"change_one"`: Only the target message.
|
|
- `"change_all"`: All messages in this topic.
|
|
|
|
Only the default value of `"change_one"` is valid when editing
|
|
only the content of a message.
|
|
|
|
This parameter determines both which messages get moved and also whether
|
|
clients that are currently narrowed to the topic containing the message
|
|
should navigate or adjust their compose box recipient to point to the
|
|
post-edit stream/topic.
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- change_one
|
|
- change_later
|
|
- change_all
|
|
default: change_one
|
|
example: change_all
|
|
- name: send_notification_to_old_thread
|
|
in: query
|
|
description: |
|
|
Whether to send an automated message to the old topic to
|
|
notify users where the messages were moved to.
|
|
|
|
**Changes**: Before Zulip 6.0 (feature level 152), this parameter
|
|
had a default of `true` and was ignored unless the stream was changed.
|
|
|
|
New in Zulip 3.0 (feature level 9).
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
- name: send_notification_to_new_thread
|
|
in: query
|
|
description: |
|
|
Whether to send an automated message to the new topic to
|
|
notify users where the messages came from.
|
|
|
|
If the move is just [resolving/unresolving a topic](/help/resolve-a-topic),
|
|
this parameter will not trigger an additional notification.
|
|
|
|
**Changes**: Before Zulip 6.0 (feature level 152), this parameter
|
|
was ignored unless the stream was changed.
|
|
|
|
New in Zulip 3.0 (feature level 9).
|
|
schema:
|
|
type: boolean
|
|
default: true
|
|
example: true
|
|
- $ref: "#/components/parameters/OptionalContent"
|
|
- name: stream_id
|
|
in: query
|
|
description: |
|
|
The stream ID to move the message(s) to, to request moving
|
|
messages to another stream.
|
|
|
|
Should only be sent when changing the stream, and will throw an error
|
|
if the target message is not a stream message.
|
|
|
|
Note that a message's content and stream cannot be changed at the
|
|
same time, so sending both `content` and `stream_id` parameters will
|
|
throw an error.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 1).
|
|
schema:
|
|
type: integer
|
|
example: 43
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- properties:
|
|
msg:
|
|
enum:
|
|
- Your organization has turned off message editing
|
|
- You don't have permission to edit this message
|
|
- The time limit for editing this message has past
|
|
- Nothing to change
|
|
- Topic can't be empty
|
|
example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "You don't have permission to edit this message",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
A typical JSON response for when one doesn't have the permission to
|
|
edit a particular message:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "MOVE_MESSAGES_TIME_LIMIT_EXCEEDED",
|
|
"first_message_id_allowed_to_move": 123,
|
|
"msg": "You only have permission to move the 2/5 most recent messages in this topic.",
|
|
"result": "error",
|
|
"total_messages_allowed_to_move": 2,
|
|
"total_messages_in_topic": 5,
|
|
}
|
|
description: |
|
|
A special failed JSON response (`"code": "MOVE_MESSAGES_TIME_LIMIT_EXCEEDED"`)
|
|
for when the user has permission to move
|
|
the target message, but asked to move all messages in a topic
|
|
(`"propagate_mode": "change_all"`) and the user does not have permission
|
|
to move the entire topic.
|
|
|
|
This happens when the topic contains some messages that are older than an
|
|
applicable time limit for the requested topic move (see
|
|
`move_messages_within_stream_limit_seconds` and/or
|
|
`move_messages_between_streams_limit_seconds` in the
|
|
[`POST /register`](/api/register-queue) response).
|
|
|
|
The error response contains data on which portion of this topic the user has
|
|
permission to move. `first_message_id_allowed_to_move` is the oldest message
|
|
ID in this topic that the user has permission to move.
|
|
There are `total_messages_in_topic` in the topic, but the user only has
|
|
permission to move the (most recent) `total_messages_allowed_to_move`
|
|
messages.
|
|
|
|
Clients should support this error code with
|
|
`"first_message_id_allowed_to_move": null` for forward compatibility
|
|
with future server versions that may use this error code with other
|
|
propagation modes where the user does not have permission to move any
|
|
messages, or where the server did not calculate the total message counts
|
|
noted above.
|
|
|
|
Clients can either only present the error to the user or, if
|
|
`first_message_id_allowed_to_move` is not `null`, prompt the user to adjust
|
|
their query with the above information.
|
|
|
|
If clients choose to present a prompt for this error code, they should
|
|
recommend the option of cancelling and (manually) asking a moderator to
|
|
move the entire topic, since that's often a better experience than
|
|
partially moving a topic. This API supports a client that wishes to allow
|
|
the user to repeat the request with a `change_later` propagation mode and
|
|
a target message ID of `first_message_id_allowed_to_move`, if the user
|
|
desires to move only the portion of the topic that they can.
|
|
|
|
Note that in a stream with [protected history](/help/stream-permissions),
|
|
the Zulip security model requires that the above calculations only include
|
|
messages the acting user has access to. So in the rare case of a user
|
|
attempting to move a topic that started before the user joined a private
|
|
stream with protected history, this API endpoint might move only the portion
|
|
of a topic that they have access to, without this error or any confirmation
|
|
dialog.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 172).
|
|
delete:
|
|
operationId: delete-message
|
|
summary: Delete a message
|
|
tags: ["messages"]
|
|
description: |
|
|
Permanently delete a message.
|
|
|
|
This API corresponds to the
|
|
[delete a message completely][delete-completely] feature documented in
|
|
the Zulip Help Center.
|
|
|
|
[delete-completely]: /help/edit-or-delete-a-message#delete-a-message-completely
|
|
x-requires-administrator: true
|
|
parameters:
|
|
- $ref: "#/components/parameters/MessageId"
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/InvalidMessageError"
|
|
- description: |
|
|
An example JSON response for when the specified message does not exist:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- description: |
|
|
An example JSON response for when the user making the query does not
|
|
have permission to delete the message:
|
|
example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "You don't have permission to delete this message",
|
|
"result": "error",
|
|
}
|
|
/user_uploads:
|
|
post:
|
|
operationId: upload-file
|
|
summary: Upload a file
|
|
tags: ["messages"]
|
|
description: |
|
|
Upload a single file and get the corresponding URI.
|
|
|
|
Initially, only you will be able to access the link. To share the
|
|
uploaded file, you'll need to [send a message][send-message]
|
|
containing the resulting link. Users who can already access the link
|
|
can reshare it with other users by sending additional Zulip messages
|
|
containing the link.
|
|
|
|
[uploaded-files]: /help/manage-your-uploaded-files
|
|
[send-message]: /api/send-message
|
|
x-parameter-description: |
|
|
As described above, the file to upload must be provided in the
|
|
request's body.
|
|
|
|
## Maximum file size
|
|
|
|
The maximum file size for uploads can be configured by the
|
|
administrator of the Zulip server by setting `MAX_FILE_UPLOAD_SIZE`
|
|
in the [server's settings][1]. `MAX_FILE_UPLOAD_SIZE` defaults
|
|
to 25MB.
|
|
|
|
[1]: https://zulip.readthedocs.io/en/latest/subsystems/settings.html#server-settings
|
|
requestBody:
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
filename:
|
|
type: string
|
|
format: binary
|
|
example: /path/to/file
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
uri:
|
|
type: string
|
|
description: |
|
|
The URI of the uploaded file.
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"result": "success",
|
|
"uri": "/user_uploads/1/4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt",
|
|
}
|
|
/user_uploads/{realm_id_str}/{filename}:
|
|
get:
|
|
operationId: get-file-temporary-url
|
|
summary: Get public temporary URL
|
|
tags: ["messages"]
|
|
description: |
|
|
Get a temporary URL for access to the file that doesn't require authentication.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 1).
|
|
parameters:
|
|
- name: realm_id_str
|
|
in: path
|
|
description: |
|
|
The realm ID.
|
|
schema:
|
|
type: integer
|
|
example: 1
|
|
required: true
|
|
- name: filename
|
|
in: path
|
|
description: |
|
|
Path to the URL.
|
|
schema:
|
|
type: string
|
|
example: 4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
url:
|
|
type: string
|
|
description: |
|
|
A temporary URL that can be used to access the uploaded file
|
|
without Zulip's normal API authentication.
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"result": "success",
|
|
"url": "/user_uploads/temporary/322F32632F39765378464E4C63306D3961396F4970705A4D74424565432F7A756C69702E7478743A316A5053616A3A3938625F44393446466D37357254315F4F414C425A4553464F6A55",
|
|
}
|
|
|
|
/users:
|
|
get:
|
|
operationId: get-users
|
|
summary: Get all users
|
|
tags: ["users"]
|
|
description: |
|
|
Retrieve details on all users in the organization. Optionally
|
|
includes values of [custom profile fields](/help/custom-profile-fields).
|
|
|
|
You can also [fetch details on a single user](/api/get-user).
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: include
|
|
parameters:
|
|
enum:
|
|
- ""
|
|
- type: exclude
|
|
parameters:
|
|
enum:
|
|
- ""
|
|
description: |
|
|
You may pass the `client_gravatar` query parameter as follows:
|
|
parameters:
|
|
- $ref: "#/components/parameters/ClientGravatar"
|
|
- $ref: "#/components/parameters/IncludeCustomProfileFields"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
members:
|
|
type: array
|
|
description: |
|
|
A list of `user` objects, each containing details about a user in the
|
|
organization.
|
|
items:
|
|
$ref: "#/components/schemas/User"
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"result": "success",
|
|
"members":
|
|
[
|
|
{
|
|
"is_active": true,
|
|
"email": "AARON@zulip.com",
|
|
"delivery_email": null,
|
|
"is_admin": false,
|
|
"is_owner": false,
|
|
"is_billing_admin": false,
|
|
"role": 400,
|
|
"avatar_url": "https://secure.gravatar.com/avatar/818c212b9f8830dfef491b3f7da99a14?d=identicon&version=1",
|
|
"bot_type": null,
|
|
"timezone": "",
|
|
"is_bot": false,
|
|
"user_id": 7,
|
|
"profile_data": {},
|
|
"is_guest": false,
|
|
"date_joined": "2019-10-20T07:50:53.728864+00:00",
|
|
"full_name": "aaron",
|
|
},
|
|
{
|
|
"date_joined": "2019-10-20T07:50:53.729659+00:00",
|
|
"full_name": "King Hamlet",
|
|
"is_guest": false,
|
|
"profile_data":
|
|
{
|
|
"4": {"value": "0"},
|
|
"2":
|
|
{
|
|
"value": "I am:\n* The prince of Denmark\n* Nephew to the usurping Claudius",
|
|
"rendered_value": "<p>I am:</p>\n<ul>\n<li>The prince of Denmark</li>\n<li>Nephew to the usurping Claudius</li>\n</ul>",
|
|
},
|
|
"5": {"value": "1900-01-01"},
|
|
"7": {"value": "[11]"},
|
|
"6": {"value": "https://blog.zulig.org"},
|
|
"1":
|
|
{
|
|
"value": "+0-11-23-456-7890",
|
|
"rendered_value": "<p>+0-11-23-456-7890</p>",
|
|
},
|
|
"8": {"value": "zulipbot"},
|
|
"3":
|
|
{
|
|
"rendered_value": "<p>Dark chocolate</p>",
|
|
"value": "Dark chocolate",
|
|
},
|
|
},
|
|
"user_id": 10,
|
|
"is_bot": false,
|
|
"bot_type": null,
|
|
"timezone": "",
|
|
"is_admin": false,
|
|
"is_owner": false,
|
|
"is_billing_admin": false,
|
|
"role": 400,
|
|
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
|
|
"is_active": true,
|
|
"email": "hamlet@zulip.com",
|
|
"delivery_email": null,
|
|
},
|
|
{
|
|
"bot_owner_id": 11,
|
|
"is_guest": false,
|
|
"date_joined": "2019-10-20T12:52:17.862053+00:00",
|
|
"full_name": "Iago's Bot",
|
|
"email": "iago-bot@zulipdev.com",
|
|
"delivery_email": "iago-bot@zulipdev.com",
|
|
"is_active": true,
|
|
"avatar_url": "https://secure.gravatar.com/avatar/7328586831cdbb1627649bd857b1ee8c?d=identicon&version=1",
|
|
"is_admin": false,
|
|
"is_owner": false,
|
|
"is_billing_admin": false,
|
|
"role": 400,
|
|
"user_id": 23,
|
|
"bot_type": 1,
|
|
"timezone": "",
|
|
"is_bot": true,
|
|
},
|
|
],
|
|
}
|
|
post:
|
|
operationId: create-user
|
|
summary: Create a user
|
|
tags: ["users"]
|
|
description: |
|
|
Create a new user account via the API.
|
|
|
|
!!! warn ""
|
|
|
|
**Note**: This endpoint is limited to organization administrators
|
|
who additionally have the `can_create_users` permission for the Zulip
|
|
organization. Zulip Cloud users can request the `can_create_users`
|
|
permission for a bot by contacting [Zulip Cloud support][support]
|
|
with an explanation for why it is needed. Self-hosted installations
|
|
can toggle `can_create_users` on an account using the `manage.py
|
|
change_user_role` [management command][management-commands].
|
|
|
|
**Changes**: Before Zulip 4.0 (feature level 36), this endpoint was
|
|
available to all organization administrators.
|
|
|
|
[support]: /help/contact-support
|
|
[management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html
|
|
x-requires-administrator: true
|
|
parameters:
|
|
- name: email
|
|
in: query
|
|
description: |
|
|
The email address of the new user.
|
|
schema:
|
|
type: string
|
|
example: username@example.com
|
|
required: true
|
|
- name: password
|
|
in: query
|
|
description: |
|
|
The password of the new user.
|
|
schema:
|
|
type: string
|
|
example: abcd1234
|
|
required: true
|
|
- name: full_name
|
|
in: query
|
|
description: |
|
|
The full name of the new user.
|
|
schema:
|
|
type: string
|
|
example: New User
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID assigned to the newly created user.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 30).
|
|
example: {"msg": "", "result": "success", "user_id": 25}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonError"
|
|
- example:
|
|
{
|
|
"msg": "Email 'newbie@zulip.com' already in use",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
A typical JSON response for when another user with the same
|
|
email address already exists in the realm:
|
|
/users/{user_id}/reactivate:
|
|
post:
|
|
operationId: reactivate-user
|
|
summary: Reactivate a user
|
|
tags: ["users"]
|
|
x-requires-administrator: true
|
|
description: |
|
|
[Reactivates a
|
|
user](https://zulip.com/help/deactivate-or-reactivate-a-user)
|
|
given their user ID.
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserId"
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
|
|
/users/{user_id_or_email}/presence:
|
|
get:
|
|
operationId: get-user-presence
|
|
summary: Get user presence
|
|
tags: ["users"]
|
|
description: |
|
|
Get the presence status for a specific user.
|
|
|
|
This endpoint is most useful for embedding data about a user's
|
|
presence status in other sites (e.g. an employee directory). Full
|
|
Zulip clients like mobile/desktop apps will want to use the [main
|
|
presence endpoint](/api/get-presence), which returns data for all
|
|
active users in the organization, instead.
|
|
|
|
See [Zulip's developer documentation][subsystems-presence]
|
|
for details on the data model for presence in Zulip.
|
|
|
|
[subsystems-presence]: https://zulip.readthedocs.io/en/latest/subsystems/presence.html
|
|
parameters:
|
|
- name: user_id_or_email
|
|
in: path
|
|
description: |
|
|
The ID or Zulip API email address of the user whose presence you want to fetch.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 43). Previous versions only supported
|
|
identifying the user by Zulip API email.
|
|
schema:
|
|
type: string
|
|
example: iago@zulip.com
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
presence:
|
|
type: object
|
|
description: |
|
|
An object containing the presence details for the user.
|
|
additionalProperties:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
timestamp:
|
|
type: integer
|
|
description: |
|
|
When this update was received. If the timestamp
|
|
is more than a few minutes in the past, the user is offline.
|
|
status:
|
|
type: string
|
|
description: |
|
|
Whether the user had recently interacted with Zulip at the time
|
|
of the timestamp.
|
|
|
|
Will be either `"active"` or `"idle"`
|
|
description: |
|
|
`{client_name}` or `"aggregated"`: Object containing the details of the user's
|
|
presence.
|
|
|
|
**Changes**: Starting with Zulip 7.0 (feature level 178), this will always
|
|
contain two keys, `"website"` and `"aggregated"`, with identical data. The
|
|
server no longer stores which client submitted presence updates.
|
|
|
|
Previously, the `{client_name}` keys for these objects were the names of the
|
|
different clients where the user was logged in, for example `website` or
|
|
`ZulipDesktop`.
|
|
example:
|
|
{
|
|
"presence":
|
|
{
|
|
"website":
|
|
{"timestamp": 1532697622, "status": "active"},
|
|
"aggregated":
|
|
{"timestamp": 1532697622, "status": "active"},
|
|
},
|
|
"result": "success",
|
|
"msg": "",
|
|
}
|
|
/users/me:
|
|
get:
|
|
operationId: get-own-user
|
|
summary: Get own user
|
|
tags: ["users"]
|
|
description: |
|
|
Get basic data about the user/bot that requests this endpoint.
|
|
responses:
|
|
"200":
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
avatar_url:
|
|
type: string
|
|
description: |
|
|
URL for the requesting user's avatar.
|
|
|
|
**Changes**: New in Zulip 2.1.0.
|
|
example: "x"
|
|
avatar_version:
|
|
type: integer
|
|
description: |
|
|
Version for the requesting user's avatar. Used for cache-busting requests
|
|
for the user's avatar. Clients generally shouldn't need to use this;
|
|
most avatar URLs sent by Zulip will already end with `?v={avatar_version}`.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 10).
|
|
example: 1
|
|
email:
|
|
type: string
|
|
description: |
|
|
Zulip API email of the requesting user.
|
|
example: "iago@zulip.com"
|
|
full_name:
|
|
type: string
|
|
description: |
|
|
Full name of the requesting user.
|
|
example: "Iago"
|
|
is_admin:
|
|
type: boolean
|
|
description: |
|
|
A boolean indicating if the requesting user is an admin.
|
|
example: true
|
|
is_owner:
|
|
type: boolean
|
|
description: |
|
|
A boolean indicating if the requesting user is
|
|
an organization owner.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 8).
|
|
example: false
|
|
is_billing_admin:
|
|
type: boolean
|
|
description: |
|
|
A boolean indicating if the requesting user is
|
|
a billing administrator.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 73).
|
|
example: false
|
|
role:
|
|
type: integer
|
|
enum:
|
|
- 100
|
|
- 200
|
|
- 300
|
|
- 400
|
|
- 600
|
|
description: |
|
|
[Organization-level role](/api/roles-and-permissions) of
|
|
the requesting user.
|
|
Possible values are:
|
|
|
|
- 100 = Organization owner
|
|
- 200 = Organization administrator
|
|
- 300 = Organization moderator
|
|
- 400 = Member
|
|
- 600 = Guest
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 59).
|
|
is_guest:
|
|
type: boolean
|
|
description: |
|
|
A boolean indicating if the requesting user is a guest.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 10).
|
|
example: false
|
|
is_bot:
|
|
type: boolean
|
|
description: |
|
|
A boolean indicating if the requesting user is a bot.
|
|
example: false
|
|
is_active:
|
|
type: boolean
|
|
description: |
|
|
A boolean specifying whether the requesting user account
|
|
has been deactivated.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 10).
|
|
example: true
|
|
timezone:
|
|
type: string
|
|
description: |
|
|
The time zone of the requesting user.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 10).
|
|
example: ""
|
|
date_joined:
|
|
type: string
|
|
description: |
|
|
The time the requesting user's account was created.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 10).
|
|
example: "2019-10-20T07:50:53.728864+00:00"
|
|
max_message_id:
|
|
type: integer
|
|
deprecated: true
|
|
description: |
|
|
The integer ID of the last message received by the requesting
|
|
user's account.
|
|
|
|
**Deprecated**. We plan to remove this in favor of recommending
|
|
using `GET /messages` with `"anchor": "newest"`.
|
|
example: 30
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The user's ID.
|
|
example: 1
|
|
delivery_email:
|
|
type: string
|
|
description: |
|
|
The requesting user's real email address.
|
|
|
|
**Changes**: Prior to Zulip 7.0 (feature level 163), this field was
|
|
present only when `email_address_visibility` was restricted and the
|
|
requesting user had permission to access realm users' emails. As of
|
|
this feature level, this field is always present.
|
|
profile_data:
|
|
$ref: "#/components/schemas/profile_data"
|
|
example:
|
|
{
|
|
"avatar_url": "https://secure.gravatar.com/avatar/af4f06322c177ef4e1e9b2c424986b54?d=identicon&version=1",
|
|
"avatar_version": 1,
|
|
"email": "iago@zulip.com",
|
|
"delivery_email": iago@zulip.com,
|
|
"full_name": "Iago",
|
|
"is_admin": true,
|
|
"is_owner": false,
|
|
"role": 200,
|
|
"is_guest": false,
|
|
"is_billing_admin": false,
|
|
"is_bot": false,
|
|
"is_active": true,
|
|
"timezone": "",
|
|
"date_joined": "2019-10-20T07:50:53.728864+00:00",
|
|
"max_message_id": 30,
|
|
"msg": "",
|
|
"result": "success",
|
|
"user_id": 5,
|
|
"profile_data":
|
|
{
|
|
"5": {"value": "2000-01-01"},
|
|
"4": {"value": "emacs"},
|
|
"7": {"value": "[10]"},
|
|
"1":
|
|
{
|
|
"value": "+1-234-567-8901",
|
|
"rendered_value": "<p>+1-234-567-8901</p>",
|
|
},
|
|
"2":
|
|
{
|
|
"rendered_value": "<p>Betrayer of Othello.</p>",
|
|
"value": "Betrayer of Othello.",
|
|
},
|
|
"8": {"value": "zulip"},
|
|
"3":
|
|
{
|
|
"value": "Apples",
|
|
"rendered_value": "<p>Apples</p>",
|
|
},
|
|
"6":
|
|
{
|
|
"value": "https://zulip.readthedocs.io/en/latest/",
|
|
},
|
|
},
|
|
}
|
|
delete:
|
|
operationId: deactivate-own-user
|
|
summary: Deactivate own user
|
|
tags: ["users"]
|
|
description: |
|
|
Deactivates the user's account. See also the administrative endpoint for
|
|
[deactivating another user](/api/deactivate-user).
|
|
|
|
This endpoint is primarily useful to Zulip clients providing a user settings UI.
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonError"
|
|
- example:
|
|
{
|
|
"msg": "Cannot deactivate the only organization owner",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON error response when attempting to deactivate the only
|
|
organization owner in an organization:
|
|
/users/me/alert_words:
|
|
get:
|
|
operationId: get-alert-words
|
|
summary: Get all alert words
|
|
tags: ["users"]
|
|
description: |
|
|
Get all of the user's configured [alert words][alert-words].
|
|
|
|
[alert-words]: /help/dm-mention-alert-notifications#alert-words
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
alert_words:
|
|
type: array
|
|
description: |
|
|
An array of strings, where each string is an alert word (or phrase)
|
|
configured by the user.
|
|
items:
|
|
type: string
|
|
example:
|
|
{
|
|
"result": "success",
|
|
"msg": "",
|
|
"alert_words": ["natural", "illustrious"],
|
|
}
|
|
post:
|
|
operationId: add-alert-words
|
|
summary: Add alert words
|
|
tags: ["users"]
|
|
description: |
|
|
Add words (or phrases) to the user's set of configured [alert words][alert-words].
|
|
|
|
[alert-words]: /help/dm-mention-alert-notifications#alert-words
|
|
parameters:
|
|
- name: alert_words
|
|
in: query
|
|
description: |
|
|
An array of strings to be added to the user's set of configured
|
|
alert words. Strings already present in the user's set of alert words
|
|
already are ignored.
|
|
|
|
Alert words are case insensitive.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
example: ["foo", "bar"]
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
alert_words:
|
|
type: array
|
|
description: |
|
|
An array of strings, where each string is an alert word (or phrase)
|
|
configured by the user.
|
|
items:
|
|
type: string
|
|
example:
|
|
{
|
|
"result": "success",
|
|
"msg": "",
|
|
"alert_words": ["foo", "bar", "natural", "illustrious"],
|
|
}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "alert_words[0] is too long (limit: 100 characters)",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON response for when a supplied alert word (or phrase)
|
|
exceeds the character limit:
|
|
delete:
|
|
operationId: remove-alert-words
|
|
summary: Remove alert words
|
|
tags: ["users"]
|
|
description: |
|
|
Remove words (or phrases) from the user's set of configured [alert words][alert-words].
|
|
|
|
Alert words are case insensitive.
|
|
|
|
[alert-words]: /help/dm-mention-alert-notifications#alert-words
|
|
parameters:
|
|
- name: alert_words
|
|
in: query
|
|
description: |
|
|
An array of strings to be removed from the user's set of configured
|
|
alert words. Strings that are not in the user's set of alert words
|
|
are ignored.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
example: ["foo"]
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
alert_words:
|
|
type: array
|
|
description: |
|
|
An array of strings, where each string is an alert word (or phrase)
|
|
configured by the user.
|
|
items:
|
|
type: string
|
|
example:
|
|
{
|
|
"result": "success",
|
|
"msg": "",
|
|
"alert_words": ["bar", "natural", "illustrious"],
|
|
}
|
|
/users/me/status:
|
|
post:
|
|
operationId: update-status
|
|
summary: Update your status
|
|
tags: ["users"]
|
|
description: |
|
|
Change your [status](/help/status-and-availability).
|
|
|
|
A request to this endpoint will only change the parameters passed.
|
|
For example, passing just `status_text` requests a change in the status
|
|
text, but will leave the status emoji unchanged.
|
|
|
|
Clients that wish to set the user's status to a specific value should
|
|
pass all supported parameters.
|
|
|
|
**Changes**: In Zulip 5.0 (feature level 86), added support for
|
|
`emoji_name`, `emoji_code`, and `reaction_type` parameters.
|
|
parameters:
|
|
- name: status_text
|
|
schema:
|
|
type: string
|
|
allowEmptyValue: true
|
|
in: query
|
|
description: |
|
|
The text content of the status message. Sending the empty string
|
|
will clear the user's status.
|
|
|
|
**Note**: The limit on the size of the message is 60 characters.
|
|
example: on vacation
|
|
required: false
|
|
- name: away
|
|
deprecated: true
|
|
schema:
|
|
type: boolean
|
|
in: query
|
|
description: |
|
|
Whether the user should be marked as "away".
|
|
|
|
**Changes**: Deprecated in Zulip 6.0 (feature level 148);
|
|
starting with that feature level, `away` is a legacy way to
|
|
access the user's `presence_enabled` setting, with
|
|
`away = !presence_enabled`. To be removed in a future release.
|
|
example: true
|
|
required: false
|
|
- name: emoji_name
|
|
schema:
|
|
type: string
|
|
allowEmptyValue: true
|
|
in: query
|
|
description: |
|
|
The name for the emoji to associate with this status.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 86).
|
|
example: car
|
|
required: false
|
|
- name: emoji_code
|
|
schema:
|
|
type: string
|
|
in: query
|
|
description: |
|
|
A unique identifier, defining the specific emoji codepoint requested,
|
|
within the namespace of the `reaction_type`.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 86).
|
|
example: 1f697
|
|
required: false
|
|
- name: reaction_type
|
|
schema:
|
|
type: string
|
|
in: query
|
|
description: |
|
|
A string indicating the type of emoji. Each emoji `reaction_type`
|
|
has an independent namespace for values of `emoji_code`.
|
|
|
|
Must be one of the following values:
|
|
|
|
- `unicode_emoji` : In this namespace, `emoji_code` will be a
|
|
dash-separated hex encoding of the sequence of Unicode codepoints
|
|
that define this emoji in the Unicode specification.
|
|
|
|
- `realm_emoji` : In this namespace, `emoji_code` will be the ID of
|
|
the uploaded [custom emoji](/help/custom-emoji).
|
|
|
|
- `zulip_extra_emoji` : These are special emoji included with Zulip.
|
|
In this namespace, `emoji_code` will be the name of the emoji (e.g.
|
|
"zulip").
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 86).
|
|
example: unicode_emoji
|
|
required: false
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Client did not pass any new values.",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
description: |
|
|
An example JSON error response when no changes were requested:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "status_text is too long (limit: 60 characters)",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
description: |
|
|
An example JSON error response when the
|
|
`status_text` message exceeds the limit of
|
|
60 characters:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Client must pass emoji_name if they pass either emoji_code or reaction_type.",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
description: |
|
|
An example JSON error response when `emoji_name` is not specified
|
|
but `emoji_code` or `reaction_type` is specified:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Emoji 'invalid' does not exist",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
description: |
|
|
An example JSON error response when the emoji name does not exist:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Invalid emoji name.",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
description: |
|
|
An example JSON error response when the emoji name is invalid:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Invalid custom emoji.",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
description: |
|
|
An example JSON error response when the custom emoji is invalid:
|
|
/users/me/{stream_id}/topics:
|
|
get:
|
|
operationId: get-stream-topics
|
|
summary: Get topics in a stream
|
|
tags: ["streams"]
|
|
description: |
|
|
Get all the topics in a specific stream
|
|
parameters:
|
|
- $ref: "#/components/parameters/StreamIdInPath"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
topics:
|
|
type: array
|
|
description: |
|
|
An array of `topic` objects.
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
max_id:
|
|
description: |
|
|
The message ID of the last message sent to this topic.
|
|
type: integer
|
|
name:
|
|
description: |
|
|
The name of the topic.
|
|
type: string
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"result": "success",
|
|
"topics":
|
|
[
|
|
{"max_id": 26, "name": "Denmark3"},
|
|
{"max_id": 23, "name": "Denmark1"},
|
|
{"max_id": 6, "name": "Denmark2"},
|
|
],
|
|
}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Invalid stream ID",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON response for when the user is attempting to fetch the topics
|
|
of a non-existing stream (or also a private stream they don't have access to):
|
|
/users/me/subscriptions:
|
|
get:
|
|
operationId: get-subscriptions
|
|
summary: Get subscribed streams
|
|
tags: ["streams"]
|
|
description: |
|
|
Get all streams that the user is subscribed to.
|
|
# operationId can be used to record which view function
|
|
# corresponds to an endpoint. TODO: Add these for more
|
|
# endpoints, and perhaps use this to provide links to implementations.
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: include
|
|
parameters:
|
|
enum:
|
|
- ""
|
|
- type: exclude
|
|
description: |
|
|
You may pass the `include_subscribers` query parameter as follows:
|
|
parameters:
|
|
enum:
|
|
- ""
|
|
parameters:
|
|
- $ref: "#/components/parameters/IncludeSubscribers"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
# TODO: Is this the best way to declare required elements in 200 responses?
|
|
- required:
|
|
- subscriptions
|
|
additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
subscriptions:
|
|
type: array
|
|
description: |
|
|
A list of dictionaries where each dictionary contains
|
|
information about one of the subscribed streams.
|
|
|
|
**Changes**: Removed `email_address` field from the dictionary
|
|
in Zulip 7.5 (feature level 186).
|
|
|
|
**Changes**: Removed `role` field from the dictionary
|
|
in Zulip 6.0 (feature level 133).
|
|
items:
|
|
$ref: "#/components/schemas/Subscriptions"
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"result": "success",
|
|
"subscriptions":
|
|
[
|
|
{
|
|
"audible_notifications": true,
|
|
"color": "#e79ab5",
|
|
"description": "A Scandinavian country",
|
|
"desktop_notifications": true,
|
|
"is_muted": false,
|
|
"invite_only": false,
|
|
"name": "Denmark",
|
|
"pin_to_top": false,
|
|
"push_notifications": false,
|
|
"stream_id": 1,
|
|
"subscribers": [7, 10, 11, 12, 14],
|
|
},
|
|
{
|
|
"audible_notifications": true,
|
|
"color": "#e79ab5",
|
|
"description": "Located in the United Kingdom",
|
|
"desktop_notifications": true,
|
|
"is_muted": false,
|
|
"invite_only": false,
|
|
"name": "Scotland",
|
|
"pin_to_top": false,
|
|
"push_notifications": false,
|
|
"stream_id": 3,
|
|
"subscribers": [7, 11, 12, 14],
|
|
},
|
|
],
|
|
}
|
|
post:
|
|
operationId: subscribe
|
|
summary: Subscribe to a stream
|
|
tags: ["streams"]
|
|
description: |
|
|
Subscribe one or more users to one or more streams.
|
|
|
|
If any of the specified streams do not exist, they are automatically
|
|
created. The initial [stream settings](/api/update-stream) will be determined
|
|
by the optional parameters like `invite_only` detailed below.
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: include
|
|
parameters:
|
|
enum:
|
|
- subscriptions
|
|
- type: include
|
|
description: |
|
|
To subscribe another user to a stream, you may pass in
|
|
the `principals` parameter, like so:
|
|
parameters:
|
|
enum:
|
|
- subscriptions
|
|
- principals
|
|
parameters:
|
|
- name: subscriptions
|
|
in: query
|
|
description: |
|
|
A list of dictionaries containing the key `name` and value
|
|
specifying the name of the stream to subscribe. If the stream does not
|
|
exist a new stream is created. The description of the stream created can
|
|
be specified by setting the dictionary key `description` with an
|
|
appropriate value.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: |
|
|
The name of the stream.
|
|
|
|
Clients should use the `max_stream_name_length` returned by the
|
|
[`POST /register`](/api/register-queue) endpoint to determine
|
|
the maximum stream name length.
|
|
description:
|
|
type: string
|
|
description: |
|
|
The [description](/help/change-the-stream-description)
|
|
to use for a new stream being created, in text/markdown format.
|
|
|
|
Clients should use the `max_stream_description_length` returned
|
|
by the [`POST /register`](/api/register-queue) endpoint to
|
|
determine the maximum stream description length.
|
|
required:
|
|
- name
|
|
example:
|
|
no-description:
|
|
value: {"name": "Verona"}
|
|
with-description:
|
|
value: {"name": "Verona", "description": "Italian city"}
|
|
example: [{"name": "Verona", "description": "Italian city"}]
|
|
required: true
|
|
- $ref: "#/components/parameters/Principals"
|
|
- name: authorization_errors_fatal
|
|
in: query
|
|
description: |
|
|
A boolean specifying whether authorization errors (such as when the
|
|
requesting user is not authorized to access a private stream) should be
|
|
considered fatal or not. When `true`, an authorization error is reported
|
|
as such. When set to `false`, the response will be a 200 and any streams
|
|
where the request encountered an authorization error will be listed
|
|
in the `unauthorized` key.
|
|
schema:
|
|
type: boolean
|
|
default: true
|
|
example: false
|
|
- name: announce
|
|
in: query
|
|
description: |
|
|
If one of the streams specified did not exist previously and is thus created
|
|
by this call, this determines whether [notification bot](/help/configure-notification-bot)
|
|
will send an announcement about the new stream's creation.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
- name: invite_only
|
|
in: query
|
|
description: |
|
|
As described above, this endpoint will create a new stream if passed
|
|
a stream name that doesn't already exist. This parameters and the ones
|
|
that follow are used to request an initial configuration of a created
|
|
stream; they are ignored for streams that already exist.
|
|
|
|
This parameter determines whether any newly created streams will be
|
|
private streams.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
- name: is_web_public
|
|
in: query
|
|
description: |
|
|
This parameter determines whether any newly created streams will be
|
|
web-public streams.
|
|
|
|
Note that creating web-public streams requires the
|
|
`WEB_PUBLIC_STREAMS_ENABLED` [server setting][server-settings]
|
|
to be enabled on the Zulip server in question, the organization
|
|
to have enabled the `enable_spectator_access` realm setting, and
|
|
the current use to have permission under the organization's
|
|
`create_web_public_stream_policy` realm setting.
|
|
|
|
[server-settings]: https://zulip.readthedocs.io/en/stable/production/settings.html
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 98).
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
- $ref: "#/components/parameters/HistoryPublicToSubscribers"
|
|
- $ref: "#/components/parameters/StreamPostPolicy"
|
|
- $ref: "#/components/parameters/MessageRetentionDays"
|
|
- $ref: "#/components/parameters/CanRemoveSubscribersGroupId"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/AddSubscriptionsResponse"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- example:
|
|
{
|
|
"already_subscribed":
|
|
{"newbie@zulip.com": ["new stream"]},
|
|
"msg": "",
|
|
"result": "success",
|
|
"subscribed": {"iago@zulip.com": ["new stream"]},
|
|
}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/JsonError"
|
|
- example:
|
|
{
|
|
"msg": "Unable to access stream (private_stream).",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
A typical response for when the requesting user does not have access to
|
|
a private stream and `"authorization_errors_fatal": true`:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/AddSubscriptionsResponse"
|
|
- example:
|
|
{
|
|
"already_subscribed": {},
|
|
"msg": "",
|
|
"result": "success",
|
|
"subscribed": {},
|
|
"unauthorized": ["private_stream"],
|
|
}
|
|
description: |
|
|
A typical response for when the requesting user does not have access to
|
|
a private stream and `"authorization_errors_fatal": false`:
|
|
patch:
|
|
operationId: update-subscriptions
|
|
summary: Update subscriptions
|
|
tags: ["streams"]
|
|
description: |
|
|
Update which streams you are subscribed to.
|
|
parameters:
|
|
- name: delete
|
|
in: query
|
|
description: |
|
|
A list of stream names to unsubscribe from.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
example: ["Verona", "Denmark"]
|
|
required: false
|
|
- name: add
|
|
in: query
|
|
description: |
|
|
A list of objects describing which streams to subscribe to, optionally
|
|
including per-user subscription parameters (e.g. color) and if the
|
|
stream is to be created, its description.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
name:
|
|
type: string
|
|
color:
|
|
type: string
|
|
description:
|
|
type: string
|
|
example:
|
|
[
|
|
{"name": "Verona"},
|
|
{
|
|
"name": "Denmark",
|
|
"color": "#e79ab5",
|
|
"description": "A Scandinavian country",
|
|
},
|
|
]
|
|
required: false
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- required:
|
|
- subscribed
|
|
- already_subscribed
|
|
- removed
|
|
additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
subscribed:
|
|
type: object
|
|
description: |
|
|
A dictionary where the key is the Zulip API email
|
|
address of the user/bot and the value is a
|
|
list of the names of the streams that were
|
|
subscribed to as a result of the query.
|
|
additionalProperties:
|
|
description: |
|
|
`{email_id}`: A list of the names of streams that
|
|
the user was subscribed to as a result of the query.
|
|
type: array
|
|
items:
|
|
type: string
|
|
already_subscribed:
|
|
type: object
|
|
description: |
|
|
A dictionary where the key is the Zulip API email
|
|
address of the user/bot and the value is a
|
|
list of the names of the streams that the
|
|
user/bot is already subscribed to.
|
|
additionalProperties:
|
|
description: |
|
|
`{email_id}`: A list of the names of streams that
|
|
the user was already subscribed to.
|
|
type: array
|
|
items:
|
|
type: string
|
|
not_removed:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: |
|
|
A list of the names of streams that the user
|
|
is already unsubscribed from, and hence
|
|
doesn't need to be unsubscribed.
|
|
removed:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: |
|
|
A list of the names of streams which were unsubscribed
|
|
from as a result of the query.
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"subscribed": {},
|
|
"already_subscribed": {"iago@zulip.com": ["Verona"]},
|
|
"not_removed": [],
|
|
"removed": ["new stream"],
|
|
"result": "success",
|
|
}
|
|
delete:
|
|
operationId: unsubscribe
|
|
summary: Unsubscribe from a stream
|
|
tags: ["streams"]
|
|
description: |
|
|
Unsubscribe yourself or other users from one or more streams.
|
|
|
|
In addition to managing the current user's subscriptions, this
|
|
endpoint can be used to remove other users from streams. This
|
|
is possible in 3 situations:
|
|
|
|
- Organization administrators can remove any user from any
|
|
stream.
|
|
- Users can remove a bot that they own from any stream that
|
|
the user [can access](/help/stream-permissions).
|
|
- Users can unsubscribe any user from a stream if they [have
|
|
access](/help/stream-permissions) to the stream and are a
|
|
member of the [user group](/api/get-user-groups) specified
|
|
by the [`can_remove_subscribers_group_id`][can-remove-parameter]
|
|
for the stream.
|
|
|
|
**Changes**: Before Zulip 7.0 (feature level 161), the
|
|
`can_remove_subscribers_group_id` for all streams was always
|
|
the system group for organization administrators.
|
|
|
|
Before Zulip 6.0 (feature level 145), users had no special
|
|
privileges for managing bots that they own.
|
|
|
|
[can-remove-parameter]: /api/subscribe#parameter-can_remove_subscribers_group_id
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: include
|
|
description: |
|
|
**Note**: Unsubscribing another user from a stream requires
|
|
administrative privileges.
|
|
parameters:
|
|
enum:
|
|
- subscriptions
|
|
- type: exclude
|
|
parameters:
|
|
enum:
|
|
- ""
|
|
description: |
|
|
You may specify the `principals` parameter like so:
|
|
parameters:
|
|
- name: subscriptions
|
|
in: query
|
|
description: |
|
|
A list of stream names to unsubscribe from. This parameter is called
|
|
`streams` in our Python API.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
example: ["Verona", "Denmark"]
|
|
required: true
|
|
- $ref: "#/components/parameters/Principals"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
not_removed:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: |
|
|
A list of the names of streams that the user is already unsubscribed
|
|
from, and hence doesn't need to be unsubscribed.
|
|
removed:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: |
|
|
A list of the names of streams which were unsubscribed from as a result
|
|
of the query.
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"not_removed": [],
|
|
"removed": ["new stream"],
|
|
"result": "success",
|
|
}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/NonExistingStreamNameError"
|
|
- description: |
|
|
A typical failed JSON response for when the target stream does not exist:
|
|
/users/me/subscriptions/muted_topics:
|
|
patch:
|
|
operationId: mute-topic
|
|
summary: Topic muting
|
|
tags: ["streams"]
|
|
description: |
|
|
[Mute or unmute a topic](/help/mute-a-topic) within a stream that
|
|
the current user is subscribed to.
|
|
|
|
**Changes**: Deprecated in Zulip 7.0 (feature level 170). Clients connecting
|
|
to newer servers should use the [POST /user_topics](/api/update-user-topic)
|
|
endpoint, as this endpoint may be removed in a future release.
|
|
|
|
Before Zulip 7.0 (feature level 169), this endpoint
|
|
returned an error if asked to mute a topic that was already muted
|
|
or asked to unmute a topic that had not previously been muted.
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: exclude
|
|
parameters:
|
|
enum:
|
|
- stream_id
|
|
parameters:
|
|
- name: stream_id
|
|
in: query
|
|
description: |
|
|
The ID of the stream to access.
|
|
|
|
Clients must provide either `stream` or `stream_id` as a parameter
|
|
to this endpoint, but not both.
|
|
|
|
**Changes**: New in Zulip 2.0.0.
|
|
schema:
|
|
type: integer
|
|
example: 43
|
|
required: false
|
|
- name: stream
|
|
in: query
|
|
description: |
|
|
The name of the stream to access.
|
|
|
|
Clients must provide either `stream` or `stream_id` as a parameter
|
|
to this endpoint, but not both. Clients should use `stream_id`
|
|
instead of the `stream` parameter when possible.
|
|
schema:
|
|
type: string
|
|
example: Denmark
|
|
required: false
|
|
- name: topic
|
|
in: query
|
|
description: |
|
|
The topic to (un)mute. Note that the request will succeed regardless of
|
|
whether any messages have been sent to the specified topic.
|
|
schema:
|
|
type: string
|
|
example: dinner
|
|
required: true
|
|
- name: op
|
|
in: query
|
|
description: |
|
|
Whether to mute (`add`) or unmute (`remove`) the provided topic.
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- add
|
|
- remove
|
|
example: add
|
|
required: true
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
/user_topics:
|
|
post:
|
|
operationId: update-user-topic
|
|
summary: Update personal preferences for a topic
|
|
tags: ["streams"]
|
|
description: |
|
|
This endpoint is used to update the personal preferences for a topic,
|
|
such as the topic's visibility policy, which is used to implement
|
|
[mute a topic](/help/mute-a-topic) and related features.
|
|
|
|
This endpoint can be used to update the visibility policy for the single
|
|
stream and topic pair indicated by the parameters for a user.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 170). Previously,
|
|
toggling whether a topic was muted or unmuted was managed by the
|
|
[PATCH /users/me/subscriptions/muted_topics](/api/mute-topic) endpoint.
|
|
parameters:
|
|
- name: stream_id
|
|
in: query
|
|
description: |
|
|
The ID of the stream to access.
|
|
schema:
|
|
type: integer
|
|
example: 1
|
|
required: true
|
|
- name: topic
|
|
in: query
|
|
description: |
|
|
The topic for which the personal preferences needs to be updated.
|
|
Note that the request will succeed regardless of whether
|
|
any messages have been sent to the specified topic.
|
|
schema:
|
|
type: string
|
|
example: dinner
|
|
required: true
|
|
- name: visibility_policy
|
|
in: query
|
|
description: |
|
|
Controls which visibility policy to set.
|
|
|
|
- 0 = None. Removes the visibility policy previously set for the topic.
|
|
- 1 = Muted. [Mutes the topic](/help/mute-a-topic) in a stream.
|
|
- 2 = Unmuted. [Unmutes the topic](/help/mute-a-topic) in a muted stream.
|
|
|
|
In an unmuted stream, a topic visibility policy of unmuted will have the
|
|
same effect as the "None" visibility policy.
|
|
schema:
|
|
type: integer
|
|
enum:
|
|
- 0
|
|
- 1
|
|
- 2
|
|
example: 1
|
|
required: true
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
/users/me/muted_users/{muted_user_id}:
|
|
post:
|
|
operationId: mute-user
|
|
summary: Mute a user
|
|
tags: ["users"]
|
|
description: |
|
|
This endpoint [mutes a user](/help/mute-a-user). Messages sent by users
|
|
you've muted will be automatically marked as read and hidden.
|
|
|
|
Muted users should be implemented by clients as follows:
|
|
|
|
- The server will immediately mark all messages sent by the muted
|
|
user as read. This will automatically clear any existing mobile
|
|
push notifications related to the muted user.
|
|
- The server will mark any new messages sent by the muted user as read
|
|
for your account, which prevents all email and mobile push notifications.
|
|
- Clients should exclude muted users from presence lists or other UI
|
|
for viewing or composing 1:1 private messages. 1:1 private messages sent by
|
|
muted users should be hidden everywhere in the Zulip UI.
|
|
- Stream messages and group private messages sent by the muted
|
|
user should avoid displaying the content and name/avatar,
|
|
but should display that N messages by a muted user were
|
|
hidden (so that it is possible to interpret the messages by
|
|
other users who are talking with the muted user).
|
|
- Group private message conversations including the muted user
|
|
should display muted users as "Muted user", rather than
|
|
showing their name, in lists of such conversations, along with using
|
|
a blank grey avatar where avatars are displayed.
|
|
- Administrative/settings UI elements for showing "All users that exist
|
|
on this stream or realm", e.g. for organization
|
|
administration or showing stream subscribers, should display
|
|
the user's name as normal.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 48).
|
|
parameters:
|
|
- $ref: "#/components/parameters/MutedUserId"
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/JsonError"
|
|
- example: {"msg": "Cannot mute self", "result": "error"}
|
|
description: |
|
|
An example JSON response for when the user is yourself:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/JsonError"
|
|
- example: {"msg": "No such user", "result": "error"}
|
|
description: |
|
|
An example JSON response for when the user is nonexistent or inaccessible:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/JsonError"
|
|
- example:
|
|
{"msg": "User already muted", "result": "error"}
|
|
description: |
|
|
An example JSON response for when the user is already muted:
|
|
delete:
|
|
operationId: unmute-user
|
|
summary: Unmute a user
|
|
tags: ["users"]
|
|
description: |
|
|
This endpoint unmutes a user.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 48).
|
|
parameters:
|
|
- $ref: "#/components/parameters/MutedUserId"
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/JsonError"
|
|
- example: {"msg": "No such user", "result": "error"}
|
|
description: |
|
|
An example JSON response for when the user is nonexistent or inaccessible:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/JsonError"
|
|
- example: {"msg": "User is not muted", "result": "error"}
|
|
description: |
|
|
An example JSON response for when the user is not previously muted:
|
|
|
|
/users/{user_id}/subscriptions/{stream_id}:
|
|
get:
|
|
operationId: get-subscription-status
|
|
summary: Get subscription status
|
|
tags: ["streams"]
|
|
description: |
|
|
Check whether a user is subscribed to a stream.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 11).
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserId"
|
|
- $ref: "#/components/parameters/StreamIdInPath"
|
|
responses:
|
|
"200":
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
is_subscribed:
|
|
type: boolean
|
|
description: |
|
|
Whether the user is subscribed to the stream.
|
|
example:
|
|
{"msg": "", "result": "success", "is_subscribed": false}
|
|
/realm/emoji/{emoji_name}:
|
|
post:
|
|
operationId: upload-custom-emoji
|
|
summary: Upload custom emoji
|
|
tags: ["server_and_organizations"]
|
|
description: |
|
|
This endpoint is used to upload a custom emoji for use in the user's
|
|
organization. Access to this endpoint depends on the
|
|
[organization's configuration](https://zulip.com/help/only-allow-admins-to-add-emoji).
|
|
x-parameter-description: |
|
|
As described above, the image file to upload must be provided in the
|
|
request's body.
|
|
|
|
## Maximum file size
|
|
|
|
The maximum file size for uploads can be configured by the
|
|
administrator of the Zulip server by setting `MAX_EMOJI_FILE_SIZE_MIB`
|
|
in the [server's settings][1]. `MAX_EMOJI_FILE_SIZE_MIB` defaults
|
|
to 5MB.
|
|
|
|
[1]: https://zulip.readthedocs.io/en/latest/subsystems/settings.html#server-settings
|
|
parameters:
|
|
- name: emoji_name
|
|
required: true
|
|
in: path
|
|
description: |
|
|
The name that should be associated with the uploaded emoji image/gif.
|
|
The emoji name can only contain letters, numbers, dashes, and spaces.
|
|
Upper and lower case letters are treated the same, and underscores (\_)
|
|
are treated the same as spaces (consistent with how the Zulip UI
|
|
handles emoji).
|
|
schema:
|
|
type: string
|
|
example: smile
|
|
requestBody:
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
filename:
|
|
type: string
|
|
format: binary
|
|
example: /path/to/img.png
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
|
|
/realm/emoji:
|
|
get:
|
|
operationId: get-custom-emoji
|
|
summary: Get all custom emoji
|
|
tags: ["server_and_organizations"]
|
|
description: |
|
|
Get all the custom emoji in the user's organization.
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
emoji:
|
|
type: object
|
|
description: |
|
|
An object that contains `emoji` objects, each identified with their
|
|
emoji ID as the key.
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/RealmEmoji"
|
|
example:
|
|
{
|
|
"result": "success",
|
|
"msg": "",
|
|
"emoji":
|
|
{
|
|
"1":
|
|
{
|
|
"id": "1",
|
|
"name": "green_tick",
|
|
"source_url": "/user_avatars/1/emoji/images/1.png",
|
|
"deactivated": false,
|
|
"author_id": 5,
|
|
},
|
|
},
|
|
}
|
|
/realm/presence:
|
|
get:
|
|
operationId: get-presence
|
|
summary: Get presence of all users
|
|
tags: ["server_and_organizations"]
|
|
description: |
|
|
Get the presence information of all the users in an organization.
|
|
|
|
See [Zulip's developer documentation][subsystems-presence]
|
|
for details on the data model for presence in Zulip.
|
|
|
|
[subsystems-presence]: https://zulip.readthedocs.io/en/latest/subsystems/presence.html
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
server_timestamp:
|
|
type: number
|
|
description: |
|
|
The time when the server fetched the `presences` data included
|
|
in the response.
|
|
presences:
|
|
type: object
|
|
description: |
|
|
A dictionary where each entry describes the presence details
|
|
of a user in the Zulip organization.
|
|
additionalProperties:
|
|
type: object
|
|
description: |
|
|
`{user_email}`: Object containing the details of a user's presence.
|
|
The object's key is the user's Zulip API email.
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/Presence"
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"presences":
|
|
{
|
|
"iago@zulip.com":
|
|
{
|
|
"website":
|
|
{
|
|
"client": "website",
|
|
"pushable": false,
|
|
"status": "active",
|
|
"timestamp": 1656958485,
|
|
},
|
|
"aggregated":
|
|
{
|
|
"client": "website",
|
|
"status": "active",
|
|
"timestamp": 1656958485,
|
|
},
|
|
},
|
|
},
|
|
"result": "success",
|
|
"server_timestamp": 1656958539.6287155,
|
|
}
|
|
/realm/profile_fields:
|
|
get:
|
|
operationId: get-custom-profile-fields
|
|
summary: Get all custom profile fields
|
|
tags: ["server_and_organizations"]
|
|
description: |
|
|
Get all the [custom profile fields](/help/custom-profile-fields)
|
|
configured for the user's organization.
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
custom_fields:
|
|
type: array
|
|
description: |
|
|
An array containing all the custom profile fields defined in this
|
|
Zulip organization.
|
|
items:
|
|
$ref: "#/components/schemas/CustomProfileField"
|
|
example:
|
|
{
|
|
"result": "success",
|
|
"msg": "",
|
|
"custom_fields":
|
|
[
|
|
{
|
|
"id": 1,
|
|
"name": "Phone number",
|
|
"type": 1,
|
|
"hint": "",
|
|
"field_data": "",
|
|
"order": 1,
|
|
},
|
|
{
|
|
"id": 2,
|
|
"name": "Biography",
|
|
"type": 2,
|
|
"hint": "What are you known for?",
|
|
"field_data": "",
|
|
"order": 2,
|
|
},
|
|
{
|
|
"id": 3,
|
|
"name": "Favorite food",
|
|
"type": 1,
|
|
"hint": "Or drink, if you'd prefer",
|
|
"field_data": "",
|
|
"order": 3,
|
|
},
|
|
{
|
|
"id": 4,
|
|
"name": "Favorite editor",
|
|
"type": 3,
|
|
"hint": "",
|
|
"field_data": '{"0":{"text":"Vim","order":"1"},"1":{"text":"Emacs","order":"2"}}',
|
|
"order": 4,
|
|
"display_in_profile_summary": true,
|
|
},
|
|
{
|
|
"id": 5,
|
|
"name": "Birthday",
|
|
"type": 4,
|
|
"hint": "",
|
|
"field_data": "",
|
|
"order": 5,
|
|
},
|
|
{
|
|
"id": 6,
|
|
"name": "Favorite website",
|
|
"type": 5,
|
|
"hint": "Or your personal blog's URL",
|
|
"field_data": "",
|
|
"order": 6,
|
|
"display_in_profile_summary": true,
|
|
},
|
|
{
|
|
"id": 7,
|
|
"name": "Mentor",
|
|
"type": 6,
|
|
"hint": "",
|
|
"field_data": "",
|
|
"order": 7,
|
|
},
|
|
{
|
|
"id": 8,
|
|
"name": "GitHub",
|
|
"type": 7,
|
|
"hint": "Enter your GitHub username",
|
|
"field_data": '{"subtype":"github"}',
|
|
"order": 8,
|
|
},
|
|
{
|
|
"id": 9,
|
|
"name": "Pronouns",
|
|
"type": 8,
|
|
"hint": "What pronouns should people use to refer to you?",
|
|
"order": 9,
|
|
},
|
|
],
|
|
}
|
|
patch:
|
|
operationId: reorder-custom-profile-fields
|
|
summary: Reorder custom profile fields
|
|
tags: ["server_and_organizations"]
|
|
description: |
|
|
Reorder the custom profile fields in the user's organization.
|
|
|
|
Custom profile fields are displayed in Zulip UI widgets in order; this
|
|
endpoint allows administrative settings UI to change the field ordering.
|
|
|
|
This endpoint is used to implement the dragging feature described in the
|
|
[custom profile fields documentation](/help/custom-profile-fields).
|
|
x-requires-administrator: true
|
|
parameters:
|
|
- name: order
|
|
in: query
|
|
description: |
|
|
A list of the IDs of all the custom profile fields defined in this
|
|
organization, in the desired new order.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
example: [11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1]
|
|
required: true
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
post:
|
|
operationId: create-custom-profile-field
|
|
summary: Create a custom profile field
|
|
tags: ["server_and_organizations"]
|
|
description: |
|
|
[Create a custom profile field](/help/custom-profile-fields#add-a-custom-profile-field) in the user's organization.
|
|
x-requires-administrator: true
|
|
parameters:
|
|
- name: name
|
|
in: query
|
|
description: |
|
|
The name of the custom profile field, which will appear both in
|
|
user-facing settings UI for configuring custom profile fields and
|
|
in UI displaying a user's profile.
|
|
schema:
|
|
type: string
|
|
example: "Favorite programming language"
|
|
- name: hint
|
|
in: query
|
|
description: |
|
|
The help text to be displayed for the custom profile field in user-facing
|
|
settings UI for configuring custom profile fields.
|
|
schema:
|
|
type: string
|
|
example: "Your favorite programming language."
|
|
- name: field_type
|
|
in: query
|
|
description: |
|
|
The field type can be any of the supported custom profile field types. See the
|
|
[custom profile fields documentation](/help/custom-profile-fields)
|
|
for more details on what each type means.
|
|
|
|
- **1**: Short text
|
|
- **2**: Long text
|
|
- **3**: List of options
|
|
- **4**: Date picker
|
|
- **5**: Link
|
|
- **6**: Person picker
|
|
- **7**: External account
|
|
- **8**: Pronouns
|
|
|
|
**Changes**: Field type `8` added in Zulip 6.0 (feature level 151).
|
|
schema:
|
|
type: integer
|
|
example: 3
|
|
required: true
|
|
- name: field_data
|
|
in: query
|
|
description: |
|
|
Field types 3 (List of options) and 7 (External account) support storing
|
|
additional configuration for the field type in the `field_data` attribute.
|
|
|
|
For field type 3 (List of options), this attribute is a JSON dictionary
|
|
defining the choices and the order they will be displayed in the
|
|
dropdown UI for individual users to select an option.
|
|
|
|
The interface for field type 7 is not yet stabilized.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
example:
|
|
{
|
|
"python": {"text": "Python", "order": "1"},
|
|
"java": {"text": "Java", "order": "2"},
|
|
}
|
|
- name: display_in_profile_summary
|
|
in: query
|
|
description: |
|
|
Whether clients should display this profile field in a summary section of a
|
|
user's profile (or in a more easily accessible "small profile").
|
|
|
|
At most 2 profile fields may have this property be true in a given
|
|
organization. The "Long text" [profile field types][profile-field-types]
|
|
profile field types cannot be selected to be displayed in profile summaries.
|
|
|
|
The "Person picker" profile field is also not supported, but that is likely to
|
|
be temporary.
|
|
|
|
[profile-field-types]: /help/custom-profile-fields#profile-field-types
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 146).
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID for the custom profile field.
|
|
example: {"result": "success", "msg": "", "id": 9}
|
|
/realm/user_settings_defaults:
|
|
patch:
|
|
operationId: update-realm-user-settings-defaults
|
|
summary: Update realm-level defaults of user settings
|
|
tags: ["server_and_organizations"]
|
|
x-requires-administrator: true
|
|
description: |
|
|
Change the [default values of settings][new-user-defaults] for new users
|
|
joining the organization. Essentially all
|
|
[personal preference settings](/api/update-settings) are supported.
|
|
|
|
This feature can be invaluable for customizing Zulip's default
|
|
settings for notifications or UI to be appropriate for how the
|
|
organization is using Zulip. (Note that this only supports
|
|
personal preference settings, like when to send push
|
|
notifications or what emoji set to use, not profile or
|
|
identity settings that naturally should be different for each user).
|
|
|
|
Note that this endpoint cannot, at present, be used to modify
|
|
settings for existing users in any way.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 96). If any parameters
|
|
sent in the request are not supported by this endpoint, an
|
|
[`ignored_parameters_unsupported`][ignored-parameters] array will
|
|
be returned in the JSON success response.
|
|
|
|
[new-user-defaults]: /help/configure-default-new-user-settings
|
|
[ignored-parameters]: /api/rest-error-handling#ignored-parameters
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: include
|
|
parameters:
|
|
enum:
|
|
- left_side_userlist
|
|
- emojiset
|
|
parameters:
|
|
- name: dense_mode
|
|
in: query
|
|
description: |
|
|
This setting has no effect at present. It is reserved for use in controlling
|
|
the default font size in Zulip.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: starred_message_counts
|
|
in: query
|
|
description: |
|
|
Whether clients should display the [number of starred
|
|
messages](/help/star-a-message#display-the-number-of-starred-messages).
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: fluid_layout_width
|
|
in: query
|
|
description: |
|
|
Whether to use the [maximum available screen width](/help/enable-full-width-display)
|
|
for the web app's center panel (message feed, recent conversations) on wide screens.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: high_contrast_mode
|
|
in: query
|
|
description: |
|
|
This setting is reserved for use to control variations in Zulip's design
|
|
to help visually impaired users.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: web_mark_read_on_scroll_policy
|
|
in: query
|
|
description: |
|
|
Whether or not to mark messages as read when the user scrolls through their
|
|
feed.
|
|
|
|
- 1 - Always
|
|
- 2 - Only in conversation views
|
|
- 3 - Never
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 175). Previously, there was no
|
|
way for the user to configure this behavior on the web, and the Zulip web and
|
|
desktop apps behaved like the "Always" setting when marking messages as read.
|
|
schema:
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
example: 1
|
|
- name: color_scheme
|
|
in: query
|
|
description: |
|
|
Controls which [color theme](/help/dark-theme) to use.
|
|
|
|
- 1 - Automatic
|
|
- 2 - Dark theme
|
|
- 3 - Light theme
|
|
|
|
Automatic detection is implementing using the standard `prefers-color-scheme`
|
|
media query.
|
|
schema:
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
example: 1
|
|
- name: enable_drafts_synchronization
|
|
in: query
|
|
description: |
|
|
A boolean parameter to control whether synchronizing drafts is enabled for
|
|
the user. When synchronization is disabled, all drafts stored in the server
|
|
will be automatically deleted from the server.
|
|
|
|
This does not do anything (like sending events) to delete local copies of
|
|
drafts stored in clients.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: translate_emoticons
|
|
in: query
|
|
description: |
|
|
Whether to [translate emoticons to emoji](/help/configure-emoticon-translations)
|
|
in messages the user sends.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: display_emoji_reaction_users
|
|
in: query
|
|
description: |
|
|
Whether to display the names of reacting users on a message.
|
|
|
|
When enabled, clients should display the names of reacting users, rather than
|
|
a count, for messages with few total reactions. The ideal cutoff may depend on
|
|
the space available for displaying reactions; the official web application
|
|
displays names when 3 or fewer total reactions are present with this setting
|
|
enabled.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 125).
|
|
schema:
|
|
type: boolean
|
|
example: false
|
|
- name: default_view
|
|
in: query
|
|
description: |
|
|
The [default view](/help/configure-default-view) used when opening a new
|
|
Zulip web app window or hitting the `Esc` keyboard shortcut repeatedly.
|
|
|
|
- "recent_topics" - Recent conversations view
|
|
- "all_messages" - All messages view
|
|
schema:
|
|
type: string
|
|
example: all_messages
|
|
- name: escape_navigates_to_default_view
|
|
in: query
|
|
description: |
|
|
Whether the escape key navigates to the
|
|
[configured default view](/help/configure-default-view).
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 107).
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: left_side_userlist
|
|
in: query
|
|
description: |
|
|
Whether the users list on left sidebar in narrow windows.
|
|
|
|
This feature is not heavily used and is likely to be reworked.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: emojiset
|
|
in: query
|
|
description: |
|
|
The user's configured [emoji set](/help/emoji-and-emoticons#use-emoticons),
|
|
used to display emoji to the user everywhere they appear in the UI.
|
|
|
|
- "google" - Google
|
|
- "twitter" - Twitter
|
|
- "text" - Plain text
|
|
- "google-blob" - Google blobs
|
|
schema:
|
|
type: string
|
|
example: "google"
|
|
- name: demote_inactive_streams
|
|
in: query
|
|
description: |
|
|
Whether to [demote inactive streams](/help/manage-inactive-streams) in the left sidebar.
|
|
|
|
- 1 - Automatic
|
|
- 2 - Always
|
|
- 3 - Never
|
|
schema:
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
example: 1
|
|
- name: user_list_style
|
|
in: query
|
|
description: |
|
|
The style selected by the user for the right sidebar user list.
|
|
|
|
- 1 - Compact
|
|
- 2 - With status
|
|
- 3 - With avatar and status
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 141).
|
|
schema:
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
example: 1
|
|
- name: enable_stream_desktop_notifications
|
|
in: query
|
|
description: |
|
|
Enable visual desktop notifications for stream messages.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: enable_stream_email_notifications
|
|
in: query
|
|
description: |
|
|
Enable email notifications for stream messages.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: enable_stream_push_notifications
|
|
in: query
|
|
description: |
|
|
Enable mobile notifications for stream messages.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: enable_stream_audible_notifications
|
|
in: query
|
|
description: |
|
|
Enable audible desktop notifications for stream messages.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: notification_sound
|
|
in: query
|
|
description: |
|
|
Notification sound name.
|
|
schema:
|
|
type: string
|
|
example: ding
|
|
- name: enable_desktop_notifications
|
|
in: query
|
|
description: |
|
|
Enable visual desktop notifications for private messages and @-mentions.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: enable_sounds
|
|
in: query
|
|
description: |
|
|
Enable audible desktop notifications for private messages and
|
|
@-mentions.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: email_notifications_batching_period_seconds
|
|
in: query
|
|
description: |
|
|
The duration (in seconds) for which the server should wait to batch
|
|
email notifications before sending them.
|
|
schema:
|
|
type: integer
|
|
example: 120
|
|
- name: enable_offline_email_notifications
|
|
in: query
|
|
description: |
|
|
Enable email notifications for private messages and @-mentions received
|
|
when the user is offline.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: enable_offline_push_notifications
|
|
in: query
|
|
description: |
|
|
Enable mobile notification for private messages and @-mentions received
|
|
when the user is offline.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: enable_online_push_notifications
|
|
in: query
|
|
description: |
|
|
Enable mobile notification for private messages and @-mentions received
|
|
when the user is online.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: enable_digest_emails
|
|
in: query
|
|
description: |
|
|
Enable digest emails when the user is away.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: message_content_in_email_notifications
|
|
in: query
|
|
description: |
|
|
Include the message's content in email notifications for new messages.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: pm_content_in_desktop_notifications
|
|
in: query
|
|
description: |
|
|
Include content of private messages in desktop notifications.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: wildcard_mentions_notify
|
|
in: query
|
|
description: |
|
|
Whether wildcard mentions (E.g. @**all**) should send notifications
|
|
like a personal mention.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: desktop_icon_count_display
|
|
in: query
|
|
description: |
|
|
Unread count badge (appears in desktop sidebar and browser tab)
|
|
|
|
- 1 - All unreads
|
|
- 2 - Private messages and mentions
|
|
- 3 - None
|
|
schema:
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
example: 1
|
|
- name: realm_name_in_email_notifications_policy
|
|
in: query
|
|
description: |
|
|
Whether to [include organization name in subject of message notification
|
|
emails](/help/email-notifications#include-organization-name-in-subject-line).
|
|
|
|
- 1 - Automatic
|
|
- 2 - Always
|
|
- 3 - Never
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 168), replacing the
|
|
previous `realm_name_in_notifications` boolean;
|
|
`true` corresponded to `Always`, and `false` to `Never`.
|
|
schema:
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
example: 1
|
|
- name: presence_enabled
|
|
in: query
|
|
description: |
|
|
Display the presence status to other users when online.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: enter_sends
|
|
in: query
|
|
description: |
|
|
Whether pressing Enter in the compose box sends a message
|
|
(or saves a message edit).
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: twenty_four_hour_time
|
|
in: query
|
|
description: |
|
|
Whether time should be [displayed in 24-hour notation](/help/change-the-time-format).
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 99).
|
|
Previously, this default was edited using the
|
|
`default_twenty_four_hour_time` parameter to the `PATCH /realm` endpoint.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: send_private_typing_notifications
|
|
in: query
|
|
description: |
|
|
Whether [typing notifications](/help/typing-notifications) be sent when composing
|
|
private messages.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 105).
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: send_stream_typing_notifications
|
|
in: query
|
|
description: |
|
|
Whether [typing notifications](/help/typing-notifications) be sent when composing
|
|
stream messages.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 105).
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: send_read_receipts
|
|
in: query
|
|
description: |
|
|
Whether other users are allowed to see whether you've
|
|
read messages.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 105).
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: email_address_visibility
|
|
in: query
|
|
description: |
|
|
The [policy][permission-level] for [which other users][help-email-visibility]
|
|
in this organization can see the user's real email address.
|
|
|
|
- 1 = Everyone
|
|
- 2 = Members only
|
|
- 3 = Administrators only
|
|
- 4 = Nobody
|
|
- 5 = Moderators only
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 163), replacing the
|
|
realm-level setting.
|
|
|
|
[permission-level]: /api/roles-and-permissions#permission-levels
|
|
[help-email-visibility]: /help/configure-email-visibility
|
|
schema:
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
- 4
|
|
- 5
|
|
example: 1
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SuccessIgnoredParameters"
|
|
|
|
/users/me/subscriptions/properties:
|
|
post:
|
|
operationId: update-subscription-settings
|
|
summary: Update subscription settings
|
|
tags: ["streams"]
|
|
description: |
|
|
This endpoint is used to update the user's personal settings for the
|
|
streams they are subscribed to, including muting, color, pinning, and
|
|
per-stream notification settings.
|
|
|
|
**Changes**: Prior to Zulip 5.0 (feature level 111), response
|
|
object included the `subscription_data` in the the
|
|
request. The endpoint now returns the more ergonomic
|
|
[`ignored_parameters_unsupported`][ignored-parameters] array instead.
|
|
|
|
[ignored-parameters]: /api/rest-error-handling#ignored-parameters
|
|
parameters:
|
|
- name: subscription_data
|
|
in: query
|
|
description: |
|
|
A list of objects that describe the changes that should be applied in
|
|
each subscription. Each object represents a subscription, and must have
|
|
a `stream_id` key that identifies the stream, as well as the `property`
|
|
being modified and its new `value`.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
The unique ID of a stream.
|
|
property:
|
|
type: string
|
|
enum:
|
|
- color
|
|
- is_muted
|
|
- in_home_view
|
|
- pin_to_top
|
|
- desktop_notifications
|
|
- audible_notifications
|
|
- push_notifications
|
|
- email_notifications
|
|
- wildcard_mentions_notify
|
|
description: |
|
|
One of the stream properties described below:
|
|
|
|
- `"color"`: The hex value of the user's display color for the stream.
|
|
|
|
- `"is_muted"`: Whether the stream is [muted](/help/mute-a-stream).<br>
|
|
**Changes**: As of Zulip 6.0 (feature level 139), updating either
|
|
`"is_muted"` or `"in_home_view"` generates two [subscription update
|
|
events](/api/get-events#subscription-update), one for each property,
|
|
that are sent to clients. Prior to this feature level, updating either
|
|
property only generated a subscription update event for
|
|
`"in_home_view"`. <br>
|
|
**Changes**: Prior to Zulip 2.1.0, this feature was represented
|
|
by the more confusingly named `"in_home_view"` (with the
|
|
opposite value: `in_home_view=!is_muted`); for
|
|
backwards-compatibility, modern Zulip still accepts that property.
|
|
|
|
- `"pin_to_top"`: Whether to pin the stream at the top of the stream list.
|
|
|
|
- `"desktop_notifications"`: Whether to show desktop notifications
|
|
for all messages sent to the stream.
|
|
|
|
- `"audible_notifications"`: Whether to play a sound
|
|
notification for all messages sent to the stream.
|
|
|
|
- `"push_notifications"`: Whether to trigger a mobile push
|
|
notification for all messages sent to the stream.
|
|
|
|
- `"email_notifications"`: Whether to trigger an email
|
|
notification for all messages sent to the stream.
|
|
|
|
- `"wildcard_mentions_notify"`: Whether wildcard mentions trigger
|
|
notifications as though they were personal mentions in this stream.
|
|
value:
|
|
oneOf:
|
|
- type: boolean
|
|
- type: string
|
|
description: |
|
|
The new value of the property being modified.
|
|
|
|
If the property is `"color"`, then `value` is a string
|
|
representing the hex value of the user's display
|
|
color for the stream. For all other above properties,
|
|
`value` is a boolean.
|
|
required:
|
|
- stream_id
|
|
- property
|
|
- value
|
|
example:
|
|
{"stream_id": 2, "property": "is_muted", "value": true}
|
|
example:
|
|
[
|
|
{"stream_id": 1, "property": "pin_to_top", "value": true},
|
|
{"stream_id": 3, "property": "color", "value": "#f00f00"},
|
|
]
|
|
required: true
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SuccessIgnoredParameters"
|
|
/users/{email}:
|
|
get:
|
|
operationId: get-user-by-email
|
|
summary: Get a user by email
|
|
tags: ["users"]
|
|
description: |
|
|
Fetch details for a single user in the organization given a Zulip
|
|
API email address.
|
|
|
|
You can also fetch details on [all users in the organization](/api/get-users)
|
|
or [by user ID](/api/get-user).
|
|
|
|
Fetching by user ID is generally recommended when possible,
|
|
as a user might [change their email address](/help/change-your-email-address)
|
|
or change their [email address visibility](/help/configure-email-visibility),
|
|
either of which could change the value of their Zulip API email address.
|
|
|
|
**Changes**: New in Zulip Server 4.0 (feature level 39).
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: include
|
|
parameters:
|
|
enum:
|
|
- ""
|
|
- type: exclude
|
|
parameters:
|
|
enum:
|
|
- ""
|
|
description: |
|
|
You may pass the `client_gravatar` or `include_custom_profile_fields` query parameter as follows:
|
|
parameters:
|
|
- name: email
|
|
in: path
|
|
description: |
|
|
The Zulip API email address of the user whose details you want to fetch.
|
|
schema:
|
|
type: string
|
|
example: iago@zulip.com
|
|
required: true
|
|
- $ref: "#/components/parameters/ClientGravatar"
|
|
- $ref: "#/components/parameters/IncludeCustomProfileFields"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
user:
|
|
$ref: "#/components/schemas/User"
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"result": "success",
|
|
"user":
|
|
{
|
|
"date_joined": "2019-10-20T07:50:53.729659+00:00",
|
|
"full_name": "King Hamlet",
|
|
"is_guest": false,
|
|
"profile_data":
|
|
{
|
|
"4": {"value": "0"},
|
|
"2":
|
|
{
|
|
"value": "I am:\n* The prince of Denmark\n* Nephew to the usurping Claudius",
|
|
"rendered_value": "<p>I am:</p>\n<ul>\n<li>The prince of Denmark</li>\n<li>Nephew to the usurping Claudius</li>\n</ul>",
|
|
},
|
|
"5": {"value": "1900-01-01"},
|
|
"7": {"value": "[11]"},
|
|
"6": {"value": "https://blog.zulig.org"},
|
|
"1":
|
|
{
|
|
"value": "+0-11-23-456-7890",
|
|
"rendered_value": "<p>+0-11-23-456-7890</p>",
|
|
},
|
|
"8": {"value": "zulipbot"},
|
|
"3":
|
|
{
|
|
"rendered_value": "<p>Dark chocolate</p>",
|
|
"value": "Dark chocolate",
|
|
},
|
|
},
|
|
"user_id": 10,
|
|
"is_bot": false,
|
|
"bot_type": null,
|
|
"timezone": "",
|
|
"is_admin": false,
|
|
"is_owner": false,
|
|
"is_billing_admin": false,
|
|
"role": 400,
|
|
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
|
|
"is_active": true,
|
|
"email": "hamlet@zulip.com",
|
|
"delivery_email": null,
|
|
},
|
|
}
|
|
/users/{user_id}:
|
|
get:
|
|
operationId: get-user
|
|
summary: Get a user
|
|
tags: ["users"]
|
|
description: |
|
|
Fetch details for a single user in the organization.
|
|
|
|
You can also fetch details on [all users in the organization](/api/get-users)
|
|
or [by a user's Zulip API email](/api/get-user-by-email).
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 1).
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: include
|
|
parameters:
|
|
enum:
|
|
- ""
|
|
- type: exclude
|
|
parameters:
|
|
enum:
|
|
- ""
|
|
description: |
|
|
You may pass the `client_gravatar` or `include_custom_profile_fields` query parameter as follows:
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserId"
|
|
- $ref: "#/components/parameters/ClientGravatar"
|
|
- $ref: "#/components/parameters/IncludeCustomProfileFields"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
user:
|
|
$ref: "#/components/schemas/User"
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"result": "success",
|
|
"user":
|
|
{
|
|
"date_joined": "2019-10-20T07:50:53.729659+00:00",
|
|
"full_name": "King Hamlet",
|
|
"is_guest": false,
|
|
"profile_data":
|
|
{
|
|
"4": {"value": "0"},
|
|
"2":
|
|
{
|
|
"value": "I am:\n* The prince of Denmark\n* Nephew to the usurping Claudius",
|
|
"rendered_value": "<p>I am:</p>\n<ul>\n<li>The prince of Denmark</li>\n<li>Nephew to the usurping Claudius</li>\n</ul>",
|
|
},
|
|
"5": {"value": "1900-01-01"},
|
|
"7": {"value": "[11]"},
|
|
"6": {"value": "https://blog.zulig.org"},
|
|
"1":
|
|
{
|
|
"value": "+0-11-23-456-7890",
|
|
"rendered_value": "<p>+0-11-23-456-7890</p>",
|
|
},
|
|
"8": {"value": "zulipbot"},
|
|
"3":
|
|
{
|
|
"rendered_value": "<p>Dark chocolate</p>",
|
|
"value": "Dark chocolate",
|
|
},
|
|
},
|
|
"user_id": 10,
|
|
"is_bot": false,
|
|
"bot_type": null,
|
|
"timezone": "",
|
|
"is_admin": false,
|
|
"is_owner": false,
|
|
"is_billing_admin": false,
|
|
"role": 400,
|
|
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
|
|
"is_active": true,
|
|
"email": "hamlet@zulip.com",
|
|
"delivery_email": null,
|
|
},
|
|
}
|
|
patch:
|
|
operationId: update-user
|
|
summary: Update a user
|
|
tags: ["users"]
|
|
x-requires-administrator: true
|
|
description: |
|
|
Administrative endpoint to update the details of another user in the organization.
|
|
|
|
Supports everything an administrator can do to edit details of another
|
|
user's account, including editing full name,
|
|
[role](/help/roles-and-permissions), and [custom profile
|
|
fields](/help/custom-profile-fields).
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserId"
|
|
- name: full_name
|
|
in: query
|
|
description: |
|
|
The user's full name.
|
|
|
|
**Changes**: Removed unnecessary JSON-encoding of this parameter in
|
|
Zulip 5.0 (feature level 106).
|
|
schema:
|
|
type: string
|
|
example: NewName
|
|
required: false
|
|
- name: role
|
|
in: query
|
|
description: |
|
|
New [role](/api/roles-and-permissions) for the user. Roles are encoded as:
|
|
|
|
- Organization owner: 100
|
|
- Organization administrator: 200
|
|
- Organization moderator: 300
|
|
- Member: 400
|
|
- Guest: 600
|
|
|
|
Only organization owners can add or remove the owner role.
|
|
|
|
The owner role cannot be removed from the only organization owner.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 8), replacing the previous
|
|
pair of `is_admin` and `is_guest` boolean parameters. Organization moderator
|
|
role added in Zulip 4.0 (feature level 60).
|
|
schema:
|
|
type: integer
|
|
example: 400
|
|
required: false
|
|
- name: profile_data
|
|
in: query
|
|
description: |
|
|
A dictionary containing the to be updated custom profile field data for the user.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
example:
|
|
[{"id": 4, "value": "0"}, {"id": 5, "value": "1909-04-05"}]
|
|
required: false
|
|
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Guests cannot be organization administrators",
|
|
"code": "BAD_REQUEST",
|
|
}
|
|
description: |
|
|
A typical unsuccessful JSON response:
|
|
|
|
delete:
|
|
operationId: deactivate-user
|
|
summary: Deactivate a user
|
|
tags: ["users"]
|
|
x-requires-administrator: true
|
|
description: |
|
|
[Deactivates a
|
|
user](https://zulip.com/help/deactivate-or-reactivate-a-user)
|
|
given their user ID.
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserId"
|
|
- name: deactivation_notification_comment
|
|
in: query
|
|
description: |
|
|
If not `null`, requests that the deactivated user receive
|
|
a notification email about their account deactivation.
|
|
|
|
If not `""`, encodes custom text written by the administrator
|
|
to be included in the notification email.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 135).
|
|
schema:
|
|
type: string
|
|
example: |
|
|
Farewell!
|
|
required: false
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonError"
|
|
- example:
|
|
{
|
|
"msg": "Cannot deactivate the only organization owner",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON error response when attempting to deactivate the only
|
|
organization owner in an organization:
|
|
/realm/linkifiers:
|
|
get:
|
|
operationId: get-linkifiers
|
|
summary: Get linkifiers
|
|
tags: ["server_and_organizations"]
|
|
description: |
|
|
List all of an organization's configured
|
|
[linkifiers](/help/add-a-custom-linkifier), regular
|
|
expression patterns that are automatically linkified when they appear
|
|
in messages and topics.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 54). On older versions,
|
|
a similar `GET /realm/filters` endpoint was available with each entry in
|
|
a `[pattern, url_format, id]` tuple format.
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
linkifiers:
|
|
type: array
|
|
description: |
|
|
An array of objects, where each object describes a linkifier.
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
pattern:
|
|
type: string
|
|
description: |
|
|
The string regex pattern which represents the pattern that
|
|
should be linkified by this linkifier.
|
|
url_template:
|
|
type: string
|
|
description: |
|
|
The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html) compliant
|
|
URL template to be used for linkifying matches.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 176). This replaced `url_format`,
|
|
which contained a URL format string.
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the linkifier.
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"linkifiers":
|
|
[
|
|
{
|
|
"pattern": "#(?P<id>[0-9]+)",
|
|
"url_template": "https://github.com/zulip/zulip/issues/{id}",
|
|
"id": 1,
|
|
},
|
|
],
|
|
"result": "success",
|
|
}
|
|
/realm/filters:
|
|
post:
|
|
operationId: add-linkifier
|
|
summary: Add a linkifier
|
|
tags: ["server_and_organizations"]
|
|
description: |
|
|
Configure [linkifiers](/help/add-a-custom-linkifier),
|
|
regular expression patterns that are automatically linkified when they
|
|
appear in messages and topics.
|
|
parameters:
|
|
- $ref: "#/components/parameters/LinkifierPattern"
|
|
- $ref: "#/components/parameters/LinkifierURLTemplate"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The numeric ID assigned to this filter.
|
|
example: {"id": 42, "result": "success", "msg": ""}
|
|
/realm/filters/{filter_id}:
|
|
delete:
|
|
operationId: remove-linkifier
|
|
summary: Remove a linkifier
|
|
tags: ["server_and_organizations"]
|
|
description: |
|
|
Remove [linkifiers](/help/add-a-custom-linkifier), regular
|
|
expression patterns that are automatically linkified when they appear
|
|
in messages and topics.
|
|
parameters:
|
|
- name: filter_id
|
|
in: path
|
|
description: |
|
|
The ID of the linkifier that you want to remove.
|
|
schema:
|
|
type: integer
|
|
example: 43
|
|
required: true
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
patch:
|
|
operationId: update-linkifier
|
|
summary: Update a linkifier
|
|
tags: ["server_and_organizations"]
|
|
description: |
|
|
Update a [linkifier](/help/add-a-custom-linkifier), regular
|
|
expression patterns that are automatically linkified when they appear
|
|
in messages and topics.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 57).
|
|
parameters:
|
|
- name: filter_id
|
|
in: path
|
|
description: |
|
|
The ID of the linkifier that you want to update.
|
|
schema:
|
|
type: integer
|
|
example: 2
|
|
required: true
|
|
- $ref: "#/components/parameters/LinkifierPattern"
|
|
- $ref: "#/components/parameters/LinkifierURLTemplate"
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
/realm/playgrounds:
|
|
post:
|
|
operationId: add-code-playground
|
|
summary: Add a code playground
|
|
tags: ["server_and_organizations"]
|
|
description: |
|
|
Configure [code playgrounds](/help/code-blocks#code-playgrounds) for the organization.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 49). A parameter encoding bug was
|
|
fixed in Zulip 4.0 (feature level 57).
|
|
parameters:
|
|
- name: name
|
|
in: query
|
|
description: |
|
|
The user-visible display name of the playground which can be
|
|
used to pick the target playground, especially when multiple
|
|
playground options exist for that programming language.
|
|
schema:
|
|
type: string
|
|
example: Python playground
|
|
required: true
|
|
- name: pygments_language
|
|
in: query
|
|
description: |
|
|
The name of the Pygments language lexer for that
|
|
programming language.
|
|
schema:
|
|
type: string
|
|
example: Python
|
|
required: true
|
|
- name: url_prefix
|
|
in: query
|
|
description: |
|
|
The url prefix for the playground.
|
|
schema:
|
|
type: string
|
|
example: https://python.example.com
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The numeric ID assigned to this playground.
|
|
example: {"id": 1, "result": "success", "msg": ""}
|
|
/realm/playgrounds/{playground_id}:
|
|
delete:
|
|
operationId: remove-code-playground
|
|
summary: Remove a code playground
|
|
tags: ["server_and_organizations"]
|
|
description: |
|
|
Remove a [code playground](/help/code-blocks#code-playgrounds) previously
|
|
configured for an organization.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 49).
|
|
parameters:
|
|
- name: playground_id
|
|
in: path
|
|
description: |
|
|
The ID of the playground that you want to remove.
|
|
schema:
|
|
type: integer
|
|
example: 1
|
|
required: true
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
/register:
|
|
post:
|
|
operationId: register-queue
|
|
summary: Register an event queue
|
|
tags: ["real_time_events"]
|
|
description: |
|
|
This powerful endpoint can be used to register a Zulip "event queue"
|
|
(subscribed to certain types of "events", or updates to the messages
|
|
and other Zulip data the current user has access to), as well as to
|
|
fetch the current state of that data.
|
|
|
|
(`register` also powers the `call_on_each_event` Python API, and is
|
|
intended primarily for complex applications for which the more convenient
|
|
`call_on_each_event` API is insufficient).
|
|
|
|
This endpoint returns a `queue_id` and a `last_event_id`; these can be
|
|
used in subsequent calls to the
|
|
["events" endpoint](/api/get-events) to request events from
|
|
the Zulip server using long-polling.
|
|
|
|
The server will queue events for up to 10 minutes of inactivity.
|
|
After 10 minutes, your event queue will be garbage-collected. The
|
|
server will send `heartbeat` events every minute, which makes it easy
|
|
to implement a robust client that does not miss events unless the
|
|
client loses network connectivity with the Zulip server for 10 minutes
|
|
or longer.
|
|
|
|
Once the server garbage-collects your event queue, the server will
|
|
[return an error](/api/get-events#bad_event_queue_id-errors)
|
|
with a code of `BAD_EVENT_QUEUE_ID` if you try to fetch events from
|
|
the event queue. Your software will need to handle that error
|
|
condition by re-initializing itself (e.g. this is what triggers your
|
|
browser reloading the Zulip web app when your laptop comes back online
|
|
after being offline for more than 10 minutes).
|
|
|
|
When prototyping with this API, we recommend first calling `register`
|
|
with no `event_types` parameter to see all the available data from all
|
|
supported event types. Before using your client in production, you
|
|
should set appropriate `event_types` and `fetch_event_types` filters
|
|
so that your client only requests the data it needs. A few minutes
|
|
doing this often saves 90% of the total bandwidth and other resources
|
|
consumed by a client using this API.
|
|
|
|
See the [events system developer documentation][events-system-docs]
|
|
if you need deeper details about how the Zulip event queue system
|
|
works, avoids clients needing to worry about large classes of
|
|
potentially messy races, etc.
|
|
|
|
**Changes**: Before Zulip 7.0 (feature level 183), the
|
|
`realm_community_topic_editing_limit_seconds` property
|
|
was returned by the response. It was removed because it
|
|
had not been in use since the realm setting
|
|
`move_messages_within_stream_limit_seconds` was introduced
|
|
in feature level 162.
|
|
|
|
In Zulip 7.0 (feature level 163), the realm setting
|
|
`email_address_visibility` was removed. It was replaced by a [user
|
|
setting](/api/update-settings#parameter-email_address_visibility) with
|
|
a [realm user default][user-defaults], with the encoding of different
|
|
values preserved. Clients can support all versions by supporting the
|
|
current API and treating every user as having the realm's
|
|
`email_address_visibility` value.
|
|
|
|
[user-defaults]: /api/update-realm-user-settings-defaults#parameter-email_address_visibility
|
|
[events-system-docs]: https://zulip.readthedocs.io/en/latest/subsystems/events-system.html
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: include
|
|
parameters:
|
|
enum:
|
|
- event_types
|
|
parameters:
|
|
- name: apply_markdown
|
|
in: query
|
|
description: |
|
|
Set to `true` if you would like the content to be rendered in HTML
|
|
format (otherwise the API will return the raw text that the user
|
|
entered)
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
- name: client_gravatar
|
|
in: query
|
|
description: |
|
|
Whether the client supports computing gravatars URLs. If
|
|
enabled, `avatar_url` will be included in the response only
|
|
if there is a Zulip avatar, and will be `null` for users who
|
|
are using gravatar as their avatar. This option
|
|
significantly reduces the compressed size of user data,
|
|
since gravatar URLs are long, random strings and thus do not
|
|
compress well. The `client_gravatar` field is set to `true` if
|
|
clients can compute their own gravatars.
|
|
|
|
The default value is `true` for authenticated requests and
|
|
`false` for [unauthenticated
|
|
requests](/help/public-access-option). Passing `true` in
|
|
an unauthenticated request is an error.
|
|
|
|
**Changes**: Before Zulip 6.0 (feature level 149), this
|
|
parameter was silently ignored and processed as though it
|
|
were `false` in unauthenticated requests.
|
|
schema:
|
|
type: boolean
|
|
example: false
|
|
- name: include_subscribers
|
|
in: query
|
|
description: |
|
|
Whether each returned stream object should include a `subscribers`
|
|
field containing a list of the user IDs of its subscribers.
|
|
|
|
(This may be significantly slower in organizations with
|
|
thousands of users subscribed to many streams.)
|
|
|
|
Passing `true` in an [unauthenticated
|
|
request](/help/public-access-option) is an error.
|
|
|
|
**Changes**: Before Zulip 6.0 (feature level 149), this
|
|
parameter was silently ignored and processed as though it
|
|
were `false` in unauthenticated requests.
|
|
|
|
New in Zulip 2.1.0.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
- name: slim_presence
|
|
in: query
|
|
description: |
|
|
Setting this to `true` will make presence dictionaries be keyed by
|
|
user ID instead of Zulip API email.
|
|
|
|
**Changes**: New in Zulip 3.0 (Unstable with no feature level yet).
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
- $ref: "#/components/parameters/Event_types"
|
|
- $ref: "#/components/parameters/AllPublicStreams"
|
|
- name: client_capabilities
|
|
in: query
|
|
description: |
|
|
Dictionary containing details on features the client supports that are
|
|
relevant to the format of responses sent by the server.
|
|
|
|
- `notification_settings_null`: Boolean for whether the
|
|
client can handle the current API with `null` values for
|
|
stream-level notification settings (which means the stream
|
|
is not customized and should inherit the user's global
|
|
notification settings for stream messages).
|
|
<br />
|
|
**Changes**: New in Zulip 2.1.0. In earlier Zulip releases,
|
|
stream-level notification settings were simple booleans.
|
|
|
|
- `bulk_message_deletion`: Boolean for whether the client's
|
|
handler for the `delete_message` event type has been
|
|
updated to process the new bulk format (with a
|
|
`message_ids`, rather than a singleton `message_id`).
|
|
Otherwise, the server will send `delete_message` events
|
|
in a loop.
|
|
<br />
|
|
**Changes**: New in Zulip 3.0 (feature level 13). This
|
|
capability is for backwards-compatibility; it will be
|
|
required in a future server release.
|
|
|
|
- `user_avatar_url_field_optional`: Boolean for whether the
|
|
client required avatar URLs for all users, or supports
|
|
using `GET /avatar/{user_id}` to access user avatars. If the
|
|
client has this capability, the server may skip sending a
|
|
`avatar_url` field in the `realm_user` at its sole discretion
|
|
to optimize network performance. This is an important optimization
|
|
in organizations with 10,000s of users.
|
|
<br />
|
|
**Changes**: New in Zulip 3.0 (feature level 18).
|
|
|
|
- `stream_typing_notifications`: Boolean for whether the client
|
|
supports stream typing notifications.
|
|
<br />
|
|
**Changes**: New in Zulip 4.0 (feature level 58). This capability is
|
|
for backwards-compatibility; it will be required in a
|
|
future server release.
|
|
|
|
- `user_settings_object`: Boolean for whether the client supports the modern
|
|
`user_settings` event type. If false, the server will additionally send the
|
|
legacy `update_global_notifications` and `update_display_settings` event
|
|
types.
|
|
<br />
|
|
**Changes**: New in Zulip 5.0 (feature level 89). This capability is for
|
|
backwards-compatibility; it will be removed in a future server release.
|
|
Because the feature level 89 API changes were merged together, clients can
|
|
safely make a request with this client capability and also request all three
|
|
event types (`user_settings`, `update_display_settings`,
|
|
`update_global_notifications`), and get exactly one copy of settings data on
|
|
any server version. Clients can then use the `zulip_feature_level` in the
|
|
`/register` response or the presence/absence of a `user_settings` key to
|
|
determine where to look for the data.
|
|
|
|
- `linkifier_url_template`: Boolean for whether the client accepts
|
|
[linkifiers][help-linkifiers] that use [RFC 6570][rfc6570] compliant
|
|
URL templates for linkifying matches. If false or unset, then the
|
|
`realm_linkifiers` array in the `/register` response will be empty
|
|
if present, and no `realm_linkifiers` [events][events-linkifiers]
|
|
will be sent to the client.
|
|
<br />
|
|
**Changes**: New in Zulip 7.0 (feature level 176). This capability
|
|
is for backwards-compatibility.
|
|
|
|
[help-linkifiers]: /help/add-a-custom-linkifier
|
|
[rfc6570]: https://www.rfc-editor.org/rfc/rfc6570.html
|
|
[events-linkifiers]: /api/get-events#realm_linkifiers
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
example: {"notification_settings_null": true}
|
|
- name: fetch_event_types
|
|
in: query
|
|
description: |
|
|
Same as the `event_types` parameter except that the values in
|
|
`fetch_event_types` are used to fetch initial data. If
|
|
`fetch_event_types` is not provided, `event_types` is used and if
|
|
`event_types` is not provided, this parameter defaults to `null`.
|
|
|
|
Event types not supported by the server are ignored, in order to simplify
|
|
the implementation of client apps that support multiple server versions.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
example: ["message"]
|
|
- $ref: "#/components/parameters/Narrow"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
queue_id:
|
|
type: string
|
|
nullable: true
|
|
description: |
|
|
The ID of the queue that has been allocated for your client.
|
|
|
|
Will be `null` only for unauthenticated access in realms that have
|
|
enabled the [public access option](/help/public-access-option).
|
|
last_event_id:
|
|
type: integer
|
|
description: |
|
|
The initial value of `last_event_id` to pass to `GET /api/v1/events`.
|
|
zulip_feature_level:
|
|
type: integer
|
|
description: |
|
|
The server's current [Zulip feature level](/api/changelog).
|
|
|
|
**Changes**: As of Zulip 3.0 (feature level 3), this is always present
|
|
in the endpoint's response. Previously, it was only present if
|
|
`event_types` included `zulip_version`.
|
|
|
|
New in Zulip 3.0 (feature level 1).
|
|
zulip_version:
|
|
type: string
|
|
description: |
|
|
The server's version number. This is often a release version number,
|
|
like `2.1.7`. But for a server running a [version from Git][git-release],
|
|
it will be a Git reference to the commit, like `5.0-dev-1650-gc3fd37755f`.
|
|
|
|
**Changes**: As of Zulip 3.0 (feature level 3), this is always present
|
|
in the endpoint's response. Previously, it was only present if
|
|
`event_types` included `zulip_version`.
|
|
|
|
[git-release]: https://zulip.readthedocs.io/en/latest/overview/release-lifecycle.html#git-versions
|
|
zulip_merge_base:
|
|
type: string
|
|
description: |
|
|
The `git merge-base` between `zulip_version` and official branches
|
|
in the public
|
|
[Zulip server and web app repository](https://github.com/zulip/zulip),
|
|
in the same format as `zulip_version`. This will equal
|
|
`zulip_version` if the server is not running a fork of the Zulip server.
|
|
|
|
This will be `""` if the server does not know its `merge-base`.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 88).
|
|
alert_words:
|
|
type: array
|
|
description: |
|
|
Present if `alert_words` is present in `fetch_event_types`.
|
|
|
|
An array of strings, each an [alert word](/help/dm-mention-alert-notifications#alert-words)
|
|
that the current user has configured.
|
|
items:
|
|
type: string
|
|
custom_profile_fields:
|
|
type: array
|
|
description: |
|
|
Present if `custom_profile_fields` is present in `fetch_event_types`.
|
|
|
|
An array of dictionaries where each dictionary contains the
|
|
details of a single custom profile field that is available to users
|
|
in this Zulip organization. This must be combined with the custom profile
|
|
field values on individual user objects to display users' profiles.
|
|
items:
|
|
$ref: "#/components/schemas/CustomProfileField"
|
|
custom_profile_field_types:
|
|
type: object
|
|
description: |
|
|
Present if `custom_profile_fields` is present in `fetch_event_types`.
|
|
|
|
An array of objects; each object describes a type of custom profile field
|
|
that could be configured on this Zulip server. Each custom profile type
|
|
has an ID and the `type` property of a custom profile field is equal
|
|
to one of these IDs.
|
|
|
|
This attribute is only useful for clients containing UI for changing
|
|
the set of configured custom profile fields in a Zulip organization.
|
|
additionalProperties:
|
|
type: object
|
|
description: |
|
|
`{FIELD_TYPE}`: Dictionary which contains the details
|
|
of the field type with the field type as the name of the
|
|
property itself. The current supported field types are as follows:
|
|
|
|
- `SHORT_TEXT`
|
|
- `LONG_TEXT`
|
|
- `DATE` for date-based fields.
|
|
- `CHOICE` for a list of options.
|
|
- `URL` for links.
|
|
- `EXTERNAL_ACCOUNT` for external accounts.
|
|
- `USER` for selecting a user for the field.
|
|
- `PRONOUNS` for a short text field with convenient typeahead for one's preferred pronouns.
|
|
|
|
**Changes**: `PRONOUNS` type added in Zulip 6.0 (feature level 151).
|
|
additionalProperties: false
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the custom profile field type.
|
|
name:
|
|
type: string
|
|
description: |
|
|
The name of the custom profile field type.
|
|
demo_organization_scheduled_deletion_date:
|
|
type: integer
|
|
description: |
|
|
Present if the realm is a demo organization.
|
|
|
|
The UNIX timestamp (UTC) when the demo organization will be
|
|
automatically deleted. Clients should use this to display a
|
|
prominent warning to the user that the organization will be
|
|
deleted at the indicated time.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 94).
|
|
drafts:
|
|
type: array
|
|
description: |
|
|
An array containing draft objects for the user. These drafts are being
|
|
stored on the backend for the purpose of syncing across devices. This
|
|
array will be empty if `enable_drafts_synchronization` is set to `false`.
|
|
items:
|
|
$ref: "#/components/schemas/Draft"
|
|
hotspots:
|
|
type: array
|
|
description: |
|
|
Present if `hotspots` is present in `fetch_event_types`.
|
|
|
|
An array of dictionaries, where each dictionary contains details about
|
|
a single onboarding hotspot that should be shown to new users.
|
|
|
|
We expect that only official Zulip clients will interact with these data.
|
|
items:
|
|
$ref: "#/components/schemas/Hotspot"
|
|
max_message_id:
|
|
type: integer
|
|
deprecated: true
|
|
description: |
|
|
Present if `message` is present in `fetch_event_types`.
|
|
|
|
The highest message ID among all messages the user has received as of the
|
|
moment of this request.
|
|
|
|
**Deprecated**: This field may be removed in future versions as it no
|
|
longer has a clear purpose. Clients wishing to fetch the latest messages
|
|
should pass `"anchor": "latest"` to `GET /messages`.
|
|
max_stream_name_length:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The maximum allowed length for a stream name, in Unicode code
|
|
points. Clients should use this property rather than hardcoding
|
|
field sizes.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 53). Previously,
|
|
this required `stream` in `fetch_event_types`, was called
|
|
`stream_name_max_length`, and always had a value of 60.
|
|
max_stream_description_length:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The maximum allowed length for a stream description, in Unicode
|
|
code points. Clients should use this property rather than hardcoding
|
|
field sizes.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 53). Previously,
|
|
this required `stream` in `fetch_event_types`, was called
|
|
`stream_description_max_length`, and always had a value of 1024.
|
|
max_topic_length:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The maximum allowed length for a topic, in Unicode code points.
|
|
Clients should use this property rather than hardcoding field
|
|
sizes.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 53). Previously,
|
|
this property always had a value of 60.
|
|
max_message_length:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The maximum allowed length for a message, in Unicode code points.
|
|
Clients should use this property rather than hardcoding field
|
|
sizes.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 53). Previously,
|
|
this property always had a value of 10000.
|
|
server_presence_ping_interval_seconds:
|
|
type: integer
|
|
description: |
|
|
For clients implementing the [presence](/api/get-presence) system,
|
|
the time interval the client should use for sending presence requests
|
|
to the server (and thus receive presence updates from the server).
|
|
|
|
It is important for presence implementations to use both this and
|
|
`server_presence_offline_threshold_seconds` correctly, so that a Zulip
|
|
server can change these values to manage the trade-off between load and
|
|
freshness of presence data.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 164). Clients should use 60
|
|
for older Zulip servers, since that's the value that was hardcoded in the
|
|
the Zulip mobile apps prior to this parameter being introduced.
|
|
server_presence_offline_threshold_seconds:
|
|
type: integer
|
|
description: |
|
|
How old a presence timestamp for a given user can be before the user
|
|
should be displayed as offline by clients displaying Zulip presence
|
|
data. See the related `server_presence_ping_interval_seconds` for details.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 164). Clients should use 140
|
|
for older Zulip servers, since that's the value that was hardcoded in the
|
|
Zulip client apps prior to this parameter being introduced.
|
|
scheduled_messages:
|
|
type: array
|
|
description: |
|
|
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:
|
|
type: array
|
|
deprecated: true
|
|
description: |
|
|
Present if `muted_topics` is present in `fetch_event_types`.
|
|
|
|
Array of tuples, where each tuple describes a muted topic.
|
|
The first element of the tuple is the stream name in which the topic
|
|
has to be muted, the second element is the topic name to be muted
|
|
and the third element is an integer UNIX timestamp representing
|
|
when the topic was muted.
|
|
|
|
**Changes**: Deprecated in Zulip 6.0 (feature level 134). Starting
|
|
with this version, `muted_topics` will only be present in the
|
|
response if the `user_topic` object, which generalizes and replaces
|
|
this field, is not explicitly requested via `fetch_event_types`.
|
|
|
|
**Changes**: Before Zulip 3.0 (feature level 1), the `muted_topics`
|
|
array objects were 2-item tuples and did not include the timestamp
|
|
information for when the topic was muted.
|
|
items:
|
|
type: array
|
|
items:
|
|
oneOf:
|
|
- type: string
|
|
- type: integer
|
|
muted_users:
|
|
type: array
|
|
description: |
|
|
Present if `muted_users` is present in `fetch_event_types`.
|
|
|
|
A list of dictionaries where each dictionary describes
|
|
a [muted user](/api/mute-user).
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 48).
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Object containing the user ID and timestamp of a muted user.
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the muted user.
|
|
timestamp:
|
|
type: integer
|
|
description: |
|
|
An integer UNIX timestamp representing when the user was muted.
|
|
presences:
|
|
type: object
|
|
description: |
|
|
Present if `presence` is present in `fetch_event_types`.
|
|
|
|
A dictionary where each entry describes the presence details of a
|
|
user in the Zulip organization.
|
|
|
|
Users who have been offline for multiple weeks may not appear in this object.
|
|
additionalProperties:
|
|
type: object
|
|
description: |
|
|
`{user_id}` or `{user_email}`: Object containing the details of a user's
|
|
presence . Depending on the value of `slim_presence`, the object's key is
|
|
either the user's ID or the user's Zulip API email.
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/Presence"
|
|
server_timestamp:
|
|
type: number
|
|
description: |
|
|
Present if `presence` is present in `fetch_event_types`.
|
|
|
|
The time when the server fetched the
|
|
`presences` data included in the response.
|
|
Matches the similar field in presence
|
|
responses.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 70).
|
|
realm_domains:
|
|
type: array
|
|
description: |
|
|
Present if `realm_domains` is present in `fetch_event_types`.
|
|
|
|
An array of dictionaries where each dictionary describes a domain within
|
|
which users can join the organization without and invitation.
|
|
items:
|
|
$ref: "#/components/schemas/RealmDomain"
|
|
realm_emoji:
|
|
description: |
|
|
Present if `realm_emoji` is present in `fetch_event_types`.
|
|
|
|
An array of dictionaries where each dictionary describes a custom
|
|
emoji that has been uploaded in this Zulip organization.
|
|
oneOf:
|
|
- type: object
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/RealmEmoji"
|
|
- type: array
|
|
items:
|
|
type: integer
|
|
realm_linkifiers:
|
|
type: array
|
|
description: |
|
|
Present if `realm_linkifiers` is present in `fetch_event_types`.
|
|
|
|
Array of objects where each object describes a single
|
|
[linkifier](/help/add-a-custom-linkifier).
|
|
|
|
Clients will receive an empty array unless the event queue is
|
|
registered with the client capability `{"linkifier_url_template": true}`.
|
|
See [`client_capabilities`](/api/register-queue#parameter-client_capabilities)
|
|
parameter for how this can be specified.
|
|
|
|
**Changes**: Before Zulip 7.0 (feature level 176), the
|
|
`linkifier_url_template` client capability was not required. The
|
|
requirement was added because linkifiers were updated to contain
|
|
a URL template instead of a URL format string, which was a not
|
|
backwards-compatible change.
|
|
|
|
New in Zulip 4.0 (feature level 54). Clients can access this data for
|
|
servers on earlier feature levels via the legacy `realm_filters` property.
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
pattern:
|
|
type: string
|
|
description: |
|
|
The [Python regular expression](https://docs.python.org/3/howto/regex.html)
|
|
pattern which represents the pattern that should be linkified on matching.
|
|
url_template:
|
|
type: string
|
|
description: |
|
|
The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html) compliant URL
|
|
template with which the pattern matching string should be linkified.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 176). This replaced `url_format`,
|
|
which contained a URL format string.
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the linkifier.
|
|
realm_filters:
|
|
type: array
|
|
deprecated: true
|
|
items:
|
|
type: array
|
|
items:
|
|
oneOf:
|
|
- type: integer
|
|
- type: string
|
|
description: |
|
|
Legacy property for [linkifiers](/help/add-a-custom-linkifier).
|
|
Present if `realm_filters` is present in `fetch_event_types`.
|
|
|
|
When present, this is always an empty array.
|
|
|
|
**Changes**: Prior to Zulip 7.0 (feature level 176), this was
|
|
an array of tuples, where each tuple described a linkifier. The first
|
|
element of the tuple was a string regex pattern which represented the
|
|
pattern to be linkified on matching, for example `"#(?P<id>[123])"`.
|
|
The second element was a URL format string that the pattern should be
|
|
linkified with. A URL format string for the above example would be
|
|
`"https://realm.com/my_realm_filter/%(id)s"`. And the third element
|
|
was the ID of the realm filter.
|
|
|
|
**Deprecated** in Zulip 4.0 (feature level 54), replaced by the
|
|
`realm_linkifiers` key.
|
|
realm_playgrounds:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/RealmPlayground"
|
|
description: |
|
|
Present if `realm_playgrounds` is present in `fetch_event_types`.
|
|
|
|
An array of dictionaries where each dictionary describes a
|
|
[code playground](/help/code-blocks#code-playgrounds) configured for this Zulip organization.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 49).
|
|
realm_user_groups:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/UserGroup"
|
|
description: |
|
|
Present if `realm_user_groups` is present in `fetch_event_types`.
|
|
|
|
An array of dictionaries where each dictionary describes a
|
|
[user group](/help/user-groups) in the Zulip organization.
|
|
realm_bots:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Bot"
|
|
description: |
|
|
Present if `realm_bot` is present in `fetch_event_types`.
|
|
|
|
An array of dictionaries where each dictionary describes a bot that the
|
|
current user can administer. If the current user is an organization
|
|
administrator, this will include all bots in the organization. Otherwise,
|
|
it will only include bots owned by the user (either because the user created
|
|
the bot or an administrator transferred the bot's ownership to the user).
|
|
realm_embedded_bots:
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Object containing details of an embedded bot. Embedded bots are an experimental
|
|
feature not enabled in production yet.
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: |
|
|
The name of the bot.
|
|
config:
|
|
$ref: "#/components/schemas/Config"
|
|
description: |
|
|
Present if `realm_embedded_bots` is present in `fetch_event_types`.
|
|
|
|
An array of dictionaries where each dictionary describes an type of embedded
|
|
bot that is available to be configured on this Zulip server.
|
|
|
|
Clients only need these data if they contain UI for creating or administering bots.
|
|
realm_incoming_webhook_bots:
|
|
description: |
|
|
Present if `realm_incoming_webhook_bots` is present in `fetch_event_types`.
|
|
|
|
An array of dictionaries where each dictionary describes an type of incoming webhook
|
|
integration that is available to be configured on this Zulip server.
|
|
|
|
Clients only need these data if they contain UI for creating or administering bots.
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Object containing details of the bot.
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: |
|
|
The name of the bot.
|
|
config:
|
|
$ref: "#/components/schemas/Config"
|
|
recent_private_conversations:
|
|
description: |
|
|
Present if `recent_private_conversations` is present in `fetch_event_types`.
|
|
|
|
An array of dictionaries containing data on all private message and group private message
|
|
conversations that the user has received (or sent) messages in, organized by
|
|
conversation. This data set is designed to support UI elements such as the
|
|
"Private messages" widget in the web application showing recent private message
|
|
conversations that the user has participated in.
|
|
|
|
"Recent" is defined as the server's discretion; the original implementation
|
|
interpreted that as "the 1000 most recent private messages the user received".
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Object describing a single recent private conversation in the user's history.
|
|
properties:
|
|
max_message_id:
|
|
type: integer
|
|
description: |
|
|
The highest message ID of the conversation, intended to support sorting
|
|
the conversations by recency.
|
|
user_ids:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
The list of users other than the current user in the private message
|
|
conversation. This will be an empty list for private messages sent to
|
|
oneself.
|
|
subscriptions:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Subscriptions"
|
|
description: |
|
|
Present if `subscription` is present in `fetch_event_types`.
|
|
|
|
A array of dictionaries where each dictionary describes the properties
|
|
of a stream the user is subscribed to (as well as that user's
|
|
personal per-stream settings).
|
|
|
|
**Changes**: Removed `email_address` field from the dictionary
|
|
in Zulip 7.5 (feature level 186).
|
|
|
|
**Changes**: Removed `role` field from the dictionary
|
|
in Zulip 6.0 (feature level 133).
|
|
unsubscribed:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Subscriptions"
|
|
description: |
|
|
Present if `subscription` is present in `fetch_event_types`.
|
|
|
|
A array of dictionaries where each dictionary describes one of the
|
|
streams the user has unsubscribed from but was previously subscribed to
|
|
along with the subscription details.
|
|
|
|
Unlike `never_subscribed`, the user might have messages in their personal
|
|
message history that were sent to these streams.
|
|
|
|
**Changes**: Removed `email_address` field from the dictionary
|
|
in Zulip 7.5 (feature level 186).
|
|
|
|
**Changes**: Removed `role` field from the dictionary
|
|
in Zulip 6.0 (feature level 133).
|
|
never_subscribed:
|
|
type: array
|
|
items:
|
|
allOf:
|
|
- $ref: "#/components/schemas/BasicStreamBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
stream_id: {}
|
|
name: {}
|
|
description: {}
|
|
date_created: {}
|
|
invite_only: {}
|
|
rendered_description: {}
|
|
is_web_public: {}
|
|
stream_post_policy: {}
|
|
message_retention_days:
|
|
nullable: true
|
|
history_public_to_subscribers: {}
|
|
first_message_id:
|
|
nullable: true
|
|
is_announcement_only: {}
|
|
can_remove_subscribers_group_id: {}
|
|
stream_weekly_traffic:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
The average number of messages sent to the stream in recent weeks,
|
|
rounded to the nearest integer.
|
|
|
|
If `null`, the stream was recently created and there is
|
|
insufficient data to estimate the average traffic.
|
|
subscribers:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
A list of user IDs of users who are subscribed
|
|
to the stream. Included only if `include_subscribers` is `true`.
|
|
|
|
If a user is not allowed to know the subscribers for
|
|
a stream, we will send an empty array. API authors
|
|
should use other data to determine whether users like
|
|
guest users are forbidden to know the subscribers.
|
|
|
|
description: |
|
|
Present if `subscription` is present in `fetch_event_types`.
|
|
|
|
A array of dictionaries where each dictionary describes one of the
|
|
streams that is visible to the user and the user has never been subscribed
|
|
to.
|
|
|
|
Important for clients containing UI where one can browse streams to subscribe
|
|
to.
|
|
unread_msgs:
|
|
type: object
|
|
description: |
|
|
Present if `message` and `update_message_flags` are both present in
|
|
`event_types`.
|
|
|
|
A set of data structures describing the conversations containing
|
|
the 50000 most recent unread messages the user has received. This will usually
|
|
contain every unread message the user has received, but clients should support
|
|
users with even more unread messages (and not hardcode the number 50000).
|
|
additionalProperties: false
|
|
properties:
|
|
count:
|
|
type: integer
|
|
description: |
|
|
The total number of unread messages to display; this includes private
|
|
and group private messages, as well as all messages to unmuted topics
|
|
on unmuted streams.
|
|
pms:
|
|
type: array
|
|
description: |
|
|
An array of dictionaries where each entry contains details
|
|
of unread private messages with a specific user.
|
|
items:
|
|
type: object
|
|
description: |
|
|
Object containing the details of a unread private message with
|
|
a specific user. Note that in rare situations, it is possible
|
|
for a message that you sent to another user to be marked as
|
|
unread and thus appear here.
|
|
additionalProperties: false
|
|
properties:
|
|
other_user_id:
|
|
type: integer
|
|
description: |
|
|
The user ID of the other participant in this non-group private
|
|
message conversation. Will be your own user ID for messages
|
|
that you sent to only yourself.
|
|
sender_id:
|
|
deprecated: true
|
|
type: integer
|
|
description: |
|
|
Old name for `other_user_id`. Clients should access this
|
|
field in Zulip server versions that do not yet support
|
|
`other_user_id`.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 119).
|
|
We expect to provide a next version of the full `unread_msgs`
|
|
API before removing this legacy name.
|
|
message_ids:
|
|
type: array
|
|
description: |
|
|
The message IDs of the recent unread PM messages sent by the other user.
|
|
items:
|
|
type: integer
|
|
streams:
|
|
type: array
|
|
description: |
|
|
An array of dictionaries where each dictionary contains
|
|
details of all unread messages of a single subscribed stream,
|
|
including muted streams.
|
|
|
|
**Changes**: Prior to Zulip 5.0 (feature level 90), the
|
|
dictionaries included an additional `sender_ids` key listing
|
|
the set of IDs of users who had sent the unread messages.
|
|
items:
|
|
type: object
|
|
description: |
|
|
`{message_id}`: Object containing the details of a unread stream
|
|
message with the message_id as the key.
|
|
additionalProperties: false
|
|
properties:
|
|
topic:
|
|
type: string
|
|
description: |
|
|
The topic under which the message was sent.
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the stream to which the message was sent.
|
|
unread_message_ids:
|
|
type: array
|
|
description: |
|
|
The message IDs of the recent unread messages sent in this stream.
|
|
items:
|
|
type: integer
|
|
huddles:
|
|
type: array
|
|
description: |
|
|
An array of dictionaries where each dictionary contains
|
|
details of all unread group private messages of a single
|
|
group.
|
|
items:
|
|
type: object
|
|
description: |
|
|
Object containing the details of a unread group PM
|
|
messages of a single group.
|
|
additionalProperties: false
|
|
properties:
|
|
user_ids_string:
|
|
type: string
|
|
description: |
|
|
A string containing the IDs of all users in the group
|
|
private message conversation separated by commas
|
|
(,). Example: "1,2,3".
|
|
message_ids:
|
|
type: array
|
|
description: |
|
|
The message IDs of the recent unread messages which have been sent in
|
|
this group.
|
|
items:
|
|
type: integer
|
|
mentions:
|
|
type: array
|
|
description: |
|
|
Array containing the IDs of all messages in which the user has been mentioned.
|
|
For muted streams, wildcard mentions will not be considered for this array.
|
|
items:
|
|
type: integer
|
|
old_unreads_missing:
|
|
type: boolean
|
|
description: |
|
|
Whether this data set was truncated because the user has too many
|
|
unread messages. When truncation occurs, only the most recent
|
|
`MAX_UNREAD_MESSAGES` (currently 50000) messages will be considered
|
|
when forming this response. When `true`, we recommend that clients
|
|
display a warning, as they are likely to produce erroneous results
|
|
until reloaded with the user having fewer than `MAX_UNREAD_MESSAGES`
|
|
unread messages.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 44).
|
|
starred_messages:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
Present if `starred_messages` is present in `fetch_event_types`.
|
|
|
|
Array containing the IDs of all messages which have been
|
|
[starred](/help/star-a-message) by the user.
|
|
streams:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/BasicStream"
|
|
description: |
|
|
Present if `stream` is present in `fetch_event_types`.
|
|
|
|
Array of dictionaries where each dictionary contains details about
|
|
a single stream in the organization that is visible to the user.
|
|
|
|
For organization administrators, this will include all private streams
|
|
in the organization.
|
|
|
|
**Changes**: As of Zulip 7.5 (feature level 186), this will include all
|
|
web-public streams in the organization as well.
|
|
realm_default_streams:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/BasicStream"
|
|
description: |
|
|
Present if `default_streams` is present in `fetch_event_types`.
|
|
|
|
An array of dictionaries where each dictionary contains details
|
|
about a single [default stream](/help/set-default-streams-for-new-users)
|
|
for the Zulip organization.
|
|
realm_default_stream_groups:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/DefaultStreamGroup"
|
|
description: |
|
|
Present if `default_stream_groups` is present in `fetch_event_types`.
|
|
|
|
An array of dictionaries where each dictionary contains details
|
|
about a single default stream group configured for this
|
|
Zulip organization.
|
|
|
|
Default stream groups are an experimental feature.
|
|
stop_words:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: |
|
|
Present if `stop_words` is present in `fetch_event_types`.
|
|
|
|
An array containing the stop words used by the Zulip server's
|
|
full-text search implementation. Useful for showing helpful
|
|
error messages when a search returns limited results because
|
|
a stop word in the query was ignored.
|
|
user_status:
|
|
type: object
|
|
description: |
|
|
Present if `user_status` is present in `fetch_event_types`.
|
|
|
|
A dictionary which contains the [status](/help/status-and-availability)
|
|
of all users in the Zulip organization who have set a status.
|
|
|
|
**Changes**: The emoji parameters are new in Zulip 5.0 (feature level 86).
|
|
Previously, Zulip did not support emoji associated with statuses.
|
|
additionalProperties:
|
|
description: |
|
|
`{user_id}`: Object containing the status details of a user
|
|
with the key of the object being the ID of the user.
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
away:
|
|
type: boolean
|
|
deprecated: true
|
|
description: |
|
|
If present, the user has marked themself "away".
|
|
|
|
**Changes**: Deprecated in Zulip 6.0 (feature level 148);
|
|
starting with that feature level, `away` is a legacy way to
|
|
access the user's `presence_enabled` setting, with
|
|
`away = !presence_enabled`. To be removed in a future release.
|
|
status_text:
|
|
type: string
|
|
description: |
|
|
If present, the text content of the user's status message.
|
|
emoji_name:
|
|
type: string
|
|
description: |
|
|
If present, the name for the emoji to associate with the user's status.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 86).
|
|
emoji_code:
|
|
type: string
|
|
description: |
|
|
If present, a unique identifier, defining the specific emoji codepoint
|
|
requested, within the namespace of the `reaction_type`.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 86).
|
|
reaction_type:
|
|
type: string
|
|
description: |
|
|
If present, a string indicating the type of emoji. Each emoji
|
|
`reaction_type` has an independent namespace for values of `emoji_code`.
|
|
|
|
Must be one of the following values:
|
|
|
|
- `unicode_emoji` : In this namespace, `emoji_code` will be a
|
|
dash-separated hex encoding of the sequence of Unicode codepoints
|
|
that define this emoji in the Unicode specification.
|
|
|
|
- `realm_emoji` : In this namespace, `emoji_code` will be the ID of
|
|
the uploaded [custom emoji](/help/custom-emoji).
|
|
|
|
- `zulip_extra_emoji` : These are special emoji included with Zulip.
|
|
In this namespace, `emoji_code` will be the name of the emoji (e.g.
|
|
"zulip").
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 86).
|
|
user_settings:
|
|
type: object
|
|
description: |
|
|
Present if `user_settings` is present in `fetch_event_types`.
|
|
|
|
A dictionary containing the user's personal settings.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 89). Previously,
|
|
these settings appeared in the top-level object, where they are
|
|
available for clients without the `user_settings_object` client
|
|
capability for backwards-compatibility.
|
|
additionalProperties: false
|
|
properties:
|
|
twenty_four_hour_time:
|
|
type: boolean
|
|
description: |
|
|
Whether time should be [displayed in 24-hour notation](/help/change-the-time-format).
|
|
dense_mode:
|
|
type: boolean
|
|
description: |
|
|
This setting has no effect at present. It is reserved for use in controlling
|
|
the default font size in Zulip.
|
|
web_mark_read_on_scroll_policy:
|
|
type: integer
|
|
description: |
|
|
Whether or not to mark messages as read when the user scrolls through their
|
|
feed.
|
|
|
|
- 1 - Always
|
|
- 2 - Only in conversation views
|
|
- 3 - Never
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 175). Previously, there was no
|
|
way for the user to configure this behavior on the web, and the Zulip web and
|
|
desktop apps behaved like the "Always" setting when marking messages as read.
|
|
starred_message_counts:
|
|
type: boolean
|
|
description: |
|
|
Whether clients should display the [number of starred
|
|
messages](/help/star-a-message#display-the-number-of-starred-messages).
|
|
fluid_layout_width:
|
|
type: boolean
|
|
description: |
|
|
Whether to use the [maximum available screen width](/help/enable-full-width-display)
|
|
for the web app's center panel (message feed, recent conversations) on wide screens.
|
|
high_contrast_mode:
|
|
type: boolean
|
|
description: |
|
|
This setting is reserved for use to control variations in Zulip's design
|
|
to help visually impaired users.
|
|
color_scheme:
|
|
type: integer
|
|
description: |
|
|
Controls which [color theme](/help/dark-theme) to use.
|
|
|
|
- 1 - Automatic
|
|
- 2 - Dark theme
|
|
- 3 - Light theme
|
|
|
|
Automatic detection is implementing using the standard `prefers-color-scheme`
|
|
media query.
|
|
translate_emoticons:
|
|
type: boolean
|
|
description: |
|
|
Whether to [translate emoticons to emoji](/help/configure-emoticon-translations)
|
|
in messages the user sends.
|
|
display_emoji_reaction_users:
|
|
type: boolean
|
|
description: |
|
|
Whether to display the names of reacting users on a message.
|
|
|
|
When enabled, clients should display the names of reacting
|
|
users, rather than a count, for messages with few total
|
|
reactions. The ideal cutoff may depend on the space
|
|
available for displaying reactions; the official web
|
|
application displays names when 3 or fewer total reactions
|
|
are present with this setting enabled.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 125).
|
|
default_language:
|
|
type: string
|
|
description: |
|
|
What [default language](/help/change-your-language) to use for the account.
|
|
|
|
This controls both the Zulip UI as well as email notifications sent to the user.
|
|
|
|
The value needs to be a standard language code that the Zulip server has
|
|
translation data for; for example, `"en"` for English or `"de"` for German.
|
|
default_view:
|
|
type: string
|
|
description: |
|
|
The [default view](/help/configure-default-view) used when opening a new
|
|
Zulip web app window or hitting the `Esc` keyboard shortcut repeatedly.
|
|
|
|
- "recent_topics" - Recent conversations view
|
|
- "all_messages" - All messages view
|
|
escape_navigates_to_default_view:
|
|
type: boolean
|
|
description: |
|
|
Whether the escape key navigates to the
|
|
[configured default view](/help/configure-default-view).
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 107).
|
|
left_side_userlist:
|
|
type: boolean
|
|
description: |
|
|
Whether the users list on left sidebar in narrow windows.
|
|
|
|
This feature is not heavily used and is likely to be reworked.
|
|
emojiset:
|
|
type: string
|
|
description: |
|
|
The user's configured [emoji set](/help/emoji-and-emoticons#use-emoticons),
|
|
used to display emoji to the user everywhere they appear in the UI.
|
|
|
|
- "google" - Google modern
|
|
- "google-blob" - Google classic
|
|
- "twitter" - Twitter
|
|
- "text" - Plain text
|
|
demote_inactive_streams:
|
|
type: integer
|
|
description: |
|
|
Whether to [demote inactive streams](/help/manage-inactive-streams) in the left sidebar.
|
|
|
|
- 1 - Automatic
|
|
- 2 - Always
|
|
- 3 - Never
|
|
user_list_style:
|
|
type: integer
|
|
description: |
|
|
The style selected by the user for the right sidebar user list.
|
|
|
|
- 1 - Compact
|
|
- 2 - With status
|
|
- 3 - With avatar and status
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 141).
|
|
timezone:
|
|
type: string
|
|
description: |
|
|
The IANA identifier of the user's [configured time zone](/help/change-your-timezone).
|
|
enter_sends:
|
|
type: boolean
|
|
description: |
|
|
Whether the user setting for [sending on pressing Enter](/help/mastering-the-compose-box#toggle-between-ctrl-enter-and-enter-to-send-a-message)
|
|
in the compose box is enabled.
|
|
enable_drafts_synchronization:
|
|
type: boolean
|
|
description: |
|
|
A boolean parameter to control whether synchronizing drafts is enabled for
|
|
the user. When synchronization is disabled, all drafts stored in the server
|
|
will be automatically deleted from the server.
|
|
|
|
This does not do anything (like sending events) to delete local copies of
|
|
drafts stored in clients.
|
|
enable_stream_desktop_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable visual desktop notifications for stream messages.
|
|
enable_stream_email_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable email notifications for stream messages.
|
|
enable_stream_push_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable mobile notifications for stream messages.
|
|
enable_stream_audible_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable audible desktop notifications for stream messages.
|
|
notification_sound:
|
|
type: string
|
|
description: |
|
|
Notification sound name.
|
|
enable_desktop_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable visual desktop notifications for private messages and @-mentions.
|
|
enable_sounds:
|
|
type: boolean
|
|
description: |
|
|
Enable audible desktop notifications for private messages and
|
|
@-mentions.
|
|
email_notifications_batching_period_seconds:
|
|
type: integer
|
|
description: |
|
|
The duration (in seconds) for which the server should wait to batch
|
|
email notifications before sending them.
|
|
enable_offline_email_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable email notifications for private messages and @-mentions received
|
|
when the user is offline.
|
|
enable_offline_push_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable mobile notification for private messages and @-mentions received
|
|
when the user is offline.
|
|
enable_online_push_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable mobile notification for private messages and @-mentions received
|
|
when the user is online.
|
|
enable_digest_emails:
|
|
type: boolean
|
|
description: |
|
|
Enable digest emails when the user is away.
|
|
enable_marketing_emails:
|
|
type: boolean
|
|
description: |
|
|
Enable marketing emails. Has no function outside Zulip Cloud.
|
|
enable_login_emails:
|
|
type: boolean
|
|
description: |
|
|
Enable email notifications for new logins to account.
|
|
message_content_in_email_notifications:
|
|
type: boolean
|
|
description: |
|
|
Include the message's content in email notifications for new messages.
|
|
pm_content_in_desktop_notifications:
|
|
type: boolean
|
|
description: |
|
|
Include content of private messages in desktop notifications.
|
|
wildcard_mentions_notify:
|
|
type: boolean
|
|
description: |
|
|
Whether wildcard mentions (E.g. @**all**) should send notifications
|
|
like a personal mention.
|
|
desktop_icon_count_display:
|
|
type: integer
|
|
description: |
|
|
Unread count badge (appears in desktop sidebar and browser tab)
|
|
|
|
- 1 - All unreads
|
|
- 2 - Private messages and mentions
|
|
- 3 - None
|
|
realm_name_in_email_notifications_policy:
|
|
type: integer
|
|
description: |
|
|
Whether to [include organization name in subject of message notification
|
|
emails](/help/email-notifications#include-organization-name-in-subject-line).
|
|
|
|
- 1 - Automatic
|
|
- 2 - Always
|
|
- 3 - Never
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 168), replacing the
|
|
previous `realm_name_in_notifications` boolean;
|
|
`true` corresponded to `Always`, and `false` to `Never`.
|
|
presence_enabled:
|
|
type: boolean
|
|
description: |
|
|
Display the presence status to other users when online.
|
|
available_notification_sounds:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: |
|
|
Array containing the names of the notification sound options
|
|
supported by this Zulip server. Only relevant to support UI
|
|
for configuring notification sounds.
|
|
emojiset_choices:
|
|
description: |
|
|
Array of dictionaries where each dictionary describes an emoji set
|
|
supported by this version of the Zulip server.
|
|
|
|
Only relevant to clients with configuration UI for choosing an emoji set;
|
|
the currently selected emoji set is available in the `emojiset` key.
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
type: array
|
|
items:
|
|
type: object
|
|
description: |
|
|
Object describing a emoji set.
|
|
additionalProperties: false
|
|
properties:
|
|
key:
|
|
type: string
|
|
description: |
|
|
The key or the name of the emoji set which will be the value
|
|
of `emojiset` if this emoji set is chosen.
|
|
text:
|
|
type: string
|
|
description: |
|
|
The text describing the emoji set.
|
|
send_private_typing_notifications:
|
|
type: boolean
|
|
description: |
|
|
Whether the user has chosen to send [typing
|
|
notifications](/help/typing-notifications)
|
|
when composing private messages. The client should send typing
|
|
notifications for private messages if and only if this setting is enabled.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 105).
|
|
send_stream_typing_notifications:
|
|
type: boolean
|
|
description: |
|
|
Whether the user has chosen to send [typing
|
|
notifications](/help/typing-notifications)
|
|
when composing stream messages. The client should send typing
|
|
notifications for stream messages if and only if this setting is enabled.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 105).
|
|
send_read_receipts:
|
|
type: boolean
|
|
description: |
|
|
Whether other users are allowed to see whether you've
|
|
read messages.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 105).
|
|
email_address_visibility:
|
|
$ref: "#/components/schemas/EmailAddressVisibility"
|
|
user_topics:
|
|
type: array
|
|
description: |
|
|
Present if `user_topic` is present in `fetch_event_types`.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 134), deprecating and
|
|
replacing the previous `muted_topics` structure.
|
|
items:
|
|
type: object
|
|
description: |
|
|
Object describing the user's configuration for a given topic.
|
|
additionalProperties: false
|
|
properties:
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the stream to which the topic belongs.
|
|
topic_name:
|
|
type: string
|
|
description: |
|
|
The name of the topic.
|
|
last_updated:
|
|
type: integer
|
|
description: |
|
|
An integer UNIX timestamp representing when the user-topic
|
|
relationship was changed.
|
|
visibility_policy:
|
|
type: integer
|
|
description: |
|
|
An integer indicating the user's visibility configuration for
|
|
the topic.
|
|
|
|
- 1 = Muted. Used to record [muted topics](/help/mute-a-topic).
|
|
- 2 = Unmuted. Used to record [unmuted topics](/help/mute-a-topic).
|
|
|
|
**Changes**: In Zulip 7.0 (feature level 170), added unmuted as
|
|
a visibility policy option.
|
|
has_zoom_token:
|
|
type: boolean
|
|
description: |
|
|
Present if `video_calls` is present in `fetch_event_types`.
|
|
|
|
A boolean which signifies whether the user has a zoom token and has thus completed
|
|
OAuth flow for the [Zoom integration](/help/start-a-call). Clients need
|
|
to know whether initiating Zoom OAuth is required before creating a Zoom call.
|
|
giphy_api_key:
|
|
type: string
|
|
description: |
|
|
Present if `giphy` is present in `fetch_event_types`.
|
|
|
|
GIPHY's client-side SDKs needs this API key to use the GIPHY API.
|
|
GIPHY API keys are not secret (their main purpose appears to be
|
|
allowing GIPHY to block a problematic app). Please don't use our API
|
|
key for an app unrelated to Zulip.
|
|
|
|
Developers of clients should also read the
|
|
[GIPHY API TOS](https://support.giphy.com/hc/en-us/articles/360028134111-GIPHY-API-Terms-of-Service-)
|
|
before using this API key.
|
|
|
|
**Changes**: Added in Zulip 4.0 (feature level 47).
|
|
enable_desktop_notifications:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
enable_digest_emails:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
enable_login_emails:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
enable_marketing_emails:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
email_notifications_batching_period_seconds:
|
|
deprecated: true
|
|
type: integer
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
enable_offline_email_notifications:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
enable_offline_push_notifications:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
enable_online_push_notifications:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
enable_sounds:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
enable_stream_desktop_notifications:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
enable_stream_email_notifications:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
enable_stream_push_notifications:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
enable_stream_audible_notifications:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
wildcard_mentions_notify:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
message_content_in_email_notifications:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
notification_sound:
|
|
deprecated: true
|
|
type: string
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
pm_content_in_desktop_notifications:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
desktop_icon_count_display:
|
|
deprecated: true
|
|
type: integer
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
realm_name_in_email_notifications_policy:
|
|
deprecated: true
|
|
type: integer
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: In Zulip 7.0 (feature level 168), replaced previous
|
|
`realm_name_in_notifications` global notifications setting with
|
|
`realm_name_in_email_notifications_policy`.
|
|
|
|
**Deprecated** since Zulip 5.0 (feature level 89); both
|
|
`realm_name_in_notifications` and the newer
|
|
`realm_name_in_email_notifications_policy` are deprecated. Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
presence_enabled:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
available_notification_sounds:
|
|
deprecated: true
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in their
|
|
[`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
Array containing the names of the notification sound options supported by
|
|
this Zulip server. Only relevant to support UI for configuring notification
|
|
sounds.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
color_scheme:
|
|
deprecated: true
|
|
type: integer
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in
|
|
their [`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The color scheme selected by the user.
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
default_language:
|
|
deprecated: true
|
|
type: string
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in
|
|
their [`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The default language chosen by the user.
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
demote_inactive_streams:
|
|
deprecated: true
|
|
type: integer
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in
|
|
their [`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
Whether the user has chosen to demote inactive streams.
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
dense_mode:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in
|
|
their [`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
Whether the user has switched on dense mode. Dense mode is an experimental
|
|
feature that is only available in development environments.
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
emojiset:
|
|
deprecated: true
|
|
type: string
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in
|
|
their [`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The name of the emoji set that the user has chosen.
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
enable_drafts_synchronization:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in
|
|
their [`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
Whether drafts synchronization is enabled for the user. If disabled,
|
|
clients will receive an error when trying to use the `drafts` endpoints.
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
New in Zulip 5.0 (feature level 87).
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
fluid_layout_width:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in
|
|
their [`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
Whether the user has chosen for the layout width to be fluid.
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
default_view:
|
|
deprecated: true
|
|
type: string
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in
|
|
their [`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The [default view](/help/configure-default-view) in Zulip, represented
|
|
as the URL suffix after `#` to be rendered when Zulip loads.
|
|
|
|
Currently supported values are `all_messages` and `recent_topics`.
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
high_contrast_mode:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in
|
|
their [`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
Whether has switched on high contrast mode.
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
left_side_userlist:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in
|
|
their [`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
Whether the user has chosen for the userlist to be displayed
|
|
on the left side of the screen (for desktop app and web app) in narrow
|
|
windows.
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
starred_message_counts:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in
|
|
their [`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
Whether the user has chosen the number of starred messages to
|
|
be displayed similar to unread counts.
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
timezone:
|
|
deprecated: true
|
|
type: string
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in
|
|
their [`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
The time zone configured for the user. This is used primarily to display
|
|
the user's time zone to other users.
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
translate_emoticons:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in
|
|
their [`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
Whether the user has chosen for emoticons to be translated into emoji
|
|
in the Zulip compose box.
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
twenty_four_hour_time:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in
|
|
their [`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
Whether the user has chosen a twenty four hour time display (true)
|
|
or a twelve hour one (false).
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
enter_sends:
|
|
deprecated: true
|
|
type: boolean
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in
|
|
their [`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
Whether the user setting for [sending on pressing Enter][set-enter-send]
|
|
in the compose box is enabled.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and process the `user_settings` event type instead.
|
|
|
|
Prior to Zulip 5.0 (feature level 84), this field was present
|
|
in response if 'realm_user' was present in `fetch_event_types`, not
|
|
`update_display_settings`.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
[set-enter-send]: /help/mastering-the-compose-box#toggle-between-ctrl-enter-and-enter-to-send-a-message
|
|
emojiset_choices:
|
|
deprecated: true
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`
|
|
and only for clients that did not include `user_settings_object` in
|
|
their [`client_capabilities`][capabilities] when registering the event queue.
|
|
|
|
Array of dictionaries where each dictionary describes an emoji set
|
|
supported by this version of the Zulip server.
|
|
|
|
Only relevant to clients with configuration UI for choosing an emoji set;
|
|
the currently selected emoji set is available in the `emojiset` key.
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
|
|
connecting to newer servers should declare the `user_settings_object`
|
|
client capability and access the `user_settings` object instead.
|
|
|
|
[capabilities]: /api/register-queue#parameter-client_capabilities
|
|
type: array
|
|
items:
|
|
type: object
|
|
description: |
|
|
Object describing a emoji set.
|
|
additionalProperties: false
|
|
properties:
|
|
key:
|
|
type: string
|
|
description: |
|
|
The key or the name of the emoji set which will be the value
|
|
of `emojiset` if this emoji set is chosen.
|
|
text:
|
|
type: string
|
|
description: |
|
|
The text describing the emoji set.
|
|
realm_add_custom_emoji_policy:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The [policy][permission-level] for which users can upload new custom emoji
|
|
in this organization.
|
|
|
|
- 1 = Members only
|
|
- 2 = Administrators only
|
|
- 3 = [Full members][calc-full-member] only
|
|
- 4 = Moderators only
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 85) replacing the
|
|
previous `realm_add_emoji_by_admins_only` boolean.
|
|
|
|
[permission-level]: /api/roles-and-permissions#permission-levels
|
|
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
|
|
realm_allow_edit_history:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether this organization is configured to allow users to access
|
|
[message edit history](/help/view-a-messages-edit-history).
|
|
realm_delete_own_message_policy:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The [policy][permission-level] defining which users can delete
|
|
messages that they had sent.
|
|
|
|
- 1 = Members only
|
|
- 2 = Admins only
|
|
- 3 = [Full members][calc-full-member] only
|
|
- 4 = Admins and moderators only
|
|
- 5 = Everyone
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 101), replacing the
|
|
previous `allow_message_deleting` boolean;
|
|
`true` corresponded to `everyone`, and `false` to `admins only`.
|
|
|
|
[permission-level]: /api/roles-and-permissions#permission-levels
|
|
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
|
|
realm_bot_creation_policy:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The [policy](/api/roles-and-permissions#permission-levels)
|
|
for which users can create bot users in this organization.
|
|
realm_create_public_stream_policy:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The [policy][permission-level] for which users can create public streams
|
|
in this organization.
|
|
|
|
- 1 = Members only
|
|
- 2 = Admins only
|
|
- 3 = [Full members][calc-full-member] only
|
|
- 4 = Admins and moderators only
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 102), permission to
|
|
create streams was controlled by the `realm_create_stream_policy` setting.
|
|
|
|
[permission-level]: /api/roles-and-permissions#permission-levels
|
|
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
|
|
realm_create_private_stream_policy:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The [policy][permission-level] for which users can create private streams
|
|
in this organization.
|
|
|
|
- 1 = Members only
|
|
- 2 = Admins only
|
|
- 3 = [Full members][calc-full-member] only
|
|
- 4 = Admins and moderators only
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 102), permission to
|
|
create streams was controlled by the `realm_create_stream_policy` setting.
|
|
|
|
[permission-level]: /api/roles-and-permissions#permission-levels
|
|
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
|
|
realm_create_web_public_stream_policy:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Has no effect and should not be displayed in settings UI
|
|
unless the Zulip server has the `WEB_PUBLIC_STREAMS_ENABLED`
|
|
server-level setting enabled and the organization has enabled
|
|
the `enable_spectator_access` realm setting.
|
|
|
|
The [policy][permission-level] for which users can create web
|
|
public streams in this organization. Allowed
|
|
values are:
|
|
|
|
- 2 = Admins only
|
|
- 4 = Admins and moderators only
|
|
- 6 = Nobody
|
|
- 7 = Owners only
|
|
|
|
**Changes**: Added in Zulip 5.0 (feature level 103).
|
|
|
|
[permission-level]: /api/roles-and-permissions#permission-levels
|
|
realm_invite_to_stream_policy:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The [policy](/api/roles-and-permissions#permission-levels)
|
|
for which users can add other users to streams in this organization.
|
|
realm_wildcard_mention_policy:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The [policy][permission-level] for who can use wildcard mentions
|
|
in large streams.
|
|
|
|
- 1 = Any user can use wildcard mentions in large streams.
|
|
- 2 = Only members can use wildcard mentions in large streams.
|
|
- 3 = Only [full members][calc-full-member] can use wildcard mentions in large streams.
|
|
- 5 = Only organization administrators can use wildcard mentions in large streams.
|
|
- 6 = Nobody can use wildcard mentions in large streams.
|
|
- 7 = Only organization administrators and moderators can use wildcard mentions in large streams.
|
|
|
|
All users will receive a warning/reminder when using
|
|
mentions in large streams, even when permitted to do so.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 33). Moderators option added in
|
|
Zulip 4.0 (feature level 62). Stream administrators option removed in
|
|
Zulip 6.0 (feature level 133).
|
|
|
|
[permission-level]: /api/roles-and-permissions#permission-levels
|
|
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
|
|
realm_default_language:
|
|
type: string
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The [organization language][org-lang] for automated messages and invitation emails.
|
|
|
|
[org-lang]: /help/configure-organization-language
|
|
realm_description:
|
|
type: string
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The description of the organization, used on login and registration pages.
|
|
realm_digest_emails_enabled:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether the organization has enabled [weekly digest emails](/help/digest-emails).
|
|
realm_disallow_disposable_email_addresses:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether the organization disallows disposable email
|
|
addresses.
|
|
realm_email_changes_disabled:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether users are allowed to change their own email address in this
|
|
organization. This is typically disabled for organizations that
|
|
synchronize accounts from LDAP or a similar corporate database.
|
|
realm_invite_required:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether an invitation is required to join this organization.
|
|
realm_invite_to_realm_policy:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
[Policy][permission-level] for [who can invite new
|
|
users](/help/restrict-account-creation#change-who-can-send-invitations)
|
|
to join the organization:
|
|
|
|
- 1 = Members only
|
|
- 2 = Administrators only
|
|
- 3 = [Full members][calc-full-member] only
|
|
- 4 = Moderators only
|
|
- 6 = Nobody
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 50) replacing the
|
|
previous `realm_invite_by_admins_only` boolean.
|
|
|
|
[permission-level]: /api/roles-and-permissions#permission-levels
|
|
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
|
|
realm_move_messages_between_streams_policy:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The [policy][permission-level] for which users can move messages
|
|
from one stream to another.
|
|
|
|
- 1 = Members only
|
|
- 2 = Administrators only
|
|
- 3 = [Full members][calc-full-member] only
|
|
- 4 = Moderators only
|
|
- 6 = Nobody
|
|
|
|
**Changes**: Nobody added as an option in Zulip 7.0 (feature level 159).
|
|
|
|
New in Zulip 4.0 (feature level 56).
|
|
|
|
[permission-level]: /api/roles-and-permissions#permission-levels
|
|
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
|
|
realm_inline_image_preview:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether this organization has been configured to enable
|
|
[previews of linked images](/help/allow-image-link-previews).
|
|
realm_inline_url_embed_preview:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether this organization has been configured to enable
|
|
[previews of linked websites](/help/allow-image-link-previews).
|
|
realm_mandatory_topics:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether [topics are required](/help/require-topics) for messages in this organization.
|
|
realm_message_retention_days:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The default [message retention policy](/help/message-retention-policy)
|
|
for this organization. It can have one special value:
|
|
|
|
- `-1` denoting that the messages will be retained forever for this realm, by default.
|
|
|
|
**Changes**: Prior to Zulip 3.0 (feature level 22), no limit was
|
|
encoded as `null` instead of `-1`. Clients can correctly handle all
|
|
server versions by treating both `-1` and `null` as indicating
|
|
unlimited message retention.
|
|
realm_name:
|
|
type: string
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The name of the organization, used in login pages etc.
|
|
realm_name_changes_disabled:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Indicates whether users are
|
|
[allowed to change](/help/restrict-name-and-email-changes) their name
|
|
via the Zulip UI in this organization. Typically disabled
|
|
in organizations syncing this type of account information from
|
|
an external user database like LDAP.
|
|
realm_avatar_changes_disabled:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Indicates whether users are
|
|
[allowed to change](/help/restrict-name-and-email-changes) their avatar
|
|
via the Zulip UI in this organization. Typically disabled
|
|
in organizations syncing this type of account information from
|
|
an external user database like LDAP.
|
|
realm_emails_restricted_to_domains:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether [new users joining](/help/restrict-account-creation#configuring-email-domain-restrictions)
|
|
this organization are required to have an email
|
|
address in one of the `realm_domains` configured for the organization.
|
|
realm_send_welcome_emails:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether or not this organization is configured to send the standard Zulip
|
|
[welcome emails](/help/disable-welcome-emails) to new users joining the organization.
|
|
realm_message_content_allowed_in_email_notifications:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether notification emails in this organization are allowed to
|
|
contain Zulip the message content, or simply indicate that a new
|
|
message was sent.
|
|
realm_enable_spectator_access:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether web-public streams and related anonymous access APIs/features
|
|
are enabled in this organization.
|
|
|
|
Can only be enabled if the `WEB_PUBLIC_STREAMS_ENABLED`
|
|
[server setting][server-settings] is enabled on the Zulip
|
|
server. See also the `create_web_public_stream_policy` realm
|
|
setting.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 109).
|
|
|
|
[server-settings]: https://zulip.readthedocs.io/en/stable/production/settings.html
|
|
realm_want_advertise_in_communities_directory:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether the organization has given permission to be advertised in the
|
|
Zulip [communities directory](/help/communities-directory).
|
|
|
|
Useful only to clients supporting changing this setting for the
|
|
organization.
|
|
|
|
Giving permission via this setting does not guarantee that an
|
|
organization will be listed in the Zulip communities directory.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 129).
|
|
realm_video_chat_provider:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The configured [video call provider](/help/start-a-call) for the
|
|
organization.
|
|
|
|
- 0 = None
|
|
- 1 = Jitsi Meet
|
|
- 3 = Zoom
|
|
- 4 = BigBlueButton
|
|
|
|
**Changes**: None added as an option in Zulip 3.0 (feature level 1)
|
|
to disable video call UI.
|
|
realm_giphy_rating:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The configured GIPHY rating for the organization.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 55).
|
|
realm_waiting_period_threshold:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Members whose accounts have been created at least this many days ago
|
|
will be treated as [full members][calc-full-member]
|
|
for the purpose of settings that restrict access to new members.
|
|
|
|
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
|
|
realm_digest_weekday:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The day of the week when the organization will send
|
|
its weekly digest email to inactive users.
|
|
realm_private_message_policy:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
[Policy](/api/roles-and-permissions#permission-levels)
|
|
for [who can send direct messages](/help/restrict-direct-messages)
|
|
in this organization.
|
|
|
|
- 1 = Everyone
|
|
- 2 = Nobody
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 1).
|
|
realm_user_group_edit_policy:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The organization's [policy][permission-level] for
|
|
[who can manage user groups][user-group-permissions].
|
|
|
|
- 1 = All members can create and edit user groups
|
|
- 2 = Only organization administrators can create and edit user groups
|
|
- 3 = Only [full members][calc-full-member] can create and edit user groups.
|
|
- 4 = Only organization administrators and moderators can create and edit user groups.
|
|
|
|
[user-group-permissions]: /help/user-groups#configure-who-can-create-and-manage-user-groups
|
|
[permission-level]: /api/roles-and-permissions#permission-levels
|
|
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
|
|
realm_default_code_block_language:
|
|
type: string
|
|
nullable: true
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The default pygments language code to be used for a code blocks
|
|
in this organization. If `null`, no default has been set.
|
|
realm_message_content_delete_limit_seconds:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Messages sent more than this many seconds ago cannot be deleted
|
|
with this organization's
|
|
[message deletion policy](/help/restrict-message-editing-and-deletion).
|
|
|
|
Will not be 0. A `null` value means no limit: messages can be deleted
|
|
regardless of how long ago they were sent.
|
|
|
|
**Changes**: No limit was represented using the
|
|
special value `0` before Zulip 5.0 (feature level 100).
|
|
realm_authentication_methods:
|
|
type: object
|
|
additionalProperties:
|
|
description: |
|
|
Boolean describing whether the authentication method (i.e its key)
|
|
is enabled in this organization.
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Dictionary of 'authentication_method_name': 'boolean' with each
|
|
entry describing whether the authentication name can be used for
|
|
authenticating into the organization.
|
|
realm_allow_message_editing:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether this organizations [message edit policy](/help/restrict-message-editing-and-deletion)
|
|
allows editing the content of messages.
|
|
realm_edit_topic_policy:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The [policy][permission-level] for which users can edit topics of any message.
|
|
|
|
- 1 = Members only
|
|
- 2 = Admins only
|
|
- 3 = [Full members][calc-full-member] only
|
|
- 4 = Moderators only
|
|
- 5 = Everyone
|
|
- 6 = Nobody
|
|
|
|
**Changes**: Nobody added as an option in Zulip 7.0 (feature level 159).
|
|
|
|
New in Zulip 5.0 (feature level 75), replacing the previous
|
|
`allow_community_topic_editing` boolean.
|
|
|
|
[permission-level]: /api/roles-and-permissions#permission-levels
|
|
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
|
|
realm_message_content_edit_limit_seconds:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Messages sent more than this many seconds ago cannot be edited
|
|
with this organization's
|
|
[message edit policy](/help/restrict-message-editing-and-deletion).
|
|
|
|
Will not be 0. A `null` value means no limit: messages can be edited
|
|
regardless of how long ago they were sent.
|
|
|
|
**Changes**: No limit was represented using the
|
|
special value `0` before Zulip 6.0 (feature level 138).
|
|
realm_move_messages_within_stream_limit_seconds:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Messages sent more than this many seconds ago cannot be moved within a
|
|
stream to another topic by users who have permission to do so based on this
|
|
organization's [topic edit policy](/help/restrict-moving-messages). This
|
|
setting does not affect moderators and administrators.
|
|
|
|
Will not be 0. A `null` value means no limit, so message topics can be
|
|
edited regardless of how long ago they were sent.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 162). Previously, this time
|
|
limit was always 72 hours for users who were not administrators or
|
|
moderators.
|
|
realm_move_messages_between_streams_limit_seconds:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Messages sent more than this many seconds ago cannot be moved between
|
|
streams by users who have permission to do so based on this organization's
|
|
[message move policy](/help/restrict-moving-messages). This setting does
|
|
not affect moderators and administrators.
|
|
|
|
Will not be 0. A `null` value means no limit, so messages can be moved
|
|
regardless of how long ago they were sent.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 162). Previously, there was
|
|
no time limit for moving messages between streams for users with permission
|
|
to do so.
|
|
realm_enable_read_receipts:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether read receipts is enabled in the organization or not.
|
|
|
|
If disabled, read receipt data will be unavailable to clients, regardless
|
|
of individual users' personal read receipt settings. See also the
|
|
`send_read_receipts` setting within `realm_user_settings_defaults`.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 137).
|
|
realm_icon_url:
|
|
type: string
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The URL of the organization's [profile icon](/help/create-your-organization-profile).
|
|
realm_icon_source:
|
|
type: string
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
String indicating whether the organization's
|
|
[profile icon](/help/create-your-organization-profile) was uploaded
|
|
by a user or is the default. Useful for UI allowing editing the organization's icon.
|
|
|
|
- "G" means generated by Gravatar (the default).
|
|
- "U" means uploaded by an organization administrator.
|
|
max_icon_file_size_mib:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The maximum file size allowed for the organization's
|
|
icon. Useful for UI allowing editing the organization's icon.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 72). Previously,
|
|
this was called `max_icon_file_size`.
|
|
realm_logo_url:
|
|
type: string
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The URL of the organization's wide logo configured in the
|
|
[organization profile](/help/create-your-organization-profile).
|
|
realm_logo_source:
|
|
type: string
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
String indicating whether the organization's
|
|
[profile wide logo](/help/create-your-organization-profile) was uploaded
|
|
by a user or is the default. Useful for UI allowing editing the
|
|
organization's wide logo.
|
|
|
|
- "D" means the logo is the default Zulip logo.
|
|
- "U" means uploaded by an organization administrator.
|
|
realm_night_logo_url:
|
|
type: string
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The URL of the organization's dark theme wide-format logo configured in the
|
|
[organization profile](/help/create-your-organization-profile).
|
|
realm_night_logo_source:
|
|
type: string
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
String indicating whether the organization's dark theme
|
|
[profile wide logo](/help/create-your-organization-profile) was uploaded
|
|
by a user or is the default. Useful for UI allowing editing the
|
|
organization's wide logo.
|
|
|
|
- "D" means the logo is the default Zulip logo.
|
|
- "U" means uploaded by an organization administrator.
|
|
max_logo_file_size_mib:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The maximum file size allowed for the uploaded organization logos.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 72). Previously,
|
|
this was called `max_logo_file_size`.
|
|
realm_bot_domain:
|
|
type: string
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The fake email domain that will be used for new bots created this
|
|
organization. Useful for UI for creating bots.
|
|
realm_uri:
|
|
type: string
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The URL for the organization.
|
|
realm_available_video_chat_providers:
|
|
type: object
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Dictionary where each entry describes a supported
|
|
[video call provider](/help/start-a-call)
|
|
that is configured on this server and could be selected by an
|
|
organization administrator.
|
|
|
|
Useful for administrative settings UI that allows changing the
|
|
realm setting `video_chat_provider`.
|
|
additionalProperties:
|
|
description: |
|
|
`{provider_name}`: Dictionary containing the details of the
|
|
video call provider with the name of the chat provider as
|
|
the key.
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: |
|
|
The name of the video call provider.
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the video call provider.
|
|
realm_presence_disabled:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether online presence of other users is shown in this
|
|
organization.
|
|
settings_send_digest_emails:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether this Zulip server is configured to allow organizations to
|
|
enable [digest emails](/help/digest-emails).
|
|
|
|
Relevant for administrative settings UI that can change the digest
|
|
email settings.
|
|
realm_is_zephyr_mirror_realm:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether the organization is a Zephyr mirror realm.
|
|
realm_email_auth_enabled:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether the organization has enabled Zulip's default email and password
|
|
authentication feature. Determines whether Zulip stores a password
|
|
for the user and clients should offer any UI for changing the user's
|
|
Zulip password.
|
|
realm_password_auth_enabled:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether the organization allows any sort of password-based
|
|
authentication (whether via EmailAuthBackend or LDAP passwords).
|
|
|
|
Determines whether a client might ever need to display a password prompt
|
|
(clients will primarily look at this attribute in [server_settings](/api/get-server-settings)
|
|
before presenting a login page).
|
|
realm_push_notifications_enabled:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether push notifications are enabled for this organization. Typically
|
|
`false` for self-hosted servers that have not configured the
|
|
[Mobile push notifications service](https://zulip.readthedocs.io/en/latest/production/mobile-push-notifications.html).
|
|
realm_upload_quota_mib:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The total quota for uploaded files in this organization.
|
|
|
|
Clients are not responsible for checking this quota; it is included
|
|
in the API only for display purposes.
|
|
|
|
If `null`, there is no limit.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 72). Previously,
|
|
this was called `realm_upload_quota`.
|
|
realm_org_type:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The [organization type](/help/organization-type) for the realm.
|
|
Useful only to clients supporting changing this setting for the
|
|
organization, or clients implementing onboarding content or
|
|
other features that varies with organization type.
|
|
|
|
- 0 = Unspecified
|
|
- 10 = Business
|
|
- 20 = Open-source project
|
|
- 30 = Education (non-profit)
|
|
- 35 = Education (for-profit)
|
|
- 40 = Research
|
|
- 50 = Event or conference
|
|
- 60 = Non-profit (registered)
|
|
- 70 = Government
|
|
- 80 = Political group
|
|
- 90 = Community
|
|
- 100 = Personal
|
|
- 1000 = Other
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 128).
|
|
realm_plan_type:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The plan type of the organization.
|
|
|
|
- 1 = Self-hosted organization (SELF_HOSTED)
|
|
- 2 = Zulip Cloud free plan (LIMITED)
|
|
- 3 = Zulip Cloud Standard plan (STANDARD)
|
|
- 4 = Zulip Cloud Standard plan, sponsored for free (STANDARD_FREE)
|
|
zulip_plan_is_not_limited:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether the organization is using a limited (Zulip Cloud Free) plan.
|
|
upgrade_text_for_wide_organization_logo:
|
|
type: string
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Text to use when displaying UI for wide organization logos, a feature
|
|
that is currently not available on the Zulip Cloud Free plan.
|
|
|
|
Useful only for clients supporting administrative UI for uploading
|
|
a new wide organization logo to brand the organization.
|
|
realm_default_external_accounts:
|
|
type: object
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Dictionary where each entry describes a default external
|
|
account type that can be configured with Zulip's [custom
|
|
profile fields feature](/help/custom-profile-fields).
|
|
|
|
**Changes**: New in Zulip 2.1.0.
|
|
additionalProperties:
|
|
description: |
|
|
`{site_name}`: Dictionary containing the details of the
|
|
default external account provider with the name of the
|
|
website as the key.
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: |
|
|
The name of the external account provider
|
|
text:
|
|
type: string
|
|
description: |
|
|
The text describing the external account.
|
|
hint:
|
|
type: string
|
|
description: |
|
|
The help text to be displayed for the
|
|
custom profile field in user-facing
|
|
settings UI for configuring custom
|
|
profile fields for this account.
|
|
url_pattern:
|
|
type: string
|
|
description: |
|
|
The regex pattern of the URL of a profile page
|
|
on the external site.
|
|
jitsi_server_url:
|
|
type: string
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The base URL the organization uses to create Jitsi video calls.
|
|
development_environment:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether this Zulip server is a development environment. Used
|
|
to control certain features or UI (such as error popups)
|
|
that should only apply when connected to a Zulip development
|
|
environment.
|
|
server_generation:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
A timestamp indicating when the process hosting this
|
|
event queue was started. Clients will likely only find
|
|
this value useful for inclusion in detailed error reports.
|
|
password_min_length:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
This Zulip server's configured minimum required length for passwords.
|
|
Necessary for password change UI to show whether the password
|
|
will be accepted.
|
|
password_min_guesses:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
This Zulip server's configured minimum `zxcvbn` minimum guesses.
|
|
Necessary for password change UI to show whether the password
|
|
will be accepted.
|
|
giphy_rating_options:
|
|
type: object
|
|
description: |
|
|
Dictionary where each entry describes a valid rating
|
|
that is configured on this server and could be selected by an
|
|
organization administrator.
|
|
|
|
Useful for administrative settings UI that allows changing the
|
|
allowed rating of GIFs.
|
|
additionalProperties:
|
|
description: |
|
|
`{rating_name}`: Dictionary containing the details of the
|
|
rating with the name of the rating as
|
|
the key.
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: |
|
|
The description of the rating option.
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the rating option.
|
|
max_file_upload_size_mib:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The maximum file size that can be uploaded to this Zulip server.
|
|
max_avatar_file_size_mib:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The maximum avatar size that can be uploaded to this Zulip server.
|
|
server_inline_image_preview:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether the server is configured with support for inline image previews.
|
|
Clients containing administrative UI for changing
|
|
`realm_inline_image_preview` should consult this field before offering
|
|
that feature.
|
|
server_inline_url_embed_preview:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether the server is configured with support for inline URL previews.
|
|
Clients containing administrative UI for changing
|
|
`realm_inline_url_embed_preview` should consult this field before offering
|
|
that feature.
|
|
server_avatar_changes_disabled:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether the server allows avatar changes. Similar to
|
|
`realm_avatar_changes_disabled` but based on the `AVATAR_CHANGES_DISABLED`
|
|
Zulip server level setting.
|
|
server_name_changes_disabled:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether the server allows name changes. Similar to
|
|
`realm_name_changes_disabled` but based on the `NAME_CHANGES_DISABLED`
|
|
Zulip server level setting.
|
|
server_needs_upgrade:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether the server is running an old version based on the Zulip
|
|
[server release lifecycle](https://zulip.readthedocs.io/en/latest/overview/release-lifecycle.html#upgrade-nag),
|
|
such that the web app will display to the current user a prominent warning.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 74).
|
|
server_web_public_streams_enabled:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The value of the `WEB_PUBLIC_STREAMS_ENABLED` Zulip server level
|
|
setting. A server that has disabled this setting intends to not offer [web
|
|
public streams](/help/public-access-option) to realms it hosts. (Zulip Cloud
|
|
defaults to `true`; self-hosted servers default to `false`).
|
|
|
|
Clients should use this to determine whether to offer UI for the
|
|
realm-level setting for enabling web-public streams
|
|
(`realm_enable_spectator_access`).
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 110).
|
|
server_emoji_data_url:
|
|
type: string
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The URL to a JSON file that describes which emoji names map to which
|
|
emoji codes, for all Unicode emoji this Zulip server accepts.
|
|
|
|
The data at the given URL is a JSON object with one property, `code_to_names`.
|
|
The value of that property is a JSON object where each key is an
|
|
[emoji code](/api/add-reaction#parameter-emoji_code) for an available
|
|
Unicode emoji, and each value is the corresponding
|
|
[emoji names](/api/add-reaction#parameter-emoji_name) for this emoji,
|
|
with the canonical name for the emoji always appearing first.
|
|
|
|
The HTTP response at that URL will have appropriate HTTP caching headers, such
|
|
any HTTP implementation should get a cached version if emoji haven't changed
|
|
since the last request.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 140).
|
|
event_queue_longpoll_timeout_seconds:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Recommended client-side HTTP request timeout for [`GET /events`](/api/get-events) calls.
|
|
This is guaranteed to be somewhat greater than the heartbeat frequency. It is important
|
|
that clients respect this parameter, so that increases in the heartbeat frequency do not
|
|
break clients.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 74). Previously,
|
|
this was hardcoded to 90 seconds, and clients should use that as a fallback
|
|
value when interacting with servers where this field is not present.
|
|
realm_notifications_stream_id:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The ID of the stream to which automated messages announcing the
|
|
[creation of new streams][new-stream-announce] are sent.
|
|
|
|
Will be `-1` if such automated messages are disabled.
|
|
|
|
Since these automated messages are sent by the server, this field is
|
|
primarily relevant to clients containing UI for changing it.
|
|
|
|
[new-stream-announce]: /help/configure-notification-bot#new-stream-announcements
|
|
realm_signup_notifications_stream_id:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The ID of the stream to which automated messages announcing
|
|
that [new users have joined the organization][new-user-announce] are sent.
|
|
|
|
Will be `-1` if such automated messages are disabled.
|
|
|
|
Since these automated messages are sent by the server, this field is
|
|
primarily relevant to clients containing UI for changing it.
|
|
|
|
[new-user-announce]: /help/configure-notification-bot#new-user-announcements
|
|
realm_user_settings_defaults:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Present if `realm_user_settings_defaults` is present in `fetch_event_types`.
|
|
|
|
A dictionary containing the default values of settings for new users.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 95).
|
|
properties:
|
|
twenty_four_hour_time:
|
|
type: boolean
|
|
description: |
|
|
Whether time should be [displayed in 24-hour notation](/help/change-the-time-format).
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 99).
|
|
This value was previously available as
|
|
`realm_default_twenty_four_hour_time` in
|
|
the top-level response object (only when `realm` was
|
|
present in `fetch_event_types`).
|
|
dense_mode:
|
|
type: boolean
|
|
description: |
|
|
This setting has no effect at present. It is reserved for use in
|
|
controlling the default font size in Zulip.
|
|
web_mark_read_on_scroll_policy:
|
|
type: integer
|
|
description: |
|
|
Whether or not to mark messages as read when the user scrolls through their
|
|
feed.
|
|
|
|
- 1 - Always
|
|
- 2 - Only in conversation views
|
|
- 3 - Never
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 175). Previously, there was no
|
|
way for the user to configure this behavior on the web, and the Zulip web and
|
|
desktop apps behaved like the "Always" setting when marking messages as read.
|
|
starred_message_counts:
|
|
type: boolean
|
|
description: |
|
|
Whether clients should display the [number of starred
|
|
messages](/help/star-a-message#display-the-number-of-starred-messages).
|
|
fluid_layout_width:
|
|
type: boolean
|
|
description: |
|
|
Whether to use the [maximum available screen width](/help/enable-full-width-display)
|
|
for the web app's center panel (message feed, recent conversations) on wide screens.
|
|
high_contrast_mode:
|
|
type: boolean
|
|
description: |
|
|
This setting is reserved for use to control variations in Zulip's design
|
|
to help visually impaired users.
|
|
color_scheme:
|
|
type: integer
|
|
description: |
|
|
Controls which [color theme](/help/dark-theme) to use.
|
|
|
|
- 1 - Automatic
|
|
- 2 - Dark theme
|
|
- 3 - Light theme
|
|
|
|
Automatic detection is implementing using the standard `prefers-color-scheme`
|
|
media query.
|
|
translate_emoticons:
|
|
type: boolean
|
|
description: |
|
|
Whether to [translate emoticons to emoji](/help/configure-emoticon-translations)
|
|
in messages the user sends.
|
|
display_emoji_reaction_users:
|
|
type: boolean
|
|
description: |
|
|
Whether to display the names of reacting users on a message.
|
|
|
|
When enabled, clients should display the names of reacting
|
|
users, rather than a count, for messages with few total
|
|
reactions. The ideal cutoff may depend on the space
|
|
available for displaying reactions; the official web
|
|
application displays names when 3 or fewer total reactions
|
|
are present with this setting enabled.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 125).
|
|
default_language:
|
|
type: string
|
|
description: |
|
|
What [default language](/help/change-your-language) to use for the account.
|
|
|
|
This controls both the Zulip UI as well as email notifications sent to the user.
|
|
|
|
The value needs to be a standard language code that the Zulip server has
|
|
translation data for; for example, `"en"` for English or `"de"` for German.
|
|
default_view:
|
|
type: string
|
|
description: |
|
|
The [default view](/help/configure-default-view) used when opening a new
|
|
Zulip web app window or hitting the `Esc` keyboard shortcut repeatedly.
|
|
|
|
- "recent_topics" - Recent conversations view
|
|
- "all_messages" - All messages view
|
|
escape_navigates_to_default_view:
|
|
type: boolean
|
|
description: |
|
|
Whether the escape key navigates to the
|
|
[configured default view](/help/configure-default-view).
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 107).
|
|
left_side_userlist:
|
|
type: boolean
|
|
description: |
|
|
Whether the users list on left sidebar in narrow windows.
|
|
|
|
This feature is not heavily used and is likely to be reworked.
|
|
emojiset:
|
|
type: string
|
|
description: |
|
|
The user's configured [emoji set](/help/emoji-and-emoticons#use-emoticons),
|
|
used to display emoji to the user everywhere they appear in the UI.
|
|
|
|
- "google" - Google modern
|
|
- "google-blob" - Google classic
|
|
- "twitter" - Twitter
|
|
- "text" - Plain text
|
|
demote_inactive_streams:
|
|
type: integer
|
|
description: |
|
|
Whether to [demote inactive streams](/help/manage-inactive-streams) in the left sidebar.
|
|
|
|
- 1 - Automatic
|
|
- 2 - Always
|
|
- 3 - Never
|
|
user_list_style:
|
|
type: integer
|
|
description: |
|
|
The style selected by the user for the right sidebar user list.
|
|
|
|
- 1 - Compact
|
|
- 2 - With status
|
|
- 3 - With avatar and status
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 141).
|
|
enable_stream_desktop_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable visual desktop notifications for stream messages.
|
|
enable_stream_email_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable email notifications for stream messages.
|
|
enable_stream_push_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable mobile notifications for stream messages.
|
|
enable_stream_audible_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable audible desktop notifications for stream messages.
|
|
notification_sound:
|
|
type: string
|
|
description: |
|
|
Notification sound name.
|
|
enable_desktop_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable visual desktop notifications for private messages and @-mentions.
|
|
enable_sounds:
|
|
type: boolean
|
|
description: |
|
|
Enable audible desktop notifications for private messages and
|
|
@-mentions.
|
|
enable_offline_email_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable email notifications for private messages and @-mentions received
|
|
when the user is offline.
|
|
enable_offline_push_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable mobile notification for private messages and @-mentions received
|
|
when the user is offline.
|
|
enable_online_push_notifications:
|
|
type: boolean
|
|
description: |
|
|
Enable mobile notification for private messages and @-mentions received
|
|
when the user is online.
|
|
enable_digest_emails:
|
|
type: boolean
|
|
description: |
|
|
Enable digest emails when the user is away.
|
|
enable_marketing_emails:
|
|
type: boolean
|
|
description: |
|
|
Enable marketing emails. Has no function outside Zulip Cloud.
|
|
enable_login_emails:
|
|
type: boolean
|
|
description: |
|
|
Enable email notifications for new logins to account.
|
|
message_content_in_email_notifications:
|
|
type: boolean
|
|
description: |
|
|
Include the message's content in email notifications for new messages.
|
|
pm_content_in_desktop_notifications:
|
|
type: boolean
|
|
description: |
|
|
Include content of private messages in desktop notifications.
|
|
wildcard_mentions_notify:
|
|
type: boolean
|
|
description: |
|
|
Whether wildcard mentions (E.g. @**all**) should send notifications
|
|
like a personal mention.
|
|
desktop_icon_count_display:
|
|
type: integer
|
|
description: |
|
|
Unread count badge (appears in desktop sidebar and browser tab)
|
|
|
|
- 1 - All unreads
|
|
- 2 - Private messages and mentions
|
|
- 3 - None
|
|
realm_name_in_email_notifications_policy:
|
|
type: integer
|
|
description: |
|
|
Whether to [include organization name in subject of message notification
|
|
emails](/help/email-notifications#include-organization-name-in-subject-line).
|
|
|
|
- 1 - Automatic
|
|
- 2 - Always
|
|
- 3 - Never
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 168), replacing the
|
|
previous `realm_name_in_notifications` boolean;
|
|
`true` corresponded to `Always`, and `false` to `Never`.
|
|
presence_enabled:
|
|
type: boolean
|
|
description: |
|
|
Display the presence status to other users when online.
|
|
enter_sends:
|
|
type: boolean
|
|
description: |
|
|
Whether the user setting for [sending on pressing Enter](/help/mastering-the-compose-box#toggle-between-ctrl-enter-and-enter-to-send-a-message)
|
|
in the compose box is enabled.
|
|
enable_drafts_synchronization:
|
|
type: boolean
|
|
description: |
|
|
A boolean parameter to control whether synchronizing drafts is enabled for
|
|
the user. When synchronization is disabled, all drafts stored in the server
|
|
will be automatically deleted from the server.
|
|
|
|
This does not do anything (like sending events) to delete local copies of
|
|
drafts stored in clients.
|
|
email_notifications_batching_period_seconds:
|
|
type: integer
|
|
description: |
|
|
The duration (in seconds) for which the server should wait to batch
|
|
email notifications before sending them.
|
|
available_notification_sounds:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: |
|
|
Array containing the names of the notification sound options
|
|
supported by this Zulip server. Only relevant to support UI
|
|
for configuring notification sounds.
|
|
emojiset_choices:
|
|
description: |
|
|
Array of dictionaries where each dictionary describes an emoji set
|
|
supported by this version of the Zulip server.
|
|
|
|
Only relevant to clients with configuration UI for choosing an emoji set;
|
|
the currently selected emoji set is available in the `emojiset` key.
|
|
|
|
See [PATCH /settings](/api/update-settings) for details on
|
|
the meaning of this setting.
|
|
type: array
|
|
items:
|
|
type: object
|
|
description: |
|
|
Object describing a emoji set.
|
|
additionalProperties: false
|
|
properties:
|
|
key:
|
|
type: string
|
|
description: |
|
|
The key or the name of the emoji set which will be the value
|
|
of `emojiset` if this emoji set is chosen.
|
|
text:
|
|
type: string
|
|
description: |
|
|
The text describing the emoji set.
|
|
send_private_typing_notifications:
|
|
type: boolean
|
|
description: |
|
|
Whether [typing notifications](/help/typing-notifications) be sent when composing
|
|
private messages.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 105).
|
|
send_stream_typing_notifications:
|
|
type: boolean
|
|
description: |
|
|
Whether [typing notifications](/help/typing-notifications) be sent when composing
|
|
stream messages.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 105).
|
|
send_read_receipts:
|
|
type: boolean
|
|
description: |
|
|
Whether other users are allowed to see whether you've
|
|
read messages.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 105).
|
|
email_address_visibility:
|
|
$ref: "#/components/schemas/EmailAddressVisibility"
|
|
realm_users:
|
|
type: array
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
A array of dictionaries where each entry describes a user
|
|
whose account has not been deactivated. Note that unlike
|
|
the usual User dictionary, this does not contain the `is_active`
|
|
key, as all the users present in this array have active accounts.
|
|
|
|
See also `cross_realm_bots` and `realm_non_active_users`.
|
|
items:
|
|
$ref: "#/components/schemas/User"
|
|
realm_non_active_users:
|
|
type: array
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
A array of dictionaries where each entry describes a user
|
|
whose account has been deactivated. Note that unlike
|
|
the usual User dictionary this does not contain the `is_active`
|
|
key as all the users present in this array have deactivated
|
|
accounts.
|
|
items:
|
|
$ref: "#/components/schemas/User"
|
|
avatar_source:
|
|
type: string
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
The avatar data source type for the current user.
|
|
|
|
Value values are `G` (gravatar) and `U` (uploaded by user).
|
|
avatar_url_medium:
|
|
type: string
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
The avatar URL for the current user at 500x500 resolution, appropriate
|
|
for use in settings UI showing the user's avatar.
|
|
avatar_url:
|
|
type: string
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
The URL of the avatar for the current user at 100x100
|
|
resolution. See also `avatar_url_medium`.
|
|
can_create_streams:
|
|
type: boolean
|
|
deprecated: true
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
Whether the current user is allowed to create at least one type
|
|
of stream with the organization's [stream creation
|
|
policy](/help/configure-who-can-create-streams). Its value will
|
|
always equal `can_create_public_streams || can_create_private_streams`.
|
|
|
|
**Changes**: Deprecated in Zulip 5.0 (feature level 102), when
|
|
the new `create_private_stream_policy` and
|
|
`create_public_stream_policy` properties introduced the
|
|
possibility that a user could only create one type of stream.
|
|
|
|
This field will be removed in a future release.
|
|
can_create_public_streams:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
Whether the current user is allowed to create public streams with
|
|
the organization's [stream creation policy](/help/configure-who-can-create-streams).
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 102). In older
|
|
versions, the deprecated `can_create_streams` property should be
|
|
used to determine whether the user can create public streams.
|
|
can_create_private_streams:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
Whether the current user is allowed to create private streams with
|
|
the organization's [stream creation policy](/help/configure-who-can-create-streams).
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 102). In older
|
|
versions, the deprecated `can_create_streams` property should be
|
|
used to determine whether the user can create private streams.
|
|
can_create_web_public_streams:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
Whether the current user is allowed to create public streams with
|
|
the organization's [stream creation policy](/help/configure-who-can-create-streams).
|
|
|
|
Note that this will be false if the Zulip server does not have the
|
|
`WEB_PUBLIC_STREAMS_ENABLED` setting enabled or if the organization has
|
|
not enabled the `enable_spectator_access` realm setting.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 103).
|
|
can_subscribe_other_users:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
Whether the current user is allowed to subscribe other users to streams with
|
|
the organization's [streams policy](/help/configure-who-can-invite-to-streams).
|
|
can_invite_others_to_realm:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
Whether the current user [is allowed to invite others][who-can-send-invitations]
|
|
to the organization.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 51).
|
|
|
|
[who-can-send-invitations]: /help/restrict-account-creation#change-who-can-send-invitations
|
|
is_admin:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
Whether the current user is an [organization administrator](/api/roles-and-permissions).
|
|
is_owner:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
Whether the current user is an [organization owner](/api/roles-and-permissions).
|
|
is_billing_admin:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
Whether the current user is a billing administrator.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 73).
|
|
is_moderator:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
Whether the current user is an [organization moderator](/api/roles-and-permissions).
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 60).
|
|
is_guest:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
Whether the current user is a [guest user](/api/roles-and-permissions).
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
The unique ID for the current user.
|
|
email:
|
|
type: string
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
The Zulip API email address for the current user. See also
|
|
`delivery_email`; these may be the same or different depending
|
|
on the user's `email_address_visibility` policy.
|
|
delivery_email:
|
|
type: string
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
The user's email address, appropriate for UI for changing
|
|
the user's email address. See also `email`.
|
|
full_name:
|
|
type: string
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
The full name of the current user.
|
|
cross_realm_bots:
|
|
type: array
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
Array of dictionaries where each dictionary contains details of
|
|
a single cross realm bot. Cross-realm bots are special system bot accounts
|
|
like Notification Bot.
|
|
|
|
Most clients will want to combine this with `realm_users` in many
|
|
contexts.
|
|
items:
|
|
allOf:
|
|
- $ref: "#/components/schemas/UserBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
user_id: {}
|
|
delivery_email: {}
|
|
email: {}
|
|
full_name: {}
|
|
date_joined: {}
|
|
is_active: {}
|
|
is_owner: {}
|
|
is_admin: {}
|
|
is_guest: {}
|
|
is_billing_admin: {}
|
|
is_bot: {}
|
|
# Referenced schema properties are rendered before any
|
|
# non-referenced properties in the API documentation, so
|
|
# `is_system_bot` appears last instead of in this order.
|
|
# General practice should be to define properties in the
|
|
# same order that they are rendered in the API documentation.
|
|
# TODO: See if we can match the order of properties as
|
|
# listed here when rendered in the API documentation.
|
|
is_system_bot:
|
|
type: boolean
|
|
description: |
|
|
Whether the user is a system bot. System bots are special
|
|
bot user accounts that are managed by the system, rather than
|
|
the organization's administrators.
|
|
|
|
**Changes**: This field was called `is_cross_realm_bot`
|
|
before Zulip 5.0 (feature level 83).
|
|
bot_type:
|
|
nullable: true
|
|
bot_owner_id:
|
|
nullable: true
|
|
role: {}
|
|
timezone: {}
|
|
avatar_url:
|
|
nullable: true
|
|
avatar_version: {}
|
|
profile_data: {}
|
|
example:
|
|
{
|
|
"last_event_id": -1,
|
|
"msg": "",
|
|
"queue_id": "fb67bf8a-c031-47cc-84cf-ed80accacda8",
|
|
"realm_emoji":
|
|
{
|
|
"1":
|
|
{
|
|
"author_id": 5,
|
|
"deactivated": false,
|
|
"id": "1",
|
|
"name": "green_tick",
|
|
"source_url": "/user_avatars/1/emoji/images/1.png",
|
|
},
|
|
"2":
|
|
{
|
|
"author_id": 3,
|
|
"deactivated": false,
|
|
"id": "2",
|
|
"name": "animated_img",
|
|
"source_url": "/user_avatars/1/emoji/images/animated_img.gif",
|
|
"still_url": "/user_avatars/1/emoji/images/still/animated_img.png",
|
|
},
|
|
},
|
|
"result": "success",
|
|
"zulip_feature_level": 2,
|
|
"zulip_version": "5.0-dev-1650-gc3fd37755f",
|
|
"zulip_merge_base": "5.0-dev-1646-gea6b21cd8c",
|
|
}
|
|
/server_settings:
|
|
get:
|
|
operationId: get-server-settings
|
|
summary: Get server settings
|
|
tags: ["server_and_organizations"]
|
|
x-response-description: |
|
|
Please note that not all of these attributes are guaranteed to appear in a
|
|
response, for two reasons:
|
|
|
|
* This endpoint has evolved over time, so responses from older Zulip servers
|
|
might be missing some keys (in which case a client should assume the
|
|
appropriate default).
|
|
* If a `/server_settings` request is made to the root domain of a
|
|
multi-subdomain server, like the root domain of zulip.com, the settings
|
|
that are realm-specific are not known and thus not provided.
|
|
description: |
|
|
Fetch global settings for a Zulip server.
|
|
|
|
**Note:** this endpoint does not require any authentication at all, and you can use it to check:
|
|
|
|
- If this is a Zulip server, and if so, what version of Zulip it's running.
|
|
- What a Zulip client (e.g. a mobile app or
|
|
[zulip-terminal](https://github.com/zulip/zulip-terminal/)) needs to
|
|
know in order to display a login prompt for the server (e.g. what
|
|
authentication methods are available).
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
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 for a single-organization server
|
|
may look like:
|
|
|
|
[ignored_params]: /api/rest-error-handling#ignored-parameters
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
authentication_methods:
|
|
type: object
|
|
additionalProperties: false
|
|
deprecated: true
|
|
description: |
|
|
Each key-value pair in the object indicates whether the authentication
|
|
method is enabled on this server.
|
|
|
|
**Changes**: Deprecated in Zulip 2.1.0, in favor of the more expressive
|
|
`external_authentication_methods`.
|
|
properties:
|
|
password:
|
|
description: |
|
|
Whether the user can authenticate using password.
|
|
type: boolean
|
|
dev:
|
|
description: |
|
|
Whether the user can authenticate using development API key.
|
|
type: boolean
|
|
email:
|
|
description: |
|
|
Whether the user can authenticate using email.
|
|
type: boolean
|
|
ldap:
|
|
description: |
|
|
Whether the user can authenticate using LDAP.
|
|
type: boolean
|
|
remoteuser:
|
|
description: |
|
|
Whether the user can authenticate using REMOTE_USER.
|
|
type: boolean
|
|
github:
|
|
description: |
|
|
Whether the user can authenticate using their GitHub account.
|
|
type: boolean
|
|
azuread:
|
|
description: |
|
|
Whether the user can authenticate using their Azure Active Directory account.
|
|
type: boolean
|
|
gitlab:
|
|
description: |
|
|
Whether the user can authenticate using their GitLab account.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 1).
|
|
type: boolean
|
|
apple:
|
|
description: |
|
|
Whether the user can authenticate using their Apple account.
|
|
type: boolean
|
|
google:
|
|
description: |
|
|
Whether the user can authenticate using their Google account.
|
|
type: boolean
|
|
saml:
|
|
description: |
|
|
Whether the user can authenticate using SAML.
|
|
type: boolean
|
|
openid connect:
|
|
description: |
|
|
Whether the user can authenticate using OpenID Connect.
|
|
type: boolean
|
|
external_authentication_methods:
|
|
type: array
|
|
description: |
|
|
A list of dictionaries describing the available external
|
|
authentication methods (E.g. Google, GitHub, or SAML)
|
|
enabled for this organization.
|
|
|
|
The list is sorted in the order in which these
|
|
authentication methods should be displayed.
|
|
|
|
**Changes**: New in Zulip 2.1.0.
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: |
|
|
A unique, table, machine-readable name for the authentication method,
|
|
intended to be used by clients with special behavior for specific
|
|
authentication methods to correctly identify the method.
|
|
display_name:
|
|
type: string
|
|
description: |
|
|
Display name of the authentication method, to be used in all buttons
|
|
for the authentication method.
|
|
display_icon:
|
|
type: string
|
|
nullable: true
|
|
description: |
|
|
URL for an image to be displayed as an icon in all buttons for
|
|
the external authentication method.
|
|
|
|
When `null`, no icon should be displayed.
|
|
login_url:
|
|
type: string
|
|
description: |
|
|
URL to be used to initiate authentication using this method.
|
|
signup_url:
|
|
type: string
|
|
description: |
|
|
URL to be used to initiate account registration using this method.
|
|
zulip_feature_level:
|
|
type: integer
|
|
description: |
|
|
An integer indicating what features are
|
|
available on the server. The feature level increases monotonically;
|
|
a value of N means the server supports all API features introduced
|
|
before feature level N. This is designed to provide a simple way
|
|
for client apps to decide whether the server supports a given
|
|
feature or API change. See the [changelog](/api/changelog) for
|
|
details on what each feature level means.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 1). We recommend using an
|
|
implied value of 0 for Zulip servers that do not send this field.
|
|
zulip_version:
|
|
type: string
|
|
description: |
|
|
The server's version number. This is often a release version number,
|
|
like `2.1.7`. But for a server running a [version from Git][git-release],
|
|
it will be a Git reference to the commit, like `5.0-dev-1650-gc3fd37755f`.
|
|
|
|
[git-release]: https://zulip.readthedocs.io/en/latest/overview/release-lifecycle.html#git-versions
|
|
zulip_merge_base:
|
|
type: string
|
|
description: |
|
|
The `git merge-base` between `zulip_version` and official branches
|
|
in the public
|
|
[Zulip server and web app repository](https://github.com/zulip/zulip),
|
|
in the same format as `zulip_version`. This will equal
|
|
`zulip_version` if the server is not running a fork of the Zulip server.
|
|
|
|
This will be `""` if unavailable.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 88).
|
|
push_notifications_enabled:
|
|
type: boolean
|
|
description: |
|
|
Whether mobile/push notifications are enabled.
|
|
is_incompatible:
|
|
type: boolean
|
|
description: |
|
|
Whether the Zulip client that has sent a request to this endpoint is
|
|
deemed incompatible with the server.
|
|
email_auth_enabled:
|
|
type: boolean
|
|
description: |
|
|
Setting for allowing users authenticate with an email-password
|
|
combination.
|
|
require_email_format_usernames:
|
|
type: boolean
|
|
description: |
|
|
Whether all valid usernames for authentication to this
|
|
organization will be email addresses. This is important
|
|
for clients to know whether to do client side validation
|
|
of email address format in a login prompt.
|
|
|
|
This value will be false if the server has [LDAP
|
|
authentication][ldap-auth] enabled with a username and
|
|
password combination.
|
|
|
|
[ldap-auth]: https://zulip.readthedocs.io/en/latest/production/authentication-methods.html#ldap-including-active-directory
|
|
realm_uri:
|
|
type: string
|
|
description: |
|
|
The organization's canonical URL.
|
|
realm_name:
|
|
type: string
|
|
description: |
|
|
The organization's name (for display purposes).
|
|
realm_icon:
|
|
type: string
|
|
description: |
|
|
The URL for the organization's logo formatted as a square image,
|
|
used for identifying the organization in small locations in the
|
|
mobile and desktop apps.
|
|
realm_description:
|
|
type: string
|
|
description: |
|
|
HTML description of the organization, as configured by the [organization
|
|
profile](/help/create-your-organization-profile).
|
|
realm_web_public_access_enabled:
|
|
type: boolean
|
|
description: |
|
|
Whether the organization has enabled the creation of
|
|
[web-public streams](/help/public-access-option) and
|
|
at least one web-public stream on the server currently
|
|
exists. Clients that support viewing content
|
|
in web-public streams without an account can
|
|
use this to determine whether to offer that
|
|
feature on the login page for an organization.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 116).
|
|
example:
|
|
{
|
|
"authentication_methods":
|
|
{
|
|
"password": true,
|
|
"dev": true,
|
|
"email": true,
|
|
"ldap": false,
|
|
"remoteuser": false,
|
|
"github": true,
|
|
"azuread": false,
|
|
"google": true,
|
|
"saml": true,
|
|
},
|
|
"zulip_version": "5.0-dev-1650-gc3fd37755f",
|
|
"zulip_merge_base": "5.0-dev-1646-gea6b21cd8c",
|
|
"push_notifications_enabled": false,
|
|
"msg": "",
|
|
"is_incompatible": false,
|
|
"email_auth_enabled": true,
|
|
"require_email_format_usernames": true,
|
|
"realm_uri": "http://localhost:9991",
|
|
"realm_name": "Zulip Dev",
|
|
"realm_icon": "https://secure.gravatar.com/avatar/62429d594b6ffc712f54aee976a18b44?d=identicon",
|
|
"realm_description": "<p>The Zulip development environment default organization. It's great for testing!</p>",
|
|
"realm_web_public_access_enabled": false,
|
|
"result": "success",
|
|
"external_authentication_methods":
|
|
[
|
|
{
|
|
"name": "saml:idp_name",
|
|
"display_name": "SAML",
|
|
"display_icon": null,
|
|
"login_url": "/accounts/login/social/saml/idp_name",
|
|
"signup_url": "/accounts/register/social/saml/idp_name",
|
|
},
|
|
{
|
|
"name": "google",
|
|
"display_name": "Google",
|
|
"display_icon": "/static/images/authentication_backends/googl_e-icon.png",
|
|
"login_url": "/accounts/login/social/google",
|
|
"signup_url": "/accounts/register/social/google",
|
|
},
|
|
{
|
|
"name": "github",
|
|
"display_name": "GitHub",
|
|
"display_icon": "/static/images/authentication_backends/github-icon.png",
|
|
"login_url": "/accounts/login/social/github",
|
|
"signup_url": "/accounts/register/social/github",
|
|
},
|
|
],
|
|
}
|
|
/settings:
|
|
patch:
|
|
operationId: update-settings
|
|
summary: Update settings
|
|
tags: ["users"]
|
|
description: |
|
|
This endpoint is used to edit the current user's settings.
|
|
|
|
**Changes**: Prior to Zulip 5.0 (feature level 80), this
|
|
endpoint only supported the `full_name`, `email`,
|
|
`old_password`, and `new_password` parameters. Notification
|
|
settings were managed by `PATCH /settings/notifications`, and
|
|
all other settings by `PATCH /settings/display`.
|
|
|
|
The feature level 80 migration to merge these endpoints did not
|
|
change how request parameters are encoded. However, it did change
|
|
the handling of any invalid parameters present in a request
|
|
(see feature level 78 change below).
|
|
|
|
The `/settings/display` and `/settings/notifications`
|
|
endpoints are now deprecated aliases for this endpoint for
|
|
backwards-compatibility, and will be removed once clients have
|
|
migrated to use this endpoint.
|
|
|
|
**Changes**: Prior to Zulip 5.0 (feature level 78),
|
|
the `/settings` endpoint indicated which parameters it had
|
|
processed by including in the response object `"key": value`
|
|
entries for values successfully changed by the request. That
|
|
was replaced by the more ergonomic
|
|
[`ignored_parameters_unsupported`][ignored-parameters] array.
|
|
|
|
The `/settings/notifications` and `/settings/display` endpoints
|
|
also had this behavior before they became aliases of `/settings`
|
|
in Zulip 5.0 (see feature level 80 change above).
|
|
|
|
Before these changes, request parameters that were not supported
|
|
(or were unchanged) were silently ignored.
|
|
|
|
[ignored-parameters]: /api/rest-error-handling#ignored-parameters
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: include
|
|
parameters:
|
|
enum:
|
|
- left_side_userlist
|
|
- emojiset
|
|
parameters:
|
|
- name: full_name
|
|
in: query
|
|
description: |
|
|
A new display name for the user.
|
|
schema:
|
|
type: string
|
|
example: NewName
|
|
- name: email
|
|
in: query
|
|
description: |
|
|
Asks the server to initiate a confirmation sequence to change the user's email
|
|
address to the indicated value. The user will need to demonstrate control of the
|
|
new email address by clicking a confirmation link sent to that address.
|
|
schema:
|
|
type: string
|
|
example: newname@example.com
|
|
- name: old_password
|
|
in: query
|
|
description: |
|
|
The user's old Zulip password (or LDAP password, if LDAP authentication is in use).
|
|
|
|
Required only when sending the `new_password` parameter.
|
|
schema:
|
|
type: string
|
|
example: old12345
|
|
- name: new_password
|
|
in: query
|
|
description: |
|
|
The user's new Zulip password (or LDAP password, if LDAP authentication is in use).
|
|
|
|
The `old_password` parameter must be included in the request.
|
|
schema:
|
|
type: string
|
|
example: new12345
|
|
- name: twenty_four_hour_time
|
|
in: query
|
|
description: |
|
|
Whether time should be [displayed in 24-hour notation](/help/change-the-time-format).
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/display` endpoint.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: dense_mode
|
|
in: query
|
|
description: |
|
|
This setting has no effect at present. It is reserved for use in controlling
|
|
the default font size in Zulip.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/display` endpoint.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: web_mark_read_on_scroll_policy
|
|
in: query
|
|
description: |
|
|
Whether or not to mark messages as read when the user scrolls through their
|
|
feed.
|
|
|
|
- 1 - Always
|
|
- 2 - Only in conversation views
|
|
- 3 - Never
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 175). Previously, there was no
|
|
way for the user to configure this behavior on the web, and the Zulip web and
|
|
desktop apps behaved like the "Always" setting when marking messages as read.
|
|
schema:
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
example: 1
|
|
- name: starred_message_counts
|
|
in: query
|
|
description: |
|
|
Whether clients should display the [number of starred
|
|
messages](/help/star-a-message#display-the-number-of-starred-messages).
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/display` endpoint.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: fluid_layout_width
|
|
in: query
|
|
description: |
|
|
Whether to use the [maximum available screen width](/help/enable-full-width-display)
|
|
for the web app's center panel (message feed, recent conversations) on wide screens.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/display` endpoint.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: high_contrast_mode
|
|
in: query
|
|
description: |
|
|
This setting is reserved for use to control variations in Zulip's design
|
|
to help visually impaired users.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/display` endpoint.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: color_scheme
|
|
in: query
|
|
description: |
|
|
Controls which [color theme](/help/dark-theme) to use.
|
|
|
|
- 1 - Automatic
|
|
- 2 - Dark theme
|
|
- 3 - Light theme
|
|
|
|
Automatic detection is implementing using the standard `prefers-color-scheme`
|
|
media query.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/display` endpoint.
|
|
schema:
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
example: 1
|
|
- name: enable_drafts_synchronization
|
|
in: query
|
|
description: |
|
|
A boolean parameter to control whether synchronizing drafts is enabled for
|
|
the user. When synchronization is disabled, all drafts stored in the server
|
|
will be automatically deleted from the server.
|
|
|
|
This does not do anything (like sending events) to delete local copies of
|
|
drafts stored in clients.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 87).
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: translate_emoticons
|
|
in: query
|
|
description: |
|
|
Whether to [translate emoticons to emoji](/help/configure-emoticon-translations)
|
|
in messages the user sends.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/display` endpoint.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: display_emoji_reaction_users
|
|
in: query
|
|
description: |
|
|
Whether to display the names of reacting users on a message.
|
|
|
|
When enabled, clients should display the names of reacting users, rather than
|
|
a count, for messages with few total reactions. The ideal cutoff may depend on
|
|
the space available for displaying reactions; the official web application
|
|
displays names when 3 or fewer total reactions are present with this setting
|
|
enabled.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 125).
|
|
schema:
|
|
type: boolean
|
|
example: false
|
|
- name: default_language
|
|
in: query
|
|
description: |
|
|
What [default language](/help/change-your-language) to use for the account.
|
|
|
|
This controls both the Zulip UI as well as email notifications sent to the user.
|
|
|
|
The value needs to be a standard language code that the Zulip server has
|
|
translation data for; for example, `"en"` for English or `"de"` for German.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/display` endpoint.
|
|
|
|
Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 63).
|
|
schema:
|
|
type: string
|
|
example: en
|
|
- name: default_view
|
|
in: query
|
|
description: |
|
|
The [default view](/help/configure-default-view) used when opening a new
|
|
Zulip web app window or hitting the `Esc` keyboard shortcut repeatedly.
|
|
|
|
- "recent_topics" - Recent conversations view
|
|
- "all_messages" - All messages view
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/display` endpoint.
|
|
|
|
Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 64).
|
|
schema:
|
|
type: string
|
|
example: all_messages
|
|
- name: escape_navigates_to_default_view
|
|
in: query
|
|
description: |
|
|
Whether the escape key navigates to the
|
|
[configured default view](/help/configure-default-view).
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 107).
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: left_side_userlist
|
|
in: query
|
|
description: |
|
|
Whether the users list on left sidebar in narrow windows.
|
|
|
|
This feature is not heavily used and is likely to be reworked.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/display` endpoint.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: emojiset
|
|
in: query
|
|
description: |
|
|
The user's configured [emoji set](/help/emoji-and-emoticons#use-emoticons),
|
|
used to display emoji to the user everywhere they appear in the UI.
|
|
|
|
- "google" - Google modern
|
|
- "google-blob" - Google classic
|
|
- "twitter" - Twitter
|
|
- "text" - Plain text
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/display` endpoint.
|
|
|
|
Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 64).
|
|
schema:
|
|
type: string
|
|
example: "google"
|
|
- name: demote_inactive_streams
|
|
in: query
|
|
description: |
|
|
Whether to [demote inactive streams](/help/manage-inactive-streams) in the left sidebar.
|
|
|
|
- 1 - Automatic
|
|
- 2 - Always
|
|
- 3 - Never
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/display` endpoint.
|
|
schema:
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
example: 1
|
|
- name: user_list_style
|
|
in: query
|
|
description: |
|
|
The style selected by the user for the right sidebar user list.
|
|
|
|
- 1 - Compact
|
|
- 2 - With status
|
|
- 3 - With avatar and status
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 141).
|
|
schema:
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
example: 1
|
|
- name: timezone
|
|
in: query
|
|
description: |
|
|
The IANA identifier of the user's [configured time zone](/help/change-your-timezone).
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/display` endpoint.
|
|
|
|
Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 64).
|
|
schema:
|
|
type: string
|
|
example: "Asia/Kolkata"
|
|
- name: enable_stream_desktop_notifications
|
|
in: query
|
|
description: |
|
|
Enable visual desktop notifications for stream messages.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: enable_stream_email_notifications
|
|
in: query
|
|
description: |
|
|
Enable email notifications for stream messages.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: enable_stream_push_notifications
|
|
in: query
|
|
description: |
|
|
Enable mobile notifications for stream messages.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: enable_stream_audible_notifications
|
|
in: query
|
|
description: |
|
|
Enable audible desktop notifications for stream messages.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: notification_sound
|
|
in: query
|
|
description: |
|
|
Notification sound name.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
|
|
Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 63).
|
|
schema:
|
|
type: string
|
|
example: ding
|
|
- name: enable_desktop_notifications
|
|
in: query
|
|
description: |
|
|
Enable visual desktop notifications for private messages and @-mentions.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: enable_sounds
|
|
in: query
|
|
description: |
|
|
Enable audible desktop notifications for private messages and
|
|
@-mentions.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: email_notifications_batching_period_seconds
|
|
in: query
|
|
description: |
|
|
The duration (in seconds) for which the server should wait to batch
|
|
email notifications before sending them.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 82)
|
|
schema:
|
|
type: integer
|
|
example: 120
|
|
- name: enable_offline_email_notifications
|
|
in: query
|
|
description: |
|
|
Enable email notifications for private messages and @-mentions received
|
|
when the user is offline.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: enable_offline_push_notifications
|
|
in: query
|
|
description: |
|
|
Enable mobile notification for private messages and @-mentions received
|
|
when the user is offline.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: enable_online_push_notifications
|
|
in: query
|
|
description: |
|
|
Enable mobile notification for private messages and @-mentions received
|
|
when the user is online.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: enable_digest_emails
|
|
in: query
|
|
description: |
|
|
Enable digest emails when the user is away.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: enable_marketing_emails
|
|
in: query
|
|
description: |
|
|
Enable marketing emails. Has no function outside Zulip Cloud.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: enable_login_emails
|
|
in: query
|
|
description: |
|
|
Enable email notifications for new logins to account.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: message_content_in_email_notifications
|
|
in: query
|
|
description: |
|
|
Include the message's content in email notifications for new messages.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: pm_content_in_desktop_notifications
|
|
in: query
|
|
description: |
|
|
Include content of private messages in desktop notifications.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: wildcard_mentions_notify
|
|
in: query
|
|
description: |
|
|
Whether wildcard mentions (E.g. @**all**) should send notifications
|
|
like a personal mention.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: desktop_icon_count_display
|
|
in: query
|
|
description: |
|
|
Unread count badge (appears in desktop sidebar and browser tab)
|
|
|
|
- 1 - All unreads
|
|
- 2 - Private messages and mentions
|
|
- 3 - None
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
schema:
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
example: 1
|
|
- name: realm_name_in_email_notifications_policy
|
|
in: query
|
|
description: |
|
|
Whether to [include organization name in subject of message notification
|
|
emails](/help/email-notifications#include-organization-name-in-subject-line).
|
|
|
|
- 1 - Automatic
|
|
- 2 - Always
|
|
- 3 - Never
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 168), replacing the
|
|
previous `realm_name_in_notifications` boolean;
|
|
`true` corresponded to `Always`, and `false` to `Never`.
|
|
|
|
Before Zulip 5.0 (feature level 80), the previous `realm_name_in_notifications`
|
|
setting was managed by the `PATCH /settings/notifications` endpoint.
|
|
schema:
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
example: 1
|
|
- name: presence_enabled
|
|
in: query
|
|
description: |
|
|
Display the presence status to other users when online.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
|
|
the `PATCH /settings/notifications` endpoint.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: enter_sends
|
|
in: query
|
|
description: |
|
|
Whether pressing Enter in the compose box sends a message
|
|
(or saves a message edit).
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 81), this setting was managed by
|
|
the `POST /users/me/enter-sends` endpoint, with the same parameter format.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: send_private_typing_notifications
|
|
in: query
|
|
description: |
|
|
Whether [typing notifications](/help/typing-notifications) be sent when composing
|
|
private messages.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 105).
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: send_stream_typing_notifications
|
|
in: query
|
|
description: |
|
|
Whether [typing notifications](/help/typing-notifications) be sent when composing
|
|
stream messages.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 105).
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: send_read_receipts
|
|
in: query
|
|
description: |
|
|
Whether other users are allowed to see whether you've
|
|
read messages.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 105).
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: email_address_visibility
|
|
in: query
|
|
description: |
|
|
The [policy][permission-level] this user has selected for [which other
|
|
users][help-email-visibility] in this organization can see their real
|
|
email address.
|
|
|
|
- 1 = Everyone
|
|
- 2 = Members only
|
|
- 3 = Administrators only
|
|
- 4 = Nobody
|
|
- 5 = Moderators only
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 163), replacing the
|
|
realm-level setting.
|
|
|
|
[permission-level]: /api/roles-and-permissions#permission-levels
|
|
[help-email-visibility]: /help/configure-email-visibility
|
|
schema:
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
- 4
|
|
- 5
|
|
example: 1
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SuccessIgnoredParameters"
|
|
/streams/{stream_id}/members:
|
|
get:
|
|
operationId: get-subscribers
|
|
summary: Get the subscribers of a stream
|
|
tags: ["streams"]
|
|
description: |
|
|
Get all users subscribed to a stream.
|
|
parameters:
|
|
- $ref: "#/components/parameters/StreamIdInPath"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
subscribers:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
A list containing the IDs of all active users who are subscribed
|
|
to the stream.
|
|
example:
|
|
{"result": "success", "msg": "", "subscribers": [11, 26]}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Invalid stream ID",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON response for when the requested stream does not exist,
|
|
or where the user does not have permission to access the target stream:
|
|
/streams:
|
|
get:
|
|
operationId: get-streams
|
|
summary: Get all streams
|
|
tags: ["streams"]
|
|
description: |
|
|
Get all streams that the user has access to.
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: include
|
|
parameters:
|
|
enum:
|
|
- ""
|
|
- type: include
|
|
parameters:
|
|
enum:
|
|
- include_public
|
|
description: |
|
|
You may pass in one or more of the parameters mentioned above
|
|
as URL query parameters, like so:
|
|
parameters:
|
|
- name: include_public
|
|
in: query
|
|
description: |
|
|
Include all public streams.
|
|
schema:
|
|
type: boolean
|
|
default: true
|
|
example: false
|
|
- name: include_web_public
|
|
in: query
|
|
description: |
|
|
Include all web-public streams.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
- name: include_subscribed
|
|
in: query
|
|
description: |
|
|
Include all streams that the user is subscribed to.
|
|
schema:
|
|
type: boolean
|
|
default: true
|
|
example: false
|
|
- name: include_all_active
|
|
in: query
|
|
description: |
|
|
Include all active streams. The user must have administrative privileges
|
|
to use this parameter.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
- name: include_default
|
|
in: query
|
|
description: |
|
|
Include all default streams for the user's realm.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
- name: include_owner_subscribed
|
|
in: query
|
|
description: |
|
|
If the user is a bot, include all streams that the bot's owner is
|
|
subscribed to.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
streams:
|
|
description: |
|
|
A list of `stream` objects with details on the requested streams.
|
|
type: array
|
|
items:
|
|
allOf:
|
|
- $ref: "#/components/schemas/BasicStreamBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
stream_id: {}
|
|
name: {}
|
|
description: {}
|
|
date_created: {}
|
|
invite_only: {}
|
|
rendered_description: {}
|
|
is_web_public: {}
|
|
stream_post_policy: {}
|
|
message_retention_days:
|
|
nullable: true
|
|
history_public_to_subscribers: {}
|
|
first_message_id:
|
|
nullable: true
|
|
is_announcement_only: {}
|
|
can_remove_subscribers_group_id: {}
|
|
is_default:
|
|
type: boolean
|
|
description: |
|
|
Whether the given stream is a
|
|
[default stream](/help/set-default-streams-for-new-users). Only
|
|
returned if the `include_default` parameter is `true`.
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"result": "success",
|
|
"streams":
|
|
[
|
|
{
|
|
"description": "A Scandinavian country",
|
|
"invite_only": false,
|
|
"name": "Denmark",
|
|
"stream_id": 1,
|
|
},
|
|
{
|
|
"description": "Yet another Italian city",
|
|
"invite_only": false,
|
|
"name": "Rome",
|
|
"stream_id": 2,
|
|
},
|
|
{
|
|
"description": "Located in the United Kingdom",
|
|
"invite_only": false,
|
|
"name": "Scotland",
|
|
"stream_id": 3,
|
|
},
|
|
{
|
|
"description": "A northeastern Italian city",
|
|
"invite_only": false,
|
|
"name": "Venice",
|
|
"stream_id": 4,
|
|
},
|
|
{
|
|
"description": "A city in Italy",
|
|
"invite_only": false,
|
|
"name": "Verona",
|
|
"stream_id": 5,
|
|
},
|
|
{
|
|
"description": "New stream for testing",
|
|
"invite_only": false,
|
|
"name": "new stream",
|
|
"stream_id": 6,
|
|
},
|
|
],
|
|
}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "User not authorized for this query",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON response for when the user is not authorized to use the
|
|
`include_all_active` parameter (i.e. because they are not an organization
|
|
administrator):
|
|
/streams/{stream_id}:
|
|
get:
|
|
operationId: get-stream-by-id
|
|
summary: Get a stream by ID
|
|
tags: ["streams"]
|
|
description: |
|
|
Fetch details for the stream with the ID `stream_id`.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 132).
|
|
parameters:
|
|
- $ref: "#/components/parameters/StreamIdInPath"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
stream:
|
|
$ref: "#/components/schemas/BasicStream"
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"result": "success",
|
|
"stream":
|
|
{
|
|
"description": "A Scandinavian country",
|
|
"first_message_id": 1,
|
|
"history_public_to_subscribers": true,
|
|
"invite_only": false,
|
|
"is_announcement_only": false,
|
|
"is_web_public": false,
|
|
"message_retention_days": null,
|
|
"name": "Denmark",
|
|
"rendered_description": "<p>A Scandinavian country</p>",
|
|
"stream_id": 7,
|
|
"stream_post_policy": 1,
|
|
"can_remove_subscribers_group_id": 2,
|
|
},
|
|
}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Invalid stream ID",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON response for when the stream ID is not valid.
|
|
delete:
|
|
operationId: archive-stream
|
|
summary: Archive a stream
|
|
tags: ["streams"]
|
|
description: |
|
|
[Archive the stream](/help/archive-a-stream) with the ID `stream_id`.
|
|
parameters:
|
|
- $ref: "#/components/parameters/StreamIdInPath"
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Invalid stream ID",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON response for when the supplied stream does not exist:
|
|
patch:
|
|
operationId: update-stream
|
|
summary: Update a stream
|
|
tags: ["streams"]
|
|
description: |
|
|
Configure the stream with the ID `stream_id`. This endpoint supports
|
|
an organization administrator editing any property of a stream,
|
|
including:
|
|
|
|
- Stream [name](/help/rename-a-stream) and [description](/help/change-the-stream-description)
|
|
- Stream [permissions](/help/stream-permissions), including
|
|
[privacy](/help/change-the-privacy-of-a-stream) and [who can
|
|
send](/help/stream-sending-policy).
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: include
|
|
parameters:
|
|
enum:
|
|
- new_name
|
|
- description
|
|
- is_private
|
|
parameters:
|
|
- $ref: "#/components/parameters/StreamIdInPath"
|
|
- name: description
|
|
in: query
|
|
description: |
|
|
The new [description](/help/change-the-stream-description) for
|
|
the stream, in text/markdown format.
|
|
|
|
Clients should use the `max_stream_description_length` returned
|
|
by the [`POST /register`](/api/register-queue) endpoint to
|
|
determine the maximum stream description length.
|
|
|
|
**Changes**: Removed unnecessary JSON-encoding of this parameter in
|
|
Zulip 4.0 (feature level 64).
|
|
schema:
|
|
type: string
|
|
example: "Discuss Italian history and travel destinations."
|
|
required: false
|
|
allowEmptyValue: true
|
|
- name: new_name
|
|
in: query
|
|
description: |
|
|
The new name for the stream.
|
|
|
|
Clients should use the `max_stream_name_length` returned by the
|
|
[`POST /register`](/api/register-queue) endpoint to determine
|
|
the maximum stream name length.
|
|
|
|
**Changes**: Removed unnecessary JSON-encoding of this parameter in
|
|
Zulip 4.0 (feature level 64).
|
|
schema:
|
|
type: string
|
|
example: Italy
|
|
required: false
|
|
- name: is_private
|
|
in: query
|
|
description: |
|
|
Change whether the stream is a private stream.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
required: false
|
|
- name: is_announcement_only
|
|
in: query
|
|
deprecated: true
|
|
description: |
|
|
Whether the stream is limited to announcements.
|
|
|
|
**Changes**: Deprecated in Zulip 3.0 (feature level 1). Clients
|
|
should use `stream_post_policy` instead.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
required: false
|
|
- name: is_web_public
|
|
in: query
|
|
description: |
|
|
Change whether the stream is a web-public stream.
|
|
|
|
Note that creating web-public streams requires the
|
|
`WEB_PUBLIC_STREAMS_ENABLED` [server setting][server-settings]
|
|
to be enabled on the Zulip server in question, the organization
|
|
to have enabled the `enable_spectator_access` realm setting, and
|
|
the current use to have permission under the organization's
|
|
`create_web_public_stream_policy` realm setting.
|
|
|
|
[server-settings]: https://zulip.readthedocs.io/en/stable/production/settings.html
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 98).
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
required: false
|
|
- name: history_public_to_subscribers
|
|
in: query
|
|
description: |
|
|
Whether the stream's message history should be available to
|
|
newly subscribed members, or users can only access messages
|
|
they actually received while subscribed to the stream.
|
|
|
|
Corresponds to the [shared history](/help/stream-permissions)
|
|
option in documentation.
|
|
|
|
It's an error for this parameter to be false for a public or
|
|
web-public stream and when is_private is false.
|
|
|
|
**Changes**: Before Zulip 6.0 (feature level 136), `history_public_to_subscribers`
|
|
was silently ignored unless the request also contained either `is_private` or
|
|
`is_web_public`.
|
|
schema:
|
|
type: boolean
|
|
example: false
|
|
required: false
|
|
- $ref: "#/components/parameters/StreamPostPolicy"
|
|
- $ref: "#/components/parameters/MessageRetentionDays"
|
|
- $ref: "#/components/parameters/CanRemoveSubscribersGroupId"
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/JsonError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Invalid stream ID",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON response for when the supplied stream does not exist:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/JsonError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Invalid parameters",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON response for when invalid combination of stream permission
|
|
parameters are passed.
|
|
/streams/{stream_id}/email_address:
|
|
get:
|
|
operationId: get-stream-email-address
|
|
summary: Get the email address of a stream
|
|
tags: ["streams"]
|
|
description: |
|
|
Get email address of a stream.
|
|
|
|
**Changes**: New in Zulip 7.5 (feature level 186).
|
|
parameters:
|
|
- $ref: "#/components/parameters/StreamIdInPath"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
email:
|
|
type: string
|
|
description: |
|
|
Email address of the stream.
|
|
example:
|
|
{
|
|
"result": "success",
|
|
"msg": "",
|
|
"email": "test_stream.af64447e9e39374841063747ade8e6b0.show-sender@testserver",
|
|
}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Invalid stream ID",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON response for when the supplied stream does not exist:
|
|
/streams/{stream_id}/delete_topic:
|
|
post:
|
|
operationId: delete-topic
|
|
summary: Delete a topic
|
|
tags: ["streams"]
|
|
description: |
|
|
Delete all messages in a topic.
|
|
|
|
Topics are a field on messages (not an independent
|
|
data structure), so deleting all the messages in the topic
|
|
deletes the topic from Zulip.
|
|
|
|
**Changes**: Before Zulip 6.0 (feature level 147), this
|
|
request did a single atomic operation, which could time out
|
|
for very large topics. It now deletes messages in batches,
|
|
starting with the newest messages, so that progress will be
|
|
made even if the request times out.
|
|
|
|
As of feature level 154, in case of timeout, a success response
|
|
with "partially_completed" result will now be returned.
|
|
parameters:
|
|
- $ref: "#/components/parameters/StreamIdInPath"
|
|
- name: topic_name
|
|
in: query
|
|
description: |
|
|
The name of the topic to delete.
|
|
schema:
|
|
type: string
|
|
example: new coffee machine
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Success or partial success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/JsonSuccess"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- allOf:
|
|
- $ref: "#/components/schemas/PartiallyCompleted"
|
|
- example:
|
|
{
|
|
"code": "REQUEST_TIMEOUT",
|
|
"msg": "",
|
|
"result": "partially_completed",
|
|
}
|
|
description: |
|
|
If the request exceeds its processing time limit after having
|
|
successfully marked some messages as read, response code 200
|
|
with result "partially_completed" and code "REQUEST_TIMEOUT" will be returned like this:
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"msg": "Must be an organization administrator",
|
|
"code": "UNAUTHORIZED_PRINCIPAL",
|
|
}
|
|
description: |
|
|
Error when the user does not have permission
|
|
to delete topics in this organization:
|
|
/typing:
|
|
post:
|
|
operationId: set-typing-status
|
|
summary: Set "typing" status
|
|
tags: ["users"]
|
|
description: |
|
|
Notify other users whether the current user is [typing a message](/help/typing-notifications).
|
|
|
|
Clients implementing Zulip's typing notifications protocol should work as follows:
|
|
|
|
- Send a request to this endpoint with `"op": "start"` when a user starts typing a message,
|
|
and also every 10 seconds (`TYPING_STARTED_WAIT_PERIOD`) that the user continues to
|
|
actively type or otherwise interact with the compose UI (e.g. interacting with the
|
|
compose box emoji picker).
|
|
- Send a request to this endpoint with `"op": "stop"` when a user pauses using the
|
|
compose UI for at least 5 seconds (`TYPING_STOPPED_WAIT_PERIOD`) or cancels
|
|
the compose action (if it had previously sent a "start" operation for that
|
|
compose action).
|
|
- Start displaying "Sender is typing" for a given conversation when the client
|
|
receives an `"op": "start"` event from the [`GET /events`](/api/get-events#typing-start)
|
|
endpoint.
|
|
- Continue displaying "Sender is typing" until they receive an `"op": "stop"` event
|
|
from the [`GET /events`](/api/get-events#typing-stop) endpoint or
|
|
15 seconds (`TYPING_STARTED_EXPIRY_PERIOD`) have passed without a new `"op": "start"`
|
|
event for that conversation.
|
|
- Support for displaying stream typing notifications was new in Zulip 4.0
|
|
(feature level 58). Clients should indicate they support processing stream typing
|
|
events via the `stream_typing_notifications` value in the `client_capabilities`
|
|
parameter to [`POST /register`](/api/register-queue#parameter-client_capabilities)
|
|
endpoint.
|
|
|
|
This protocol is designed to allow the server-side typing notifications implementation
|
|
to be stateless while being resilient; network failures cannot result in a user being
|
|
incorrectly displayed as perpetually typing.
|
|
|
|
See
|
|
[the typing notification docs](https://zulip.readthedocs.io/en/latest/subsystems/typing-indicators.html)
|
|
for additional design details on Zulip's typing notifications protocol.
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: exclude
|
|
parameters:
|
|
enum:
|
|
- topic
|
|
parameters:
|
|
- name: type
|
|
in: query
|
|
description: |
|
|
Type of the message being composed.
|
|
|
|
**Changes**: In Zulip 7.0 (feature level 174), `"direct"` was added
|
|
as the preferred way to indicate a direct message is being composed,
|
|
becoming the default value for this parameter and deprecating the
|
|
original `"private"`.
|
|
|
|
New in Zulip 4.0 (feature level 58). Previously, typing notifications
|
|
were only for direct messages.
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- direct
|
|
- stream
|
|
- private
|
|
default: direct
|
|
example: direct
|
|
- name: op
|
|
in: query
|
|
description: |
|
|
Whether the user has started (`"start"`) or stopped (`"stop"`) typing.
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- start
|
|
- stop
|
|
example: start
|
|
required: true
|
|
- name: to
|
|
in: query
|
|
description: |
|
|
For `"direct"` type it is the user IDs of the recipients of the message
|
|
being typed. Send a JSON-encoded list of user IDs. (Use a list even if
|
|
there is only one recipient.)
|
|
|
|
For `"stream"` type it is a single element list containing ID of stream in
|
|
which the message is being typed.
|
|
|
|
**Changes**: Support for typing notifications for stream messages
|
|
is new in Zulip 4.0 (feature level 58). Previously, typing
|
|
notifications were only for direct messages.
|
|
|
|
Before Zulip 2.0.0, this parameter accepted only a JSON-encoded
|
|
list of email addresses. Support for the email address-based format was
|
|
removed in Zulip 3.0 (feature level 11).
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
example: [9, 10]
|
|
required: true
|
|
- name: topic
|
|
in: query
|
|
description: |
|
|
Topic to which message is being typed. Required for the `"stream"` type.
|
|
Ignored in the case of `"direct"` type.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 58). Previously, typing
|
|
notifications were only for direct messages.
|
|
schema:
|
|
type: string
|
|
example: typing notifications
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Cannot send to multiple streams",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON error response for when user sends to multiple streams:
|
|
|
|
/user_groups/create:
|
|
post:
|
|
operationId: create-user-group
|
|
summary: Create a user group
|
|
tags: ["users"]
|
|
description: |
|
|
Create a new [user group](/help/user-groups).
|
|
parameters:
|
|
- name: name
|
|
in: query
|
|
description: |
|
|
The name of the user group.
|
|
schema:
|
|
type: string
|
|
example: marketing
|
|
required: true
|
|
- name: description
|
|
in: query
|
|
description: |
|
|
The description of the user group.
|
|
schema:
|
|
type: string
|
|
example: The marketing team.
|
|
required: true
|
|
- name: members
|
|
in: query
|
|
description: |
|
|
An array containing the user IDs of the initial members for the
|
|
new user group.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
example: [1, 2, 3, 4]
|
|
required: true
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Invalid user ID: 500",
|
|
}
|
|
description: |
|
|
An example JSON error response for when the one of the users does not exist:
|
|
/user_groups/{user_group_id}/members:
|
|
post:
|
|
operationId: update-user-group-members
|
|
summary: Update user group members
|
|
tags: ["users"]
|
|
description: |
|
|
Update the members of a [user group](/help/user-groups).
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: exclude
|
|
parameters:
|
|
enum:
|
|
- delete
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserGroupId"
|
|
- name: delete
|
|
in: query
|
|
description: |
|
|
The list of user IDs to be removed from the user group.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
example: [10]
|
|
required: false
|
|
- name: add
|
|
in: query
|
|
description: |
|
|
The list of user IDs to be added to the user group.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
example: [12, 13]
|
|
required: false
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
get:
|
|
operationId: get-user-group-members
|
|
summary: Get user group members
|
|
tags: ["users"]
|
|
description: |
|
|
Get the members of a [user group](/help/user-groups).
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 127).
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserGroupId"
|
|
- $ref: "#/components/parameters/DirectMemberOnly"
|
|
responses:
|
|
"200":
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
members:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
A list containing the user IDs of members of the user group.
|
|
example:
|
|
{"msg": "", "result": "success", "members": [10, 12]}
|
|
/user_groups/{user_group_id}:
|
|
patch:
|
|
operationId: update-user-group
|
|
summary: Update a user group
|
|
tags: ["users"]
|
|
description: |
|
|
Update the name or description of a [user group](/help/user-groups).
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserGroupId"
|
|
- name: name
|
|
in: query
|
|
description: |
|
|
The new name of the group.
|
|
|
|
**Changes**: Before Zulip 7.0 (feature level 165), this was
|
|
a required field.
|
|
schema:
|
|
type: string
|
|
example: marketing team
|
|
- name: description
|
|
in: query
|
|
description: |
|
|
The new description of the group.
|
|
|
|
**Changes**: Before Zulip 7.0 (feature level 165), this was
|
|
a required field.
|
|
schema:
|
|
type: string
|
|
example: The marketing team.
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Invalid user group",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON response when the user group ID is invalid:
|
|
delete:
|
|
operationId: remove-user-group
|
|
summary: Delete a user group
|
|
tags: ["users"]
|
|
description: |
|
|
Delete a [user group](/help/user-groups).
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserGroupId"
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Invalid user group",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
An example JSON error response for an invalid user group ID:
|
|
|
|
/user_groups:
|
|
get:
|
|
operationId: get-user-groups
|
|
summary: Get user groups
|
|
tags: ["users"]
|
|
description: |
|
|
Fetches all of the user groups in the organization.
|
|
|
|
!!! warn ""
|
|
|
|
**Note**: This endpoint is only available to [members and
|
|
administrators](/help/roles-and-permissions); bots and guests
|
|
cannot use this endpoint.
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
user_groups:
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
description:
|
|
type: string
|
|
description: |
|
|
The human-readable description of the user group.
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The user group's integer ID.
|
|
members:
|
|
type: array
|
|
description: |
|
|
The integer user IDs of the user group members.
|
|
items:
|
|
type: integer
|
|
direct_subgroup_ids:
|
|
type: array
|
|
description: |
|
|
The integer user group IDs of the direct subgroups.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 131).
|
|
Introduced in feature level 127 as `subgroups`, but
|
|
clients can ignore older events as this feature level
|
|
predates subgroups being fully implemented.
|
|
items:
|
|
type: integer
|
|
name:
|
|
type: string
|
|
description: |
|
|
User group name.
|
|
is_system_group:
|
|
type: boolean
|
|
description: |
|
|
Whether the user group is a system group which cannot be
|
|
modified by users.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 93).
|
|
description: |
|
|
A list of `user_group` objects.
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"result": "success",
|
|
"user_groups":
|
|
[
|
|
{
|
|
"description": "Owners of this organization",
|
|
"id": 1,
|
|
"name": "@role:owners",
|
|
"members": [1],
|
|
"direct_subgroup_ids": [],
|
|
"is_system_group": true,
|
|
},
|
|
{
|
|
"description": "Administrators of this organization, including owners",
|
|
"id": 2,
|
|
"name": "@role:administrators",
|
|
"members": [2],
|
|
"direct_subgroup_ids": [1],
|
|
"is_system_group": true,
|
|
},
|
|
{
|
|
"description": "Characters of Hamlet",
|
|
"id": 3,
|
|
"name": "hamletcharacters",
|
|
"members": [3, 4],
|
|
"direct_subgroup_ids": [],
|
|
"is_system_group": false,
|
|
},
|
|
],
|
|
}
|
|
/user_groups/{user_group_id}/subgroups:
|
|
post:
|
|
operationId: update-user-group-subgroups
|
|
summary: Update subgroups of a user group
|
|
tags: ["users"]
|
|
description: |
|
|
Update the subgroups of a [user group](/help/user-groups).
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 127).
|
|
x-curl-examples-parameters:
|
|
oneOf:
|
|
- type: exclude
|
|
parameters:
|
|
enum:
|
|
- delete
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserGroupId"
|
|
- name: delete
|
|
in: query
|
|
description: |
|
|
The list of user group IDs to be removed from the user group.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
example: [10]
|
|
required: false
|
|
- name: add
|
|
in: query
|
|
description: |
|
|
The list of user group IDs to be added to the user group.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
example: [9, 10]
|
|
required: false
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/SimpleSuccess"
|
|
get:
|
|
operationId: get-user-group-subgroups
|
|
summary: Get subgroups of the user group
|
|
tags: ["users"]
|
|
description: |
|
|
Get the subgroups of a [user group](/help/user-groups).
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 127).
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserGroupId"
|
|
- name: direct_subgroup_only
|
|
in: query
|
|
description: |
|
|
Whether to consider only direct subgroups of the user group
|
|
or subgroups of subgroups also.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
required: false
|
|
responses:
|
|
"200":
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
subgroups:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
A list containing the IDs of subgroups of the user group.
|
|
example:
|
|
{"msg": "", "result": "success", "subgroups": [2, 3]}
|
|
/user_groups/{user_group_id}/members/{user_id}:
|
|
get:
|
|
operationId: get-is-user-group-member
|
|
summary: Get user group membership status
|
|
tags: ["users"]
|
|
description: |
|
|
Check whether a user is member of user group.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 127).
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserGroupId"
|
|
- $ref: "#/components/parameters/UserId"
|
|
- $ref: "#/components/parameters/DirectMemberOnly"
|
|
responses:
|
|
"200":
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
is_user_group_member:
|
|
type: boolean
|
|
description: |
|
|
Whether the user is member of user group.
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"result": "success",
|
|
"is_user_group_member": false,
|
|
}
|
|
/real-time:
|
|
# This entry is a hack; it exists to give us a place to put the text
|
|
# documenting the parameters for call_on_each_event and friends.
|
|
post:
|
|
tags: ["real_time_events"]
|
|
description: |
|
|
(Ignored)
|
|
parameters:
|
|
- $ref: "#/components/parameters/Event_types"
|
|
- $ref: "#/components/parameters/Narrow"
|
|
- $ref: "#/components/parameters/AllPublicStreams"
|
|
security:
|
|
- basicAuth: []
|
|
responses:
|
|
# Makeshift response for this hack entry.
|
|
"200":
|
|
description: Success
|
|
/rest-error-handling:
|
|
post:
|
|
operationId: rest-error-handling
|
|
summary: Error handling
|
|
tags: ["real_time_events"]
|
|
description: |
|
|
Common error to many endpoints
|
|
responses:
|
|
"400":
|
|
description: |
|
|
Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/InvalidApiKeyError"
|
|
- $ref: "#/components/schemas/MissingArgumentError"
|
|
- $ref: "#/components/schemas/UserNotAuthorizedError"
|
|
"401":
|
|
description: |
|
|
Unauthorized.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/UserDeactivatedError"
|
|
- $ref: "#/components/schemas/RealmDeactivatedError"
|
|
"429":
|
|
description: |
|
|
Rate limit exceeded.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/RateLimitedError"
|
|
/zulip-outgoing-webhook:
|
|
post:
|
|
operationId: zulip-outgoing-webhooks
|
|
summary: Outgoing webhooks
|
|
tags: ["webhooks"]
|
|
description: |
|
|
Outgoing webhooks allow you to build or set up Zulip integrations which are
|
|
notified when certain types of messages are sent in Zulip.
|
|
responses:
|
|
"200":
|
|
description: |
|
|
Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
This is an example of the JSON payload that the Zulip server will `POST`
|
|
to your server:
|
|
properties:
|
|
bot_email:
|
|
type: string
|
|
description: |
|
|
Email of the bot user.
|
|
bot_full_name:
|
|
type: string
|
|
description: |
|
|
The full name of the bot user.
|
|
data:
|
|
type: string
|
|
description: |
|
|
The message content, in raw Markdown format (not rendered to HTML).
|
|
trigger:
|
|
type: string
|
|
description: |
|
|
What aspect of the message triggered the outgoing webhook notification.
|
|
Possible values include `private_message` and `mention`.
|
|
token:
|
|
type: string
|
|
description: |
|
|
A string of alphanumeric characters that can be used to authenticate the
|
|
webhook request (each bot user uses a fixed token). You can get the token used by a given outgoing webhook bot
|
|
in the `zuliprc` file downloaded when creating the bot.
|
|
message:
|
|
description: |
|
|
A dictionary containing details on the message that triggered the
|
|
outgoing webhook, in the format used by [`GET /messages`](/api/get-messages).
|
|
allOf:
|
|
- $ref: "#/components/schemas/MessagesBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
avatar_url:
|
|
nullable: true
|
|
client: {}
|
|
content: {}
|
|
content_type: {}
|
|
display_recipient: {}
|
|
edit_history: {}
|
|
id: {}
|
|
is_me_message: {}
|
|
last_edit_timestamp: {}
|
|
reactions: {}
|
|
recipient_id: {}
|
|
sender_email: {}
|
|
sender_full_name: {}
|
|
sender_id: {}
|
|
sender_realm_str: {}
|
|
stream_id: {}
|
|
subject: {}
|
|
submessages: {}
|
|
timestamp: {}
|
|
topic_links: {}
|
|
type: {}
|
|
rendered_content:
|
|
type: string
|
|
description: |
|
|
The content/body of the message rendered in HTML.
|
|
example:
|
|
{
|
|
"data": "@**Outgoing webhook test** Zulip is the world\u2019s most productive group chat!",
|
|
"trigger": "mention",
|
|
"token": "xvOzfurIutdRRVLzpXrIIHXJvNfaJLJ0",
|
|
"message":
|
|
{
|
|
"subject": "Verona2",
|
|
"sender_email": "iago@zulip.com",
|
|
"timestamp": 1527876931,
|
|
"client": "website",
|
|
"submessages": [],
|
|
"recipient_id": 20,
|
|
"topic_links": [],
|
|
"sender_full_name": "Iago",
|
|
"avatar_url": "https://secure.gravatar.com/avatar/1f4f1575bf002ae562fea8fc4b861b09?d=identicon&version=1",
|
|
"rendered_content": "<p><span class=\"user-mention\" data-user-id=\"25\">@Outgoing webhook test</span> Zulip is the world\u2019s most productive group chat!</p>",
|
|
"sender_id": 5,
|
|
"stream_id": 5,
|
|
"content": "@**Outgoing webhook test** Zulip is the world\u2019s most productive group chat!",
|
|
"display_recipient": "Verona",
|
|
"type": "stream",
|
|
"id": 112,
|
|
"is_me_message": false,
|
|
"reactions": [],
|
|
"sender_realm_str": "zulip",
|
|
},
|
|
"bot_email": "outgoing-bot@localhost",
|
|
"bot_full_name": "Outgoing webhook test",
|
|
}
|
|
|
|
/calls/bigbluebutton/create:
|
|
get:
|
|
tags: ["streams"]
|
|
operationId: create-big-blue-button-video-call
|
|
summary: Create BigBlueButton video call
|
|
description: |
|
|
Create a video call URL for a BigBlueButton video call.
|
|
Requires BigBlueButton to be configured on the Zulip server.
|
|
parameters:
|
|
- in: query
|
|
name: meeting_name
|
|
schema:
|
|
type: string
|
|
required: true
|
|
description: |
|
|
Title to use for the BigBlueButton meeting.
|
|
|
|
A good choice is something like "{stream_name} meeting".
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
url:
|
|
description: |
|
|
The URL for the BigBlueButton video call.
|
|
type: string
|
|
example: "/calls/bigbluebutton/join?meeting_id=%22zulip-something%22&password=%22something%22&name=%22your_meeting_name%22&checksum=%22somechecksum%22"
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"result": "success",
|
|
"url": "/calls/bigbluebutton/join?meeting_id=%22zulip-something%22&password=%22something%22&checksum=%22somechecksum%22",
|
|
}
|
|
|
|
components:
|
|
#######################
|
|
# Security definitions
|
|
#######################
|
|
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.
|
|
|
|
schemas:
|
|
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.
|
|
EventIdSchema:
|
|
type: integer
|
|
description: |
|
|
The ID of the event. Events appear in increasing order but may not be consecutive.
|
|
EventTypeSchema:
|
|
type: string
|
|
description: |
|
|
The event's type, relevant both for client-side dispatch and server-side
|
|
filtering by event type in [POST /register](/api/register-queue).
|
|
Attachments:
|
|
type: object
|
|
description: |
|
|
Dictionary containing details of a file uploaded by a user.
|
|
additionalProperties: false
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The unique ID for the attachment.
|
|
name:
|
|
type: string
|
|
description: |
|
|
Name of the uploaded file.
|
|
path_id:
|
|
type: string
|
|
description: |
|
|
A representation of the path of the file within the
|
|
repository of user-uploaded files. If the `path_id` of a
|
|
file is `{realm_id}/ab/cdef/temp_file.py`, its URL will be:
|
|
`{server_url}/user_uploads/{realm_id}/ab/cdef/temp_file.py`.
|
|
size:
|
|
type: integer
|
|
description: |
|
|
Size of the file in bytes.
|
|
create_time:
|
|
type: integer
|
|
description: |
|
|
Time when the attachment was uploaded as a UNIX timestamp
|
|
multiplied by 1000 (matching the format of getTime() in JavaScript).
|
|
|
|
**Changes**: Changed in Zulip 3.0 (feature level 22). This field was
|
|
previously a floating point number.
|
|
messages:
|
|
type: array
|
|
description: |
|
|
Contains basic details on any Zulip messages that have been
|
|
sent referencing this [uploaded file](/api/upload-file).
|
|
This includes messages sent by any user in the Zulip
|
|
organization who sent a message containing a link to the
|
|
uploaded file.
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
date_sent:
|
|
type: integer
|
|
description: |
|
|
Time when the message was sent as a UNIX timestamp
|
|
multiplied by 1000 (matching the format of getTime() in JavaScript).
|
|
|
|
**Changes**: Changed in Zulip 3.0 (feature level 22). This
|
|
field was previously strangely called `name` and was a floating
|
|
point number.
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The unique message ID. Messages should always be
|
|
displayed sorted by ID.
|
|
BasicStream:
|
|
allOf:
|
|
- $ref: "#/components/schemas/BasicStreamBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
stream_id: {}
|
|
name: {}
|
|
description: {}
|
|
date_created: {}
|
|
invite_only: {}
|
|
rendered_description: {}
|
|
is_web_public: {}
|
|
stream_post_policy: {}
|
|
message_retention_days:
|
|
nullable: true
|
|
history_public_to_subscribers: {}
|
|
first_message_id:
|
|
nullable: true
|
|
is_announcement_only: {}
|
|
can_remove_subscribers_group_id: {}
|
|
BasicStreamBase:
|
|
type: object
|
|
description: |
|
|
Object containing basic details about the stream.
|
|
properties:
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
The unique ID of the stream.
|
|
name:
|
|
type: string
|
|
description: |
|
|
The name of the stream.
|
|
description:
|
|
type: string
|
|
description: |
|
|
The short description of the stream in text/markdown format,
|
|
intended to be used to prepopulate UI for editing a stream's
|
|
description.
|
|
date_created:
|
|
type: integer
|
|
description: |
|
|
The UNIX timestamp for when the stream was created, in UTC seconds.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 30).
|
|
invite_only:
|
|
type: boolean
|
|
description: |
|
|
Specifies whether the stream is private or not.
|
|
Only people who have been invited can access a private stream.
|
|
rendered_description:
|
|
type: string
|
|
description: |
|
|
The short description of the stream rendered as HTML, intended to
|
|
be used when displaying the stream description in a UI.
|
|
|
|
One should use the standard Zulip rendered_markdown CSS when
|
|
displaying this content so that emoji, LaTeX, and other syntax
|
|
work correctly. And any client-side security logic for
|
|
user-generated message content should be applied when displaying
|
|
this HTML as though it were the body of a Zulip message.
|
|
is_web_public:
|
|
type: boolean
|
|
description: |
|
|
Whether the stream has been configured to allow unauthenticated
|
|
access to its message history from the web.
|
|
stream_post_policy:
|
|
type: integer
|
|
description: |
|
|
[Policy][permission-level] for which users can post messages to the stream.
|
|
|
|
- 1 = Any user can post.
|
|
- 2 = Only administrators can post.
|
|
- 3 = Only [full members][calc-full-member] can post.
|
|
- 4 = Only moderators can post.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 1), replacing the previous
|
|
`is_announcement_only` boolean.
|
|
|
|
[permission-level]: /api/roles-and-permissions#permission-levels
|
|
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
|
|
message_retention_days:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
Number of days that messages sent to this stream will be stored
|
|
before being automatically deleted by the [message retention
|
|
policy](/help/message-retention-policy). There are two special values:
|
|
|
|
- `null`, the default, means the stream will inherit the organization
|
|
level setting.
|
|
- `-1` encodes retaining messages in this stream forever.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 17).
|
|
history_public_to_subscribers:
|
|
type: boolean
|
|
description: |
|
|
Whether the history of the stream is public to its subscribers.
|
|
|
|
Currently always true for public streams (i.e. `"invite_only": false` implies
|
|
`"history_public_to_subscribers": true`), but clients should not make that
|
|
assumption, as we may change that behavior in the future.
|
|
first_message_id:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
The ID of the first message in the stream.
|
|
|
|
Intended to help clients determine whether they need to display
|
|
UI like the "more topics" widget that would suggest the stream
|
|
has older history that can be accessed.
|
|
|
|
Is `null` for streams with no message history.
|
|
is_announcement_only:
|
|
type: boolean
|
|
deprecated: true
|
|
description: |
|
|
Whether the given stream is announcement only or not.
|
|
|
|
**Changes**: Deprecated in Zulip 3.0 (feature level 1). Clients
|
|
should use `stream_post_policy` instead.
|
|
can_remove_subscribers_group_id:
|
|
type: integer
|
|
description: |
|
|
ID of the user group whose members are allowed to unsubscribe others
|
|
from the stream.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 142).
|
|
BasicBot:
|
|
allOf:
|
|
- $ref: "#/components/schemas/BasicBotBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
user_id: {}
|
|
full_name: {}
|
|
api_key: {}
|
|
default_sending_stream:
|
|
nullable: true
|
|
default_events_register_stream:
|
|
nullable: true
|
|
default_all_public_streams: {}
|
|
avatar_url: {}
|
|
owner_id:
|
|
nullable: true
|
|
services: {}
|
|
BasicBotBase:
|
|
type: object
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The user ID of the bot.
|
|
full_name:
|
|
type: string
|
|
description: |
|
|
The full name of the bot.
|
|
api_key:
|
|
type: string
|
|
description: |
|
|
The API key of the bot which it uses to make API requests.
|
|
default_sending_stream:
|
|
type: string
|
|
nullable: true
|
|
description: |
|
|
The default sending stream of the bot. If `null`, the bot doesn't
|
|
have a default sending stream.
|
|
default_events_register_stream:
|
|
type: string
|
|
nullable: true
|
|
description: |
|
|
The default stream for which the bot receives events/register data.
|
|
If `null`, the bot doesn't have such a default stream.
|
|
default_all_public_streams:
|
|
type: boolean
|
|
description: |
|
|
Whether the bot can send messages to all streams by default.
|
|
avatar_url:
|
|
type: string
|
|
description: |
|
|
The URL of the bot's avatar.
|
|
owner_id:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
The user ID of the bot's owner.
|
|
|
|
If `null`, the bot has no owner.
|
|
services:
|
|
type: array
|
|
description: |
|
|
The "Services" array contains extra configuration fields only relevant
|
|
for Outgoing webhook bots and Embedded bots. It is always a single-element
|
|
array.
|
|
|
|
We consider this part of the Zulip API to be unstable; it is used only for
|
|
UI elements for administering bots and is likely to change.
|
|
items:
|
|
description: |
|
|
Object containing details extra details. Which fields appear depend
|
|
on the type of bot.
|
|
oneOf:
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
When the bot is an outgoing webhook bot.
|
|
properties:
|
|
base_url:
|
|
type: string
|
|
description: |
|
|
The URL the outgoing webhook is configured to post to.
|
|
token:
|
|
type: string
|
|
description: |
|
|
A unique token that the third-party service can use to confirm
|
|
that the request is indeed coming from Zulip.
|
|
interface:
|
|
type: integer
|
|
description: |
|
|
Integer indicating what format requests are posted in:
|
|
|
|
- 1 = Zulip's native outgoing webhook format.
|
|
- 2 = Emulate the Slack outgoing webhook format.
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
When the bot is an embedded bot.
|
|
properties:
|
|
service_name:
|
|
type: string
|
|
description: |
|
|
The name of the bot.
|
|
config_data:
|
|
$ref: "#/components/schemas/Config"
|
|
Bot:
|
|
allOf:
|
|
- $ref: "#/components/schemas/BasicBotBase"
|
|
- description: |
|
|
Object containing details of a bot.
|
|
additionalProperties: false
|
|
properties:
|
|
user_id: {}
|
|
full_name: {}
|
|
api_key: {}
|
|
default_sending_stream:
|
|
nullable: true
|
|
default_events_register_stream:
|
|
nullable: true
|
|
default_all_public_streams: {}
|
|
avatar_url: {}
|
|
owner_id:
|
|
nullable: true
|
|
services: {}
|
|
email:
|
|
type: string
|
|
description: |
|
|
The email of the bot.
|
|
bot_type:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
An integer describing the type of bot:
|
|
|
|
- `1` for a `Generic` bot.
|
|
- `2` for an `Incoming webhook` bot.
|
|
- `3` for an `Outgoing webhook` bot.
|
|
- `4` for an `Embedded` bot.
|
|
is_active:
|
|
type: boolean
|
|
description: |
|
|
A boolean describing whether the user account has been deactivated.
|
|
Config:
|
|
type: object
|
|
description: |
|
|
A "string: string" dictionary which describes the configuration
|
|
for the embedded bot (usually details like API keys).
|
|
additionalProperties:
|
|
description: |
|
|
String describing the config data.
|
|
type: string
|
|
CustomProfileField:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Dictionary containing the details of a custom profile field configured
|
|
for this organization.
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the custom profile field. This will be referenced in the custom
|
|
profile fields section of user objects.
|
|
type:
|
|
type: integer
|
|
description: |
|
|
An integer indicating the type of the custom profile field, which determines
|
|
how it is configured and displayed to users.
|
|
|
|
See the [Custom profile fields](/help/custom-profile-fields#profile-field-types)
|
|
article for details on what each type means.
|
|
|
|
- **1**: Short text
|
|
- **2**: Long text
|
|
- **3**: List of options
|
|
- **4**: Date picker
|
|
- **5**: Link
|
|
- **6**: Person picker
|
|
- **7**: External account
|
|
- **8**: Pronouns
|
|
|
|
**Changes**: Field type `8` added in Zulip 6.0 (feature level 151).
|
|
order:
|
|
type: integer
|
|
description: |
|
|
Custom profile fields are displayed in both settings UI and
|
|
UI showing users' profiles in increasing `order`.
|
|
name:
|
|
type: string
|
|
description: |
|
|
The name of the custom profile field.
|
|
hint:
|
|
type: string
|
|
description: |
|
|
The help text to be displayed for the custom profile field in user-facing
|
|
settings UI for configuring custom profile fields.
|
|
field_data:
|
|
type: string
|
|
description: |
|
|
Field types 3 (List of options) and 7 (External account) support storing
|
|
additional configuration for the field type in the `field_data` attribute.
|
|
|
|
For field type 3 (List of options), this attribute is a JSON dictionary
|
|
defining the choices and the order they will be displayed in the
|
|
dropdown UI for individual users to select an option.
|
|
|
|
The interface for field type 7 is not yet stabilized.
|
|
display_in_profile_summary:
|
|
type: boolean
|
|
description: |
|
|
Whether the custom profile field, display or not on the user card.
|
|
|
|
Currently it's value not allowed to be `true` of `Long text` and `Person picker`
|
|
[profile field types](/help/custom-profile-fields#profile-field-types).
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 146).
|
|
Hotspot:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Dictionary containing details of a single hotspot.
|
|
properties:
|
|
delay:
|
|
type: number
|
|
description: |
|
|
The delay after which the user should be shown the hotspot.
|
|
name:
|
|
type: string
|
|
description: |
|
|
The name of the hotspot.
|
|
title:
|
|
type: string
|
|
description: |
|
|
The title of the hotspot, as will be displayed to the user.
|
|
description:
|
|
type: string
|
|
description: |
|
|
The description of the hotspot, as will be displayed to the
|
|
user.
|
|
RealmEmoji:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
`{emoji_id}`: Object containing details about the emoji with
|
|
the specified ID. It has the following properties:
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: |
|
|
The ID for this emoji, same as the object's key.
|
|
name:
|
|
type: string
|
|
description: |
|
|
The user-friendly name for this emoji. Users in the organization
|
|
can use this emoji by writing this name between colons (`:name :`).
|
|
source_url:
|
|
type: string
|
|
description: |
|
|
The path relative to the organization's URL where the
|
|
emoji's image can be found.
|
|
still_url:
|
|
type: string
|
|
nullable: true
|
|
description: |
|
|
Only non-null when the emoji's image is animated.
|
|
|
|
The path relative to the organization's URL where a still
|
|
(not animated) version of the emoji can be found. (This is
|
|
currently always the first frame of the animation).
|
|
|
|
This is useful for clients to display the emoji in contexts
|
|
where continuously animating it would be a bad user experience
|
|
(E.g. because it would be distracting).
|
|
|
|
**Changes**: New in Zulip 5.0 (added as optional field in
|
|
feature level 97 and then made mandatory, but nullable, in
|
|
feature level 113).
|
|
deactivated:
|
|
type: boolean
|
|
description: |
|
|
Whether the emoji has been deactivated or not.
|
|
author_id:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
The user ID of the user who uploaded the custom emoji.
|
|
Will be `null` if the uploader is unknown.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 7). Previously
|
|
was accessible via an `author` object with an `id` field.
|
|
RealmDomain:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Object containing details of the newly added domain.
|
|
properties:
|
|
domain:
|
|
type: string
|
|
description: |
|
|
The new allowed domain.
|
|
allow_subdomains:
|
|
type: boolean
|
|
description: |
|
|
Whether subdomains are allowed for this domain.
|
|
RealmPlayground:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Object containing details about a realm playground.
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The unique ID for the realm playground.
|
|
name:
|
|
type: string
|
|
description: |
|
|
The user-visible display name of the playground. Clients
|
|
should display this in UI for picking which playground to
|
|
open a code block in, to differentiate between multiple
|
|
configured playground options for a given pygments
|
|
language.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 49).
|
|
pygments_language:
|
|
type: string
|
|
description: |
|
|
The name of the Pygments language lexer for that
|
|
programming language.
|
|
url_prefix:
|
|
type: string
|
|
description: |
|
|
The url prefix for the playground.
|
|
RealmExport:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Object containing details about a realm export.
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the export.
|
|
acting_user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user who did the export.
|
|
export_time:
|
|
type: number
|
|
description: |
|
|
The UNIX timestamp of when the export was made.
|
|
deleted_timestamp:
|
|
type: number
|
|
nullable: true
|
|
description: |
|
|
The timestamp of when the export was deleted.
|
|
If `null`, it wasn't deleted.
|
|
failed_timestamp:
|
|
type: number
|
|
nullable: true
|
|
description: |
|
|
The timestamp of when the export failed.
|
|
If `null`, it didn't fail.
|
|
export_url:
|
|
type: string
|
|
nullable: true
|
|
description: |
|
|
The URL of the export. `null` if there's no URL.
|
|
pending:
|
|
type: boolean
|
|
description: |
|
|
Whether the export is pending or not.
|
|
UserGroup:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Object containing the user group's attributes.
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: |
|
|
The name of the user group.
|
|
description:
|
|
type: string
|
|
description: |
|
|
The description of the user group.
|
|
members:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
Array containing the ID of the users who are
|
|
members of this user group.
|
|
direct_subgroup_ids:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
Array containing the ID of the direct_subgroups of
|
|
this user group.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 131).
|
|
Introduced in feature level 127 as `subgroups`, but
|
|
clients can ignore older events as this feature level
|
|
predates subgroups being fully implemented.
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user group.
|
|
is_system_group:
|
|
type: boolean
|
|
description: |
|
|
Whether the user group is a system group which cannot be
|
|
directly modified by users.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 93).
|
|
Subscriptions:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
The unique ID of a stream.
|
|
name:
|
|
type: string
|
|
description: |
|
|
The name of a stream.
|
|
description:
|
|
type: string
|
|
description: |
|
|
The [description](/help/change-the-stream-description) of the stream in text/markdown format,
|
|
intended to be used to prepopulate UI for editing a stream's
|
|
description.
|
|
|
|
See also `rendered_description`.
|
|
rendered_description:
|
|
type: string
|
|
description: |
|
|
The [description](/help/change-the-stream-description) of the stream rendered as HTML, intended to
|
|
be used when displaying the stream description in a UI.
|
|
|
|
One should use the standard Zulip rendered_markdown CSS when
|
|
displaying this content so that emoji, LaTeX, and other syntax
|
|
work correctly. And any client-side security logic for
|
|
user-generated message content should be applied when displaying
|
|
this HTML as though it were the body of a Zulip message.
|
|
|
|
See also `description`.
|
|
date_created:
|
|
type: integer
|
|
description: |
|
|
The UNIX timestamp for when the stream was created, in UTC seconds.
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 30).
|
|
invite_only:
|
|
type: boolean
|
|
description: |
|
|
Specifies whether the stream is private or not.
|
|
Only people who have been invited can access a private stream.
|
|
# TODO: This subscribers item should probably be declared optional more
|
|
# explicitly in the OpenAPI format?
|
|
subscribers:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
A list of user IDs of users who are also subscribed
|
|
to a given stream. Included only if `include_subscribers` is `true`.
|
|
desktop_notifications:
|
|
type: boolean
|
|
nullable: true
|
|
description: |
|
|
A boolean specifying whether desktop notifications
|
|
are enabled for the given stream.
|
|
|
|
A `null` value means the value of this setting
|
|
should be inherited from the user-level default
|
|
setting, enable_stream_desktop_notifications, for
|
|
this stream.
|
|
email_notifications:
|
|
type: boolean
|
|
nullable: true
|
|
description: |
|
|
A boolean specifying whether email notifications
|
|
are enabled for the given stream.
|
|
|
|
A `null` value means the value of this setting
|
|
should be inherited from the user-level default
|
|
setting, enable_stream_email_notifications, for
|
|
this stream.
|
|
wildcard_mentions_notify:
|
|
type: boolean
|
|
nullable: true
|
|
description: |
|
|
A boolean specifying whether wildcard mentions
|
|
trigger notifications as though they were personal
|
|
mentions in this stream.
|
|
|
|
A `null` value means the value of this setting
|
|
should be inherited from the user-level default
|
|
setting, wildcard_mentions_notify, for
|
|
this stream.
|
|
push_notifications:
|
|
type: boolean
|
|
nullable: true
|
|
description: |
|
|
A boolean specifying whether push notifications
|
|
are enabled for the given stream.
|
|
|
|
A `null` value means the value of this setting
|
|
should be inherited from the user-level default
|
|
setting, enable_stream_push_notifications, for
|
|
this stream.
|
|
audible_notifications:
|
|
type: boolean
|
|
nullable: true
|
|
description: |
|
|
A boolean specifying whether audible notifications
|
|
are enabled for the given stream.
|
|
|
|
A `null` value means the value of this setting
|
|
should be inherited from the user-level default
|
|
setting, enable_stream_audible_notifications, for
|
|
this stream.
|
|
pin_to_top:
|
|
type: boolean
|
|
description: |
|
|
A boolean specifying whether the given stream has been pinned
|
|
to the top.
|
|
is_muted:
|
|
type: boolean
|
|
description: |
|
|
Whether the user has muted the stream. Muted streams do
|
|
not count towards your total unread count and do not show up in
|
|
`All messages` view (previously known as `Home` view).
|
|
|
|
**Changes**: Prior to Zulip 2.1.0, this feature was
|
|
represented by the more confusingly named `in_home_view` (with the
|
|
opposite value, `in_home_view=!is_muted`).
|
|
in_home_view:
|
|
type: boolean
|
|
deprecated: true
|
|
description: |
|
|
Legacy property for if the given stream is muted, with inverted meaning.
|
|
|
|
**Changes**: Deprecated in Zulip 2.1.0. Clients should use `is_muted`
|
|
where available.
|
|
is_announcement_only:
|
|
type: boolean
|
|
deprecated: true
|
|
description: |
|
|
Whether only organization administrators can post to the stream.
|
|
|
|
**Changes**: Deprecated in Zulip 3.0 (feature level 1). Clients
|
|
should use `stream_post_policy` instead.
|
|
is_web_public:
|
|
type: boolean
|
|
description: |
|
|
Whether the stream has been configured to allow unauthenticated
|
|
access to its message history from the web.
|
|
color:
|
|
type: string
|
|
description: |
|
|
The user's personal color for the stream.
|
|
stream_post_policy:
|
|
type: integer
|
|
description: |
|
|
[Policy][permission-level] for which users can post messages to the stream.
|
|
|
|
- 1 = Any user can post.
|
|
- 2 = Only administrators can post.
|
|
- 3 = Only [full members][calc-full-member] can post.
|
|
- 4 = Only moderators can post.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 1), replacing the previous
|
|
`is_announcement_only` boolean.
|
|
|
|
[permission-level]: /api/roles-and-permissions#permission-levels
|
|
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
|
|
message_retention_days:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
Number of days that messages sent to this stream will be stored
|
|
before being automatically deleted by the [message retention
|
|
policy](/help/message-retention-policy). There are two special values:
|
|
|
|
- `null`, the default, means the stream will inherit the organization
|
|
level setting.
|
|
- `-1` encodes retaining messages in this stream forever.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 17).
|
|
history_public_to_subscribers:
|
|
type: boolean
|
|
description: |
|
|
Whether the history of the stream is public to its subscribers.
|
|
|
|
Currently always true for public streams (i.e. `"invite_only": false` implies
|
|
`"history_public_to_subscribers": true`), but clients should not make that
|
|
assumption, as we may change that behavior in the future.
|
|
first_message_id:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
The ID of the first message in the stream.
|
|
|
|
Intended to help clients determine whether they need to display
|
|
UI like the "more topics" widget that would suggest the stream
|
|
has older history that can be accessed.
|
|
|
|
Is `null` for streams with no message history.
|
|
stream_weekly_traffic:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
The average number of messages sent to the stream in recent weeks,
|
|
rounded to the nearest integer.
|
|
|
|
If `null`, the stream was recently created and there is
|
|
insufficient data to estimate the average traffic.
|
|
can_remove_subscribers_group_id:
|
|
type: integer
|
|
description: |
|
|
ID of the user group whose members are allowed to unsubscribe others
|
|
from the stream.
|
|
|
|
**Changes**: New in Zulip 6.0 (feature level 142).
|
|
DefaultStreamGroup:
|
|
type: object
|
|
description: |
|
|
Dictionary containing details of a default stream
|
|
group.
|
|
additionalProperties: false
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: |
|
|
Name of the default stream group.
|
|
description:
|
|
type: string
|
|
description: |
|
|
Description of the default stream group.
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the default stream group.
|
|
streams:
|
|
type: array
|
|
description: |
|
|
Array containing details about the streams
|
|
in the default stream group.
|
|
items:
|
|
$ref: "#/components/schemas/BasicStream"
|
|
EmailAddressVisibility:
|
|
type: integer
|
|
description: |
|
|
The [policy][permission-level] for [which other users][help-email-visibility]
|
|
in this organization can see the user's real email address.
|
|
|
|
- 1 = Everyone
|
|
- 2 = Members only
|
|
- 3 = Administrators only
|
|
- 4 = Nobody
|
|
- 5 = Moderators only
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 163), replacing the
|
|
realm-level setting.
|
|
|
|
[permission-level]: /api/roles-and-permissions#permission-levels
|
|
[help-email-visibility]: /help/configure-email-visibility
|
|
EmojiReaction:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EmojiReactionBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
emoji_code: {}
|
|
emoji_name: {}
|
|
reaction_type: {}
|
|
user_id: {}
|
|
user: {}
|
|
EmojiBase:
|
|
type: object
|
|
properties:
|
|
emoji_name:
|
|
type: string
|
|
description: |
|
|
Name of the emoji.
|
|
emoji_code:
|
|
type: string
|
|
description: |
|
|
A unique identifier, defining the specific emoji codepoint requested,
|
|
within the namespace of the `reaction_type`.
|
|
reaction_type:
|
|
type: string
|
|
description: |
|
|
A string indicating the type of emoji. Each emoji `reaction_type`
|
|
has an independent namespace for values of `emoji_code`.
|
|
|
|
Must be one of the following values:
|
|
|
|
- `unicode_emoji` : In this namespace, `emoji_code` will be a
|
|
dash-separated hex encoding of the sequence of Unicode codepoints
|
|
that define this emoji in the Unicode specification.
|
|
|
|
- `realm_emoji` : In this namespace, `emoji_code` will be the ID of
|
|
the uploaded [custom emoji](/help/custom-emoji).
|
|
|
|
- `zulip_extra_emoji` : These are special emoji included with Zulip.
|
|
In this namespace, `emoji_code` will be the name of the emoji (e.g.
|
|
"zulip").
|
|
EmojiReactionBase:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EmojiBase"
|
|
- properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user who added the reaction.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 2). The `user`
|
|
object is deprecated and will be removed in the future.
|
|
user:
|
|
type: object
|
|
additionalProperties: false
|
|
deprecated: true
|
|
description: |
|
|
Dictionary with data on the user who added the
|
|
reaction, including the user ID as the `id`
|
|
field. Note that reactions data received from the
|
|
[events API](/api/get-events) has a slightly different
|
|
`user` dictionary format, with the user ID field
|
|
called `user_id` instead.
|
|
|
|
**Changes**: Deprecated and to be removed in a future release
|
|
once core clients have migrated to use the adjacent `user_id`
|
|
field, which was introduced in Zulip 3.0 (feature level 2).
|
|
Clients supporting older Zulip server versions should use
|
|
the user ID mentioned in the description above as they would
|
|
the `user_id` field.
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: |
|
|
ID of the user.
|
|
email:
|
|
type: string
|
|
description: |
|
|
Zulip API email of the user.
|
|
full_name:
|
|
type: string
|
|
description: |
|
|
Full name of the user.
|
|
is_mirror_dummy:
|
|
type: boolean
|
|
description: |
|
|
Whether the user is a mirror dummy.
|
|
MessagesEvent:
|
|
allOf:
|
|
- $ref: "#/components/schemas/MessagesBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
avatar_url:
|
|
nullable: true
|
|
client: {}
|
|
content: {}
|
|
content_type: {}
|
|
display_recipient: {}
|
|
edit_history: {}
|
|
id: {}
|
|
is_me_message: {}
|
|
last_edit_timestamp: {}
|
|
reactions: {}
|
|
recipient_id: {}
|
|
sender_email: {}
|
|
sender_full_name: {}
|
|
sender_id: {}
|
|
sender_realm_str: {}
|
|
stream_id: {}
|
|
subject: {}
|
|
submessages: {}
|
|
timestamp: {}
|
|
topic_links: {}
|
|
type: {}
|
|
MessagesBase:
|
|
type: object
|
|
description: |
|
|
Object containing details of the message.
|
|
properties:
|
|
avatar_url:
|
|
type: string
|
|
nullable: true
|
|
description: |
|
|
The URL of the message sender's avatar. Can be `null` only if
|
|
the current user has access to the sender's real email address
|
|
and `client_gravatar` was `true`.
|
|
|
|
If `null`, then the sender has not uploaded an avatar in Zulip,
|
|
and the client can compute the gravatar URL by hashing the
|
|
sender's email address, which corresponds in this case to their
|
|
real email address.
|
|
|
|
**Changes**: Before Zulip 7.0 (feature level 163), access to a
|
|
user's real email address was a realm-level setting. As of this
|
|
feature level, `email_address_visibility` is a user setting.
|
|
client:
|
|
type: string
|
|
description: |
|
|
A Zulip "client" string, describing what Zulip client
|
|
sent the message.
|
|
content:
|
|
type: string
|
|
description: |
|
|
The content/body of the message.
|
|
content_type:
|
|
type: string
|
|
description: |
|
|
The HTTP `content_type` for the message content. This
|
|
will be `text/html` or `text/x-markdown`, depending on
|
|
whether `apply_markdown` was set.
|
|
display_recipient:
|
|
oneOf:
|
|
- type: string
|
|
- type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: |
|
|
ID of the user.
|
|
email:
|
|
type: string
|
|
description: |
|
|
Zulip API email of the user.
|
|
full_name:
|
|
type: string
|
|
description: |
|
|
Full name of the user.
|
|
is_mirror_dummy:
|
|
type: boolean
|
|
description: |
|
|
Whether the user is a mirror dummy.
|
|
description: |
|
|
Data on the recipient of the message;
|
|
either the name of a stream or a dictionary containing basic data on
|
|
the users who received the message.
|
|
edit_history:
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
prev_content:
|
|
type: string
|
|
description: |
|
|
Only present if message's content was edited.
|
|
|
|
The content of the message immediately prior to this
|
|
edit event.
|
|
prev_rendered_content:
|
|
type: string
|
|
description: |
|
|
Only present if message's content was edited.
|
|
|
|
The rendered HTML representation of `prev_content`.
|
|
prev_rendered_content_version:
|
|
type: integer
|
|
description: |
|
|
Only present if message's content was edited.
|
|
|
|
The Markdown processor version number for the message
|
|
immediately prior to this edit event.
|
|
prev_stream:
|
|
type: integer
|
|
description: |
|
|
Only present if message's stream was edited.
|
|
|
|
The stream ID of the message immediately prior to this
|
|
edit event.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 1).
|
|
prev_topic:
|
|
type: string
|
|
description: |
|
|
Only present if message's topic was edited.
|
|
|
|
The topic of the message immediately prior to this
|
|
edit event.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 118).
|
|
Previously, this field was called `prev_subject`;
|
|
clients are recommended to rename `prev_subject` to
|
|
`prev_topic` if present for compatibility with
|
|
older Zulip servers.
|
|
stream:
|
|
type: integer
|
|
description: |
|
|
Only present if message's stream was edited.
|
|
|
|
The ID of the stream containing the message
|
|
immediately after this edit event.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 118).
|
|
timestamp:
|
|
type: integer
|
|
description: |
|
|
The UNIX timestamp for the edit.
|
|
topic:
|
|
type: string
|
|
description: |
|
|
Only present if message's topic was edited.
|
|
|
|
The topic of the message immediately after this edit event.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 118).
|
|
user_id:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
The ID of the user that made the edit.
|
|
|
|
Will be `null` only for edit history
|
|
events predating March 2017.
|
|
|
|
Clients can display edit history events where this
|
|
is `null` as modified by either the sender (for content
|
|
edits) or an unknown user (for topic edits).
|
|
required:
|
|
- user_id
|
|
- timestamp
|
|
description: |
|
|
An array of objects, with each object documenting the
|
|
changes in a previous edit made to the the message,
|
|
ordered chronologically from most recent to least recent
|
|
edit.
|
|
|
|
Not present if the message has never been edited or if the realm has
|
|
[disabled viewing of message edit history][disable-edit-history].
|
|
|
|
Every object will contain `user_id` and `timestamp`.
|
|
|
|
The other fields are optional, and will be present or not
|
|
depending on whether the stream, topic, and/or message
|
|
content were modified in the edit event. For example, if
|
|
only the topic was edited, only `prev_topic` and `topic`
|
|
will be present in addition to `user_id` and `timestamp`.
|
|
|
|
[disable-edit-history]: /help/disable-message-edit-history
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The unique message ID. Messages should always be
|
|
displayed sorted by ID.
|
|
is_me_message:
|
|
type: boolean
|
|
description: |
|
|
Whether the message is a [/me status message][status-messages]
|
|
|
|
[status-messages]: /help/format-your-message-using-markdown#status-messages
|
|
last_edit_timestamp:
|
|
type: integer
|
|
description: |
|
|
The UNIX timestamp for when the message was last edited,
|
|
in UTC seconds.
|
|
|
|
Not present if the message has never been edited.
|
|
reactions:
|
|
type: array
|
|
description: |
|
|
Data on any reactions to the message.
|
|
items:
|
|
$ref: "#/components/schemas/EmojiReaction"
|
|
recipient_id:
|
|
type: integer
|
|
description: |
|
|
A unique ID for the set of users receiving the
|
|
message (either a stream or group of users). Useful primarily
|
|
for hashing.
|
|
sender_email:
|
|
type: string
|
|
description: |
|
|
The Zulip API email address of the message's sender.
|
|
sender_full_name:
|
|
type: string
|
|
description: |
|
|
The full name of the message's sender.
|
|
sender_id:
|
|
type: integer
|
|
description: |
|
|
The user ID of the message's sender.
|
|
sender_realm_str:
|
|
type: string
|
|
description: |
|
|
A string identifier for the realm the sender is in. Unique only within
|
|
the context of a given Zulip server.
|
|
|
|
E.g. on `example.zulip.com`, this will be `example`.
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
Only present for stream messages; the ID of the stream.
|
|
subject:
|
|
type: string
|
|
description: |
|
|
The `topic` of the message. Currently always `""` for private messages,
|
|
though this could change if Zulip adds support for topics in private
|
|
message conversations.
|
|
|
|
The field name is a legacy holdover from when topics were
|
|
called "subjects" and will eventually change.
|
|
submessages:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: |
|
|
Data used for certain experimental Zulip integrations.
|
|
timestamp:
|
|
type: integer
|
|
description: |
|
|
The UNIX timestamp for when the message was sent,
|
|
in UTC seconds.
|
|
topic_links:
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
text:
|
|
type: string
|
|
description: |
|
|
The original link text present in the topic.
|
|
url:
|
|
type: string
|
|
description: |
|
|
The expanded target url which the link points to.
|
|
description: |
|
|
Data on any links to be included in the `topic`
|
|
line (these are generated by [custom linkification
|
|
filters](/help/add-a-custom-linkifier) that match content in the
|
|
message's topic.)
|
|
|
|
**Changes**: This field contained a list of urls before
|
|
Zulip 4.0 (feature level 46).
|
|
|
|
New in Zulip 3.0 (feature level 1). Previously, this field was called
|
|
`subject_links`; clients are recommended to rename `subject_links` to `topic_links`
|
|
if present for compatibility with older Zulip servers.
|
|
type:
|
|
type: string
|
|
description: |
|
|
The type of the message: `stream` or `private`.
|
|
Presence:
|
|
type: object
|
|
description: |
|
|
`{client_name}` or `"aggregated"`: Object containing the details of the user's
|
|
presence.
|
|
|
|
**Changes**: Starting with Zulip 7.0 (feature level 178), this will always
|
|
contain two keys, `"website"` and `"aggregated"`, with identical data. The
|
|
server no longer stores which client submitted presence updates.
|
|
|
|
Previously, the `{client_name}` keys for these objects were the names of the
|
|
different clients where the user was logged in, for example `website` or
|
|
`ZulipDesktop`.
|
|
additionalProperties: false
|
|
properties:
|
|
client:
|
|
type: string
|
|
description: |
|
|
The client's platform name.
|
|
|
|
**Changes**: Starting with Zulip 7.0 (feature level 178), this will
|
|
always be `"website"` as the server no longer stores which client
|
|
submitted presence data.
|
|
status:
|
|
type: string
|
|
enum:
|
|
- idle
|
|
- active
|
|
description: |
|
|
The status of the user on this client. Will be either `"idle"`
|
|
or `"active"`.
|
|
timestamp:
|
|
type: integer
|
|
description: |
|
|
The UNIX timestamp of when this client sent the user's presence
|
|
to the server with the precision of a second.
|
|
pushable:
|
|
type: boolean
|
|
description: |
|
|
Whether the client is capable of showing mobile/push notifications
|
|
to the user.
|
|
|
|
Not present in objects with the `"aggregated"` key.
|
|
|
|
**Changes**: Starting with Zulip 7.0 (feature level 178), always
|
|
`false` when present as the server no longer stores which client
|
|
submitted presence data.
|
|
Draft:
|
|
type: object
|
|
description: |
|
|
A dictionary for representing a message draft.
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The unique ID of the draft. It will only used whenever the drafts are
|
|
fetched. This field should not be specified when the draft is being
|
|
created or edited.
|
|
type:
|
|
type: string
|
|
description: |
|
|
The type of the draft. Either unaddressed (empty string), "stream",
|
|
or "private" (for PMs and private group messages).
|
|
enum:
|
|
- ""
|
|
- stream
|
|
- private
|
|
to:
|
|
type: array
|
|
description: |
|
|
An array of the tentative target audience IDs. For "stream"
|
|
messages, this should contain exactly 1 ID, the ID of the
|
|
target stream. For private messages, this should be an array
|
|
of target user IDs. For unaddressed drafts, this is ignored,
|
|
and clients should send an empty array.
|
|
items:
|
|
type: integer
|
|
topic:
|
|
type: string
|
|
description: |
|
|
For stream message drafts, the tentative topic name. For private
|
|
or unaddressed messages, this will be ignored and should ideally
|
|
be the empty string. Should not contain null bytes.
|
|
content:
|
|
type: string
|
|
description: |
|
|
The body of the draft. Should not contain null bytes.
|
|
timestamp:
|
|
type: number
|
|
description: |
|
|
A Unix timestamp (seconds only) representing when the draft was
|
|
last edited. When creating a draft, this key need not be present
|
|
and it will be filled in automatically by the server.
|
|
example: 1595479019
|
|
additionalProperties: false
|
|
required:
|
|
- type
|
|
- to
|
|
- topic
|
|
- content
|
|
ScheduledMessage:
|
|
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 stream messages, it will be the unique ID of the target
|
|
stream. For private 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 stream message.
|
|
content:
|
|
type: string
|
|
description: |
|
|
The content/body of the scheduled message, in text/markdown 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
|
|
User:
|
|
allOf:
|
|
- $ref: "#/components/schemas/UserBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
user_id: {}
|
|
delivery_email:
|
|
nullable: true
|
|
email: {}
|
|
full_name: {}
|
|
date_joined: {}
|
|
is_active: {}
|
|
is_owner: {}
|
|
is_admin: {}
|
|
is_guest: {}
|
|
is_billing_admin: {}
|
|
is_bot: {}
|
|
bot_type:
|
|
nullable: true
|
|
bot_owner_id:
|
|
nullable: true
|
|
role: {}
|
|
timezone: {}
|
|
avatar_url:
|
|
nullable: true
|
|
avatar_version: {}
|
|
profile_data: {}
|
|
UserBase:
|
|
type: object
|
|
description: |
|
|
A dictionary containing basic data on a given Zulip user.
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The unique ID of the user.
|
|
delivery_email:
|
|
type: string
|
|
nullable: true
|
|
description: |
|
|
The user's real email address. This value will be `null` if you cannot
|
|
access user's real email address. For bot users, this field is always
|
|
set to the real email of the bot, because bot users always have
|
|
`email_address_visibility` set to everyone.
|
|
|
|
**Changes**: Prior to Zulip 7.0 (feature level 163), this field was
|
|
present only when `email_address_visibility` was restricted and you had
|
|
access to the user's real email. As of this feature level, this field
|
|
is always present, including the case when `email_address_visibility`
|
|
is set to everyone (and therefore not restricted).
|
|
email:
|
|
type: string
|
|
description: |
|
|
The Zulip API email address of the user or bot.
|
|
|
|
If you do not have permission to view the email address of the target user,
|
|
this will be a fake email address that is usable for the Zulip API but nothing else.
|
|
full_name:
|
|
type: string
|
|
description: |
|
|
Full name of the user or bot, used for all display purposes.
|
|
date_joined:
|
|
type: string
|
|
description: |
|
|
The time the user account was created.
|
|
is_active:
|
|
type: boolean
|
|
description: |
|
|
A boolean specifying whether the user account has been deactivated.
|
|
is_owner:
|
|
type: boolean
|
|
description: |
|
|
A boolean specifying whether the user is an organization owner.
|
|
If true, `is_admin` will also be true.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 8).
|
|
is_admin:
|
|
type: boolean
|
|
description: |
|
|
A boolean specifying whether the user is an organization administrator.
|
|
is_guest:
|
|
type: boolean
|
|
description: |
|
|
A boolean specifying whether the user is a guest user.
|
|
is_billing_admin:
|
|
type: boolean
|
|
description: |
|
|
A boolean specifying whether the user is a billing administrator.
|
|
|
|
**Changes**: New in Zulip 5.0 (feature level 73).
|
|
is_bot:
|
|
type: boolean
|
|
description: |
|
|
A boolean specifying whether the user is a bot or full account.
|
|
bot_type:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
An integer describing the type of bot:
|
|
|
|
- `null` if the user isn't a bot.
|
|
- `1` for a `Generic` bot.
|
|
- `2` for an `Incoming webhook` bot.
|
|
- `3` for an `Outgoing webhook` bot.
|
|
- `4` for an `Embedded` bot.
|
|
bot_owner_id:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
If the user is a bot (i.e. `is_bot` is true), then `bot_owner_id`
|
|
is the user ID of the bot's owner (usually, whoever created the bot).
|
|
|
|
Will be `null` for legacy bots that do not have an owner.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 1). In previous
|
|
versions, there was a `bot_owner` field containing the email
|
|
address of the bot's owner.
|
|
role:
|
|
type: integer
|
|
enum:
|
|
- 100
|
|
- 200
|
|
- 300
|
|
- 400
|
|
- 600
|
|
description: |
|
|
[Organization-level role](/api/roles-and-permissions) of the user.
|
|
Possible values are:
|
|
|
|
- 100 = Organization owner
|
|
- 200 = Organization administrator
|
|
- 300 = Organization moderator
|
|
- 400 = Member
|
|
- 600 = Guest
|
|
|
|
**Changes**: New in Zulip 4.0 (feature level 59).
|
|
timezone:
|
|
type: string
|
|
description: |
|
|
The time zone of the user.
|
|
avatar_url:
|
|
type: string
|
|
nullable: true
|
|
description: |
|
|
URL for the user's avatar.
|
|
|
|
Will be `null` if the `client_gravatar`
|
|
query parameter was set to `true`, the current user has access to
|
|
this user's real email address, and this user's avatar is hosted by
|
|
the Gravatar provider (i.e. this user has never uploaded an avatar).
|
|
|
|
**Changes**: Before Zulip 7.0 (feature level 163), access to a
|
|
user's real email address was a realm-level setting. As of this
|
|
feature level, `email_address_visibility` is a user setting.
|
|
|
|
In Zulip 3.0 (feature level 18), if the client has the
|
|
`user_avatar_url_field_optional` capability, this will be missing at
|
|
the server's sole discretion.
|
|
avatar_version:
|
|
type: integer
|
|
description: |
|
|
Version for the user's avatar. Used for cache-busting requests
|
|
for the user's avatar. Clients generally shouldn't need to use this;
|
|
most avatar URLs sent by Zulip will already end with `?v={avatar_version}`.
|
|
profile_data:
|
|
$ref: "#/components/schemas/profile_data"
|
|
profile_data:
|
|
type: object
|
|
description: |
|
|
Only present if `is_bot` is false; bots can't have custom profile fields.
|
|
|
|
A dictionary containing custom profile field data for the user. Each entry
|
|
maps the integer ID of a custom profile field in the organization to a
|
|
dictionary containing the user's data for that field. Generally the data
|
|
includes just a single `value` key; for those custom profile fields
|
|
supporting Markdown, a `rendered_value` key will also be present.
|
|
additionalProperties:
|
|
type: object
|
|
additionalProperties: false
|
|
description: |
|
|
`{id}`: Object with data about what value the user filled in the custom
|
|
profile field with that ID.
|
|
properties:
|
|
value:
|
|
type: string
|
|
description: |
|
|
User's personal value for this custom profile field.
|
|
rendered_value:
|
|
type: string
|
|
description: |
|
|
The `value` rendered in HTML. Will only be present for
|
|
custom profile field types that support Markdown rendering.
|
|
|
|
This user-generated HTML content should be rendered
|
|
using the same CSS and client-side security protections
|
|
as are used for message content.
|
|
JsonResponseBase:
|
|
type: object
|
|
properties:
|
|
result:
|
|
type: string
|
|
SuccessDescription:
|
|
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
|
|
JsonSuccess:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
JsonSuccessBase:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonResponseBase"
|
|
- required:
|
|
- result
|
|
- msg
|
|
properties:
|
|
result:
|
|
enum:
|
|
- success
|
|
msg:
|
|
type: string
|
|
ignored_parameters_unsupported:
|
|
$ref: "#/components/schemas/IgnoredParametersUnsupported"
|
|
example: {"msg": "", "result": "success"}
|
|
IgnoredParametersSuccess:
|
|
allOf:
|
|
- $ref: "#/components/schemas/IgnoredParametersBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
description: |
|
|
**Changes**: The [`ignored_parameters_unsupported`][ignored_params]
|
|
array was added as a possible return value for all REST API endpoint
|
|
JSON success responses in Zulip 7.0 (feature level 167).
|
|
|
|
Previously, it was added to
|
|
[`POST /users/me/subscriptions/properties`](/api/update-subscription-settings)
|
|
in Zulip 5.0 (feature level 111) and to
|
|
[`PATCH /realm/user_settings_defaults`](/api/update-realm-user-settings-defaults)
|
|
in Zulip 5.0 (feature level 96). The feature was introduced in Zulip 5.0
|
|
(feature level 78) as a return value for the
|
|
[`PATCH /settings`](/api/update-settings) endpoint.
|
|
|
|
A typical successful JSON response with ignored parameters may look like:
|
|
|
|
[ignored_params]: /api/rest-error-handling#ignored-parameters
|
|
IgnoredParametersBase:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonResponseBase"
|
|
- required:
|
|
- result
|
|
- msg
|
|
properties:
|
|
result:
|
|
enum:
|
|
- success
|
|
msg:
|
|
type: string
|
|
ignored_parameters_unsupported:
|
|
$ref: "#/components/schemas/IgnoredParametersUnsupported"
|
|
example:
|
|
{
|
|
"ignored_parameters_unsupported":
|
|
["invalid_param_1", "invalid_param_2"],
|
|
"msg": "",
|
|
"result": "success",
|
|
}
|
|
JsonError:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonErrorBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
JsonErrorBase:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonResponseBase"
|
|
- required:
|
|
- result
|
|
- msg
|
|
properties:
|
|
result:
|
|
enum:
|
|
- error
|
|
msg:
|
|
type: string
|
|
PartiallyCompleted:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonResponseBase"
|
|
- required:
|
|
- result
|
|
- code
|
|
additionalProperties: false
|
|
properties:
|
|
result:
|
|
enum:
|
|
- partially_completed
|
|
code:
|
|
type: string
|
|
description: |
|
|
A string that identifies the cause of the partial completion of the request.
|
|
msg:
|
|
type: string
|
|
ApiKeyResponse:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- required:
|
|
- api_key
|
|
- email
|
|
additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
api_key:
|
|
type: string
|
|
description: |
|
|
The API key that can be used to authenticate as the requested user.
|
|
email:
|
|
type: string
|
|
description: |
|
|
The email address of the user who owns the API key.
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The unique ID of the user who owns the API key.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 171).
|
|
example:
|
|
{
|
|
"api_key": "gjA04ZYcqXKalvYMA8OeXSfzUOLrtbZv",
|
|
"email": "iago@zulip.com",
|
|
"msg": "",
|
|
"result": "success",
|
|
"user_id": 5,
|
|
}
|
|
CodedError:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedErrorBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
code: {}
|
|
CodedErrorBase:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonErrorBase"
|
|
- properties:
|
|
result: {}
|
|
msg: {}
|
|
code:
|
|
type: string
|
|
description: |
|
|
A string that identifies the error.
|
|
BadEventQueueIdError:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedErrorBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
code: {}
|
|
queue_id:
|
|
type: string
|
|
description: |
|
|
The string that identifies the invalid event queue.
|
|
example:
|
|
{
|
|
"code": "BAD_EVENT_QUEUE_ID",
|
|
"msg": "Bad event queue ID: fb67bf8a-c031-47cc-84cf-ed80accacda8",
|
|
"queue_id": "fb67bf8a-c031-47cc-84cf-ed80accacda8",
|
|
"result": "error",
|
|
}
|
|
InvalidMessageError:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonErrorBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
example:
|
|
{
|
|
"msg": "Invalid message(s)",
|
|
"code": "BAD_REQUEST",
|
|
"result": "error",
|
|
}
|
|
NonExistingStreamNameError:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedErrorBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
code: {}
|
|
stream:
|
|
type: string
|
|
description: |
|
|
The name of the stream that could not be found.
|
|
example:
|
|
{
|
|
"code": "STREAM_DOES_NOT_EXIST",
|
|
"msg": "Stream 'nonexistent_stream' does not exist",
|
|
"result": "error",
|
|
"stream": "nonexistent_stream",
|
|
}
|
|
NonExistingStreamIdError:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedErrorBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
code: {}
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
The stream ID that could not be found.
|
|
example:
|
|
{
|
|
"code": "STREAM_DOES_NOT_EXIST",
|
|
"msg": "Stream with ID '9' does not exist",
|
|
"result": "error",
|
|
"stream_id": 9,
|
|
}
|
|
AddSubscriptionsResponse:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
ignored_parameters_unsupported: {}
|
|
subscribed:
|
|
type: object
|
|
description: |
|
|
A dictionary where the key is the Zulip API email address of the user/bot
|
|
and the value is a list of the names of the streams that were subscribed
|
|
to as a result of the query.
|
|
additionalProperties:
|
|
description: |
|
|
`{email_address}`: List of the names of the streams that were subscribed
|
|
to as a result of the query.
|
|
type: array
|
|
items:
|
|
type: string
|
|
already_subscribed:
|
|
type: object
|
|
description: |
|
|
A dictionary where the key is the Zulip API email address of the user/bot
|
|
and the value is a list of the names of the streams that the user/bot is
|
|
already subscribed to.
|
|
additionalProperties:
|
|
description: |
|
|
`{email_address}`: List of the names of the streams that the user is
|
|
already subscribed to.
|
|
type: array
|
|
items:
|
|
type: string
|
|
unauthorized:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: |
|
|
A list of names of streams that the requesting user/bot was not
|
|
authorized to subscribe to. Only present if `"authorization_errors_fatal": false`.
|
|
InvalidApiKeyError:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonError"
|
|
- example: {"msg": "Invalid API key", "result": "error"}
|
|
description: |
|
|
## Invalid API key
|
|
|
|
A typical failed JSON response for when the API key is invalid:
|
|
MissingArgumentError:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedErrorBase"
|
|
- additionalProperties: false
|
|
description: |
|
|
## Missing request parameter(s)
|
|
|
|
A typical failed JSON response for when a required request parameter
|
|
is not supplied:
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
code: {}
|
|
var_name:
|
|
type: string
|
|
description: |
|
|
It contains the information about the missing parameter.
|
|
example:
|
|
{
|
|
"code": "REQUEST_VARIABLE_MISSING",
|
|
"msg": "Missing 'content' argument",
|
|
"result": "error",
|
|
"var_name": "content",
|
|
}
|
|
UserNotAuthorizedError:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "User not authorized for this query",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
## User not authorized for query
|
|
|
|
A typical failed JSON response for when the user is not authorized for
|
|
a query:
|
|
UserDeactivatedError:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "USER_DEACTIVATED",
|
|
"msg": "Account is deactivated",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
## User account deactivated
|
|
|
|
**Changes**: These errors used the HTTP 403 status code
|
|
before Zulip 5.0 (feature level 76).
|
|
|
|
A typical failed json response for when user's account is deactivated:
|
|
RateLimitedError:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "RATE_LIMIT_HIT",
|
|
"msg": "API usage exceeded rate limit",
|
|
"result": "error",
|
|
"retry-after": 28.706807374954224,
|
|
}
|
|
description: |
|
|
## Rate limit exceeded
|
|
|
|
The `retry-after` parameter in the response indicates how many seconds
|
|
the client must wait before making additional requests.
|
|
|
|
Zulip sets a few [HTTP response headers][rate-limit-headers]
|
|
to help with preventing rate limit errors.
|
|
|
|
**Changes**: The `code` field was not present in rate
|
|
limit errors before Zulip 4.0 (feature level 36).
|
|
|
|
A typical failed JSON response for when a rate limit is exceeded:
|
|
|
|
[rate-limit-headers]: /api/http-headers#rate-limiting-response-headers
|
|
RealmDeactivatedError:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "REALM_DEACTIVATED",
|
|
"msg": "This organization is deactivated",
|
|
"result": "error",
|
|
}
|
|
description: |
|
|
## Realm deactivated
|
|
|
|
**Changes**: These errors used the HTTP 403 status code
|
|
before Zulip 5.0 (feature level 76).
|
|
|
|
A typical failed json response for when user's organization is deactivated:
|
|
|
|
###################
|
|
# Shared responses
|
|
###################
|
|
responses:
|
|
SimpleSuccess:
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccess"
|
|
- $ref: "#/components/schemas/SuccessDescription"
|
|
SuccessIgnoredParameters:
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/IgnoredParametersSuccess"
|
|
|
|
####################
|
|
# Shared parameters
|
|
####################
|
|
parameters:
|
|
Event_types:
|
|
name: event_types
|
|
in: query
|
|
description: |
|
|
A JSON-encoded array indicating which types of events you're interested
|
|
in. Values that you might find useful include:
|
|
|
|
- **message** (messages)
|
|
- **subscription** (changes in your subscriptions)
|
|
- **realm_user** (changes to users in the organization and
|
|
their properties, such as their name).
|
|
|
|
If you do not specify this parameter, you will receive all
|
|
events, and have to filter out the events not relevant to
|
|
your client in your client code. For most applications, one
|
|
is only interested in messages, so one specifies:
|
|
`"event_types": ["message"]`
|
|
|
|
Event types not supported by the server are ignored, in order to simplify
|
|
the implementation of client apps that support multiple server versions.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
example: ["message"]
|
|
required: false
|
|
Narrow:
|
|
name: narrow
|
|
in: query
|
|
description: |
|
|
A JSON-encoded array of arrays of length 2 indicating the
|
|
[narrow filter(s)](/api/construct-narrow) for which you'd
|
|
like to receive events for.
|
|
|
|
For example, to receive events for direct messages (including
|
|
group direct messages) received by the user, one can use
|
|
`"narrow": [["is", "dm"]]`.
|
|
|
|
Unlike the API for [fetching messages](/api/get-messages),
|
|
this narrow parameter is simply a filter on messages that the
|
|
user receives through their stream subscriptions (or because
|
|
they are a recipient of a direct message).
|
|
|
|
This means that a client that requests a `narrow` filter of
|
|
`[["stream", "Denmark"]]` will receive events for new messages
|
|
sent to that stream while the user is subscribed to that
|
|
stream. The client will not receive any message events at all
|
|
if the user is not subscribed to `"Denmark"`.
|
|
|
|
Newly created bot users are not usually subscribed to any
|
|
streams, so bots using this API need to be
|
|
[subscribed](/api/subscribe) to any streams whose messages
|
|
you'd like them to process using this endpoint.
|
|
|
|
See the `all_public_streams` parameter for how to process all
|
|
public stream messages in an organization.
|
|
|
|
Defaults to `[]`.
|
|
|
|
**Changes**: In Zulip 7.0 (feature level 177), narrows gained support
|
|
for three new filters related to direct messages: `is:dm`, `dm` and
|
|
`dm-including`; replacing and deprecating `is:private`, `pm-with` and
|
|
`group-pm-with` respectively.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: array
|
|
items:
|
|
type: string
|
|
default: []
|
|
example: [["stream", "Denmark"]]
|
|
required: false
|
|
AllPublicStreams:
|
|
name: all_public_streams
|
|
in: query
|
|
description: |
|
|
Whether you would like to request message events from all public
|
|
streams. Useful for workflow bots that you'd like to see all new messages
|
|
sent to public streams. (You can also subscribe the user to private streams).
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
UserGroupId:
|
|
name: user_group_id
|
|
in: path
|
|
description: |
|
|
The ID of the target user group.
|
|
schema:
|
|
type: integer
|
|
example: 33
|
|
required: true
|
|
QueueId:
|
|
name: queue_id
|
|
in: query
|
|
description: |
|
|
The ID of an event queue that was previously registered via
|
|
`POST /api/v1/register` (see [Register a queue](/api/register-queue)).
|
|
schema:
|
|
type: string
|
|
example: fb67bf8a-c031-47cc-84cf-ed80accacda8
|
|
required: true
|
|
StreamIdInPath:
|
|
name: stream_id
|
|
in: path
|
|
description: |
|
|
The ID of the stream to access.
|
|
schema:
|
|
type: integer
|
|
example: 1
|
|
required: true
|
|
ClientGravatar:
|
|
name: client_gravatar
|
|
in: query
|
|
description: |
|
|
Whether the client supports computing gravatars URLs. If
|
|
enabled, `avatar_url` will be included in the response only
|
|
if there is a Zulip avatar, and will be `null` for users who
|
|
are using gravatar as their avatar. This option
|
|
significantly reduces the compressed size of user data,
|
|
since gravatar URLs are long, random strings and thus do not
|
|
compress well. The `client_gravatar` field is set to `true` if
|
|
clients can compute their own gravatars.
|
|
|
|
**Changes**: The default value of this parameter was `false`
|
|
prior to Zulip 5.0 (feature level 92).
|
|
schema:
|
|
type: boolean
|
|
default: true
|
|
example: false
|
|
RequiredContent:
|
|
name: content
|
|
in: query
|
|
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.
|
|
schema:
|
|
type: string
|
|
example: Hello
|
|
required: true
|
|
OptionalContent:
|
|
name: content
|
|
in: query
|
|
description: |
|
|
The updated content of the target message.
|
|
|
|
Clients should use the `max_message_length` returned by the
|
|
[`POST /register`](/api/register-queue) endpoint to determine
|
|
the maximum message size.
|
|
|
|
Note that a message's content and stream cannot be changed at the
|
|
same time, so sending both `content` and `stream_id` parameters will
|
|
throw an error.
|
|
schema:
|
|
type: string
|
|
example: Hello
|
|
MessageId:
|
|
name: message_id
|
|
in: path
|
|
description: |
|
|
The target message's ID.
|
|
schema:
|
|
type: integer
|
|
example: 43
|
|
required: true
|
|
UserId:
|
|
name: user_id
|
|
in: path
|
|
description: |
|
|
The target user's ID.
|
|
schema:
|
|
type: integer
|
|
example: 12
|
|
required: true
|
|
MutedUserId:
|
|
name: muted_user_id
|
|
in: path
|
|
description: |
|
|
The ID of the user to mute/un-mute.
|
|
schema:
|
|
type: integer
|
|
example: 10
|
|
required: true
|
|
StreamPostPolicy:
|
|
name: stream_post_policy
|
|
in: query
|
|
description: |
|
|
[Policy][permission-level] for which users can post messages to the stream.
|
|
|
|
- 1 = Any user can post.
|
|
- 2 = Only administrators can post.
|
|
- 3 = Only [full members][calc-full-member] can post.
|
|
- 4 = Only moderators can post.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 1), replacing the previous
|
|
`is_announcement_only` boolean.
|
|
|
|
[permission-level]: /api/roles-and-permissions#permission-levels
|
|
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
|
|
schema:
|
|
type: integer
|
|
default: 1
|
|
example: 2
|
|
required: false
|
|
HistoryPublicToSubscribers:
|
|
name: history_public_to_subscribers
|
|
in: query
|
|
description: |
|
|
Whether the stream's message history should be available to
|
|
newly subscribed members, or users can only access messages
|
|
they actually received while subscribed to the stream.
|
|
|
|
Corresponds to the [shared history](/help/stream-permissions)
|
|
option in documentation.
|
|
schema:
|
|
type: boolean
|
|
example: false
|
|
required: false
|
|
|
|
IncludeSubscribers:
|
|
name: include_subscribers
|
|
in: query
|
|
description: |
|
|
Whether each returned stream object should include a `subscribers`
|
|
field containing a list of the user IDs of its subscribers.
|
|
|
|
(This may be significantly slower in organizations with
|
|
thousands of users subscribed to many streams.)
|
|
|
|
**Changes**: New in Zulip 2.1.0.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
IncludeCustomProfileFields:
|
|
name: include_custom_profile_fields
|
|
in: query
|
|
description: |
|
|
Whether the client wants [custom profile field](/help/custom-profile-fields)
|
|
data to be included in the response.
|
|
|
|
**Changes**: New in Zulip 2.1.0. Previous versions do no offer these
|
|
data via the API.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
Principals:
|
|
name: principals
|
|
in: query
|
|
description: |
|
|
A list of user IDs (preferred) or Zulip API email
|
|
addresses of the users to be subscribed to or unsubscribed
|
|
from the streams specified in the `subscriptions` parameter. If
|
|
not provided, then the requesting user/bot is subscribed.
|
|
|
|
**Changes**: The integer format is new in Zulip 3.0 (feature level 9).
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- type: array
|
|
items:
|
|
type: string
|
|
- type: array
|
|
items:
|
|
type: integer
|
|
example: ["ZOE@zulip.com"]
|
|
ReactionType:
|
|
name: reaction_type
|
|
in: query
|
|
description: |
|
|
A string indicating the type of emoji. Each emoji `reaction_type`
|
|
has an independent namespace for values of `emoji_code`.
|
|
|
|
If an API client is adding/removing a vote on an existing reaction,
|
|
it should pass this parameter using the value the server provided
|
|
for the existing reaction for specificity. Supported values:
|
|
|
|
- `unicode_emoji` : In this namespace, `emoji_code` will be a
|
|
dash-separated hex encoding of the sequence of Unicode codepoints
|
|
that define this emoji in the Unicode specification.
|
|
|
|
- `realm_emoji` : In this namespace, `emoji_code` will be the ID of
|
|
the uploaded [custom emoji](/help/custom-emoji).
|
|
|
|
- `zulip_extra_emoji` : These are special emoji included with Zulip.
|
|
In this namespace, `emoji_code` will be the name of the emoji (e.g.
|
|
"zulip").
|
|
|
|
**Changes**: In Zulip 3.0 (feature level 2), this parameter became
|
|
optional for [custom emoji](/help/custom-emoji);
|
|
previously, this endpoint assumed `unicode_emoji` if this
|
|
parameter was not specified.
|
|
schema:
|
|
type: string
|
|
example: "unicode_emoji"
|
|
required: false
|
|
EmojiCode:
|
|
name: emoji_code
|
|
in: query
|
|
description: |
|
|
A unique identifier, defining the specific emoji codepoint requested,
|
|
within the namespace of the `reaction_type`.
|
|
|
|
For most API clients, you won't need this, but it's important
|
|
for Zulip apps to handle rare corner cases when
|
|
adding/removing votes on an emoji reaction added previously by
|
|
another user.
|
|
|
|
If the existing reaction was added when the Zulip server was
|
|
using a previous version of the emoji data mapping between
|
|
Unicode codepoints and human-readable names, sending the
|
|
`emoji_code` in the data for the original reaction allows the
|
|
Zulip server to correctly interpret your upvote as an upvote
|
|
rather than a reaction with a "different" emoji.
|
|
schema:
|
|
type: string
|
|
example: "1f419"
|
|
required: false
|
|
MessageRetentionDays:
|
|
name: message_retention_days
|
|
in: query
|
|
description: |
|
|
Number of days that messages sent to this stream will be stored
|
|
before being automatically deleted by the [message retention
|
|
policy](/help/message-retention-policy). Two special string format
|
|
values are supported:
|
|
|
|
- `"realm_default"`: Return to the organization-level setting.
|
|
- `"unlimited"`: Retain messages forever.
|
|
|
|
**Changes**: Prior to Zulip 5.0 (feature level 91), retaining
|
|
messages forever was encoded using `"forever"` instead of
|
|
`"unlimited"`.
|
|
|
|
New in Zulip 3.0 (feature level 17).
|
|
schema:
|
|
oneOf:
|
|
- type: string
|
|
- type: integer
|
|
example: "20"
|
|
required: false
|
|
CanRemoveSubscribersGroupId:
|
|
name: can_remove_subscribers_group_id
|
|
in: query
|
|
description: |
|
|
ID of the [user group](/api/get-user-groups) whose members are
|
|
allowed to unsubscribe others from the stream. Note that a user
|
|
who is a member of the specified user group must also [have
|
|
access](/help/stream-permissions) to the stream in order to
|
|
unsubscribe others.
|
|
|
|
This setting can currently only be set to user groups that are
|
|
system groups, except for the system groups named
|
|
`"@role:internet"` and `"@role:owners"`.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 161).
|
|
schema:
|
|
type: integer
|
|
example: 20
|
|
required: false
|
|
LinkifierPattern:
|
|
name: pattern
|
|
in: query
|
|
description: |
|
|
The [Python regular
|
|
expression](https://docs.python.org/3/howto/regex.html) that should
|
|
trigger the linkifier.
|
|
schema:
|
|
type: string
|
|
example: "#(?P<id>[0-9]+)"
|
|
required: true
|
|
LinkifierURLTemplate:
|
|
name: url_template
|
|
in: query
|
|
description: |
|
|
The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html)
|
|
compliant URL template used for the link.
|
|
If you used named groups in `pattern`, you can insert their
|
|
content here with `{name_of_group}`.
|
|
|
|
**Changes**: New in Zulip 7.0 (feature level 176). This replaced
|
|
the `url_format_string` parameter, which was a format string in which
|
|
named groups' content could be inserted with `%(name_of_group)s`.
|
|
schema:
|
|
type: string
|
|
example: https://github.com/zulip/zulip/issues/{id}
|
|
required: true
|
|
DirectMemberOnly:
|
|
name: direct_member_only
|
|
in: query
|
|
description: |
|
|
Whether to consider only the direct members of user group and not members
|
|
of its subgroups. Default is `false`.
|
|
schema:
|
|
type: boolean
|
|
example: false
|
|
required: false
|