openapi: 3.0.1 info: version: 1.0.0 title: Zulip REST authentication real_time_events API description: 'Powerful open source group chat ' contact: url: https://zulip.com license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://{subdomain}.zulipchat.com/api/v1 variables: subdomain: default: example - url: '{server}/api/v1' variables: server: default: https:// - url: https://chat.zulip.org/api/v1 - url: http://localhost:9991/api/v1 - url: http://{subdomain}.testserver/json security: - basicAuth: [] tags: - name: real_time_events paths: /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 timeout and should be respected by clients to avoid breaking when heartbeat timeout increases. ' x-curl-examples-parameters: oneOf: - type: include parameters: enum: - queue_id - last_event_id x-parameter-description: "!!! warn \"\"\n\n **Note**: The parameters documented above are optional in the sense that\n even if you haven't registered a queue by explicitly requesting the\n `POST /register` endpoint, you could pass the parameters for\n [the `POST /register` endpoint](/api/register-queue) to this\n endpoint and a queue would be registered in the absence of a `queue_id`.\n" 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' - 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 a user''s clients when that user''s settings have changed. **Changes**: In Zulip 12.0 (feature level 439), the deprecated, legacy `update_display_settings` and `update_global_notifications` event types were removed entirely. All clients should be using this event type for updates to a user''s settings. New in Zulip 5.0 (feature level 89), replaced and deprecated the `update_display_settings` and `update_global_notifications` event types. ' 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 who can access the modified user for changes in the set of users or those users metadata. **Changes**: Prior to Zulip 8.0 (feature level 228), this event was sent to all users in the organization. ' 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. **Changes**: Removed `is_billing_admin` field in Zulip 10.0 (feature level 363), as it was replaced by the `can_manage_billing_group` realm setting. ' 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. Valid values are: - "G" = Hosted by Gravatar - "J" = Generated using Jdenticon - "U" = Uploaded by user **Changes**: The "J" value is new in Zulip 12.0 (feature level 466). ' 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 [profile time zone](/help/change-your-timezone). ' 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 IANA identifier of the new profile time zone for 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/user-roles) 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 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. See [Markdown message formatting](/api/message-formatting) for details on Zulip''s HTML format. ' - 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. ' - type: object additionalProperties: false description: 'When a user is deactivated or reactivated. Only users who can access the modified user under the organization''s `can_access_all_users_group` policy will receive this event. Clients receiving a deactivation event should remove the user from all user groups in their data structures, because deactivated users cannot be members of groups. **Changes**: Prior to Zulip 10.0 (feature level 303), reactivation events were sent to users who could not access the reactivated user due to a `can_access_all_users_group` policy. Also, previously, Clients were not required to update group membership records during user deactivation. New in Zulip 8.0 (feature level 222). Previously the server sent a `realm_user` event with `op` field set to `remove` when deactivating a user and a `realm_user` event with `op` field set to `add` when reactivating a user. ' properties: user_id: type: integer description: 'The ID of the user affected by this change. ' is_active: type: boolean description: 'A boolean describing whether the user account has been deactivated. ' - type: object additionalProperties: false description: 'When an imported user logs into the organization for the first time. **Changes**: New in Zulip 12.0 (feature level 433). ' properties: user_id: type: integer description: 'The ID of the user affected by this change. ' is_imported_stub: type: boolean description: This value is always `false`. - type: object additionalProperties: false description: 'Sent when the `date_joined` value is updated after an imported stub user or a user created via the API logs in for the first time. **Changes**: New in Zulip 12.0 (feature level 475). ' properties: user_id: type: integer description: 'The ID of the user affected by this change. ' date_joined: type: string description: 'The time when the user logged in to their account for the first time. ' 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 channel 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 channels. **Changes**: Removed `email_address` field from the dictionary in Zulip 8.0 (feature level 226). Removed `role` field from the dictionary in Zulip 6.0 (feature level 133). ' items: $ref: '#/components/schemas/Subscription' additionalProperties: false example: type: subscription op: add subscriptions: - name: test stream_id: 9 is_archived: false creator_id: null description: '' rendered_description: '' invite_only: false is_web_public: false stream_post_policy: 1 history_public_to_subscribers: true first_message_id: null folder_id: 1 is_recently_active: true 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_add_subscribers_group: 2 can_remove_subscribers_group: 2 can_subscribe_group: 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 channels. ' 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 channels. ' items: type: object additionalProperties: false description: 'Dictionary containing details about the unsubscribed channel. ' properties: stream_id: type: integer description: 'The ID of the channel. ' name: type: string description: 'The name of the channel. ' additionalProperties: false example: type: subscription op: remove subscriptions: - name: test 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 channel has been updated. This event is used only for personal properties like `is_muted` or `pin_to_top`. See the [`stream op: update` event](/api/get-events#stream-update) for updates to global properties of a channel. ' 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 channel 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 when another user subscribes to a channel, or their subscription is newly visible to the current user. When a user subscribes to a channel, the current user will receive this event only if they [have permission to see the channel''s subscriber list](/help/channel-permissions). When the current user gains permission to see a given channel''s subscriber list, they will receive this event for the existing subscriptions to the channel. **Changes**: Prior to Zulip 8.0 (feature level 220), this event was incorrectly not sent to guest users when subscribers to web-public channels and subscribed public channels changed. Prior to Zulip 8.0 (feature level 205), this event was not sent when a user gained access to a channel due to their [role changing](/help/user-roles). Prior to Zulip 6.0 (feature level 134), this event was not sent when a private channel was made public. In Zulip 4.0 (feature level 35), the singular `user_id` and `stream_id` integers included in this event were replaced with plural `user_ids` and `stream_ids` integer arrays. In Zulip 3.0 (feature level 19), the `stream_id` field was added to identify the channel the user subscribed to, replacing the `name` field. ' 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 channels that have new or updated subscriber data. **Changes**: New in Zulip 4.0 (feature level 35), replacing the `stream_id` integer. ' items: type: integer user_ids: type: array description: 'The IDs of the users who are newly visible as subscribed to the specified channels. **Changes**: New in Zulip 4.0 (feature level 35), replacing the `user_id` integer. ' items: type: integer additionalProperties: false example: type: subscription op: peer_add stream_ids: - 9 user_ids: - 12 id: 0 - type: object description: 'Event sent to other users when users have been unsubscribed from channels. Sent to all users if the channel is public or to only the existing subscribers if the channel is private. **Changes**: Prior to Zulip 8.0 (feature level 220), this event was incorrectly not sent to guest users when subscribers to web-public channels and subscribed public channels changed. In Zulip 4.0 (feature level 35), the singular `user_id` and `stream_id` integers included in this event were replaced with plural `user_ids` and `stream_ids` integer arrays. In Zulip 3.0 (feature level 19), the `stream_id` field was added to identify the channel the user unsubscribed from, replacing the `name` field. ' 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 channels from which the users have been unsubscribed from. When a user is deactivated, the server will send this event removing the user''s subscriptions before the `realm_user` event for the user''s deactivation. **Changes**: Before Zulip 12.0 (feature level 428), this event was incorrectly not sent when deactivating a user subscribed to archived channels. Clients supporting older server versions and maintaining peer subscriber data need to remove all channel subscriptions for a user when processing the `realm_user` event with `op="remove"`. **Changes**: Before Zulip 10.0 (feature level 377), this event was not sent on user deactivation. **Changes**: New in Zulip 4.0 (feature level 35), replacing the `stream_id` integer. ' items: type: integer user_ids: type: array description: 'The IDs of the users who have been unsubscribed. **Changes**: New in Zulip 4.0 (feature level 35), replacing the `user_id` integer. ' items: type: integer additionalProperties: false example: type: subscription op: peer_remove stream_ids: - 9 user_ids: - 12 id: 0 - type: object description: 'Event type for messages. **Changes**: In Zulip 3.1 (feature level 26), the `sender_short_name` field was removed from message objects. ' 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. **Changes**: In Zulip 8.0 (feature level 224), the `wildcard_mentioned` flag was deprecated in favor of the `stream_wildcard_mentioned` and `topic_wildcard_mentioned` flags. The `wildcard_mentioned` flag exists for backwards compatibility with older clients and equals `stream_wildcard_mentioned || topic_wildcard_mentioned`. Clients supporting older server versions should treat this field as a previous name for the `stream_wildcard_mentioned` flag as topic wildcard mentions were not available prior to this feature level. [message-flags]: /api/update-message-flags#available-flags ' items: type: string local_message_id: type: string description: 'For clients supporting [local echo](https://zulip.readthedocs.io/en/latest/subsystems/sending-messages.html#local-echo). Only present if [`local_id`](/api/send-message#parameter-local_id) and [`queue_id`](/api/send-message#parameter-queue_id) were passed by the client when the message was sent to the server. The same unique string-format identifier chosen by the client to identify the locally echoed message (which was the value passed as the `local_id` parameter). 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). ' additionalProperties: false example: type: message message: id: 31 sender_id: 10 content:

First message ...zulip.txt

recipient_id: 23 timestamp: 1594825416 client: test suite subject: test topic_links: [] is_me_message: false reactions: [] submessages: [] sender_full_name: King 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/configure-call-provider). 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: 'Event sent to a user''s clients when the user completes the OAuth flow for the [Webex integration](/help/configure-call-provider). Clients need to know whether initiating Webex OAuth flow is required before creating a Webex call. ' properties: id: $ref: '#/components/schemas/EventIdSchema' type: allOf: - $ref: '#/components/schemas/EventTypeSchema' - enum: - has_webex_token value: type: boolean description: 'A boolean specifying whether the user has a Webex access token. ' additionalProperties: false example: type: has_webex_token value: true id: 0 - type: object description: 'A simple event sent when the set of invitations changes. This event is sent to organization administrators and the creator of the changed invitation; this tells clients they need to refetch data from `GET /invites` if they are displaying UI containing active invitations. **Changes**: Before Zulip 8.0 (feature level 209), this event was only sent to organization administrators. ' 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 or when a guest user gains access to a user. Processing this event is important to being able to display basic details on other users given only their ID. If the current user is a guest whose access to a newly created user is limited by a `can_access_all_users_group` policy, and the event queue was registered with the `user_list_incomplete` client capability, then the event queue will not receive an event for such a new user. If a newly created user is inaccessible to the current user via such a policy, but the client lacks `user_list_incomplete` client capability, then this event will be delivered to the queue, with an "Unknown user" object with the usual format but placeholder data whose only variable content is the user ID. **Changes**: Before Zulip 8.0 (feature level 232), the `user_list_incomplete` client capability did not exist, and so all clients whose access to a new user was prevented by `can_access_all_users_group` policy would receive a fake "Unknown user" event for such a user. Starting with Zulip 8.0 (feature level 228), this event is also sent when a guest user gains access to a user. ' 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 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: {} is_imported_stub: false id: 0 - type: object description: 'Event sent to guest users when they lose access to a user. **Changes**: As of Zulip 8.0 (feature level 228), this event is no longer deprecated. In Zulip 8.0 (feature level 222), this event was deprecated and no longer sent to clients. Prior to this feature level, it was sent to all users in a Zulip organization when a user was 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. In addition to handling these events, a client that wants to maintain presence data must poll the [main presence endpoint](https://zulip.com/api/get-presence). Most updates to presence data, refreshing the timestamps of users who are already online, do not appear in the event queue. This design is an optimization by allowing those updates to be batched up, because there is no urgency in the information that an already-online user is still online. These events are provided because when a user transitions from offline to online, that is information the client may want to show promptly in the UI to avoid showing a confusing state (for example, if the newly-online user sends a message or otherwise demonstrates they''re online). If the client supports the `simplified_presence_events` [client capability](/api/register-queue#parameter-client_capabilities), these events will include the `presences` field, which provides the modified user''s presence data in the modern format. Clients are strongly encouraged to implement this client capability, as legacy format support will be removed in a future release. If the `CAN_ACCESS_ALL_USERS_GROUP_LIMITS_PRESENCE` server-level setting is set to `true`, then the event is only sent to users who can access the user who came back online. **Changes**: Prior to Zulip 11.0 (feature level 419), the `simplified_presence_events` client capability did not exist. Therefore, all events were in the legacy format, and did not include the `presences` field. Prior to Zulip 8.0 (feature level 228), this event was sent to all users in the organization. ' properties: id: $ref: '#/components/schemas/EventIdSchema' type: allOf: - $ref: '#/components/schemas/EventTypeSchema' - enum: - presence presences: type: object description: 'Only present for clients that support the `simplified_presence_events` [client capability](/api/register-queue#parameter-client_capabilities). A dictionary mapping user IDs to the presence data (modern format) for the modified user(s). Clients should support updating multiple users in a single event. **Changes**: New in Zulip 11.0 (feature level 419). ' additionalProperties: $ref: '#/components/schemas/ModernPresenceFormat' user_id: type: integer description: 'Not present for clients that support the `simplified_presence_events` [client capability](/api/register-queue#parameter-client_capabilities). The ID of the modified user. ' email: type: string description: 'Not present for clients that support the `simplified_presence_events` [client capability](/api/register-queue#parameter-client_capabilities). 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: 'Not present for clients that support the `simplified_presence_events` [client capability](/api/register-queue#parameter-client_capabilities). The timestamp of when the Zulip server received the user''s presence as a UNIX timestamp. ' presence: type: object description: 'Not present for clients that support the `simplified_presence_events` [client capability](/api/register-queue#parameter-client_capabilities). Object containing the presence data (legacy format) of of the modified user. ' 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.3200784 presence: website: client: website status: idle timestamp: 1594825445 pushable: false id: 0 - type: object description: 'Event sent when a new channel is created to users who can see the new channel exists (for private channels, only subscribers and organization administrators will receive this event). This event is also sent when a user gains access to a channel they previously [could not access](/help/channel-permissions), such as when their [role](/help/user-roles) changes, a private channel is made public, or a guest user is subscribed to a public (or private) channel. This event is also sent when a channel is unarchived but only to clients that did not declare the `archived_channels` [client capability][client-capabilities]. Note that organization administrators who are not subscribed will not be able to see content on the channel; just that it exists. **Changes**: Prior to Zulip 11.0 (feature level 378), this event was sent to all the users who could see the channel when it was unarchived. Prior to Zulip 8.0 (feature level 220), this event was incorrectly not sent to guest users a web-public channel was created. Prior to Zulip 8.0 (feature level 205), this event was not sent when a user gained access to a channel due to their role changing. Prior to Zulip 8.0 (feature level 192), this event was not sent when guest users gained access to a public channel by being subscribed. Prior to Zulip 6.0 (feature level 134), this event was not sent when a private channel was made public. ' 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 objects, each containing details about the newly added channel(s). ' items: $ref: '#/components/schemas/BasicChannel' additionalProperties: false example: type: stream op: create streams: - name: private stream_id: 12 is_archived: false description: '' rendered_description: '' date_created: 1691057093 creator_id: 11 invite_only: true is_web_public: false stream_post_policy: 1 history_public_to_subscribers: false first_message_id: null folder_id: 1 is_recently_active: true message_retention_days: null is_announcement_only: false can_add_subscribers_group: 2 can_remove_subscribers_group: 2 can_subscribe_group: 2 stream_weekly_traffic: null subscriber_count: 0 id: 0 - type: object description: 'Event sent when a user loses access to a channel they previously [could access](/help/channel-permissions) because they are unsubscribed from a private channel or their [role](/help/user-roles) has changed. This event is also sent when a channel is archived but only to clients that did not declare the `archived_channels` [client capability][client-capabilities]. **Changes**: Prior to Zulip 11.0 (feature level 378), this event was sent to all the users who could see the channel when it was archived. Prior to Zulip 8.0 (feature level 205), this event was not sent when a user lost access to a channel due to their role changing. [client-capabilities]: /api/register-queue#parameter-client_capabilities ' properties: id: $ref: '#/components/schemas/EventIdSchema' type: allOf: - $ref: '#/components/schemas/EventTypeSchema' - enum: - stream op: type: string enum: - delete streams: type: array deprecated: true description: 'Array of objects, each containing ID of the channel that was deleted. **Changes**: **Deprecated** in Zulip 10.0 (feature level 343) and will be removed in a future release. Previously, these objects additionally contained all the standard fields for a channel object. ' items: type: object properties: stream_id: type: integer description: 'ID of the deleted channel. ' additionalProperties: false stream_ids: type: array description: 'Array containing the IDs of the channels that were deleted. **Changes**: New in Zulip 10.0 (feature level 343). Previously, these IDs were available only via the legacy `streams` array. ' items: type: integer additionalProperties: false example: type: stream op: delete streams: - stream_id: 1 - stream_id: 2 stream_ids: - 1 - 2 id: 0 - type: object description: 'Event sent to all users who can see that a channel exists when a property of that channel changes. See [GET /streams](/api/get-streams#response) response for details on the various properties of a channel. This event is also sent when archiving or unarchiving a channel to all the users who can see that channel exists but only to the clients that declared the `archived_channels` [client capability][client-capabilities]. **Changes**: Prior to Zulip 11.0 (feature level 378), this event was never sent when archiving or unarchiving a channel. Before Zulip 9.0 (feature level 256), this event was never sent when the `first_message_id` property of a channel was updated because the oldest message that had been sent to it changed. [client-capabilities]: /api/register-queue#parameter-client_capabilities ' 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 channel whose details have changed. ' name: type: string description: 'The name of the channel whose details have changed. ' property: type: string description: 'The property of the channel which has changed. See [GET /streams](/api/get-streams#response) response for details on the various properties of a channel. 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. **Changes**: Starting with Zulip 11.0 (feature level 389), this value can be `null` when a channel is removed from the folder. Starting with Zulip 10.0 (feature level 320), this field can be an object for `can_remove_subscribers_group` property, which is a [group-setting value][setting-values], when the setting is set to a combination of users and groups. [setting-values]: /api/group-setting-values ' oneOf: - type: object additionalProperties: false properties: direct_members: description: 'The list of IDs of individual users in the collection of users with this permission. ' type: array items: type: integer direct_subgroups: description: 'The list of IDs of the groups in the collection of users with this permission. ' type: array items: type: integer description: 'If an object, it will be a [group-setting value][setting-values] with these fields: [setting-values]: /api/group-setting-values ' - type: integer - type: boolean - type: string nullable: true rendered_description: type: string description: 'Note: Only present if the changed property was `description`. The short description of the channel rendered as HTML, intended to be used when displaying the channel 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 [Markdown message formatting](/api/message-formatting) for details on Zulip''s HTML format. ' history_public_to_subscribers: type: boolean description: 'Note: Only present if the changed property was `invite_only`. Whether the history of the channel is public to its subscribers. Currently always true for public channels (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 channel''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 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/EmojiReactionEvent' - 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: {} example: type: reaction op: add user_id: 10 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/EmojiReactionEvent' - 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: {} example: type: reaction op: remove user_id: 10 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/Attachment' 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: 1594825414 message_ids: [] 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/Attachment' 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: 1594825414 message_ids: [] 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 to a user''s clients when they [register a device](/api/register-client-device). Helps clients to live-update the `devices` dictionary returned in [`POST /register`](/api/register-queue) response. **Changes**: New in Zulip 12.0 (feature level 468). ' properties: id: $ref: '#/components/schemas/EventIdSchema' type: allOf: - $ref: '#/components/schemas/EventTypeSchema' - enum: - device op: type: string enum: - add device_id: type: integer description: 'The ID of the new registered device. ' example: id: 1 type: device op: add device_id: 1144 - type: object additionalProperties: false description: 'Event sent to a user''s clients when they deregister a device. Helps clients to live-update the `devices` dictionary returned in [`POST /register`](/api/register-queue) response. **Changes**: New in Zulip 12.0 (feature level 468). ' properties: id: $ref: '#/components/schemas/EventIdSchema' type: allOf: - $ref: '#/components/schemas/EventTypeSchema' - enum: - device op: type: string enum: - remove device_id: type: integer description: 'The ID of the device which deregistered. ' example: id: 1 type: device op: remove device_id: 1144 - type: object additionalProperties: false description: 'Event sent to a user''s clients when the metadata in the `devices` dictionary for the user changes. Helps clients to live-update the `devices` dictionary returned in [`POST /register`](/api/register-queue) response. Besides `id`, `type`, `op`, and `device_id`, all other fields are optional. Only fields whose values needs to be updated are included in the event. **Changes**: New in Zulip 12.0 (feature level 468). ' properties: id: $ref: '#/components/schemas/EventIdSchema' type: allOf: - $ref: '#/components/schemas/EventTypeSchema' - enum: - device op: type: string enum: - update device_id: type: integer description: 'The ID of the registered device whose metadata changed. ' push_key_id: type: integer description: 'ID to reference the encryption key used to encrypt push notifications sent to the device. ' push_token_id: type: string nullable: true description: 'ID to reference the token provided by FCM/APNs to the device, which is registered to the push bouncer service. A `null` value means the referenced token expired. ' pending_push_token_id: type: string nullable: true description: 'ID to reference the token provided by FCM/APNs to the device, whose registration is in progress to the push bouncer service. A `null` value means the pending registration succeeded. ' push_token_last_updated_timestamp: type: integer description: 'The UNIX timestamp for the last time when `pending_push_token_id` was set to a new non-null value, in UTC seconds. ' push_registration_error_code: type: string nullable: true description: 'If the push registration failed, a [Zulip API error code](/api/rest-error-handling) indicating the type of failure that occurred. The following error codes have recommended client behavior: - `"INVALID_BOUNCER_PUBLIC_KEY"` - Inform the user to update app. - `"REQUEST_EXPIRED` - Retry with a fresh payload. ' example: id: 2 type: device op: update device_id: 12 push_key_id: 57 - 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 who can access the modified user when the status of a user changes. **Changes**: Prior to Zulip 8.0 (feature level 228), this event was sent to all users in the organization. ' 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 enum: - unicode_emoji - realm_emoji - zulip_extra_emoji 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 required: true editable_by_user: true - id: 2 name: Biography type: 2 hint: What are you known for? field_data: '' order: 2 required: true editable_by_user: true - id: 3 name: Favorite food type: 1 hint: Or drink, if you'd prefer field_data: '' order: 3 required: false editable_by_user: true - 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 required: true editable_by_user: true - id: 5 name: Birthday type: 4 hint: '' field_data: '' order: 5 required: false editable_by_user: false - id: 6 name: Favorite website type: 5 hint: Or your personal blog's URL field_data: '' order: 6 display_in_profile_summary: true required: false editable_by_user: true - id: 7 name: Mentor type: 6 hint: '' field_data: '' order: 7 required: true editable_by_user: false - id: 8 name: GitHub type: 7 hint: Enter your GitHub username field_data: '{"subtype":"github"}' order: 8 required: true editable_by_user: true use_for_user_matching: true 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 channel groups. Default channel 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 channel group. ' items: $ref: '#/components/schemas/DefaultChannelGroup' example: type: default_stream_groups default_stream_groups: - name: group1 id: 2 description: New description streams: - 3 - 1 - 5 id: 0 - type: object additionalProperties: false description: 'Event sent to all users in a Zulip organization when the default channels 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 IDs of all the [default channels](/help/set-default-streams-for-new-users) in the organization. **Changes**: Before Zulip 10.0 (feature level 330), we sent array of dictionaries where each dictionary contained details about a single default stream for the Zulip organization. ' items: type: integer example: type: default_streams default_streams: - 2 - 3 id: 0 - type: object additionalProperties: false description: 'Event sent when a message has been deleted. Sent to all users who currently are subscribed to the messages'' recipient. May also be sent to additional users who had access to the deleted message, including, in particular, an administrator user deleting messages in a channel that they are not subscribed to, but have content access to. Clients can thus reliably remove the messages from whatever view the administrator was using to delete them. Clients will receive an event of this type for message deletions that the client itself initiated if and only if the user previously had access to the deleted messages. (Some moderation actions, such as deleting all messages sent by a user, allow deleting DMs or private channel messages that the acting user cannot themselves access. The user will not receive deletion events for such inaccessible messages). This event is also sent when the user loses access to a message, such as when it is [moved to a channel][message-move-channel] that the user does not [have permission to access][channel-access]. **Changes**: Before Zulip 12.0 (feature level 457), an administrator who initiated the deletion of messages that they did not have permission to access could theoretically receive this event for inaccessible messages. However, no Zulip feature actually generated events of that type. Prior to Zulip 12.0 (feature level 452) messages deleted via a message retention policy incorrectly failed to generate `delete_message` events. Before Zulip 9.0 (feature level 274), this event was only sent to subscribers of the message''s recipient. Before Zulip 5.0 (feature level 77), events for direct messages contained additional `sender_id` and `recipient_id` fields. [message-move-channel]: /help/move-content-to-another-channel [channel-access]: /help/channel-permissions ' 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 sorted list containing the IDs of the newly deleted messages. **Changes**: Before Zulip 11.0 (feature level 393), this list was not guaranteed to be sorted. [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 channel 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. For clients that don''t support the `empty_topic_name` [client capability][client-capabilities], if the actual topic name was empty string, this field''s value will instead be the value of `realm_empty_topic_display_name` found in the [`POST /register`](/api/register-queue) response. **Changes**: Before 10.0 (feature level 334), `empty_topic_name` client capability didn''t exist and empty string as the topic name for channel messages wasn''t allowed. [client-capabilities]: /api/register-queue#parameter-client_capabilities ' 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 channel 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. 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 channel to which the topic belongs. ' topic_name: type: string description: 'The name of the topic. For clients that don''t support the `empty_topic_name` [client capability][client-capabilities], if the actual topic name is empty string, this field''s value will instead be the value of `realm_empty_topic_display_name` found in the [`POST /register`](/api/register-queue) response. **Changes**: Before 10.0 (feature level 334), `empty_topic_name` client capability didn''t exist and empty string as the topic name for channel messages wasn''t allowed. [client-capabilities]: /api/register-queue#parameter-client_capabilities ' 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\npreferences for the topic, such as whether the topic\nis muted.\n\n- 0 = None. Used to indicate that the user no\n longer has a special visibility policy for this topic.\n- 1 = Muted. Used to record [muted topics](/help/mute-a-topic).\n- 2 = Unmuted. Used to record unmuted topics.\n- 3 = Followed. Used to record [followed topics](/help/follow-a-topic).\n\n**Changes**: In Zulip 7.0 (feature level 219), added followed as\na visibility policy option.\n\nIn Zulip 7.0 (feature level 170), added unmuted as a visibility\npolicy option.\n" 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 steps to show for the current user has 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. **Changes**: Before Zulip 8.0 (feature level 233), this event was named `hotspots`. Prior to this feature level, one-time notice onboarding steps were not supported. ' properties: id: $ref: '#/components/schemas/EventIdSchema' type: allOf: - $ref: '#/components/schemas/EventTypeSchema' - enum: - onboarding_steps onboarding_steps: type: array description: 'An array of dictionaries where each dictionary contains details about a single onboarding step. **Changes**: Before Zulip 8.0 (feature level 233), this array was named `hotspots`. Prior to this feature level, one-time notice onboarding steps were not supported, and the `type` field in these objects did not exist as all onboarding steps were implicitly hotspots. ' items: $ref: '#/components/schemas/OnboardingStep' example: type: onboarding_steps onboarding_steps: - type: one_time_notice name: visibility_policy_banner id: 0 - type: object additionalProperties: false description: 'Event sent when a message''s content, topic and/or channel 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 **Changes**: In Zulip 10.0 (feature level 284), removed the `prev_rendered_content_version` field as it is an internal server implementation detail not used by any client. ' 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. Will be `null` when event is for a rendering update of the original message, such as for an [inline URL preview][inline-url-previews]. **Changes**: Prior to Zulip 5.0 (feature level 114), 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 events prior to this feature level 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 channel 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: 'A sorted list of IDs of messages to which any channel or topic changes encoded in this event should be applied. This list always includes `message_id`, even when there are no channel or topic changes to apply. These messages are guaranteed to have all been previously sent to channel `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 channel and topic. Content changes should be applied only to the single message indicated by `message_id`. **Changes**: Before Zulip 11.0 (feature level 393), this list was not guaranteed to be sorted. ' 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. **Changes**: In Zulip 8.0 (feature level 224), the `wildcard_mentioned` flag was deprecated in favor of the `stream_wildcard_mentioned` and `topic_wildcard_mentioned` flags. The `wildcard_mentioned` flag exists for backwards compatibility with older clients and equals `stream_wildcard_mentioned || topic_wildcard_mentioned`. Clients supporting older server versions should treat this field as a previous name for the `stream_wildcard_mentioned` flag as topic wildcard mentions were not available prior to this feature level. [message-flags]: /api/update-message-flags#available-flags ' items: type: string edit_timestamp: type: integer description: 'The UNIX timestamp when this message edit operation was processed by the server, in UTC seconds. **Changes**: Prior to Zulip 5.0 (feature level 114), 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 channel. The name of the channel 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 channel. The pre-edit channel 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 channel message. Previously, it was not present when only the content of the channel message was edited. ' new_stream_id: type: integer description: 'Only present if message(s) were moved to a different channel. The post-edit channel 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\ntopic and/or channel.\n\nThe choice the editing user made about which messages should be\naffected by a channel/topic edit:\n\n- `\"change_one\"`: Just change the one indicated in `message_id`.\n- `\"change_later\"`: Change messages in the same topic that had\n been sent after this one.\n- `\"change_all\"`: Change all messages in that topic.\n\nThis parameter should be used to decide whether to change\nnavigation and compose box state in response to the edit. For\nexample, if the user was previously in topic narrow, and the\ntopic was edited with `\"change_later\"` or `\"change_all\"`, the Zulip\nweb app will automatically navigate to the new topic narrow.\nSimilarly, a message being composed to the old topic should\nhave its recipient changed to the new topic.\n\nThis navigation makes it much more convenient to move content\nbetween topics without disruption or messages continuing\nto be sent to the pre-edit topic by accident.\n" 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 channel. The pre-edit topic for all of the messages with IDs in `message_ids`. For clients that don''t support the `empty_topic_name` [client capability][client-capabilities], if the actual pre-edit topic name is empty string, this field''s value will instead be the value of `realm_empty_topic_display_name` found in the [`POST /register`](/api/register-queue) response. **Changes**: Before 10.0 (feature level 334), `empty_topic_name` client capability didn''t exist and empty string as the topic name for channel messages wasn''t allowed. [client-capabilities]: /api/register-queue#parameter-client_capabilities ' subject: type: string description: 'Only present if this event moved messages to a different topic; this field will not be present when moving messages to the same topic name in a different channel. The post-edit topic for all of the messages with IDs in `message_ids`. For clients that don''t support the `empty_topic_name` [client capability][client-capabilities], if the actual post-edit topic name is empty string, this field''s value will instead be the value of `realm_empty_topic_display_name` found in the [`POST /register`](/api/register-queue) response. **Changes**: Before 10.0 (feature level 334), `empty_topic_name` client capability didn''t exist and empty string as the topic name for channel messages wasn''t allowed. [client-capabilities]: /api/register-queue#parameter-client_capabilities ' 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; this field will not be present when moving messages to the same topic name in a different channel. 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 [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format. ' 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. See [Markdown message formatting](/api/message-formatting) for details on Zulip''s HTML format. ' 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 [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format. ' 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. See [Markdown message formatting](/api/message-formatting) for details on Zulip''s HTML format. ' 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:

hello

content: new content rendered_content:

new content

is_me_message: false propagate_mode: change_all stream_id: 5 orig_subject: test subject: new_topic topic_links: [] message_ids: - 57 - 58 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 channel 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 channel 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 `"direct"`. **Changes**: In Zulip 8.0 (feature level 215), replaced the value `"private"` with `"direct"`. New in Zulip 4.0 (feature level 58). Previously, all typing notifications were implicitly direct messages. ' enum: - direct - 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 `"direct"`. 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 channel to which message is being typed. **Changes**: New in Zulip 4.0 (feature level 58). Previously, typing notifications were only for direct messages. ' topic: type: string description: 'Only present if `message_type` is `"stream"`. Topic within the channel where the message is being typed. For clients that don''t support the `empty_topic_name` [client capability][client-capabilities], if the actual topic name is empty string, this field''s value will instead be the value of `realm_empty_topic_display_name` found in the [`POST /register`](/api/register-queue) response. **Changes**: Before 10.0 (feature level 334), `empty_topic_name` client capability didn''t exist and empty string as the topic name for channel messages wasn''t allowed. New in Zulip 4.0 (feature level 58). Previously, typing notifications were only for direct messages. [client-capabilities]: /api/register-queue#parameter-client_capabilities ' example: type: typing op: start message_type: direct 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 channel 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 channel 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 `"direct"`. **Changes**: In Zulip 8.0 (feature level 215), replaced the value `"private"` with `"direct"`. New in Zulip 4.0 (feature level 58). Previously all typing notifications were implicitly direct messages. ' enum: - direct - 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 `"direct"`. 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 channel to which message is being typed. **Changes**: New in Zulip 4.0 (feature level 58). Previously, typing notifications were only for direct messages. ' topic: type: string description: 'Only present if `message_type` is `"stream"`. Topic within the channel where the message is being typed. **Changes**: New in Zulip 4.0 (feature level 58). Previously, typing notifications were only for direct messages. ' example: type: typing op: stop message_type: direct 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 starts editing a message. Event sent when a user starts typing in a textarea to edit the content of a message. See the [edit message typing notifications endpoint](/api/set-typing-status-for-message-edit). Clients requesting `typing_edit_message` event type that have `receives_typing_notifications` enabled will receive this event if they would have been notified if the message''s content edit were to be saved (E.g., because they were a direct message recipient or are a subscribe to the channel). **Changes**: New in Zulip 10.0 (feature level 351). Previously, typing notifications were not available when editing messages. ' properties: id: $ref: '#/components/schemas/EventIdSchema' type: allOf: - $ref: '#/components/schemas/EventTypeSchema' - enum: - typing_edit_message op: type: string enum: - start sender_id: type: integer description: 'The ID of the user who is typing the edit of the message. Clients should be careful to display this user as the person who is typing, not that of the sender of the message, in case a collaborative editing feature be might be added in the future. ' message_id: type: integer description: 'Indicates the message id of the message that is being edited. ' recipient: type: object description: 'Object containing details about recipients of message edit typing notification. ' additionalProperties: false properties: type: type: string description: 'Type of message being composed. Must be `"channel"` or `"direct"`. ' enum: - direct - channel channel_id: type: integer description: 'Only present if `type` is `"channel"`. The unique ID of the channel to which message is being edited. ' topic: type: string description: 'Only present if `type` is `"channel"`. Topic within the channel where the message is being edited. ' user_ids: type: array items: type: integer description: 'Present only if `type` is `direct`. The user IDs of every recipient of this direct message. ' example: type: typing_edit_message op: start sender_id: 10 recipient: type: direct user_ids: - 8 - 10 message_id: 7 id: 0 - type: object additionalProperties: false description: 'Event sent when a user stops typing in a textarea to edit the content of a message. See the [edit message typing notifications endpoint](/api/set-typing-status-for-message-edit). Clients requesting `typing_edit_message` event type that have `receives_typing_notifications` enabled will receive this event if they would have been notified if the message''s content edit were to be saved (E.g., because they were a direct message recipient or are a subscribe to the channel). **Changes**: New in Zulip 10.0 (feature level 351). Previously, typing notifications were not available when editing messages. ' properties: id: $ref: '#/components/schemas/EventIdSchema' type: allOf: - $ref: '#/components/schemas/EventTypeSchema' - enum: - typing_edit_message op: type: string enum: - stop sender_id: type: integer description: 'The ID of the user who sent the message. ' message_id: type: integer description: 'Indicates the message id of the message that is being edited. ' recipient: type: object description: 'Object containing details about recipients of message edit typing notification. ' additionalProperties: false properties: type: type: string description: 'Type of message being composed. Must be `"channel"` or `"direct"`. ' enum: - direct - channel channel_id: type: integer description: 'Only present if `type` is `"channel"`. The unique ID of the channel to which message is being edited. ' topic: type: string description: 'Only present if `type` is `"channel"`. Topic within the channel where the message is being edited. ' user_ids: type: array items: type: integer description: 'Present only if `type` is `direct`. The user IDs of every recipient of this direct message. ' example: type: typing_edit_message op: stop sender_id: 10 message_id: 31 recipient: type: direct user_ids: - 8 - 10 id: 0 - type: object additionalProperties: false description: "Event sent to a user when [message flags][message-flags] are added\nto messages.\n\nThis can reflect a direct user action, or can be the indirect\nconsequence of another action. Whatever the cause, if there's a change\nin the set of message flags that the user has for a message, then an\n`update_message_flags` event will be sent with the change. Note\nthat this applies when the user already had access to the message, and\ncontinues to have access to it. When a message newly appears or\ndisappears, a [`message`][message-event] or\n[`delete_message`][message-delete] event is sent instead.\n\nSome examples of actions that trigger an `update_message_flags`\nevent:\n\n- The `\"starred\"` flag is added when the user chooses to [star a\n message](/help/star-a-message).\n- The `\"read\"` flag is added when the user marks messages as read by\n scrolling through them, or uses [Mark all messages as read][all-read]\n on a conversation.\n- The `\"read\"` flag is added when the user [mutes](/help/mute-a-user) a\n message's sender.\n- The `\"read\"` flag is added after the user unsubscribes from a channel,\n or messages are moved to a not-subscribed channel, provided the user\n can still access the messages at all. Note a\n [`delete_message`][message-delete] event is sent in the case where the\n user can no longer access the messages.\n\nIn some cases, a change in message flags that's caused by another change\nmay happen a short while after the original change, rather than\nsimultaneously. For example, when messages that were unread are moved to\na channel where the user is not subscribed, the resulting change in\nmessage flags (and the corresponding `update_message_flags` event with\nflag `\"read\"`) may happen later than the message move itself. The delay\nin that example is typically at most a few hundred milliseconds and can\nin rare cases be minutes or longer.\n\n[message-flags]: /api/update-message-flags#available-flags\n[message-event]: /api/get-events#message\n[message-delete]: /api/get-events#delete_message\n[all-read]: /help/marking-messages-as-read#mark-messages-in-multiple-topics-and-channels-as-read\n" 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 the `op` field in this event type. **Deprecated** in Zulip 4.0 (feature level 32), and replaced by the `op` field. ' type: string enum: - add flag: type: string description: 'The [flag][message-flags] 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 specified flag was added to all messages. This field is only relevant for the `"read"` flag, and will be `false` for all other flags. When `true` for the `"read"` flag, 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 messages. See the description for the [`update_message_flags` op: `add`](/api/get-events#update_message_flags-add) event for more details about these events. [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: - remove operation: deprecated: true type: string description: 'Old name for the `op` field in this event type. **Deprecated** in Zulip 4.0 (feature level 32), and replaced by the `op` field. ' enum: - remove flag: type: string description: 'The [flag][message-flags] to be removed. ' messages: type: array description: 'Array containing the IDs of the messages from which the flag was removed. ' items: type: integer all: deprecated: true type: boolean description: 'Will be `false` for all specified flags. **Deprecated** and will be removed in a future release. ' message_details: description: 'Only present if the specified `flag` is `"read"`. A set of data structures describing the messages that are being marked as unread with additional details to allow clients 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: '`{message_id}`: Object containing details about the message with the specified ID. ' additionalProperties: false required: - type properties: type: type: string description: 'The type of this message. Either `"stream"` or `"private"`. ' 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 direct 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 channel where the message was sent. ' topic: type: string description: 'Present only if `type` is `"stream"`. Name of the topic where the message was sent. For clients that don''t support the `empty_topic_name` [client capability][client-capabilities], if the actual topic name is empty string, this field''s value will instead be the value of `realm_empty_topic_display_name` found in the [`POST /register`](/api/register-queue) response. **Changes**: Before 10.0 (feature level 334), `empty_topic_name` client capability didn''t exist and empty string as the topic name for channel messages wasn''t allowed. [client-capabilities]: /api/register-queue#parameter-client_capabilities ' 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 creator_id: 9 date_created: 1717484476 description: Backend team id: 2 is_system_group: false can_add_members_group: 16 can_join_group: 16 can_leave_group: 15 can_manage_group: 16 can_mention_group: 11 can_remove_members_group: 16 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. For group deactivation, this event is only sent if `include_deactivated_groups` client capability is set to `true`. This event is also sent when deactivating or reactivating a user for settings set to anonymous user groups which the user is direct member of. When deactivating the user, event is only sent to users who cannot access the deactivated user. **Changes**: Starting with Zulip 10.0 (feature level 303), this event can also be sent when deactivating or reactivating a user. Prior to Zulip 10.0 (feature level 294), this event was sent to all clients when a user group was deactivated. ' 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. ' can_add_members_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value][setting-values] defining the set of users who have permission to add members to this group. Only present if this user group permission setting changed. **Changes**: New in Zulip 10.0 (feature level 305). Previously, this permission was controlled by the `can_manage_group` setting. Will be one of the following: [setting-values]: /api/group-setting-values ' can_join_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value][setting-values] defining the set of users who have permission to join this group. Only present if this user group permission setting changed. **Changes**: New in Zulip 10.0 (feature level 301). Will be one of the following: [setting-values]: /api/group-setting-values ' can_leave_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value][setting-values] defining the set of users who have permission to leave this group. Only present if this user group permission setting changed. **Changes**: New in Zulip 10.0 (feature level 308). Will be one of the following: [setting-values]: /api/group-setting-values ' can_manage_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value][setting-values] defining the set of users who have permission to [manage this group][manage-user-groups]. Only present if this user group permission setting changed. **Changes**: New in Zulip 10.0 (feature level 283). Will be one of the following: [setting-values]: /api/group-setting-values [manage-user-groups]: /help/manage-user-groups ' can_mention_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value][setting-values] defining the set of users who have permission to [mention this user group][mentions]. Only present if this user group permission setting changed. **Changes**: Before Zulip 9.0 (feature level 258), this setting was always the integer form of a [group-setting value][setting-values]. Before Zulip 8.0 (feature level 198), this setting was named `can_mention_group_id`. New in Zulip 8.0 (feature level 191). Previously, groups could be mentioned only if they were not [system groups][system-groups]. Will be one of the following: [setting-values]: /api/group-setting-values [system-groups]: /api/group-setting-values#system-groups [mentions]: /help/mention-a-user-or-group ' can_remove_members_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value][setting-values] defining the set of users who have permission to remove members from this group. Only present if this user group permission setting changed. **Changes**: New in Zulip 10.0 (feature level 324). Previously, this permission was controlled by the `can_manage_group` setting. Will be one of the following: [setting-values]: /api/group-setting-values ' deactivated: type: boolean description: 'Whether the user group is deactivated. Deactivated groups cannot be used as a subgroup of another group or used for any other purpose. **Changes**: New in Zulip 10.0 (feature level 290). ' 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. This event is also sent when reactivating a user for all the user groups the reactivated user was a member of before being deactivated. **Changes**: Starting with Zulip 10.0 (feature level 303), this event can also be sent when reactivating a user. ' 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. This event is also sent when deactivating a user, for all the user groups the deactivated user is a member of, but only to the users who cannot access the deactivated user. **Changes**: Starting with Zulip 10.0 (feature level 303), this event can also be sent when deactivating a user. ' 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 when a user group is deactivated but only to clients with `include_deactivated_groups` client capability set to `false`. **Changes**: Prior to Zulip 10.0 (feature level 294), this event was sent when a user group was 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: 'An ordered array of dictionaries where each dictionary contains details about a single linkifier. Clients should always process linkifiers in the order given; this is important if the realm has linkifiers with overlapping patterns. The order can be modified using [`PATCH /realm/linkifiers`](/api/reorder-linkifiers). ' 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_input: type: string nullable: true description: 'An example input string that matches the linkifier''s pattern. This is required for reverse linkifiers. **Changes**: New in Zulip 12.0 (feature level 471). ' reverse_template: type: string nullable: true description: 'A simple template using `{variable}` for variables that can be used to generate the Markdown linkifier syntax, given a URL matching the URL template. `{{ "{{/}}" }}` can be used for literal `{/}` characters. **Changes**: New in Zulip 12.0 (feature level 471). ' alternative_url_templates: type: array items: type: string description: 'An array of additional [RFC 6570][rfc6570] compliant URL template strings that are used for reverse linkification (converting pasted URLs to linkifier pattern text). These templates have no effect on forward linkification. [rfc6570]: https://www.rfc-editor.org/rfc/rfc6570.html **Changes**: New in Zulip 12.0 (feature level e2b257). ' example: type: realm_linkifiers realm_linkifiers: - pattern: '#(?P[123])' url_template: https://realm.com/my_realm_filter/{id} id: 1 example_input: '#1234' reverse_template: '#{id}' alternative_url_templates: - https://realm.com/my_realm_filter/issue/{id} 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[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_template: 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 added. Only sent to clients that set the `individual_emoji_changes` client capability. **Changes**: New in Zulip 12.0 (feature level 491), replacing half of the functionality of the `realm_emoji/update` event. ' properties: id: $ref: '#/components/schemas/EventIdSchema' type: allOf: - $ref: '#/components/schemas/EventTypeSchema' - enum: - realm_emoji op: type: string enum: - add emoji: $ref: '#/components/schemas/RealmEmoji' example: type: realm_emoji op: add emoji: id: '2' name: my_emoji source_url: /user_avatars/2/emoji/images/2.png still_url: null deactivated: false author_id: 11 id: 0 - type: object additionalProperties: false description: 'Event sent to all users in a Zulip organization when a property of a [custom emoji](/help/custom-emoji) has been changed. Only the fields being updated are included in the event. Currently, the only property that can be updated is `deactivated`, but this may be extended in the future. Only sent to clients that set the `individual_emoji_changes` client capability. **Changes**: New in Zulip 12.0 (feature level 491), replacing half of the functionality of the `realm_emoji/update` event. ' properties: id: $ref: '#/components/schemas/EventIdSchema' type: allOf: - $ref: '#/components/schemas/EventTypeSchema' - enum: - realm_emoji op: type: string enum: - update_one emoji_id: type: string description: 'The ID of the custom emoji being updated. ' data: type: object description: 'And object containing the properties that have changed. ' properties: deactivated: type: boolean description: 'Whether the custom emoji has been deactivated. ' additionalProperties: false required: - id - type - op - emoji_id - data example: type: realm_emoji op: update_one emoji_id: '2' data: deactivated: true 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. This legacy event is sent to clients that do not set the `individual_emoji_changes` client capability. **Changes**: Before Zulip 12.0 (feature level 491), this was the only format of `realm_emoji` event sent. Clients should set the `individual_emoji_changes` capability and handle `realm_emoji/add` and `realm_emoji/edit` events instead. ' 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 keys are RealmEmoji ids, and the values describe the custom emoji for that id. ' 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 a new domain has been added to the set of [allowed domains for account creation and email changes](/help/restrict-account-creation#configuring-email-domain-restrictions). ' properties: id: $ref: '#/components/schemas/EventIdSchema' type: allOf: - $ref: '#/components/schemas/EventTypeSchema' - enum: - realm_domains op: type: string enum: - add realm_domain: allOf: - $ref: '#/components/schemas/RealmDomain' - description: 'Object containing details of the newly added domain. ' 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 account creation and email changes](/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: allOf: - $ref: '#/components/schemas/RealmDomain' - description: 'Object containing details of the edited 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 a domain has been removed from the set of [allowed domains for account creation and email changes](/help/restrict-account-creation#configuring-email-domain-restrictions). ' 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 data 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 details about a data export of the organization. **Changes**: Prior to Zulip 10.0 (feature level 304), `export_type` parameter was not present as only public data export was supported via API. ' items: $ref: '#/components/schemas/RealmExport' example: type: realm_export exports: - id: 107 export_time: 1594825443.656797 acting_user_id: 10 export_url: null deleted_timestamp: null failed_timestamp: 1594825444.436336 pending: false export_type: public id: 1 - type: object additionalProperties: false description: 'Event sent to administrators when the [data export consent][help-export-consent] status for a user changes, whether due to a user changing their consent preferences or a user being created or reactivated (since user creation/activation events do not contain these data). [help-export-consent]: /help/export-your-organization#configure-whether-administrators-can-export-your-private-data **Changes**: New in Zulip 10.0 (feature level 312). Previously, there was not event available to administrators with these data. ' properties: id: $ref: '#/components/schemas/EventIdSchema' type: allOf: - $ref: '#/components/schemas/EventTypeSchema' - enum: - realm_export_consent user_id: type: integer description: 'The ID of the user whose setting was changed. ' consented: type: boolean description: 'Whether the user has consented for their private data export. ' example: type: realm_export_consent user_id: 1 consented: true - 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: user_id: 36 default_sending_stream: null default_events_register_stream: null default_all_public_streams: false services: [] 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. **Changes**: Starting from Zulip 12.0 (feature level 474), this event is not sent when updating bot''s avatar, email, name or owner and also when reactivating or deactivating a bot. Starting from Zulip 12.0 (feature level 474), this event is no longer sent when a bot''s API key is regenerated. Clients now use [`GET /bots/{bot_id}/api_key`](/api/get-bot-api-key) to get api key for the bot. ' 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. **Changes**: Deprecated and no longer sent since Zulip 8.0 (feature level 222). Previously, this event was sent to all users in a Zulip organization when a bot was 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 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. **Changes**: Removed the `rendered_description` property in Zulip 12.0 (feature level 464). It had been briefly present only since feature level 462 and can be safely ignored by all clients. Removed `extra_data` optional property in Zulip 10.0 (feature level 306). The `extra_data` used to include an `upload_quota` field when changed property was `plan_type`. The server now sends a standard `realm/update_dict` event for plan changes. ' 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. ' oneOf: - type: string - type: boolean - type: integer nullable: true 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 should use this event to update their tracking of the server''s capabilities, and to decide if they wish to get a new event queue after a server upgrade. Clients doing so must implement a random delay strategy to spread such restarts over 5 minutes or more to avoid creating a synchronized thundering herd effect. **Changes**: Removed the `immediate` flag, which was only used by web clients in development, in Zulip 9.0 (feature level 240). ' 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 should use this to update their tracking of the server''s capabilities, and may choose to refetch their state and create a new event queue when the API feature level has changed in a way that the client finds significant. Clients choosing to do so must implement a random delay strategy to spread such restarts over 5 or more minutes to avoid creating a synchronized thundering herd effect. **Changes**: New in Zulip 4.0 (feature level 59). ' server_generation: type: integer description: 'The timestamp at which the server started. ' additionalProperties: false example: id: 0 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 description: 'An event which signals the official Zulip web/desktop app to update, by reloading the page and fetching a new queue; this will generally follow a `restart` event. Clients which do not obtain their code from the server (e.g. mobile and terminal clients, which store their code locally) should ignore this event. Clients choosing to reload the application must implement a random delay strategy to spread such restarts over 5 or more minutes to avoid creating a synchronized thundering herd effect. **Changes**: New in Zulip 9.0 (feature level 240). ' properties: id: $ref: '#/components/schemas/EventIdSchema' type: allOf: - $ref: '#/components/schemas/EventTypeSchema' - enum: - web_reload_client 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. ' additionalProperties: false example: id: 0 type: web_reload_client immediate: true - 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. This event is also sent when deactivating or reactivating a user for settings set to anonymous user groups which the user is direct member of. When deactivating the user, event is only sent to users who cannot access the deactivated user. **Changes**: Starting with Zulip 10.0 (feature level 303), this event can also be sent when deactivating or reactivating a user. 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 10.0 (feature level 316), `edit_topic_policy` property was removed and replaced by `can_move_messages_between_topics_group` realm setting. 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: allow_message_editing: type: boolean description: 'Whether this organization''s [message edit policy][config-message-editing] allows editing the content of messages. See [`PATCH /messages/{message_id}`](/api/update-message) for details and history of how message editing permissions work. [config-message-editing]: /help/restrict-message-editing-and-deletion ' authentication_methods: type: object additionalProperties: $ref: '#/components/schemas/RealmAuthenticationMethod' description: 'Dictionary of authentication method keys mapped to dictionaries that describe the properties of the named authentication method for the organization - its enabled status and availability for use by the organization. Clients should use this to implement server-settings UI to change which methods are enabled for the organization. For authentication UI itself, clients should use the pre-authentication metadata returned by [`GET /server_settings`](/api/get-server-settings). **Changes**: In Zulip 9.0 (feature level 243), the values in this dictionary were changed. Previously, the values were a simple boolean indicating whether the backend is enabled or not. ' can_access_all_users_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value](/api/group-setting-values) defining the set of users who are allowed to access all users in the organization. **Changes**: Prior to Zulip 10.0 (feature level 314), this value used to be of type integer and did not accept anonymous user groups. New in Zulip 8.0 (feature level 225). ' can_create_groups: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value](/api/group-setting-values) defining the set of users who have permission to create user groups in this organization. **Changes**: New in Zulip 10.0 (feature level 299). Previously `user_group_edit_policy` field used to control the permission to create user groups. ' can_create_bots_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value](/api/group-setting-values) defining the set of users who have permission to create all types of bot users in the organization. See also `can_create_write_only_bots_group`. **Changes**: New in Zulip 10.0 (feature level 344). Previously, this permission was controlled by the enum `bot_creation_policy`. Values were 1=Members, 2=Generic bots limited to administrators, 3=Administrators. ' can_create_write_only_bots_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value](/api/group-setting-values) defining the set of users who have permission to create bot users that can only send messages in the organization, i.e. incoming webhooks, in addition to the users who are present in `can_create_bots_group`. **Changes**: New in Zulip 10.0 (feature level 344). Previously, this permission was controlled by the enum `bot_creation_policy`. Values were 1=Members, 2=Generic bots limited to administrators, 3=Administrators. ' can_create_public_channel_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value](/api/group-setting-values) defining the set of users who have permission to create public channels in this organization. **Changes**: New in Zulip 9.0 (feature level 264). Previously `realm_create_public_stream_policy` field used to control the permission to create public channels. ' can_create_private_channel_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value](/api/group-setting-values) defining the set of users who have permission to create private channels in this organization. **Changes**: New in Zulip 9.0 (feature level 266). Previously `realm_create_private_stream_policy` field used to control the permission to create private channels. ' can_create_web_public_channel_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value](/api/group-setting-values) defining the set of users who have permission to create web-public channels in this organization. **Changes**: New in Zulip 10.0 (feature level 280). Previously `realm_create_web_public_stream_policy` field used to control the permission to create web-public channels. ' can_add_custom_emoji_group: allOf: - description: 'A [group-setting value](/api/group-setting-values) defining the set of users who have permission to add custom emoji in the organization. **Changes**: New in Zulip 10.0 (feature level 307). Previously, this permission was controlled by the enum `add_custom_emoji_policy`. Values were 1=Members, 2=Admins, 3=Full members, 4=Moderators. Before Zulip 5.0 (feature level 85), the `realm_add_emoji_by_admins_only` boolean setting controlled this permission; `true` corresponded to `Admins`, and `false` to `Everyone`. ' - $ref: '#/components/schemas/GroupSettingValue' can_add_subscribers_group: allOf: - description: 'A [group-setting value](/api/group-setting-values) defining the set of users who have permission to add subscribers to channels in the organization. **Changes**: New in Zulip 10.0 (feature level 341). Previously, this permission was controlled by the enum `invite_to_stream_policy`. Values were 1=Members, 2=Admins, 3=Full members, 4=Moderators. ' - $ref: '#/components/schemas/GroupSettingValue' can_delete_any_message_group: allOf: - description: 'A [group-setting value](/api/group-setting-values) defining the set of users who have permission to delete any message in the organization. **Changes**: New in Zulip 10.0 (feature level 281). Previously, this permission was limited to administrators only and was uneditable. ' - $ref: '#/components/schemas/GroupSettingValue' can_delete_own_message_group: allOf: - description: 'A [group-setting value](/api/group-setting-values) defining the set of users who have permission to delete messages that they have sent in the organization. **Changes**: New in Zulip 10.0 (feature level 291). Previously, this permission was controlled by the enum `delete_own_message_policy`. Values were 1=Members, 2=Admins, 3=Full members, 4=Moderators, 5=Everyone. Before Zulip 5.0 (feature level 101), the `allow_message_deleting` boolean setting controlled this permission; `true` corresponded to `Everyone`, and `false` to `Admins`. ' - $ref: '#/components/schemas/GroupSettingValue' can_set_delete_message_policy_group: allOf: - description: 'A [group-setting value](/api/group-setting-values) defining the set of users who have permission to change per-channel `can_delete_any_message_group` and `can_delete_own_message_group` permission settings. Note that the user must be a member of both this group and the `can_administer_channel_group` of the channel whose message delete settings they want to change. Organization administrators can always change these settings of every channel. **Changes**: New in Zulip 11.0 (feature level 407). ' - $ref: '#/components/schemas/GroupSettingValue' can_set_topics_policy_group: allOf: - description: 'A [group-setting value](/api/group-setting-values) defining the set of users who have permission to change per-channel `topics_policy` setting. Note that the user must be a member of both this group and the `can_administer_channel_group` of the channel whose `topics_policy` they want to change. Organization administrators can always change the `topics_policy` setting of every channel. **Changes**: New in Zulip 11.0 (feature level 392). ' - $ref: '#/components/schemas/GroupSettingValue' can_invite_users_group: allOf: - description: 'A [group-setting value](/api/group-setting-values) defining the set of users who have permission to send email invitations for inviting other users to the organization. **Changes**: New in Zulip 10.0 (feature level 321). Previously, this permission was controlled by the enum `invite_to_realm_policy`. Values were 1=Members, 2=Admins, 3=Full members, 4=Moderators, 6=Nobody. Before Zulip 4.0 (feature level 50), the `invite_by_admins_only` boolean setting controlled this permission; `true` corresponded to `Admins`, and `false` to `Members`. ' - $ref: '#/components/schemas/GroupSettingValue' can_mention_many_users_group: allOf: - description: 'A [group-setting value](/api/group-setting-values) defining the set of users who have permission to use wildcard mentions in large channels. All users will receive a warning/reminder when using mentions in large channels, even when permitted to do so. **Changes**: New in Zulip 10.0 (feature level 352). Previously, this permission was controlled by the enum `wildcard_mention_policy`. ' - $ref: '#/components/schemas/GroupSettingValue' can_move_messages_between_channels_group: allOf: - description: 'A [group-setting value](/api/group-setting-values) defining the set of users who have permission to move messages from one channel to another in the organization. **Changes**: New in Zulip 10.0 (feature level 310). Previously, this permission was controlled by the enum `move_messages_between_streams_policy`. Values were 1=Members, 2=Admins, 3=Full members, 4=Moderators, 6=Nobody. In Zulip 7.0 (feature level 159), `Nobody` was added as an option to `move_messages_between_streams_policy` enum. ' - $ref: '#/components/schemas/GroupSettingValue' can_move_messages_between_topics_group: allOf: - description: 'A [group-setting value](/api/group-setting-values) defining the set of users who have permission to move messages from one topic to another within a channel in the organization. **Changes**: New in Zulip 10.0 (feature level 316). Previously, this permission was controlled by the enum `edit_topic_policy`. Values were 1=Members, 2=Admins, 3=Full members, 4=Moderators, 5=Everyone, 6=Nobody. In Zulip 7.0 (feature level 159), `Nobody` was added as an option to `edit_topic_policy` enum. ' - $ref: '#/components/schemas/GroupSettingValue' can_resolve_topics_group: allOf: - description: 'A [group-setting value](/api/group-setting-values) defining the set of users who have permission to [resolve topics](/help/resolve-a-topic) in the organization. **Changes**: New in Zulip 10.0 (feature level 367). Previously, permission to resolve topics was controlled by the more general can_move_messages_between_topics_group permission for moving messages. ' - $ref: '#/components/schemas/GroupSettingValue' can_manage_all_groups: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: "A [group-setting value](/api/group-setting-values)\ndefining the set of users who have permission to\nadminister all existing groups in this organization.\n\n**Changes**: Prior to Zulip 10.0 (feature level 305), only users who\nwere a member of the group or had the moderator role or above could\nexercise the permission on a given group.\n\nNew in Zulip 10.0 (feature level 299). Previously the\n`user_group_edit_policy` field controlled the permission\nto manage user groups. Valid values were as follows:\n\n- 1 = All members can create and edit user groups\n- 2 = Only organization administrators can create and edit\n user groups\n- 3 = Only [full members][calc-full-member] can create and\n edit user groups.\n- 4 = Only organization administrators and moderators can\n create and edit user groups.\n\n[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member\n" can_manage_billing_group: allOf: - description: 'A [group-setting value](/api/group-setting-values) defining the set of users who have permission to manage plans and billing in the organization. **Changes**: New in Zulip 10.0 (feature level 363). Previously, only owners and users with `is_billing_admin` property set to `true` were allowed to manage plans and billing. ' - $ref: '#/components/schemas/GroupSettingValue' can_summarize_topics_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value](/api/group-setting-values) defining the set of users who are allowed to use AI summarization. **Changes**: New in Zulip 10.0 (feature level 350). ' create_multiuse_invite_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value](/api/group-setting-values) defining the set of users who are allowed to create [reusable invitation links](/help/invite-new-users#create-a-reusable-invitation-link) to the organization. **Changes**: Prior to Zulip 10.0 (feature level 314), this value used to be of type integer and did not accept anonymous user groups. New in Zulip 8.0 (feature level 209). ' default_avatar_source: type: string description: 'The avatar data source type for new users. - "G" = Hosted by Gravatar - "J" = Generated using Jdenticon Note that "U" is not a supported value here, since there is no such thing as a "default" user-uploaded avatar. **Changes**: New in Zulip 12.0 (feature level 456). ' default_code_block_language: type: string description: 'The default pygments language code to be used for code blocks in this organization. If an empty string, no default has been set. **Changes**: Prior to Zulip 8.0 (feature level 195), a server bug meant that both `null` and an empty string could represent that no default was set for this realm setting in the [`POST /register`](/api/register-queue) response. The documentation for both that endpoint and this event incorrectly stated that the only representation for no default language was `null`. This event in fact uses the empty string to indicate that no default has been set in all server versions. ' 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. ' direct_message_initiator_group: allOf: - description: 'A [group-setting value](/api/group-setting-values) defining the set of users who have permission to start a new direct message conversation involving other non-bot users. Users who are outside this group and attempt to send the first direct message to a given collection of recipient users will receive an error, unless all other recipients are bots or the sender. **Changes**: New in Zulip 9.0 (feature level 270). Previously, access to send direct messages was controlled by the `private_message_policy` realm setting, which supported values of 1 (enabled) and 2 (disabled). ' - $ref: '#/components/schemas/GroupSettingValue' direct_message_permission_group: allOf: - description: 'A [group-setting value](/api/group-setting-values) defining the set of users who have permission to fully use direct messages. Users outside this group can only send direct messages to conversations where all the recipients are in this group, are bots, or are the sender, ensuring that every direct message conversation will be visible to at least one user in this group. **Changes**: New in Zulip 9.0 (feature level 270). Previously, access to send direct messages was controlled by the `private_message_policy` realm setting, which supported values of 1 (enabled) and 2 (disabled). ' - $ref: '#/components/schemas/GroupSettingValue' disallow_disposable_email_addresses: type: boolean description: 'Whether the organization disallows disposable email addresses. ' 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. ' 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). ' 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_guest_user_dm_warning: type: boolean description: 'Whether clients should show a warning when a user is composing a DM to a guest user in this organization. **Changes**: New in Zulip 10.0 (feature level 348). ' enable_guest_user_indicator: type: boolean description: 'Whether clients should display "(guest)" after the names of guest users to prominently highlight their status. **Changes**: New in Zulip 8.0 (feature level 216). ' enable_spectator_access: type: boolean description: 'Whether web-public channels 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 `can_create_web_public_channel_group` realm setting. [server-settings]: https://zulip.readthedocs.io/en/stable/production/settings.html **Changes**: New in Zulip 5.0 (feature level 109). ' gif_rating_policy: type: integer description: 'Maximum rating of the GIFs that will be retrieved by the GIPHY and Tenor integrations in this organization. **Changes**: Before Zulip 12.0 (feature level 453), this was called `giphy_rating`. Before Zulip 12.0 (feature level 442), this was only used for the Giphy integration. 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). ' media_preview_size: type: integer enum: - 100 - 150 - 200 description: 'The organization''s policy for the size of image and video thumbnails in messages, expressed as a percentage of the default height. Currently, only certain values are permitted. - `100`: 100% height (the default). - `150`: 150% height. - `200`: 200% height. **Changes**: New in Zulip 12.0 (feature level 469). ' inline_image_preview: type: boolean description: 'Whether this organization has been configured to enable [previews of linked images](/help/image-video-and-website-previews). ' inline_url_embed_preview: type: boolean description: 'Whether this organization has been configured to enable [previews of linked websites](/help/image-video-and-website-previews). ' invite_required: type: boolean description: 'Whether an invitation is required to join this organization. ' jitsi_server_url: type: string nullable: true description: 'The URL of the custom Jitsi Meet server configured in this organization''s settings. `null`, the default, means that the organization is using the should use the server-level configuration, `server_jitsi_server_url`. **Changes**: New in Zulip 8.0 (feature level 212). Previously, this was only available as a server-level configuration, and required a server restart to change. ' 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). ' topics_policy: type: string enum: - allow_empty_topic - disable_empty_topic description: 'The organization''s default policy for sending channel messages to the [empty "general chat" topic](/help/general-chat-topic). - `"allow_empty_topic"`: Channel messages can be sent to the empty topic. - `"disable_empty_topic"`: Channel messages cannot be sent to the empty topic. **Changes**: New in Zulip 11.0 (feature level 392). Previously, this was controlled by the boolean realm `mandatory_topics` setting, which is now deprecated. ' mandatory_topics: type: boolean deprecated: true description: 'Whether [topics are required](/help/require-topics) for messages in this organization. **Changes**: Deprecated in Zulip 11.0 (feature level 392). This is now controlled by the realm `topics_policy` setting. ' max_file_upload_size_mib: type: integer description: 'The new maximum file size that can be uploaded to this Zulip organization. **Changes**: New in Zulip 10.0 (feature level 306). Previously, this field of the core state did not support being updated via the events system, as it was typically hardcoded for a given Zulip installation. ' 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). Will not be `0`. A `null` value means no limit, so messages can be edited regardless of how long ago they were sent. See [`PATCH /messages/{message_id}`](/api/update-message) for details and history of how message editing permissions work. **Changes**: Before Zulip 6.0 (feature level 138), no limit was represented using the special value `0`. ' message_edit_history_visibility_policy: type: string description: 'Which type of message edit history is configured to allow users to access [message edit history](/help/view-a-messages-edit-history). - "all" = All edit history is visible. - "moves" = Only moves are visible. - "none" = No edit history is visible. **Changes**: New in Zulip 10.0 (feature level 358), replacing the previous `allow_edit_history` boolean setting; `true` corresponds to `all`, and `false` to `none`. ' moderation_request_channel_id: type: integer description: 'The ID of the private channel to which messages flagged by users for moderation are sent. Moderators can use this channel to review and act on reported content. Will be `-1` if moderation requests are disabled. Clients should check whether moderation requests are disabled to determine whether to present a "report message" feature in their UI within a given organization. **Changes**: New in Zulip 10.0 (feature level 331). Previously, no "report message" features existed in Zulip. ' move_messages_within_stream_limit_seconds: type: integer nullable: true description: 'Messages sent more than this many seconds ago cannot be moved within a channel 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. See [`PATCH /messages/{message_id}`](/api/update-message) for details and history of how message editing permissions work. **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 channels 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. See [`PATCH /messages/{message_id}`](/api/update-message) for details and history of how message editing permissions work. **Changes**: New in Zulip 7.0 (feature level 162). Previously, there was no time limit for moving messages between channels for users with permission to do so. ' 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). ' new_stream_announcements_stream_id: type: integer description: 'The ID of the channel to which automated messages announcing the [creation of new channels][new-channel-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-channel-announce]: /help/configure-automated-notices#new-channel-announcements **Changes**: In Zulip 9.0 (feature level 241), renamed `notifications_stream_id` to `new_stream_announcements_stream_id`. ' 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. ' push_notifications_enabled: type: boolean description: 'Whether push notifications are enabled for this organization. Typically `true` for Zulip Cloud and self-hosted realms that have a valid registration for the [Mobile push notifications service](https://zulip.readthedocs.io/en/latest/production/mobile-push-notifications.html), and `false` for self-hosted servers that do not. **Changes**: New in Zulip 8.0 (feature level 231). Previously, this value was never updated via events. ' push_notifications_enabled_end_timestamp: type: integer nullable: true description: 'If the server expects the realm''s push notifications access to end at a definite time in the future, the time at which this is expected to happen. Mobile clients should use this field to display warnings to users when the indicated timestamp is near. **Changes**: New in Zulip 8.0 (feature level 231). ' rendered_description: type: string description: 'Note: Only present if the changed property was `description`. The organization description rendered as HTML, intended to be used when displaying the organization 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. **Changes**: New in Zulip 12.0 (feature level 464). Previously in feature levels 462-463, an `update` event had been sent when updating the realm''s `description`. ' require_e2ee_push_notifications: type: boolean description: 'Whether this realm is configured to disallow sending mobile push notifications with message content through the legacy mobile push notifications APIs. The new API uses end-to-end encryption to protect message content and metadata from being accessible to the push bouncer service, APNs, and FCM. Clients that support the new E2EE API will use it automatically regardless of this setting. If `true`, mobile push notifications sent to clients that lack support for E2EE push notifications will always have "New message" as their content. Note that these legacy mobile notifications will still contain metadata, which may include the message''s ID, the sender''s name, email address, and avatar. In a future release, once the official mobile apps have implemented fully validated their E2EE protocol support, this setting will become strict, and disable the legacy protocol entirely. **Changes**: New in Zulip 11.0 (feature level 409). Previously, this behavior was available only via the `PUSH_NOTIFICATION_REDACT_CONTENT` global server setting. ' require_unique_names: type: boolean description: 'Indicates whether the organization is configured to require users to have unique full names. If true, the server will reject attempts to create a new user, or change the name of an existing user, where doing so would lead to two users whose names are identical modulo case and unicode normalization. **Changes**: New in Zulip 9.0 (feature level 246). Previously, the Zulip server could not be configured to enforce unique names. ' send_channel_events_messages: type: boolean description: 'Indicates whether channel event messages are sent in this organization. **Changes**: New in Zulip 12.0 (feature level 434). Previously, channel events were sent unconditionally. ' 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_announcements_stream_id: type: integer description: 'The ID of the channel 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-automated-notices#new-user-announcements **Changes**: In Zulip 9.0 (feature level 241), renamed `signup_notifications_stream_id` to `signup_announcements_stream_id`. ' upload_quota_mib: type: integer nullable: true description: 'The new upload quota for the Zulip organization. If `null`, there is no limit. **Changes**: New in Zulip 10.0 (feature level 306). Previously, this was present changed via an `upload_quota` field in `extra_data` property of [realm/update](#realm-update) event format for `plan_type` events. ' video_chat_provider: type: integer description: 'The configured [video call provider](/help/configure-call-provider) for the organization. - 0 = None - 1 = Jitsi Meet - 3 = Zoom (User OAuth integration) - 4 = BigBlueButton - 5 = Zoom (Server to Server OAuth integration) - 6 = Constructor Groups - 7 = Nextcloud Talk - 8 = Webex (User OAuth integration) Note that only one of the [Zoom integrations][zoom-video-calls] can be configured on a Zulip server. **Changes**: In Zulip 12.0 (feature level 493), added the Webex OAuth option. In Zulip 12.0 (feature level 465), added the Constructor Groups option. In Zulip 12.0 (feature level 460), added the Constructor Groups option. In Zulip 10.0 (feature level 353), added the Zoom Server to Server OAuth option. In Zulip 3.0 (feature level 1), added the None option to disable video call UI. [zoom-video-calls]: https://zulip.readthedocs.io/en/latest/production/video-calls.html#zoom ' 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). ' welcome_message_custom_text: type: string description: 'This organization''s configured custom message for Welcome Bot to send to new user accounts, in Zulip Markdown format. Maximum length is 8000 Unicode code points. **Changes**: New in Zulip 11.0 (feature level 416). ' workplace_users_group: allOf: - description: 'A [group-setting value](/api/group-setting-values) defining the set of users who will be considered as workplace users for billing. **Changes**: New in Zulip 12.0 (feature level 477). ' - $ref: '#/components/schemas/GroupSettingValue' zulip_update_announcements_stream_id: type: integer description: 'The ID of the channel to which automated messages announcing new features or other end-user updates about the Zulip software 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. **Changes**: New in Zulip 9.0 (feature level 242). ' 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: remove draft_id: 17 - type: object additionalProperties: false description: 'Event containing details of a newly configured navigation view. **Changes**: New in Zulip 11.0 (feature level 390). ' properties: id: $ref: '#/components/schemas/EventIdSchema' type: allOf: - $ref: '#/components/schemas/EventTypeSchema' - enum: - navigation_view op: type: string enum: - add navigation_view: $ref: '#/components/schemas/NavigationView' example: type: navigation_view op: add navigation_view: fragment: narrow/is/alerted is_pinned: true name: Alert Words - type: object additionalProperties: false description: 'Event containing details of an update to an existing navigation view. **Changes**: New in Zulip 11.0 (feature level 390). ' properties: id: $ref: '#/components/schemas/EventIdSchema' type: allOf: - $ref: '#/components/schemas/EventTypeSchema' - enum: - navigation_view op: type: string enum: - update fragment: type: string description: 'The unique URL hash of the navigation view being updated. ' data: type: object additionalProperties: false description: 'A dictionary containing the updated properties of the navigation view. ' properties: name: type: string nullable: true description: 'The user-facing name for custom navigation views. Omit this field for built-in views. ' is_pinned: type: boolean nullable: true description: 'Determines whether the view is pinned (true) or hidden in the menu (false). ' example: type: navigation_view op: update fragment: narrow/is/alerted data: is_pinned: false - type: object additionalProperties: false description: 'Event containing the fragment of a deleted navigation view. **Changes**: New in Zulip 11.0 (feature level 390). ' properties: id: $ref: '#/components/schemas/EventIdSchema' type: allOf: - $ref: '#/components/schemas/EventTypeSchema' - enum: - navigation_view op: type: string enum: - remove fragment: type: string description: 'The unique URL hash of the navigation view that was just deleted. ' example: type: navigation_view op: remove fragment: narrow/is/mentioned - type: object additionalProperties: false description: 'Event containing details of a newly created saved snippet. **Changes**: New in Zulip 10.0 (feature level 297). ' properties: id: $ref: '#/components/schemas/EventIdSchema' type: allOf: - $ref: '#/components/schemas/EventTypeSchema' - enum: - saved_snippets op: type: string enum: - add saved_snippet: $ref: '#/components/schemas/SavedSnippet' example: type: saved_snippets op: add saved_snippet: id: 1 title: Example content: Welcome to the organization. date_created: 1681662420 - type: object additionalProperties: false description: 'Event containing details of the edited saved snippet. Clients should update the existing saved snippet with the ID provided in the `saved_snippet` object. **Changes**: New in Zulip 10.0 (feature level 368). ' properties: id: $ref: '#/components/schemas/EventIdSchema' type: allOf: - $ref: '#/components/schemas/EventTypeSchema' - enum: - saved_snippets op: type: string enum: - update saved_snippet: $ref: '#/components/schemas/SavedSnippet' example: type: saved_snippets op: update saved_snippet: id: 1 title: Example content: Welcome to the organization. date_created: 1681662420 - type: object additionalProperties: false description: 'Event containing the ID of a deleted saved snippet. **Changes**: New in Zulip 10.0 (feature level 297). ' properties: id: $ref: '#/components/schemas/EventIdSchema' type: allOf: - $ref: '#/components/schemas/EventTypeSchema' - enum: - saved_snippets op: type: string enum: - remove saved_snippet_id: type: integer description: 'The ID of the saved snippet that was just deleted. **Changes**: New in Zulip 10.0 (feature level 297). ' example: type: saved_snippets op: remove saved_snippet_id: 17 - type: object additionalProperties: false description: 'Event sent to a user''s clients when a reminder is scheduled. **Changes**: New in Zulip 11.0 (feature level 399). ' properties: id: $ref: '#/components/schemas/EventIdSchema' type: allOf: - $ref: '#/components/schemas/EventTypeSchema' - enum: - reminders op: type: string enum: - add reminders: type: array description: 'An array of objects containing details of the newly created reminders. ' items: $ref: '#/components/schemas/Reminder' example: type: reminders op: add reminders: - reminder_id: 17 type: private to: - 6 content: Hello there! rendered_content:

Hello there!

scheduled_delivery_timestamp: 1681662420 failed: false reminder_target_message_id: 42 - type: object additionalProperties: false description: 'Event sent to a user''s clients when a reminder is deleted. **Changes**: New in Zulip 11.0 (feature level 399). ' properties: id: $ref: '#/components/schemas/EventIdSchema' type: allOf: - $ref: '#/components/schemas/EventTypeSchema' - enum: - reminders op: type: string enum: - remove reminder_id: type: integer description: 'The ID of the reminder that was deleted. ' example: type: reminders op: remove reminder_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:

Hello there!

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:

Hello there!

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 - type: object additionalProperties: false description: 'Event sent to users in an organization when a channel folder is created. **Changes**: New in Zulip 11.0 (feature level 389). ' properties: id: $ref: '#/components/schemas/EventIdSchema' type: allOf: - $ref: '#/components/schemas/EventTypeSchema' - enum: - channel_folder op: type: string enum: - add channel_folder: $ref: '#/components/schemas/ChannelFolder' example: type: channel_folder op: add channel_folder: name: fronted creator_id: 9 date_created: 1717484476 description: Channels for frontend discussions rendered_description:

Channels for frontend discussions

order: 1 id: 2 is_archived: false id: 0 - type: object additionalProperties: false description: 'Event sent to users in an organization when a channel folder is updated. **Changes**: New in Zulip 11.0 (feature level 389). ' properties: id: $ref: '#/components/schemas/EventIdSchema' type: allOf: - $ref: '#/components/schemas/EventTypeSchema' - enum: - channel_folder op: type: string enum: - update channel_folder_id: type: number description: 'ID of the updated channel folder. ' data: type: object additionalProperties: false description: 'Dictionary containing the changed details of the channel folder. ' properties: name: type: string description: 'The new name of the channel folder. Only present if the channel folder''s name changed. ' description: type: string description: 'The new description of the channel folder. Only present if the description changed. See [Markdown message formatting](/api/message-formatting) for details on Zulip''s HTML format. ' rendered_description: type: string description: 'The new rendered description of the channel folder. Only present if the description changed. ' is_archived: type: boolean description: 'Whether the channel folder is archived or not. Only present if the channel folder is archived or unarchived. ' example: type: channel_folder op: update data: name: New frontend id: 0 - type: object additionalProperties: false description: 'Event sent to users in an organization when channel folders are reordered. **Changes**: New in Zulip 11.0 (feature level 418). ' properties: id: $ref: '#/components/schemas/EventIdSchema' type: allOf: - $ref: '#/components/schemas/EventTypeSchema' - enum: - channel_folder op: type: string enum: - reorder order: type: array description: 'A list of channel folder IDs representing the new order. ' items: type: integer example: type: channel_folder op: reorder order: - 3 - 1 - 2 id: 0 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. ' requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: queue_id: description: 'The ID of an event queue that was previously registered via `POST /api/v1/register` (see [Register a queue](/api/register-queue)). ' type: string example: fb67bf8a-c031-47cc-84cf-ed80accacda8 required: - queue_id 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: ' /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 `idle_queue_timeout_secs` seconds of inactivity. After that timeout, 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 longer than the configured timeout. 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 `idle_queue_timeout_secs` seconds). 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**: New in Zulip 12.0 (feature level 481), the `idle_queue_timeout` request parameter and `idle_queue_timeout_secs` response field were added to allow clients to configure how long the server keeps an event queue alive during inactivity. Removed `dense_mode` setting in Zulip 10.0 (feature level 364) as we now have `web_font_size_px` and `web_line_height_percent` settings for more control. 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 requestBody: required: false content: application/x-www-form-urlencoded: schema: type: object properties: apply_markdown: 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) ' type: boolean default: false example: true client_gravatar: 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. ' type: boolean example: false include_subscribers: description: 'Whether each returned channel object should include a `subscribers` field containing a list of the user IDs of its subscribers. Client apps supporting organizations with many thousands of users should not pass `true`, because the full subscriber matrix may be several megabytes of data. The `partial` value, combined with the `subscriber_count` and fetching subscribers for individual channels as needed, is recommended to support client app features where channel subscriber data is useful. If a client passes `partial` for this parameter, the server may, for some channels, return a subset of the channel''s subscribers in the `partial_subscribers` field instead of the `subscribers` field, which always contains the complete set of subscribers. The server guarantees that it will always return a `subscribers` field for channels with fewer than 250 total subscribers. When returning a `partial_subscribers` field, the server guarantees that all bot users and users active within the last 14 days will be included. For other cases, the server may use its discretion to determine which channels and users to include, balancing between payload size and usefulness of the data provided to the client. Passing `true` in an [unauthenticated request](/help/public-access-option) is an error. **Changes**: The `partial` value is new in Zulip 11.0 (feature level 412). 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. ' type: string enum: - 'true' - 'false' - partial default: 'false' example: 'true' slim_presence: description: 'If `true`, the `presences` object returned in the response will be keyed by user ID and the entry for each user''s presence data will be in the modern format. **Changes**: New in Zulip 3.0 (no feature level; API unstable). ' type: boolean default: false example: true presence_history_limit_days: description: 'Limits how far back in time to fetch user presence data. If not specified, defaults to 14 days. A value of N means that the oldest presence data fetched will be from at most N days ago. **Changes**: New in Zulip 10.0 (feature level 288). ' type: integer example: 365 event_types: $ref: '#/components/schemas/Event_types' all_public_streams: $ref: '#/components/schemas/AllPublicChannels' client_capabilities: description: "Dictionary containing details on features the client supports that are\nrelevant to the format of responses sent by the server.\n\n- `notification_settings_null`: Boolean for whether the\n client can handle the current API with `null` values for\n channel-level notification settings (which means the channel\n is not customized and should inherit the user's global\n notification settings for channel messages).\n
\n **Changes**: New in Zulip 2.1.0. In earlier Zulip releases,\n channel-level notification settings were simple booleans.\n\n- `bulk_message_deletion`: Boolean for whether the client's\n handler for the `delete_message` event type has been\n updated to process the new bulk format (with a\n `message_ids`, rather than a singleton `message_id`).\n Otherwise, the server will send `delete_message` events\n in a loop.\n
\n **Changes**: New in Zulip 3.0 (feature level 13). This\n capability is for backwards-compatibility; it will be\n required in a future server release.\n\n- `user_avatar_url_field_optional`: Boolean for whether the\n client required avatar URLs for all users, or supports\n using `GET /avatar/{user_id}` to access user avatars. If the\n client has this capability, the server may skip sending a\n `avatar_url` field in the `realm_user` at its sole discretion\n to optimize network performance. This is an important optimization\n in organizations with 10,000s of users.\n
\n **Changes**: New in Zulip 3.0 (feature level 18).\n\n- `stream_typing_notifications`: Boolean for whether the client\n supports channel typing notifications.\n
\n **Changes**: New in Zulip 4.0 (feature level 58). This capability is\n for backwards-compatibility; it will be required in a\n future server release.\n\n- `user_settings_object`: Has no effect with modern servers. Previously,\n this was a boolean for whether the client supported the modern\n [`user_settings` event type](/api/get-events#user_settings-update) and\n the top-level `user_settings` object in this endpoint's response.\n
\n **Changes**: Prior to Zulip 12.0 (feature level 439), if false, the\n server would additionally send the legacy `update_global_notifications`\n and `update_display_settings` event types, if requested.\n
\n New in Zulip 5.0 (feature level 89). Because the feature level 89 API\n changes were merged together, clients could safely make a request with\n this client capability, and also request all three event types\n (`user_settings`, `update_display_settings`, and\n `update_global_notifications`), and then use the `zulip_feature_level`\n in this endpoint's response or the presence/absence of a `user_settings`\n key to determine where to look for the data.\n\n- `linkifier_url_template`: Boolean for whether the client accepts\n [linkifiers][help-linkifiers] that use [RFC 6570][rfc6570] compliant\n URL templates for linkifying matches. If false or unset, then the\n `realm_linkifiers` array in the `/register` response will be empty\n if present, and no `realm_linkifiers` [events][events-linkifiers]\n will be sent to the client.\n
\n **Changes**: New in Zulip 7.0 (feature level 176). This capability\n is for backwards-compatibility.\n\n- `user_list_incomplete`: Boolean for whether the client supports not having an\n incomplete user database. If true, then the `realm_users` array in the `register`\n response will not include data for inaccessible users and clients of guest users will\n not receive `realm_user op:add` events for newly created users that are not accessible\n to the current user.\n
\n **Changes**: New in Zulip 8.0 (feature level 232). This\n capability is for backwards-compatibility.\n\n- `include_deactivated_groups`: Boolean for whether the client can handle\n deactivated user groups by themselves. If false, then the `realm_user_groups`\n array in the `/register` response will only include active groups, clients\n will receive a `remove` event instead of `update` event when a group is\n deactivated and no `update` event will be sent to the client if a deactivated\n user group is renamed.\n
\n **Changes**: New in Zulip 10.0 (feature level 294). This\n capability is for backwards-compatibility.\n\n- `archived_channels`: Boolean for whether the client supports processing\n [archived channels](/help/archive-a-channel) in the `stream` and\n `subscription` event types. If `false`, the server will not include data\n related to archived channels in the `register` response or in events.\n
\n **Changes**: New in Zulip 10.0 (feature level 315). This allows clients to\n access archived channels, without breaking backwards-compatibility for\n existing clients.\n\n- `empty_topic_name`: Boolean for whether the client supports processing\n the empty string as a topic name. Clients not declaring this capability\n will be sent the value of `realm_empty_topic_display_name` found in the\n [POST /register](/api/register-queue) response instead of the empty string\n wherever topic names appear in the register response or events involving\n topic names.\n
\n **Changes**: New in Zulip 10.0 (feature level 334). Previously,\n the empty string was not a valid topic name.\n\n- `simplified_presence_events`: Boolean for whether the client supports\n receiving the [`presence` event type](/api/get-events#presence) with\n user presence data in the modern format. If true, the server will\n send these events with the `presences` field that has the user presence\n data in the modern format. Otherwise, these event will contain fields\n with legacy format user presence data.\n
\n **Changes**: New in Zulip 11.0 (feature level 419).\n\n- `individual_emoji_changes`: Boolean for whether the client supports\n receiving the [`realm_emoji/add` and `realm_emoji/edit` event\n types](/api/get-events#realm_emoji-add). If true, the server will\n send individual `realm_emoji/add` events when a custom emoji is\n added, and `realm_emoji/edit` events when a custom emoji's\n properties are changed (e.g., deactivated). Otherwise, the server\n will send the legacy `realm_emoji/update` event containing all\n custom emoji for the organization.\n
\n **Changes**: New in Zulip 12.0 (feature level 491).\n\n[help-linkifiers]: /help/add-a-custom-linkifier\n[rfc6570]: https://www.rfc-editor.org/rfc/rfc6570.html\n[events-linkifiers]: /api/get-events#realm_linkifiers\n" type: object example: notification_settings_null: true fetch_event_types: 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. ' type: array items: type: string example: - message narrow: $ref: '#/components/schemas/Narrow' idle_queue_timeout: description: 'At least how long (in seconds) the server should keep the event queue alive when the client is not polling. If the client does not poll before this timeout, the queue will eventually be garbage-collected. Alternatively, the string `"mobile"` can be passed to use the server''s recommended timeout for mobile clients. This is currently 12 hours, but may change in the future. If not specified, the server uses a default of 10 minutes. The maximum allowed value is 7 days. **Changes**: New in Zulip 12.0 (feature level 481). ' oneOf: - type: integer minimum: 1 - type: string enum: - mobile example: 3600 encoding: apply_markdown: contentType: application/json client_gravatar: contentType: application/json slim_presence: contentType: application/json event_types: contentType: application/json all_public_streams: contentType: application/json client_capabilities: contentType: application/json fetch_event_types: contentType: application/json idle_queue_timeout: contentType: application/json narrow: contentType: application/json responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - 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). ' idle_queue_timeout_secs: type: integer description: 'The effective idle queue timeout for the allocated queue, in seconds. This is the resolved value of the `idle_queue_timeout` request parameter, after applying defaults and server-side limits. Not present for unauthenticated access in realms that have enabled the [public access option](/help/public-access-option). **Changes**: New in Zulip 12.0 (feature level 481). ' 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` - `PARAGRAPH` - `DATE` for date-based fields. - `DROPDOWN` 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. ' realm_date_created: type: integer description: 'Present if `realm` is present in `fetch_event_types`. The UNIX timestamp (UTC) for when the organization was created. **Changes**: New in Zulip 8.0 (feature level 203). ' demo_organization_scheduled_deletion_date: type: integer description: 'Present if `realm` is present in `fetch_event_types`, and 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' onboarding_steps: type: array description: 'Present if `onboarding_steps` is present in `fetch_event_types`. An array of dictionaries, where each dictionary contains details about a single onboarding step that should be shown to the user. We expect that only official Zulip clients will interact with this data. **Changes**: Before Zulip 8.0 (feature level 233), this array was named `hotspots`. Prior to this feature level, one-time notice onboarding steps were not supported, and the `type` field in these objects did not exist as all onboarding steps were implicitly hotspots. ' items: $ref: '#/components/schemas/OnboardingStep' navigation_tour_video_url: type: string nullable: true description: 'Present if `onboarding_steps` is present in `fetch_event_types`. URL of the navigation tour video to display to new users during onboarding. If `null`, the onboarding video experience is disabled. **Changes**: New in Zulip 10.0 (feature level 369). ' 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_reminder_note_length: type: integer description: 'The maximum allowed length for a reminder note, in Unicode code points. **Changes**: New in Zulip 11.0 (feature level 415). ' max_stream_name_length: type: integer description: 'Present if `realm` is present in `fetch_event_types`. The maximum allowed length for a channel 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 channel 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_channel_folder_name_length: type: integer description: 'Present if `realm` is present in `fetch_event_types`. The maximum allowed length for a channel folder name, in Unicode code points. Clients should use this property rather than hardcoding field sizes. **Changes**: New in Zulip 11.0 (feature level 410). Clients should use 60 as a fallback value on previous feature levels. ' max_channel_folder_description_length: type: integer description: 'Present if `realm` is present in `fetch_event_types`. The maximum allowed length for a channel folder description, in Unicode code points. Clients should use this property rather than hardcoding field sizes. **Changes**: New in Zulip 11.0 (feature level 410). Clients should use 1024 as a fallback value on previous feature levels. ' 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_min_deactivated_realm_deletion_days: type: integer nullable: true description: 'Present if `realm` is present in `fetch_event_types`. The minimum permitted number of days before full data deletion (users, channels, messages, etc.) of a deactivated organization. If `null`, then a deactivated organization''s data can be deleted immediately. **Changes**: New in Zulip 10.0 (feature level 332) ' server_max_deactivated_realm_deletion_days: type: integer nullable: true description: 'Present if `realm` is present in `fetch_event_types`. The maximum permitted number of days before full data deletion (users, channels, messages, etc.) of a deactivated organization. If `null`, then a deactivated organization''s data can be retained indefinitely. **Changes**: New in Zulip 10.0 (feature level 332). ' server_presence_ping_interval_seconds: type: integer description: 'Present if `realm` is present in `fetch_event_types`. 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 Zulip mobile apps prior to this parameter being introduced. ' server_presence_offline_threshold_seconds: type: integer description: 'Present if `realm` is present in `fetch_event_types`. 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. ' server_typing_started_expiry_period_milliseconds: type: integer description: 'Present if `realm` is present in `fetch_event_types`. For clients implementing [typing notifications](/api/set-typing-status) protocol, the time interval in milliseconds that the client should wait for additional [typing start](/api/get-events#typing-start) events from the server before removing an active typing indicator. **Changes**: New in Zulip 8.0 (feature level 204). Clients should use 15000 for older Zulip servers, since that''s the value that was hardcoded in the Zulip apps prior to this parameter being introduced. ' server_typing_stopped_wait_period_milliseconds: type: integer description: 'Present if `realm` is present in `fetch_event_types`. For clients implementing [typing notifications](/api/set-typing-status) protocol, the time interval in milliseconds that the client should wait when a user stops interacting with the compose UI before sending a stop notification to the server. **Changes**: New in Zulip 8.0 (feature level 204). Clients should use 5000 for older Zulip servers, since that''s the value that was hardcoded in the Zulip apps prior to this parameter being introduced. ' server_typing_started_wait_period_milliseconds: type: integer description: 'Present if `realm` is present in `fetch_event_types`. For clients implementing [typing notifications](/api/set-typing-status) protocol, the time interval in milliseconds that the client should use to send regular start notifications to the server to indicate that the user is still actively interacting with the compose UI. **Changes**: New in Zulip 8.0 (feature level 204). Clients should use 10000 for older Zulip servers, since that''s the value that was hardcoded in the Zulip 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' reminders: type: array description: 'Present if `reminders` is present in `fetch_event_types`. An array of all undelivered reminders scheduled by the user. **Changes**: New in Zulip 11.0 (feature level 399). ' items: $ref: '#/components/schemas/Reminder' 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 channel 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`. 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. The format of the entry (modern or legacy) depends on the value of [`slim_presence`](#parameter-slim_presence). Users who have been offline for multiple weeks may not appear in this object. ' additionalProperties: type: object description: 'Will be one of these two formats (modern or legacy) for user presence data: ' oneOf: - $ref: '#/components/schemas/ModernPresenceFormat' - type: object description: '`{user_email}`: Presence data (legacy format) for the user with the specified Zulip API email. ' additionalProperties: $ref: '#/components/schemas/LegacyPresenceFormat' presence_last_update_id: type: integer description: 'Present if `presence` is present in `fetch_event_types`. Provides the `last_update_id` value of the latest presence data fetched by the server and included in the response in `presences`. This can be used as the value of the `presence_last_update_id` parameter when polling for presence data at the [/users/me/presence](/api/update-presence) endpoint to tell the server to only fetch the relevant newer data in order to skip redundant already-known presence information. **Changes**: New in Zulip 9.0 (feature level 263). ' 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 an allowed domain for [user account email addresses](/help/restrict-account-creation). ' items: $ref: '#/components/schemas/RealmDomain' realm_emoji: description: 'Present if `realm_emoji` is present in `fetch_event_types`. An object in which keys are RealmEmoji ids, and the values describe the custom emoji for that id. ' type: object additionalProperties: $ref: '#/components/schemas/RealmEmoji' realm_linkifiers: type: array description: 'Present if `realm_linkifiers` is present in `fetch_event_types`. An ordered array of objects where each object describes a single [linkifier](/help/add-a-custom-linkifier). The order of the array reflects the order that each linkifier should be processed when linkifying messages and topics. By default, new linkifiers are ordered last. This order can be modified with [`PATCH /realm/linkifiers`](/api/reorder-linkifiers). 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[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. Deactivated groups will only be included if `include_deactivated_groups` client capability is set to `true`. **Changes**: Prior to Zulip 10.0 (feature level 294), deactivated groups were included for all the clients. ' 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). **Changes**: Removed `avatar_url`, `bot_type`, `email`, `full_name`, `is_active` and `owner_id` fields from the dictionary in Zulip 12.0 (feature level 474). Clients can get all these data from the corresponding user object. Removed `api_key` field from the dictionary in Zulip 12.0 (feature level 474). Clients now use [`GET /bots/{bot_id}/api_key`](/api/get-bot-api-key) to get api key for the bot. ' 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/BotConfiguration' 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 a 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: 'A machine-readable unique name identifying the integration, all-lower-case without spaces. ' display_name: type: string description: 'A human-readable display name identifying the integration that this bot implements, intended to be used in menus for selecting which integration to create. **Changes**: New in Zulip 8.0 (feature level 207). ' all_event_types: type: array items: type: string nullable: true description: 'For incoming webhook integrations that support the Zulip server filtering incoming events, the list of event types supported by it. A null value will be present if this incoming webhook integration doesn''t support such filtering. **Changes**: New in Zulip 8.0 (feature level 207). ' config_options: $ref: '#/components/schemas/WebhookConfigOption' url_options: $ref: '#/components/schemas/WebhookUrlOption' recent_private_conversations: description: 'Present if `recent_private_conversations` is present in `fetch_event_types`. An array of dictionaries containing data on all direct message and group direct 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 "Direct messages" widget in the web application showing recent direct 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 direct messages the user received". ' type: array items: type: object additionalProperties: false description: 'Object describing a single recent direct 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 direct message conversation. This will be an empty list for direct messages sent to oneself. ' navigation_views: type: array items: $ref: '#/components/schemas/NavigationView' description: 'Present if `navigation_views` is present in `fetch_event_types`. An array of dictionaries containing data on all of the current user''s navigation views. **Changes**: New in Zulip 11.0 (feature level 390). ' saved_snippets: type: array items: $ref: '#/components/schemas/SavedSnippet' description: 'Present if `saved_snippets` is present in `fetch_event_types`. An array of dictionaries containing data on all of the current user''s saved snippets. **Changes**: New in Zulip 10.0 (feature level 297). ' subscriptions: type: array items: $ref: '#/components/schemas/Subscription' description: 'Present if `subscription` is present in `fetch_event_types`. A array of dictionaries where each dictionary describes the properties of a channel the user is subscribed to (as well as that user''s personal per-channel settings). **Changes**: Removed `email_address` field from the dictionary in Zulip 8.0 (feature level 226). Removed `role` field from the dictionary in Zulip 6.0 (feature level 133). ' unsubscribed: type: array items: $ref: '#/components/schemas/Subscription' description: 'Present if `subscription` is present in `fetch_event_types`. A array of dictionaries where each dictionary describes one of the channels 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 channels. **Changes**: Prior to Zulip 10.0 (feature level 349), if a user was in `can_administer_channel_group` of a channel that they had unsubscribed from, but not an organization administrator, the channel in question would not be part of this array. Removed `email_address` field from the dictionary in Zulip 8.0 (feature level 226). Removed `role` field from the dictionary in Zulip 6.0 (feature level 133). ' never_subscribed: type: array items: allOf: - $ref: '#/components/schemas/BasicChannelBase' - additionalProperties: false properties: stream_id: {} name: {} is_archived: {} description: {} date_created: {} creator_id: nullable: true invite_only: {} rendered_description: {} is_web_public: {} stream_post_policy: {} message_retention_days: nullable: true history_public_to_subscribers: {} topics_policy: {} first_message_id: nullable: true folder_id: nullable: true is_recently_active: {} is_announcement_only: {} can_add_subscribers_group: {} can_remove_subscribers_group: {} can_administer_channel_group: {} can_delete_any_message_group: {} can_delete_own_message_group: {} can_move_messages_out_of_channel_group: {} can_move_messages_within_channel_group: {} can_send_message_group: {} can_subscribe_group: {} can_resolve_topics_group: {} can_create_topic_group: {} subscriber_count: {} stream_weekly_traffic: type: integer nullable: true description: 'The average number of messages sent to the channel per week, as estimated based on recent weeks, rounded to the nearest integer. If `null`, the channel 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 channel. Included only if `include_subscribers` is `true`. If a user is not allowed to know the subscribers for a channel, 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. ' partial_subscribers: type: array items: type: integer description: 'If [`include_subscribers="partial"`](/api/get-subscriptions#parameter-include_subscribers) was requested, the server may, at its discretion, send a `partial_subscribers` list rather than a `subscribers` list for channels with a large number of subscribers. The `partial_subscribers` list contains an arbitrary subset of the channel''s subscribers that is guaranteed to include all bot user subscribers as well as all users who have been active in the last 14 days, but otherwise can be chosen arbitrarily by the server. If a user is not allowed to know the subscribers for a channel, 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. **Changes**: New in Zulip 11.0 (feature level 412). ' description: 'Present if `subscription` is present in `fetch_event_types`. A array of dictionaries where each dictionary describes one of the channels that is visible to the user and the user has never been subscribed to. Important for clients containing UI where one can browse channels to subscribe to. **Changes**: Before Zulip 10.0 (feature level 362), archived channels did not appear in this list, even if the `archived_channels` [client capability][client-capabilities] was declared by the client. Prior to Zulip 10.0 (feature level 349), if a user was in `can_administer_channel_group` of a channel that they never subscribed to, but not an organization administrator, the channel in question would not be part of this array. ' channel_folders: type: array items: $ref: '#/components/schemas/ChannelFolder' description: 'Present if `channel_folders` is present in `fetch_event_types`. An array of dictionaries where each dictionary describes one of the channel folders in the organization. Only channel folders with one or more public web channels are visible to spectators. **Changes**: New in Zulip 11.0 (feature level 389). ' 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 one-on-one and group direct messages, as well as channel messages that are not [muted](/help/mute-a-topic). **Changes**: Before Zulip 8.0 (feature level 213), the unmute and follow topic features were not handled correctly in calculating this field. ' pms: type: array description: 'An array of objects where each object contains details of unread one-on-one direct messages with a specific user. Note that it is possible for a message that the current user sent to the specified user to be marked as unread and thus appear here. ' items: type: object additionalProperties: false properties: other_user_id: type: integer description: 'The user ID of the other participant in this one-on-one direct message conversation. Will be the current user''s ID for messages that they sent in a one-on-one direct message conversation with themself. **Changes**: New in Zulip 5.0 (feature level 119), replacing the less clearly named `sender_id` field. ' sender_id: deprecated: true type: integer description: 'Old name for the `other_user_id` field. 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. ' unread_message_ids: type: array description: 'The message IDs of the recent unread direct messages sent by either user in this one-on-one direct message conversation, sorted in ascending order. ' items: type: integer streams: type: array description: 'An array of dictionaries where each dictionary contains details of all unread messages of a single subscribed channel. This includes muted channels and muted topics, even though those messages are excluded from `count`. **Changes**: Prior to Zulip 5.0 (feature level 90), these objects included a `sender_ids` property, which listed the set of IDs of users who had sent the unread messages. ' items: type: object additionalProperties: false properties: topic: type: string description: 'The topic under which the messages were sent. Note that the empty string topic may have been rewritten by the server to the value of `realm_empty_topic_display_name` found in the [`POST /register`](/api/register-queue) response depending on the value of the `empty_topic_name` [client capability][client-capabilities]. **Changes**: The `empty_topic_name` client capability is new in Zulip 10.0 (feature level 334). [client-capabilities]: /api/register-queue#parameter-client_capabilities ' stream_id: type: integer description: 'The ID of the channel to which the messages were sent. ' unread_message_ids: type: array description: 'The message IDs of the recent unread messages sent in this channel, sorted in ascending order. ' items: type: integer huddles: type: array description: 'An array of objects where each object contains details of unread group direct messages with a specific group of users. ' items: type: object additionalProperties: false properties: user_ids_string: type: string description: 'A string containing the IDs of all users in the group direct message conversation, including the current user, separated by commas and sorted numerically; for example: `"1,2,3"`. ' unread_message_ids: type: array description: 'The message IDs of the recent unread messages which have been sent in this group direct message conversation, sorted in ascending order. ' items: type: integer mentions: type: array description: 'Array containing the IDs of all unread messages in which the user was mentioned directly, and unread [non-muted](/help/mute-a-topic) messages in which the user was mentioned through a wildcard. **Changes**: Before Zulip 8.0 (feature level 213), the unmute and follow topic features were not handled correctly in calculating this field. ' 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/BasicChannel' description: 'Present if `stream` is present in `fetch_event_types`. Array of dictionaries where each dictionary contains details about a single channel in the organization that is visible to the user. For organization administrators, this will include all private channels in the organization. **Changes**: Before Zulip 11.0 (feature level 378), archived channels did not appear in this list, even if the `archived_channels` [client capability][client-capabilities] was declared by the client. As of Zulip 8.0 (feature level 205), this will include all web-public channels in the organization as well. ' realm_default_streams: type: array items: type: integer description: 'Present if `default_streams` is present in `fetch_event_types`. An array of IDs of all the [default channels](/help/set-default-streams-for-new-users) in the organization. **Changes**: Before Zulip 10.0 (feature level 330), we sent array of dictionaries where each dictionary contained details about a single default stream for the Zulip organization. ' realm_default_stream_groups: type: array items: $ref: '#/components/schemas/DefaultChannelGroup' 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 channel group configured for this Zulip organization. Default channel 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: allOf: - description: '`{user_id}`: Object containing the status details of a user with the key of the object being the ID of the user. ' - $ref: '#/components/schemas/UserStatus' user_settings: type: object description: 'Present if `user_settings` is present in `fetch_event_types`. A dictionary containing the user''s personal settings. **Changes**: In Zulip 12.0 (feature level 439), removed deprecated, duplicate copies of many of these user settings from the top-level object. Previously, clients that did not include the `user_settings_object` [client capability][client-capabilities] and included `update_display_settings` or `update_global_notifications` in `fetch_event_types` would receive those user settings that predated feature level 89 in the top-level response. In Zulip 10.0 (feature level 364), removed the `dense_mode` setting as we now have `web_font_size_px` and `web_line_height_percent` settings for more control. New in Zulip 5.0 (feature level 89). Previously, user settings appeared in the top-level object; see the `user_settings_object` [client capability][client-capabilities] for backwards-compatibility. [client-capabilities]: /api/register-queue#parameter-client_capabilities ' additionalProperties: false properties: twenty_four_hour_time: type: boolean nullable: true description: 'Whether time should be [displayed in 24-hour notation](/help/change-the-time-format). A `null` value indicates that the client should use the default time format for the user''s locale. **Changes**: Prior to Zulip 11.0 (feature level 408), `null` was not a valid value for this setting. Note that it was not possible to actually set the time format to `null` at this feature level. ' 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. ' web_channel_default_view: type: integer description: 'Web/desktop app setting controlling the default navigation behavior when clicking on a channel link. - 1 - Top topic in the channel - 2 - Channel feed - 3 - List of topics - 4 - Top unread topic in channel **Changes**: The "Top unread topic in channel" is new in Zulip 11.0 (feature level 401). The "List of topics" option is new in Zulip 11.0 (feature level 383). New in Zulip 9.0 (feature level 269). Previously, this was not configurable, and every user had the "Channel feed" behavior. ' 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). ' receives_typing_notifications: type: boolean description: 'Whether the user is configured to receive typing notifications from other users. The server will only deliver typing notifications events to users who for whom this is enabled. **Changes**: New in Zulip 9.0 (feature level 253). Previously, there were only options to disable sending typing notifications. ' web_suggest_update_timezone: type: boolean description: 'Whether the user should be shown an alert, offering to update their [profile time zone](/help/change-your-timezone), when the time displayed for the profile time zone differs from the current time displayed by the time zone configured on their device. **Changes**: New in Zulip 10.0 (feature level 329). ' 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. ' web_font_size_px: description: 'User-configured primary `font-size` for the web application, in pixels. **Changes**: New in Zulip 9.0 (feature level 245). Previously, font size was only adjustable via browser zoom. Note that this setting was not fully implemented at this feature level. ' type: integer example: 14 web_line_height_percent: description: 'User-configured primary `line-height` for the web application, in percent, so a value of 120 represents a `line-height` of 1.2. **Changes**: New in Zulip 9.0 (feature level 245). Previously, line height was not user-configurable. Note that this setting was not fully implemented at this feature level. ' type: integer example: 122 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. ' web_home_view: type: string description: 'The [home view](/help/configure-home-view) used when opening a new Zulip web app window or hitting the `Esc` keyboard shortcut repeatedly. - "recent" - Recent conversations view - "inbox" - Inbox view - "all_messages" - Combined feed view **Changes**: Before Zulip 12.0 (feature level 454), the Recent view had `"recent_topics"` as its string encoding. New in Zulip 8.0 (feature level 219). Previously, this was called `default_view`, which was new in Zulip 4.0 (feature level 42). ' web_escape_navigates_to_home_view: type: boolean description: 'Whether the escape key navigates to the [configured home view](/help/configure-home-view). **Changes**: New in Zulip 8.0 (feature level 219). Previously, this was called `escape_navigates_to_default_view`, which was 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 - "twitter" - Twitter - "text" - Plain text ' demote_inactive_streams: type: integer description: 'Whether to [hide inactive channels](/help/manage-inactive-channels) 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). ' web_animate_image_previews: type: string description: 'Controls how animated images should be played in the message feed in the web/desktop application. - "always" - Always play the animated images in the message feed. - "on_hover" - Play the animated images on hover over them in the message feed. - "never" - Never play animated images in the message feed. **Changes**: New in Zulip 9.0 (feature level 275). ' web_stream_unreads_count_display_policy: type: integer description: 'Configuration for which channels should be displayed with a numeric unread count in the left sidebar. Channels that do not have an unread count will have a simple dot indicator for whether there are any unread messages. - 1 - All channels - 2 - Unmuted channels and topics - 3 - No channels **Changes**: New in Zulip 8.0 (feature level 210). ' hide_ai_features: type: boolean description: 'Controls whether user wants AI features like topic summarization to be hidden in all Zulip clients. **Changes**: New in Zulip 10.0 (feature level 350). ' web_inbox_show_channel_folders: type: boolean description: 'Determines whether [channel folders](/help/channel-folders) are used to organize how conversations with unread messages are displayed in the web/desktop application''s Inbox view. **Changes**: New in Zulip 12.0 (feature level 431). ' web_left_sidebar_show_channel_folders: type: boolean description: 'Determines whether [channel folders](/help/channel-folders) are used to organize how channels are displayed in the web/desktop application''s left sidebar. **Changes**: New in Zulip 11.0 (feature level 411). ' web_left_sidebar_unreads_count_summary: type: boolean description: 'Determines whether the web/desktop application''s left sidebar displays the unread message count summary. **Changes**: New in Zulip 11.0 (feature level 398). ' timezone: type: string description: 'The IANA identifier of the user''s [profile time zone](/help/change-your-timezone), which is used primarily to display the user''s local time to other users. ' enter_sends: type: boolean description: 'Whether the user setting for [sending on pressing Enter](/help/configure-send-message-keys) 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 channel messages. ' enable_stream_email_notifications: type: boolean description: 'Enable email notifications for channel messages. ' enable_stream_push_notifications: type: boolean description: 'Enable mobile notifications for channel messages. ' enable_stream_audible_notifications: type: boolean description: 'Enable audible desktop notifications for channel messages. ' notification_sound: type: string description: 'Notification sound name. ' enable_desktop_notifications: type: boolean description: 'Enable visual desktop notifications for direct messages and @-mentions. ' enable_sounds: type: boolean description: 'Enable audible desktop notifications for direct messages and @-mentions. ' enable_followed_topic_desktop_notifications: type: boolean description: 'Enable visual desktop notifications for messages sent to followed topics. **Changes**: New in Zulip 8.0 (feature level 189). ' enable_followed_topic_email_notifications: type: boolean description: 'Enable email notifications for messages sent to followed topics. **Changes**: New in Zulip 8.0 (feature level 189). ' enable_followed_topic_push_notifications: type: boolean description: 'Enable push notifications for messages sent to followed topics. **Changes**: New in Zulip 8.0 (feature level 189). ' enable_followed_topic_audible_notifications: type: boolean description: 'Enable audible desktop notifications for messages sent to followed topics. **Changes**: New in Zulip 8.0 (feature level 189). ' 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 direct messages and @-mentions received when the user is offline. ' enable_offline_push_notifications: type: boolean description: 'Enable mobile notification for direct messages and @-mentions received when the user is offline. ' enable_online_push_notifications: type: boolean description: 'Enable mobile notification for direct 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 direct messages in desktop notifications. ' wildcard_mentions_notify: type: boolean description: 'Whether wildcard mentions (E.g. @**all**) should send notifications like a personal mention. ' enable_followed_topic_wildcard_mentions_notify: type: boolean description: 'Whether wildcard mentions (e.g., @**all**) in messages sent to followed topics should send notifications like a personal mention. **Changes**: New in Zulip 8.0 (feature level 189). ' desktop_icon_count_display: type: integer description: 'Unread count badge (appears in desktop sidebar and browser tab) - 1 - All unread messages - 2 - DMs, mentions, and followed topics - 3 - DMs and mentions - 4 - None **Changes**: In Zulip 8.0 (feature level 227), added `DMs, mentions, and followed topics` option, renumbering the options to insert it in order. ' 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`. ' automatically_follow_topics_policy: type: integer description: 'Which [topics to follow automatically](/help/mute-a-topic). - 1 - Topics the user participates in - 2 - Topics the user sends a message to - 3 - Topics the user starts - 4 - Never **Changes**: New in Zulip 8.0 (feature level 214). ' automatically_unmute_topics_in_muted_streams_policy: type: integer description: 'Which [topics to unmute automatically in muted channels](/help/mute-a-topic). - 1 - Topics the user participates in - 2 - Topics the user sends a message to - 3 - Topics the user starts - 4 - Never **Changes**: New in Zulip 8.0 (feature level 214). ' automatically_follow_topics_where_mentioned: type: boolean description: 'Whether the server will automatically mark the user as following topics where the user is mentioned. **Changes**: New in Zulip 8.0 (feature level 235). ' resolved_topic_notice_auto_read_policy: type: string description: 'Controls whether the resolved-topic notices are marked as read. - "always" - Always mark resolved-topic notices as read. - "except_followed" - Mark resolved-topic notices as read in topics not followed by the user. - "never" - Never mark resolved-topic notices as read. **Changes**: New in Zulip 11.0 (feature level 385). ' 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 direct messages. The client should send typing notifications for direct 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 channel messages. The client should send typing notifications for channel 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). ' allow_private_data_export: type: boolean description: 'Whether organization administrators are allowed to export your private data. **Changes**: New in Zulip 10.0 (feature level 293). ' email_address_visibility: $ref: '#/components/schemas/EmailAddressVisibility' web_navigate_to_sent_message: type: boolean description: 'Web/desktop app setting for whether the user''s view should automatically go to the conversation where they sent a message. **Changes**: New in Zulip 9.0 (feature level 268). Previously, this behavior was not configurable. ' 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 channel to which the topic belongs. ' topic_name: type: string description: 'The name of the topic. Note that the empty string topic may have been rewritten by the server to the value of `realm_empty_topic_display_name` found in the [`POST /register`](/api/register-queue) response depending on the value of the `empty_topic_name` [client capability][client-capabilities]. **Changes**: The `empty_topic_name` client capability is new in Zulip 10.0 (feature level 334). [client-capabilities]: /api/register-queue#parameter-client_capabilities ' 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). - 3 = Followed. Used to record [followed topics](/help/follow-a-topic). **Changes**: In Zulip 7.0 (feature level 219), added followed as a visibility policy option. 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/configure-call-provider). Clients need to know whether initiating Zoom OAuth is required before creating a Zoom call. ' has_webex_token: type: boolean description: 'Present if `video_calls` is present in `fetch_event_types`. A boolean that denotes whether the user has completed the OAuth flow for the [Webex integration](/help/configure-call-provider). Clients need to know whether initiating Webex OAuth flow is required before creating a Webex call. **Changes**: New in Zulip 12.0 (feature level 493). ' 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). ' tenor_api_key: type: string description: 'Present if `tenor` is present in `fetch_event_types`. Tenor API keys are meant to be sent to the clients, see the examples in the [Tenor Endpoints documentation](https://developers.google.com/tenor/guides/endpoints). Please don''t use our API key for an app unrelated to Zulip. Developers of clients are recommended to use their Zulip client string, like `ZulipFlutter`, as the `client` in the Tenor API to differentiate across clients as per the [Tenor Endpoints documentation](https://developers.google.com/tenor/guides/endpoints). Developers of clients should also read the [Tenor API TOS](https://developers.google.com/tenor/guides/api-terms). **Changes**: New in Zulip 12.0 (feature level 442). ' klipy_api_key: type: string description: 'Present if `klipy` is present in `fetch_event_types`. KLIPY API keys are meant to be sent to the clients, see the best practices in the [Migrate from Tenor documentation](https://docs.klipy.com/migrate-from-tenor/search#Best-practices). Please don''t use our API key for an app unrelated to Zulip. **Changes**: New in Zulip 12.0 (feature level 486). ' devices: type: object description: 'Present if `device` is present in `fetch_event_types`. Dictionary where each entry describes the user''s logged-in devices, registered using [`POST /register_client_device`](/api/register-client-device). **Changes**: New in Zulip 12.0 (feature level 468). ' additionalProperties: description: '`{device_id}`: Dictionary containing the details of a device with the device ID as the key. ' type: object additionalProperties: false properties: push_key_id: type: integer nullable: true description: 'ID to reference the encryption key used to encrypt push notifications sent to the device. ' push_token_id: type: string nullable: true description: 'ID to reference the token provided by FCM/APNs to the device, which is registered to the push bouncer service. ' pending_push_token_id: type: string nullable: true description: 'ID to reference the token provided by FCM/APNs to the device, whose registration is in progress to the push bouncer service. ' push_token_last_updated_timestamp: type: integer nullable: true description: 'The UNIX timestamp for the last time when `pending_push_token_id` was set to a new non-null value, in UTC seconds. ' push_registration_error_code: type: string nullable: true description: 'If the push registration failed, a [Zulip API error code](/api/rest-error-handling) indicating the type of failure that occurred. The following error codes have recommended client behavior: - `"INVALID_BOUNCER_PUBLIC_KEY"` - Inform the user to update app. - `"REQUEST_EXPIRED` - Retry with a fresh payload. ' receives_typing_notifications: type: boolean description: 'Whether the user is configured to receive typing notifications from other users. The server will only deliver typing notifications events to users who for whom this is enabled. **Changes**: New in Zulip 9.0 (feature level 253). Previously, there were only options to disable sending typing notifications. ' realm_message_edit_history_visibility_policy: type: string description: 'Present if `realm` is present in `fetch_event_types`. What typesof message edit history are accessible to users via [message edit history](/help/view-a-messages-edit-history). - "all" = All edit history is visible. - "moves" = Only moves are visible. - "none" = No edit history is visible. **Changes**: New in Zulip 10.0 (feature level 358), replacing the previous `allow_edit_history` boolean setting; `true` corresponds to `all`, and `false` to `none`. ' realm_allow_edit_history: deprecated: true 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). The value of `realm_allow_edit_history` is set as `false` if the `realm_message_edit_history_visibility_policy` is configured as "None" and `true` if it is configured as "Moves only" or "All". **Changes**: Deprecated in Zulip 10.0 (feature level 358) and will be removed in the future, as it is an inaccurate version `realm_message_edit_history_visibility_policy`, which replaces this field. ' realm_can_add_custom_emoji_group: allOf: - description: 'Present if `realm` is present in `fetch_event_types`. A [group-setting value](/api/group-setting-values) defining the set of users who have permission to add custom emoji in the organization. **Changes**: New in Zulip 10.0 (feature level 307). Previously, this permission was controlled by the enum `add_custom_emoji_policy`. Values were 1=Members, 2=Admins, 3=Full members, 4=Moderators. Before Zulip 5.0 (feature level 85), the `realm_add_emoji_by_admins_only` boolean setting controlled this permission; `true` corresponded to `Admins`, and `false` to `Everyone`. ' - $ref: '#/components/schemas/GroupSettingValue' realm_can_add_subscribers_group: allOf: - description: 'Present if `realm` is present in `fetch_event_types`. A [group-setting value](/api/group-setting-values) defining the set of users who have permission to add subscribers to channels in the organization. **Changes**: New in Zulip 10.0 (feature level 341). Previously, this permission was controlled by the enum `invite_to_stream_policy`. Values were 1=Members, 2=Admins, 3=Full members, 4=Moderators. ' - $ref: '#/components/schemas/GroupSettingValue' realm_can_delete_any_message_group: allOf: - description: 'Present if `realm` is present in `fetch_event_types`. A [group-setting value](/api/group-setting-values) defining the set of users who have permission to delete any message in the organization. Note that a user must also be able to access the content of a message in order to delete it. See [channel permissions](/help/channel-permissions) for information about content access for channel messages. For direct messages, the user must have received or sent the direct message to have content access. **Changes**: New in Zulip 10.0 (feature level 281). Previously, this permission was limited to administrators only and was uneditable. ' - $ref: '#/components/schemas/GroupSettingValue' realm_can_delete_own_message_group: allOf: - description: 'Present if `realm` is present in `fetch_event_types`. A [group-setting value](/api/group-setting-values) defining the set of users who have permission to delete messages that they have sent in the organization. **Changes**: New in Zulip 10.0 (feature level 291). Previously, this permission was controlled by the enum `delete_own_message_policy`. Values were 1=Members, 2=Admins, 3=Full members, 4=Moderators, 5=Everyone. Before Zulip 5.0 (feature level 101), the `allow_message_deleting` boolean setting controlled this permission; `true` corresponded to `Everyone`, and `false` to `Admins`. ' - $ref: '#/components/schemas/GroupSettingValue' realm_can_set_delete_message_policy_group: allOf: - description: 'Present if `realm` is present in `fetch_event_types`. A [group-setting value](/api/group-setting-values) defining the set of users who have permission to change per-channel `can_delete_any_message_group` and `can_delete_own_message_group` permission settings. Note that the user must be a member of both this group and the `can_administer_channel_group` of the channel whose message delete settings they want to change. Organization administrators can always change these settings of every channel. **Changes**: New in Zulip 11.0 (feature level 407). ' - $ref: '#/components/schemas/GroupSettingValue' realm_can_set_topics_policy_group: allOf: - description: 'Present if `realm` is present in `fetch_event_types`. A [group-setting value](/api/group-setting-values) defining the set of users who have permission to change per-channel `topics_policy` setting. Note that the user must be a member of both this group and the `can_administer_channel_group` of the channel whose `topics_policy` they want to change. Organization administrators can always change the `topics_policy` setting of every channel. **Changes**: New in Zulip 11.0 (feature level 392). ' - $ref: '#/components/schemas/GroupSettingValue' realm_can_invite_users_group: allOf: - description: 'Present if `realm` is present in `fetch_event_types`. A [group-setting value](/api/group-setting-values) defining the set of users who have permission to send email invitations for inviting other users to the organization. **Changes**: New in Zulip 10.0 (feature level 321). Previously, this permission was controlled by the enum `invite_to_realm_policy`. Values were 1=Members, 2=Admins, 3=Full members, 4=Moderators, 6=Nobody. Before Zulip 4.0 (feature level 50), the `invite_by_admins_only` boolean setting controlled this permission; `true` corresponded to `Admins`, and `false` to `Members`. ' - $ref: '#/components/schemas/GroupSettingValue' realm_can_mention_many_users_group: allOf: - description: 'Present if `realm` is present in `fetch_event_types`. A [group-setting value](/api/group-setting-values) defining the set of users who have permission to use wildcard mentions in large channels. All users will receive a warning/reminder when using mentions in large channels, even when permitted to do so. **Changes**: New in Zulip 10.0 (feature level 352). Previously, this permission was controlled by the enum `wildcard_mention_policy`. ' - $ref: '#/components/schemas/GroupSettingValue' realm_can_move_messages_between_channels_group: allOf: - description: 'Present if `realm` is present in `fetch_event_types`. A [group-setting value](/api/group-setting-values) defining the set of users who have permission to move messages from one channel to another in the organization. **Changes**: New in Zulip 10.0 (feature level 310). Previously, this permission was controlled by the enum `move_messages_between_streams_policy`. Values were 1=Members, 2=Admins, 3=Full members, 4=Moderators, 6=Nobody. In Zulip 7.0 (feature level 159), `Nobody` was added as an option to `move_messages_between_streams_policy` enum. ' - $ref: '#/components/schemas/GroupSettingValue' realm_can_move_messages_between_topics_group: allOf: - description: 'Present if `realm` is present in `fetch_event_types`. A [group-setting value](/api/group-setting-values) defining the set of users who have permission to move messages from one topic to another within a channel in the organization. **Changes**: New in Zulip 10.0 (feature level 316). Previously, this permission was controlled by the enum `edit_topic_policy`. Values were 1=Members, 2=Admins, 3=Full members, 4=Moderators, 5=Everyone, 6=Nobody. In Zulip 7.0 (feature level 159), `Nobody` was added as an option to `edit_topic_policy` enum. ' - $ref: '#/components/schemas/GroupSettingValue' realm_can_create_groups: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'Present if `realm` is present in `fetch_event_types`. A [group-setting value](/api/group-setting-values) defining the set of users who have permission to create user groups in this organization. **Changes**: New in Zulip 10.0 (feature level 299). Previously `realm_user_group_edit_policy` field used to control the permission to create user groups. ' realm_can_create_bots_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'Present if `realm` is present in `fetch_event_types`. A [group-setting value](/api/group-setting-values) defining the set of users who have permission to create all types of bot users in the organization. See also `can_create_write_only_bots_group`. **Changes**: New in Zulip 10.0 (feature level 344). Previously, this permission was controlled by the enum `bot_creation_policy`. Values were 1=Members, 2=Generic bots limited to administrators, 3=Administrators. ' realm_can_create_write_only_bots_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'Present if `realm` is present in `fetch_event_types`. A [group-setting value](/api/group-setting-values) defining the set of users who have permission to create bot users that can only send messages in the organization, i.e. incoming webhooks, in addition to the users who are present in `can_create_bots_group`. **Changes**: New in Zulip 10.0 (feature level 344). Previously, this permission was controlled by the enum `bot_creation_policy`. Values were 1=Members, 2=Generic bots limited to administrators, 3=Administrators. ' realm_can_manage_all_groups: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: "Present if `realm` is present in `fetch_event_types`.\n\nA [group-setting value](/api/group-setting-values)\ndefining the set of users who have permission to\nadminister all existing groups in this organization.\n\n**Changes**: Prior to Zulip 10.0 (feature level 305), only users who\nwere a member of the group or had the moderator role or above could\nexercise the permission on a given group.\n\nNew in Zulip 10.0 (feature level 299). Previously the\n`user_group_edit_policy` field controlled the permission\nto manage user groups. Valid values were as follows:\n\n- 1 = All members can create and edit user groups\n- 2 = Only organization administrators can create and edit\n user groups\n- 3 = Only [full members][calc-full-member] can create and\n edit user groups.\n- 4 = Only organization administrators and moderators can\n create and edit user groups.\n\n[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member\n" realm_can_manage_billing_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'Present if `realm` is present in `fetch_event_types`. A [group-setting value](/api/group-setting-values) defining the set of users who have permission to manage plans and billing in the organization. **Changes**: New in Zulip 10.0 (feature level 363). Previously, only owners and users with `is_billing_admin` property set to `true` were allowed to manage plans and billing. ' realm_can_create_public_channel_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'Present if `realm` is present in `fetch_event_types`. A [group-setting value](/api/group-setting-values) defining the set of users who have permission to create public channels in this organization. **Changes**: New in Zulip 9.0 (feature level 264). Previously `realm_create_public_stream_policy` field used to control the permission to create public channels. ' realm_can_create_private_channel_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'Present if `realm` is present in `fetch_event_types`. A [group-setting value](/api/group-setting-values) defining the set of users who have permission to create private channels in this organization. **Changes**: New in Zulip 9.0 (feature level 266). Previously `realm_create_private_stream_policy` field used to control the permission to create private channels. ' realm_can_create_web_public_channel_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'Present if `realm` is present in `fetch_event_types`. A [group-setting value](/api/group-setting-values) defining the set of users who have permission to create web-public channels in this organization. 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. **Changes**: New in Zulip 10.0 (feature level 280). Previously `realm_create_web_public_stream_policy` field used to control the permission to create web-public channels. ' realm_can_resolve_topics_group: allOf: - description: 'Present if `realm` is present in `fetch_event_types`. A [group-setting value](/api/group-setting-values) defining the set of users who have permission to [resolve topics](/help/resolve-a-topic) in the organization. **Changes**: New in Zulip 10.0 (feature level 367). Previously, permission to resolve topics was controlled by the more general `can_move_messages_between_topics_group permission for moving messages`. ' - $ref: '#/components/schemas/GroupSettingValue' realm_create_public_stream_policy: type: integer deprecated: true description: 'Present if `realm` is present in `fetch_event_types`. A deprecated representation of a superset of the users who have permission to create public channels in the organization, available for backwards-compatibility. Clients should use `can_create_public_channel_group` instead. It is an enum with the following possible values, corresponding to roles/system groups: - 1 = Members only - 2 = Admins only - 3 = [Full members][calc-full-member] only - 4 = Admins and moderators only **Changes**: Deprecated in Zulip 9.0 (feature level 264) and replaced by `realm_can_create_public_channel_group`, which supports finer resolution of configurations, resulting in this property being inaccurate following that transition. Before Zulip 5.0 (feature level 102), permission to create channels 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 deprecated: true description: 'Present if `realm` is present in `fetch_event_types`. A deprecated representation of a superset of the users who have permission to create private channels in the organization, available for backwards-compatibility. Clients should use `can_create_private_channel_group` instead. It is an enum with the following possible values, corresponding to roles/system groups: - 1 = Members only - 2 = Admins only - 3 = [Full members][calc-full-member] only - 4 = Admins and moderators only **Changes**: Deprecated in Zulip 9.0 (feature level 266) and replaced by `realm_can_create_private_channel_group`, which supports finer resolution of configurations, resulting in this property being inaccurate following that transition. **Changes**: Before Zulip 5.0 (feature level 102), permission to create channels 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 deprecated: true description: 'Present if `realm` is present in `fetch_event_types`. A deprecated representation of a superset of the users who have permission to create web-public channels in the organization, available for backwards-compatibility. Clients should use `can_create_web_public_channel_group` instead. It is an enum with the following possible values, corresponding to roles/system groups: - 2 = Admins only - 4 = Admins and moderators only - 6 = Nobody - 7 = Owners only **Changes**: Deprecated in Zulip 10.0 (feature level 280) and replaced by `realm_can_create_web_public_channel_group`, which supports finer resolution of configurations, resulting in this property being inaccurate following that transition. **Changes**: Added in Zulip 5.0 (feature level 103). [permission-level]: /api/roles-and-permissions#permission-levels ' realm_wildcard_mention_policy: type: integer deprecated: true description: 'Present if `realm` is present in `fetch_event_types`. A deprecated representation of a superset of the users who have permission to use wildcard mentions in large channels, available for backwards-compatibility. Clients should use `can_mention_many_users_group` instead. It is an enum with the following possible values, corresponding to roles/system groups: - 1 = Any user can use wildcard mentions in large channels. - 2 = Only members can use wildcard mentions in large channels. - 3 = Only [full members][calc-full-member] can use wildcard mentions in large channels. - 5 = Only organization administrators can use wildcard mentions in large channels. - 6 = Nobody can use wildcard mentions in large channels. - 7 = Only organization administrators and moderators can use wildcard mentions in large channels. All users will receive a warning/reminder when using mentions in large channels, even when permitted to do so. **Changes**: Deprecated in Zulip 10.0 (feature level 352) and replaced by `realm_can_mention_many_users_group`, which supports finer resolution of configurations, resulting in this property being inaccurate following that transition. Channel administrators option removed in Zulip 6.0 (feature level 133). Moderators option added in Zulip 4.0 (feature level 62). New in Zulip 4.0 (feature level 33). [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_welcome_message_custom_text: type: string description: 'Present if `realm` is present in `fetch_event_types`. This organization''s configured custom message for Welcome Bot to send to new user accounts, in Zulip Markdown format. **Changes**: New in Zulip 11.0 (feature level 416). ' 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_create_multiuse_invite_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'Present if `realm` is present in `fetch_event_types`. A [group-setting value](/api/group-setting-values) defining the set of users who are allowed to create [reusable invitation links](/help/invite-new-users#create-a-reusable-invitation-link) to the organization. **Changes**: Prior to Zulip 10.0 (feature level 314), this value used to be of type integer and did not accept anonymous user groups. New in Zulip 8.0 (feature level 209). ' realm_media_preview_size: type: integer enum: - 100 - 150 - 200 description: 'Present if `realm` is present in `fetch_event_types`. The organization''s policy for the size of image and video thumbnails in messages, expressed as a percentage of the default height. Currently, only certain values are permitted. - `100`: 100% height (the default). - `150`: 150% height. - `200`: 200% height. **Changes**: New in Zulip 12.0 (feature level 469). ' 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/image-video-and-website-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/image-video-and-website-previews). ' realm_topics_policy: type: string enum: - allow_empty_topic - disable_empty_topic description: 'Present if `realm` is present in `fetch_event_types`. The organization''s default policy for sending channel messages to the [empty "general chat" topic](/help/require-topics). - `"allow_empty_topic"`: Channel messages can be sent to the empty topic. - `"disable_empty_topic"`: Channel messages cannot be sent to the empty topic. **Changes**: New in Zulip 11.0 (feature level 392). Previously, this was controlled by the boolean `realm_mandatory_topics` setting, which is now deprecated. ' realm_mandatory_topics: type: boolean deprecated: true description: 'Present if `realm` is present in `fetch_event_types`. Whether [topics are required](/help/require-topics) for messages in this organization. **Changes**: Deprecated in Zulip 11.0 (feature level 392). This is now controlled by the realm `topics_policy` setting. ' 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_require_e2ee_push_notifications: type: boolean description: 'Present if `realm` is present in `fetch_event_types`. Whether this realm is configured to disallow sending mobile push notifications with message content through the legacy mobile push notifications APIs. The new API uses end-to-end encryption to protect message content and metadata from being accessible to the push bouncer service, APNs, and FCM. Clients that support the new E2EE API will use it automatically regardless of this setting. If `true`, mobile push notifications sent to clients that lack support for E2EE push notifications will always have "New message" as their content. Note that these legacy mobile notifications will still contain metadata, which may include the message''s ID, the sender''s name, email address, and avatar. In a future release, once the official mobile apps have implemented fully validated their E2EE protocol support, this setting will become strict, and disable the legacy protocol entirely. **Changes**: New in Zulip 11.0 (feature level 409). Previously, this behavior was available only via the `PUSH_NOTIFICATION_REDACT_CONTENT` global server setting. ' realm_require_unique_names: type: boolean description: 'Present if `realm` is present in `fetch_event_types`. Indicates whether the organization is configured to require users to have unique full names. If true, the server will reject attempts to create a new user, or change the name of an existing user, where doing so would lead to two users whose names are identical modulo case and unicode normalization. **Changes**: New in Zulip 9.0 (feature level 246). Previously, the Zulip server could not be configured to enforce unique names. ' 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_channel_events_messages: type: boolean description: 'Present if `realm` is present in `fetch_event_types`. Indicates whether channel event messages are sent in this organization. **Changes**: New in Zulip 12.0 (feature level 434). Previously, channel events were sent unconditionally. ' 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 channels 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 `can_create_web_public_channel_group` 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/configure-call-provider) for the organization. - 0 = None - 1 = Jitsi Meet - 3 = Zoom (User OAuth integration) - 4 = BigBlueButton - 5 = Zoom (Server to Server OAuth integration) - 6 = Constructor Groups - 7 = Nextcloud Talk - 8 = Webex (User OAuth integration) Note that only one of the [Zoom integrations][zoom-video-calls] can be configured on a Zulip server. **Changes**: In Zulip 12.0 (feature level 493), added the Webex OAuth option. In Zulip 12.0 (feature level 465), added the Nextcloud Talk option. In Zulip 12.0 (feature level 460), added the Constructor Groups option. In Zulip 10.0 (feature level 353), added the Zoom Server to Server OAuth option. In Zulip 3.0 (feature level 1), added the None option to disable video call UI. [zoom-video-calls]: https://zulip.readthedocs.io/en/latest/production/video-calls.html#zoom ' realm_jitsi_server_url: type: string nullable: true description: 'Present if `realm` is present in `fetch_event_types`. The URL of the custom Jitsi Meet server configured in this organization''s settings. `null`, the default, means that the organization is using the should use the server-level configuration, `server_jitsi_server_url`. A correct client supporting only the modern API should use `realm_jitsi_server_url || server_jitsi_server_url` to create calls. **Changes**: New in Zulip 8.0 (feature level 212). Previously, this was only available as a server-level configuration, which was available via the `jitsi_server_url` field. ' realm_gif_rating_policy: type: integer description: 'Present if `realm` is present in `fetch_event_types`. Maximum rating of the GIFs that will be retrieved by the GIPHY and Tenor integrations in this organization. **Changes**: Before Zulip 12.0 (feature level 453), this was called `realm_giphy_rating`. **Changes**: Before Zulip 12.0 (feature level 442), this was only used by the Giphy integration. 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_direct_message_initiator_group: allOf: - description: 'Present if `realm` is present in `fetch_event_types`. A [group-setting value](/api/group-setting-values) defining the set of users who have permission to start a new direct message conversation involving other non-bot users. Users who are outside this group and attempt to send the first direct message to a given collection of recipient users will receive an error, unless all other recipients are bots or the sender. **Changes**: New in Zulip 9.0 (feature level 270). Previously, access to send direct messages was controlled by the `private_message_policy` realm setting, which supported values of 1 (enabled) and 2 (disabled). ' - $ref: '#/components/schemas/GroupSettingValue' realm_direct_message_permission_group: allOf: - description: 'Present if `realm` is present in `fetch_event_types`. A [group-setting value](/api/group-setting-values) defining the set of users who have permission to fully use direct messages. Users outside this group can only send direct messages to conversations where all the recipients are in this group, are bots, or are the sender, ensuring that every direct message conversation will be visible to at least one user in this group. **Changes**: New in Zulip 9.0 (feature level 270). Previously, access to send direct messages was controlled by the `private_message_policy` realm setting, which supported values of 1 (enabled) and 2 (disabled). ' - $ref: '#/components/schemas/GroupSettingValue' realm_default_code_block_language: type: string description: 'Present if `realm` is present in `fetch_event_types`. The default pygments language code to be used for code blocks in this organization. If an empty string, no default has been set. **Changes**: Prior to Zulip 8.0 (feature level 195), a server bug meant that both `null` and an empty string could represent that no default was set for this realm setting. Clients supporting older server versions should treat either value (`null` or `""`) as no default being 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: $ref: '#/components/schemas/RealmAuthenticationMethod' description: 'Present if `realm` is present in `fetch_event_types`. Dictionary of authentication method keys mapped to dictionaries that describe the properties of the named authentication method for the organization - its enabled status and availability for use by the organization. Clients should use this to implement server-settings UI to change which methods are enabled for the organization. For authentication UI itself, clients should use the pre-authentication metadata returned by [`GET /server_settings`](/api/get-server-settings). **Changes**: In Zulip 9.0 (feature level 241), the values in this dictionary were changed. Previously, the values were a simple boolean indicating whether the backend is enabled or not. ' realm_allow_message_editing: type: boolean description: 'Present if `realm` is present in `fetch_event_types`. Whether this organization''s [message edit policy][config-message-editing] allows editing the content of messages. See [`PATCH /messages/{message_id}`](/api/update-message) for details and history of how message editing permissions work. [config-message-editing]: /help/restrict-message-editing-and-deletion ' 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, so messages can be edited regardless of how long ago they were sent. See [`PATCH /messages/{message_id}`](/api/update-message) for details and history of how message editing permissions work. **Changes**: Before Zulip 6.0 (feature level 138), no limit was represented using the special value `0`. ' 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 channel 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. See [`PATCH /messages/{message_id}`](/api/update-message) for details and history of how message editing permissions work. **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 channels 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. See [`PATCH /messages/{message_id}`](/api/update-message) for details and history of how message editing permissions work. **Changes**: New in Zulip 7.0 (feature level 162). Previously, there was no time limit for moving messages between channels 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. ' realm_workplace_users_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'Present if `realm` is present in `fetch_event_types`. A [group-setting value](/api/group-setting-values) defining the set of users who will be considered as workplace users for billing. **Changes**: New in Zulip 12.0 (feature level 477). ' 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 deprecated: true description: 'Present if `realm` is present in `fetch_event_types`. The URL for the organization. Alias of `realm_url`. **Changes**: Deprecated in Zulip 9.0 (feature level 257). The term "URI" is deprecated in [web standards](https://url.spec.whatwg.org/#goals). ' realm_url: type: string description: 'Present if `realm` is present in `fetch_event_types`. The URL for the organization. **Changes**: New in Zulip 9.0 (feature level 257), replacing the deprecated `realm_uri`. ' realm_uuid: type: string description: 'Present if `realm` is present in `fetch_event_types`. A unique identifier for the organization, expected to be stable even if the organization migrates between hosting environments. Used as the salt for Jdenticon avatars; Clients that prefer to compute Jdenticon avatars may use `{realm_uuid}:{user_id}` as the Jdenticon key. **Changes**: New in Zulip 12.0 (feature level 466). ' 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/configure-call-provider) 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_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 `true` for Zulip Cloud and self-hosted realms that have a valid registration for the [Mobile push notifications service](https://zulip.readthedocs.io/en/latest/production/mobile-push-notifications.html), and `false` for self-hosted servers that do not. **Changes**: Before Zulip 8.0 (feature level 231), this incorrectly was `true` for servers that were partly configured to use the Mobile Push Notifications Service but not properly registered. ' realm_push_notifications_enabled_end_timestamp: type: integer nullable: true description: 'Present if `realm` is present in `fetch_event_types`. If the server expects the realm''s push notifications access to end at a definite time in the future, the UNIX timestamp (UTC) at which this is expected to happen. Mobile clients should use this field to display warnings to users when the indicated timestamp is near. **Changes**: New in Zulip 8.0 (feature level 231). ' 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**: Before Zulip 9.0 (feature level 251), this field was incorrectly measured in bytes, not MiB. 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_owner_full_content_access: type: boolean description: 'Present if `realm` is present in `fetch_event_types`. Whether the organization''s security model allows owners to access all private content in this organization. Note that this security model configuration can only be changed via a command-line management command. **Changes**: New in Zulip 12.0 (feature level 438). ' 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) ' realm_enable_guest_user_dm_warning: type: boolean description: 'Present if `realm` is present in `fetch_event_types`. Whether clients should show a warning when a user is composing a DM to a guest user in this organization. **Changes**: New in Zulip 10.0 (feature level 348). ' realm_enable_guest_user_indicator: type: boolean description: 'Present if `realm` is present in `fetch_event_types`. Whether clients should display "(guest)" after the names of guest users to prominently highlight their status. **Changes**: New in Zulip 8.0 (feature level 216). ' realm_can_access_all_users_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'Present if `realm` is present in `fetch_event_types`. A [group-setting value](/api/group-setting-values) defining the set of users who are allowed to access all users in the organization. **Changes**: Prior to Zulip 10.0 (feature level 314), this value used to be of type integer and did not accept anonymous user groups. New in Zulip 8.0 (feature level 225). ' realm_can_summarize_topics_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'Present if `realm` is present in `fetch_event_types`. A [group-setting value](/api/group-setting-values) defining the set of users who are allowed to use AI summarization. **Changes**: New in Zulip 10.0 (feature level 350). ' 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. ' realm_default_avatar_source: type: string description: 'Present if `realm` is present in `fetch_event_types`. The avatar data source type for new users. - "G" = Hosted by Gravatar - "J" = Generated using Jdenticon Note that "U" is not a supported value here, since there is no such thing as a "default" user-uploaded avatar. **Changes**: New in Zulip 12.0 (feature level 456). ' jitsi_server_url: type: string deprecated: true description: 'Present if `realm` is present in `fetch_event_types`. The base URL to be used to create Jitsi video calls. Equals `realm_jitsi_server_url || server_jitsi_server_url`. **Changes**: Deprecated in Zulip 8.0 (feature level 212) and will eventually be removed. Previously, the Jitsi server to use was not configurable on a per-realm basis, and this field contained the server''s configured Jitsi server. (Which is now provided as `server_jitsi_server_url`). Clients supporting older versions should fall back to this field when creating calls: using `realm_jitsi_server_url || server_jitsi_server_url` with newer servers and using `jitsi_server_url` with servers below feature level 212. ' 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_max_length: type: integer description: 'Present if `realm` is present in `fetch_event_types`. This Zulip server''s configured maximum length for passwords. Necessary for password change UI to show whether the password will be accepted. **Changes**: New in Zulip 10.0 (feature level 338). ' 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. ' gif_rating_policy_options: type: object description: 'Present if `realm` is present in `fetch_event_types`. Dictionary where each entry describes a valid rating configuration that is available on this server and could be selected by an organization administrator. Useful for administrative settings UI that allows changing the allowed rating of GIFs. **Changes**: Before Zulip 12.0 (feature level 453), this was called `gif_rating_options`. **Changes**: Before Zulip 12.0 (feature level 442), this was called `giphy_rating_options` and only supported the original GIPHY gif picker integration. `giphy_rating_options` was new in Zulip 4.0 (feature level 55). ' 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 organization. ' 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_thumbnail_formats: description: 'Present if `realm` is present in `fetch_event_types`. A list describing the image formats that uploaded images will be thumbnailed into. Any image with a source starting with `/user_uploads/thumbnail/` can have its last path component replaced with any of the names contained in this list, to obtain the desired thumbnail size. See [Images in Markdown messages](/api/message-formatting#images) for details of how Zulip renders images, and how clients should handle them. **Changes**: New in Zulip 9.0 (feature level 273). ' type: array items: type: object additionalProperties: false properties: name: type: string description: 'The file path component of the thumbnail format. ' max_width: type: integer description: 'The maximum width of this format. ' max_height: type: integer description: 'The maximum height of this format. ' format: type: string description: 'The extension of this format. ' animated: type: boolean description: 'If this file format is animated. These formats are only generated for uploaded images which themselves are animated. ' 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 channels](/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 channels (`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). ' server_jitsi_server_url: type: string nullable: true description: 'Present if `realm` is present in `fetch_event_types`. The URL of the Jitsi server that the Zulip server is configured to use by default; the organization-level setting `realm_jitsi_server_url` takes precedence over this setting when both are set. **Changes**: New in Zulip 8.0 (feature level 212). Previously, this value was available as the now-deprecated `jitsi_server_url`. ' server_can_summarize_topics: type: boolean description: 'Present if `realm` is present in `fetch_event_types` Whether topic summarization is enabled in the server or not depending upon whether `TOPIC_SUMMARIZATION_MODEL` is set or not. **Changes**: New in Zulip 10.0 (feature level 350). ' 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 timeout. It is important that clients respect this parameter, so that increases in the heartbeat timeout 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_billing: type: object additionalProperties: false description: 'Present if `realm_billing` is present in `fetch_event_types`. A dictionary containing billing information of the organization. **Changes**: New in Zulip 10.0 (feature level 363). ' properties: has_pending_sponsorship_request: type: boolean description: 'Whether there is a pending sponsorship request for the organization. Note that this field will always be `false` if the user is not in `can_manage_billing_group`. **Changes**: New in Zulip 10.0 (feature level 363). ' realm_moderation_request_channel_id: type: integer description: 'Present if `realm` is present in `fetch_event_types`. The ID of the private channel to which messages flagged by users for moderation are sent. Moderators can use this channel to review and act on reported content. Will be `-1` if moderation requests are disabled. Clients should check whether moderation requests are disabled to determine whether to present a "report message" feature in their UI within a given organization. **Changes**: New in Zulip 10.0 (feature level 331). Previously, no "report message" feature existed in Zulip. ' realm_new_stream_announcements_stream_id: type: integer description: 'Present if `realm` is present in `fetch_event_types`. The ID of the channel to which automated messages announcing the [creation of new channels][new-channel-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-channel-announce]: /help/configure-automated-notices#new-channel-announcements **Changes**: In Zulip 9.0 (feature level 241), renamed ''realm_notifications_stream_id'' to `realm_new_stream_announcements_stream_id`. ' realm_signup_announcements_stream_id: type: integer description: 'Present if `realm` is present in `fetch_event_types`. The ID of the channel 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-automated-notices#new-user-announcements **Changes**: In Zulip 9.0 (feature level 241), renamed ''realm_signup_notifications_stream_id'' to `realm_signup_announcements_stream_id`. ' realm_zulip_update_announcements_stream_id: type: integer description: 'Present if `realm` is present in `fetch_event_types`. The ID of the channel to which automated messages announcing new features or other end-user updates about the Zulip software 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. **Changes**: New in Zulip 9.0 (feature level 242). ' realm_empty_topic_display_name: type: string description: 'Present if `realm` is present in `fetch_event_types`. Clients declaring the `empty_topic_name` client capability should use the value of `realm_empty_topic_display_name` to determine how to display the empty string topic. Clients not declaring the `empty_topic_name` client capability receive `realm_empty_topic_display_name` value as the topic name replacing empty string. **Changes**: New in Zulip 10.0 (feature level 334). Previously, the empty string was not a valid topic name. ' 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 nullable: true description: 'Whether time should be [displayed in 24-hour notation](/help/change-the-time-format). A `null` value indicates that the client should use the default time format for the user''s locale. **Changes**: Prior to Zulip 11.0 (feature level 408), `null` was not a valid value for this setting. Note that it was not possible to actually set the time format to `null` at this feature level. 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`). ' 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. ' web_channel_default_view: type: integer description: 'Web/desktop app setting controlling the default navigation behavior when clicking on a channel link. - 1 - Top topic in the channel - 2 - Channel feed - 3 - List of topics - 4 - Top unread topic in channel **Changes**: The "Top unread topic in channel" is new in Zulip 11.0 (feature level 401). In Zulip 11.0 (feature level 383), we added a new option "List of topics" to this setting. New in Zulip 9.0 (feature level 269). Previously, this was not configurable, and every user had the "Channel feed" behavior. ' 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). ' receives_typing_notifications: type: boolean description: 'Whether the user is configured to receive typing notifications from other users. The server will only deliver typing notifications events to users who for whom this is enabled. **Changes**: New in Zulip 9.0 (feature level 253). Previously, there were only options to disable sending typing notifications. ' web_suggest_update_timezone: type: boolean description: 'Whether the user should be shown an alert, offering to update their [profile time zone](/help/change-your-timezone), when the time displayed for the profile time zone differs from the current time displayed by the time zone configured on their device. **Changes**: New in Zulip 10.0 (feature level 329). ' 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. ' web_font_size_px: description: 'User-configured primary `font-size` for the web application, in pixels. **Changes**: New in Zulip 9.0 (feature level 245). Previously, font size was only adjustable via browser zoom. Note that this setting was not fully implemented at this feature level. ' type: integer example: 14 web_line_height_percent: description: 'User-configured primary `line-height` for the web application, in percent, so a value of 120 represents a `line-height` of 1.2. **Changes**: New in Zulip 9.0 (feature level 245). Previously, line height was not user-configurable. Note that this setting was not fully implemented at this feature level. ' type: integer example: 122 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. ' web_home_view: type: string description: 'The [home view](/help/configure-home-view) used when opening a new Zulip web app window or hitting the `Esc` keyboard shortcut repeatedly. - "recent" - Recent conversations view - "inbox" - Inbox view - "all_messages" - Combined feed view **Changes**: Before Zulip 12.0 (feature level 454), the Recent view had `"recent_topics"` as its string encoding. New in Zulip 8.0 (feature level 219). Previously, this was called `default_view`, which was new in Zulip 4.0 (feature level 42). ' web_escape_navigates_to_home_view: type: boolean description: 'Whether the escape key navigates to the [configured home view](/help/configure-home-view). **Changes**: New in Zulip 8.0 (feature level 219). Previously, this was called `escape_navigates_to_default_view`, which was 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 - "twitter" - Twitter - "text" - Plain text ' demote_inactive_streams: type: integer description: 'Whether to [hide inactive channels](/help/manage-inactive-channels) 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). ' web_animate_image_previews: type: string description: 'Controls how animated images should be played in the message feed in the web/desktop application. - "always" - Always play the animated images in the message feed. - "on_hover" - Play the animated images on hover over them in the message feed. - "never" - Never play animated images in the message feed. **Changes**: New in Zulip 9.0 (feature level 275). ' web_stream_unreads_count_display_policy: type: integer description: 'Configuration for which channels should be displayed with a numeric unread count in the left sidebar. Channels that do not have an unread count will have a simple dot indicator for whether there are any unread messages. - 1 - All channels - 2 - Unmuted channels and topics - 3 - No channels **Changes**: New in Zulip 8.0 (feature level 210). ' hide_ai_features: type: boolean description: 'Controls whether user wants AI features like topic summarization to be hidden in all Zulip clients. **Changes**: New in Zulip 10.0 (feature level 350). ' web_inbox_show_channel_folders: type: boolean description: 'Determines whether [channel folders](/help/channel-folders) are used to organize how conversations with unread messages are displayed in the web/desktop application''s Inbox view. **Changes**: New in Zulip 12.0 (feature level 431). ' web_left_sidebar_show_channel_folders: type: boolean description: 'Determines whether [channel folders](/help/channel-folders) are used to organize how channels are displayed in the web/desktop application''s left sidebar. **Changes**: New in Zulip 11.0 (feature level 411). ' web_left_sidebar_unreads_count_summary: type: boolean description: 'Determines whether the web/desktop application''s left sidebar displays the unread message count summary. **Changes**: New in Zulip 11.0 (feature level 398). ' enable_stream_desktop_notifications: type: boolean description: 'Enable visual desktop notifications for channel messages. ' enable_stream_email_notifications: type: boolean description: 'Enable email notifications for channel messages. ' enable_stream_push_notifications: type: boolean description: 'Enable mobile notifications for channel messages. ' enable_stream_audible_notifications: type: boolean description: 'Enable audible desktop notifications for channel messages. ' notification_sound: type: string description: 'Notification sound name. ' enable_desktop_notifications: type: boolean description: 'Enable visual desktop notifications for direct messages and @-mentions. ' enable_sounds: type: boolean description: 'Enable audible desktop notifications for direct messages and @-mentions. ' enable_offline_email_notifications: type: boolean description: 'Enable email notifications for direct messages and @-mentions received when the user is offline. ' enable_offline_push_notifications: type: boolean description: 'Enable mobile notification for direct messages and @-mentions received when the user is offline. ' enable_online_push_notifications: type: boolean description: 'Enable mobile notification for direct messages and @-mentions received when the user is online. ' enable_followed_topic_desktop_notifications: type: boolean description: 'Enable visual desktop notifications for messages sent to followed topics. **Changes**: New in Zulip 8.0 (feature level 189). ' enable_followed_topic_email_notifications: type: boolean description: 'Enable email notifications for messages sent to followed topics. **Changes**: New in Zulip 8.0 (feature level 189). ' enable_followed_topic_push_notifications: type: boolean description: 'Enable push notifications for messages sent to followed topics. **Changes**: New in Zulip 8.0 (feature level 189). ' enable_followed_topic_audible_notifications: type: boolean description: 'Enable audible desktop notifications for messages sent to followed topics. **Changes**: New in Zulip 8.0 (feature level 189). ' 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 direct messages in desktop notifications. ' wildcard_mentions_notify: type: boolean description: 'Whether wildcard mentions (E.g. @**all**) should send notifications like a personal mention. ' enable_followed_topic_wildcard_mentions_notify: type: boolean description: 'Whether wildcard mentions (e.g., @**all**) in messages sent to followed topics should send notifications like a personal mention. **Changes**: New in Zulip 8.0 (feature level 189). ' desktop_icon_count_display: type: integer description: 'Unread count badge (appears in desktop sidebar and browser tab) - 1 - All unread messages - 2 - DMs, mentions, and followed topics - 3 - DMs and mentions - 4 - None **Changes**: In Zulip 8.0 (feature level 227), added `DMs, mentions, and followed topics` option, renumbering the options to insert it in order. ' 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`. ' automatically_follow_topics_policy: type: integer description: 'Which [topics to follow automatically](/help/mute-a-topic). - 1 - Topics the user participates in - 2 - Topics the user sends a message to - 3 - Topics the user starts - 4 - Never **Changes**: New in Zulip 8.0 (feature level 214). ' automatically_unmute_topics_in_muted_streams_policy: type: integer description: 'Which [topics to unmute automatically in muted channels](/help/mute-a-topic). - 1 - Topics the user participates in - 2 - Topics the user sends a message to - 3 - Topics the user starts - 4 - Never **Changes**: New in Zulip 8.0 (feature level 214). ' automatically_follow_topics_where_mentioned: type: boolean description: 'Whether the server will automatically mark the user as following topics where the user is mentioned. **Changes**: New in Zulip 8.0 (feature level 235). ' resolved_topic_notice_auto_read_policy: type: string description: 'Controls whether the resolved-topic notices are marked as read. - "always" - Always mark resolved-topic notices as read. - "except_followed" - Mark resolved-topic notices as read in topics not followed by the user. - "never" - Never mark resolved-topic notices as read. **Changes**: New in Zulip 11.0 (feature level 385). ' 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/configure-send-message-keys) 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 direct 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 channel 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). ' allow_private_data_export: type: boolean description: 'Whether organization administrators are allowed to export your private data. **Changes**: New in Zulip 10.0 (feature level 293). ' email_address_visibility: $ref: '#/components/schemas/EmailAddressVisibility' web_navigate_to_sent_message: type: boolean description: 'Web/desktop app setting for whether the user''s view should automatically go to the conversation where they sent a message. **Changes**: New in Zulip 9.0 (feature level 268). Previously, this behavior was not configurable. ' 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. If the current user is a guest whose access to users is limited by a `can_access_all_users_group` policy, and the event queue was registered with the `user_list_incomplete` client capability, then users that the current user cannot access will not be included in this array. If the current user''s access to a user is restricted but the client lacks this capability, then that inaccessible user will appear in the users array as an "Unknown user" object with the usual format but placeholder data whose only variable content is the user ID. See also `cross_realm_bots` and `realm_non_active_users`. **Changes**: Before Zulip 8.0 (feature level 232), the `user_list_incomplete` client capability did not exist, and so all clients whose access to a new user was prevented by `can_access_all_users_group` policy would receive a fake "Unknown user" event for such 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. Valid values are: - "G" = Hosted by Gravatar - "J" = Generated using Jdenticon - "U" = Uploaded by user **Changes**: The "J" value is new in Zulip 12.0 (feature level 466). The avatar data source type for the current 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 channel with the organization''s [channel creation policy](/help/configure-who-can-create-channels). 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 channel. 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 channels with the organization''s [channel creation policy](/help/configure-who-can-create-channels). **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 channels. ' 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 channels with the organization''s [channel creation policy](/help/configure-who-can-create-channels). **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 channels. ' 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 channels with the organization''s [channel creation policy](/help/configure-who-can-create-channels). 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 channels with the organization''s [channels policy](/help/configure-who-can-invite-to-channels). ' 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 at least 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). **Changes**: New in Zulip 3.0 (feature level 11). ' is_moderator: type: boolean description: 'Present if `realm_user` is present in `fetch_event_types`. Whether the current user is at least an [organization moderator](/api/roles-and-permissions). **Changes**: Prior to Zulip 11.0 (feature level 380), this was only true for users whose role was exactly the moderator role. 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_bot: {} 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: {} is_imported_stub: {} server_report_message_types: description: 'Present if `realm` is present in `fetch_event_types`. A list of objects where each object describes a supported report type for the [message report](/help/report-a-message) feature. **Changes**: New in Zulip 12.0 (feature level 435). ' type: array items: type: object additionalProperties: false properties: key: type: string description: 'The unique ID for the report message type. ' name: type: string description: 'The user-facing string for the report message type, to be displayed in the report message UI, in the user''s language. Note that the actual report will use the name for this type in the organization''s default language. ' server_supported_permission_settings: description: 'Present if `realm` is present in `fetch_event_types`. Metadata detailing the valid values for permission settings that use [group-setting values](/api/group-setting-values). Clients should use these data as explained in the [main documentation](/api/group-setting-values#permitted-values) to determine what values to present as possible values for these settings in UI components. **Changes**: Before Zulip 10.0 (feature level 326), this part of the response had a documented-as-unstable format not suitable for general client use, and should be ignored. New in Zulip 8.0 (feature level 221). ' type: object additionalProperties: false properties: realm: type: object description: 'Configuration for realm level group permission settings. ' additionalProperties: $ref: '#/components/schemas/GroupPermissionSetting' stream: type: object description: 'Configuration for channel level group permission settings. ' additionalProperties: $ref: '#/components/schemas/GroupPermissionSetting' group: type: object description: 'Configuration for group level group permission settings. ' additionalProperties: $ref: '#/components/schemas/GroupPermissionSetting' max_bulk_new_subscription_messages: description: 'Maximum number of new subscribers for which the server will respect the `send_new_subscription_messages` parameter when [adding subscribers to a channel](/api/subscribe#parameter-send_new_subscription_messages). **Changes**: New in Zulip 11.0 (feature level 397). ' type: number example: 100 example: last_event_id: -1 msg: '' queue_id: fb67bf8a-c031-47cc-84cf-ed80accacda8 idle_queue_timeout_secs: 600 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 /real-time: post: tags: - real_time_events description: '(Ignored) ' requestBody: required: false content: application/x-www-form-urlencoded: schema: type: object properties: event_types: $ref: '#/components/schemas/Event_types' narrow: $ref: '#/components/schemas/Narrow' all_public_streams: $ref: '#/components/schemas/AllPublicChannels' encoding: event_types: contentType: application/json narrow: contentType: application/json all_public_streams: contentType: application/json security: - basicAuth: [] responses: '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/IncompatibleParametersError' - $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' components: schemas: Narrow: 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 channel subscriptions (or because they are a recipient of a direct message). This means that a client that requests a `narrow` filter of `[["channel", "Denmark"]]` will receive events for new messages sent to that channel while the user is subscribed to that channel. 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 channels, so bots using this API need to be [subscribed](/api/subscribe) to any channels whose messages you''d like them to process using this endpoint. See the `all_public_streams` parameter for how to process all public channel messages in an organization. **Changes**: See [changes section](/api/construct-narrow#changes) of search/narrow filter documentation. ' type: array items: type: array items: type: string default: [] example: - - channel - Denmark BasicChannel: allOf: - $ref: '#/components/schemas/BasicChannelBase' - additionalProperties: false properties: stream_id: {} name: {} is_archived: {} description: {} date_created: {} creator_id: nullable: true invite_only: {} rendered_description: {} is_web_public: {} stream_post_policy: {} message_retention_days: nullable: true history_public_to_subscribers: {} topics_policy: {} first_message_id: nullable: true folder_id: nullable: true is_recently_active: {} is_announcement_only: {} can_add_subscribers_group: {} can_remove_subscribers_group: {} can_administer_channel_group: {} can_delete_any_message_group: {} can_delete_own_message_group: {} can_move_messages_out_of_channel_group: {} can_move_messages_within_channel_group: {} can_send_message_group: {} can_subscribe_group: {} can_resolve_topics_group: {} can_create_topic_group: {} subscriber_count: {} stream_weekly_traffic: type: integer nullable: true description: 'The average number of messages sent to the channel per week, as estimated based on recent weeks, rounded to the nearest integer. If `null`, no information is provided on the average traffic. This can be because the channel was recently created and there is insufficient data to make an estimate, or because the server wishes to omit this information for this client, this realm, or this endpoint or type of event. **Changes**: New in Zulip 8.0 (feature level 199). Previously, this statistic was available only in subscription objects. ' required: - stream_id - name - is_archived - description - date_created - creator_id - invite_only - rendered_description - is_web_public - stream_post_policy - subscriber_count - message_retention_days - history_public_to_subscribers - first_message_id - folder_id - is_recently_active - is_announcement_only - can_remove_subscribers_group - stream_weekly_traffic - can_subscribe_group WebhookConfigOption: type: array description: 'An array of configuration options that can be set when creating a bot user for this incoming webhook integration. This is an unstable API. Please discuss in chat.zulip.org before using it. **Changes**: As of Zulip 11.0 (feature level 403), this object is reserved for integration-specific configuration options that can be set when creating a bot user. Previously, this object also included optional webhook URL parameters, which are now specified in the `url_options` object. Before Zulip 10.0 (feature level 318), this field was named `config`, and was reserved for configuration data key-value pairs. ' items: type: object additionalProperties: false properties: key: type: string description: 'A key for the configuration option. ' label: type: string description: 'A human-readable label of the configuration option. ' validator: type: string description: 'The name of the validator function for the configuration option. ' IncompatibleParametersError: allOf: - $ref: '#/components/schemas/CodedErrorBase' - additionalProperties: false description: '### Incompatible request parameters A typical failed JSON response for when two or more, optional parameters are supplied that are incompatible with each other. The value of `parameters` in the response is string containing the parameters, separated by commas, that are incompatible. ' properties: result: {} msg: {} code: {} parameters: type: string description: 'A string containing the parameters, separated by commas, that are incompatible. ' example: code: BAD_REQUEST msg: 'Unsupported parameter combination: object_id, object_name' result: error parameters: object_id, object_name MissingArgumentError: allOf: - $ref: '#/components/schemas/CodedErrorBase' - additionalProperties: false description: '### Missing request parameter A typical failed JSON response for when a required request parameter is not supplied. The value of `var_name` contains information about the missing parameter. ' 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 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. When `apply_markdown` is set, it will be in HTML format. See [Markdown message formatting](/api/message-formatting) for details on Zulip''s HTML format. ' 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. See the help center article on [message formatting](/help/format-your-message-using-markdown) for details on Zulip-flavored Markdown. ' display_recipient: description: 'Data on the recipient of the message. Will be one of the following: ' oneOf: - type: string description: 'The name of the channel the message was received in. ' - type: array description: 'An array of dictionaries containing basic data on the users who received the message. ' 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. ' 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`. See [Markdown message formatting](/api/message-formatting) for details on Zulip''s HTML format. ' prev_stream: type: integer description: 'Only present if message''s channel was edited. The channel 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 channel was edited. The ID of the channel 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 message, ordered chronologically from most recent to least recent edit. Not present if the message has never been edited or moved, or if [viewing message edit history][edit-history-access] is not allowed in the organization. Every object will contain `user_id` and `timestamp`. The other fields are optional, and will be present or not depending on whether the channel, 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`. [edit-history-access]: /help/restrict-message-edit-history-access **Changes**: In Zulip 10.0 (feature level 284), removed the `prev_rendered_content_version` field as it is an internal server implementation detail not used by any client. ' 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''s content was last edited, in UTC seconds. Not present if the message''s content has never been edited. Clients should use this field, rather than parsing the `edit_history` array, to display an indicator that the message has been edited. **Changes**: Prior to Zulip 10.0 (feature level 365), this was the time when the message was last edited or moved. ' last_moved_timestamp: type: integer description: 'The UNIX timestamp for when the message was last moved to a different channel or topic, in UTC seconds. Not present if the message has never been moved, or if the only topic moves for the message are [resolving or unresolving](/help/resolve-a-topic) the message''s topic. Clients should use this field, rather than parsing the `edit_history` array, to display an indicator that the message has been moved. **Changes**: New in Zulip 10.0 (feature level 365). Previously, parsing the `edit_history` array was required in order to correctly display moved message indicators. ' reactions: type: array description: 'Data on any [reactions](/help/emoji-reactions) to the message, ordered chronologically from oldest to newest reaction. **Changes**: In Zulip 10.0 (feature level 328), the deprecated `user` object was removed from the data for each reaction. It contained the following information about the user who added the reaction: `id`, `email`, `full_name` and `is_mirror_dummy`. ' items: $ref: '#/components/schemas/EmojiReaction' recipient_id: type: integer description: 'A unique ID for the set of users receiving the message (either a channel or group of users). Useful primarily for hashing. **Changes**: In Zulip 12.0 (feature level 482), `recipient_id` in 1:1 direct messages changed to a new value; it still has the semantics of "the 1:1 conversation with a specific user," but the raw value changed due to internal changes. Before Zulip 10.0 (feature level 327), `recipient_id` was the same across all incoming 1:1 direct messages. Now, each incoming message uniquely shares a `recipient_id` with outgoing messages in the same conversation. ' 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 channel messages; the ID of the channel. ' subject: type: string description: 'The `topic` of the message. Currently always `""` for direct messages, though this could change if Zulip adds support for topics in direct message conversations. The field name is a legacy holdover from when topics were called "subjects" and will eventually change. For clients that don''t support the `empty_topic_name` [client capability][client-capabilities], the empty string value is replaced with the value of `realm_empty_topic_display_name` found in the [POST /register](/api/register-queue) response, for channel messages. **Changes**: Before Zulip 10.0 (feature level 334), `empty_topic_name` client capability didn''t exist and empty string as the topic name for channel messages wasn''t allowed. [client-capabilities]: /api/register-queue#parameter-client_capabilities ' submessages: type: array description: 'Data used for certain experimental Zulip integrations. ' items: type: object additionalProperties: false properties: 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. ' id: type: integer description: 'The ID of the submessage. ' 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"`. ' EmojiReactionEvent: allOf: - $ref: '#/components/schemas/EmojiBase' - properties: user_id: type: integer description: 'The ID of the user who added the reaction. **Changes**: In Zulip 12.0 (feature level 484), the deprecated `user` object field was removed. It contained the following properties: `user_id`, `email`, `full_name`, and `is_mirror_dummy`. Previously, in Zulip 10.0 (feature level 339), this object was temporarily re-added to support older mobile clients, after having been removed in Zulip 10.0 (feature level 328). New in Zulip 3.0 (feature level 2). ' 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. ' RealmAuthenticationMethod: type: object properties: enabled: type: boolean description: 'Boolean describing whether the authentication method (i.e. its key) is enabled in this organization. ' available: type: boolean description: 'Boolean describing whether the authentication method is available for use. If false, the organization is not eligible to enable the authentication method. ' unavailable_reason: type: string description: 'Reason why the authentication method is unavailable. This field is optional and is only present when ''available'' is false. ' additionalProperties: false description: 'Dictionary describing the properties of an authentication method for the organization - its enabled status and availability for use by the organization. ' RealmDeactivatedError: allOf: - $ref: '#/components/schemas/CodedError' - example: code: REALM_DEACTIVATED msg: This organization is deactivated result: error description: '### Realm deactivated A typical failed json response for when user''s organization is deactivated. **Changes**: As of Zulip 5.0 (feature level 76), these errors use the HTTP 401 status code. Before this feature level, they used the HTTP 403 status code. ' ChannelCanAddSubscribersGroup: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value][setting-values] defining the set of users who have permission to add subscribers to this channel. Users who can administer the channel or have similar realm-level permissions can add subscribers to a public channel regardless of the value of this setting. Users in this group need not be subscribed to a private channel to add subscribers to it. Note that a user must [have content access](/help/channel-permissions) to a channel and permission to administer the channel in order to modify this setting. **Changes**: New in Zulip 10.0 (feature level 342). Previously, there was no channel-level setting for this permission. [setting-values]: /api/group-setting-values ' Draft: type: object description: 'A dictionary for representing a message draft. ' properties: id: type: integer readOnly: true description: 'The unique ID of the draft. ' type: type: string description: 'The type of the draft. Either unaddressed (empty string), `"stream"`, or `"private"` (for one-on-one and group direct messages). ' enum: - '' - stream - private to: type: array description: 'An array of the tentative target audience IDs. For channel messages, this should contain exactly 1 ID, the ID of the target channel. For direct 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 channel message drafts, the tentative topic name. For direct 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: integer 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 CodedError: allOf: - $ref: '#/components/schemas/CodedErrorBase' - additionalProperties: false properties: result: {} msg: {} code: {} InvalidApiKeyError: allOf: - $ref: '#/components/schemas/CodedError' - example: code: INVALID_API_KEY msg: Invalid API key result: error description: '### Invalid API key A typical failed JSON response for when the API key is invalid. ' AllPublicChannels: description: 'Whether you would like to request message events from all public channels. Useful for workflow bots that you''d like to see all new messages sent to public channels. (You can also subscribe the user to private channels). ' type: boolean default: false example: true 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 DefaultChannelGroup: type: object description: 'Dictionary containing details of a default channel group. ' additionalProperties: false properties: name: type: string description: 'Name of the default channel group. ' description: type: string description: 'Description of the default channel group. ' id: type: integer description: 'The ID of the default channel group. ' streams: type: array description: 'An array of IDs of all the channels in the default stream group. **Changes**: Before Zulip 10.0 (feature level 330), we sent array of dictionaries where each dictionary contained details about a single stream in the default stream group. ' items: type: integer FolderId: type: integer nullable: true description: 'The ID of the folder to which the channel belongs. Is `null` if channel does not belong to any folder. **Changes**: New in Zulip 11.0 (feature level 389). ' UserStatus: 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 enum: - unicode_emoji - realm_emoji - zulip_extra_emoji description: "If present, a string indicating the type of emoji. Each emoji\n`reaction_type` has an independent namespace for values of `emoji_code`.\n\nMust be one of the following values:\n\n- `unicode_emoji` : In this namespace, `emoji_code` will be a\n dash-separated hex encoding of the sequence of Unicode codepoints\n that define this emoji in the Unicode specification.\n\n- `realm_emoji` : In this namespace, `emoji_code` will be the ID of\n the uploaded [custom emoji](/help/custom-emoji).\n\n- `zulip_extra_emoji` : These are special emoji included with Zulip.\n In this namespace, `emoji_code` will be the name of the emoji (e.g.\n \"zulip\").\n\n**Changes**: New in Zulip 5.0 (feature level 86).\n" CanCreateTopicGroup: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value][setting-values] defining the set of users who have permission to create a new topic in this channel. Note that using this permission requires also having permission to send messages in the channel. Note that this must be the `role:everyone` [system group][system-groups] for [private channels with protected history][private-channels]. **Changes**: New in Zulip 12.0 (feature level 441). Previously, if you could send messages in a channel, you could create topics in the channel. [setting-values]: /api/group-setting-values [private-channels]: /help/channel-permissions/#private-channels [system-groups]: /api/group-setting-values#system-groups ' RealmExport: type: object additionalProperties: false description: 'Object containing details about a [data export](/help/export-your-organization). ' properties: id: type: integer description: 'The ID of the data export. ' acting_user_id: type: integer description: 'The ID of the user who created the data export. ' export_time: type: number description: 'The UNIX timestamp of when the data export was started. ' deleted_timestamp: type: number nullable: true description: 'The UNIX timestamp of when the data export was deleted. Will be `null` if the data export has not been deleted. ' failed_timestamp: type: number nullable: true description: 'The UNIX timestamp of when the data export failed. Will be `null` if the data export succeeded, or if it''s still being generated. ' export_url: type: string nullable: true description: 'The URL to download the generated data export. Will be `null` if the data export failed, or if it''s still being generated. ' pending: type: boolean description: 'Whether the data export is pending, which indicates it is still being generated, or if it succeeded, failed or was deleted before being generated. Depending on the size of the organization, it can take anywhere from seconds to an hour to generate the data export. ' export_type: type: string enum: - public - full_with_consent - full_without_consent description: "Whether the data export is public, full with consent, or full without consent.\n\n- `public` = Public data export.\n- `full_with_consent` = Public and private data export (with consent), which includes private data\n for users who have granted consent.\n- `full_without_consent` = All public and private data, which includes private data for all users.\n\n**Changes**: Zulip 12.0 (feature level 449) changed the type of\nthis field from int to string with `1` being replaced by `public` and\n`2` being replaced by `full_with_consent`. The option `full_without_consent`\nwas added for full exports without member consent.\n\n**Changes**: New in Zulip 10.0 (feature level 304). Previously,\nthe export type was not included in these objects because only\npublic data exports could be created or listed via the API or UI.\n" SavedSnippet: type: object description: 'Object containing the details of the saved snippet. ' additionalProperties: false properties: id: type: integer description: 'The unique ID of the saved snippet. ' title: type: string description: 'The title of the saved snippet. ' content: type: string description: 'The content of the saved snippet in [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format. Clients should insert this content into a message when using a saved snippet. ' date_created: type: integer description: 'The UNIX timestamp for when the saved snippet was created, in UTC seconds. ' JsonSuccess: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} example: msg: '' result: success Attachment: 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. **Changes**: Before Zulip 12.0 (feature level 443), this value was milliseconds since the epoch, not seconds. Changed in Zulip 3.0 (feature level 22). This field was previously a floating point number. ' message_ids: type: array description: 'Array containing the IDs of messages that reference 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. **Changes**: In Zulip 12.0 (feature level 472), this replaced the previous `messages` field, which was an array of objects containing both `id` and `date_sent` properties. ' items: type: integer CanMoveMessagesWithinChannelGroup: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value][setting-values] defining the set of users who have permission to move messages within this channel. Note that a user must [have content access](/help/channel-permissions) to a channel in order to move messages within the channel. Channel administrators and users present in the organization-level `can_move_messages_between_topics_group` setting can always move messages within the channel if they [have content access](/help/channel-permissions) to the channel. **Changes**: New in Zulip 11.0 (feature level 396). Prior to this change, only the users in `can_move_messages_between_topics_group` were able move messages between topics of a channel. [setting-values]: /api/group-setting-values ' BasicBot: allOf: - $ref: '#/components/schemas/BasicBotBase' - additionalProperties: false properties: user_id: {} default_sending_stream: nullable: true default_events_register_stream: nullable: true default_all_public_streams: {} services: {} TopicsPolicy: type: string enum: - inherit - allow_empty_topic - disable_empty_topic - empty_topic_only example: inherit description: "Whether [named topics](/help/introduction-to-topics) and the empty\ntopic (i.e., [\"general chat\" topic](/help/general-chat-topic))\nare enabled in this channel.\n\n- `\"inherit\"`: Messages can be sent to named topics in this channel,\n and the [organization-level `realm_topics_policy`][realm-topics-policy]\n is used for whether messages can be sent to the empty topic in this\n channel.\n- `\"allow_empty_topic\"`: Messages can be sent to both named topics and\n the empty topic in this channel.\n- `\"disable_empty_topic\"`: Messages can be sent to named topics in this\n channel, but the empty topic is disabled.\n- `\"empty_topic_only\"`: Messages can be sent to the empty topic in this\n channel, but named topics are disabled. See [\"general chat\"\n channels](/help/general-chat-channels).\n\nThe `\"empty_topic_only\"` policy can only be set if all existing messages\nin the channel are already in the empty topic.\n\nWhen creating a new channel, if the `topics_policy` is not specified, the\n`\"inherit\"` option will be set.\n\n**Changes**: In Zulip 11.0 (feature level 404), the `\"empty_topic_only\"`\noption was added.\n\nNew in Zulip 11.0 (feature level 392).\n\n[realm-topics-policy]: /help/require-topics#set-the-default-general-chat-topic-configuration\n" CanSubscribeGroup: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value][setting-values] defining the set of users who have permission to subscribe themselves to this channel. Everyone, excluding guests, can subscribe to any public channel irrespective of this setting. Users in this group can subscribe to a private channel as well. Note that a user must [have content access](/help/channel-permissions) to a channel and permission to administer the channel in order to modify this setting. **Changes**: New in Zulip 10.0 (feature level 357). [setting-values]: /api/group-setting-values ' CanMoveMessagesOutOfChannelGroup: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value][setting-values] defining the set of users who have permission to move messages out of this channel. Note that a user must [have content access](/help/channel-permissions) to a channel in order to move messages out of the channel. Channel administrators and users present in the organization-level `can_move_messages_between_channels_group` setting can always move messages out of the channel if they [have content access](/help/channel-permissions) to the channel. **Changes**: New in Zulip 11.0 (feature level 396). Prior to this change, only the users in `can_move_messages_between_channels_group` were able move messages between channels. [setting-values]: /api/group-setting-values ' UserDeactivatedError: allOf: - $ref: '#/components/schemas/CodedError' - example: code: USER_DEACTIVATED msg: Account is deactivated result: error description: '### User account deactivated A typical failed json response for when user''s account is deactivated. **Changes**: As of Zulip 5.0 (feature level 76), these errors use the HTTP 401 status code. Before this feature level, they used the HTTP 403 status code. ' NavigationView: type: object description: 'Represents a user''s personal configuration for a specific navigation view (displayed most visibly at the top of the web application''s left sidebar). Navigation views can be either an override to the default behavior of a built-in view, or a custom view. **Changes**: New in Zulip 11.0 (feature level 390). ' additionalProperties: false required: - fragment - is_pinned properties: fragment: type: string description: 'A unique identifier for the view, used to determine navigation behavior when clicked. Clients should use this value to navigate to the corresponding URL hash. ' example: narrow/is/alerted is_pinned: type: boolean description: 'Determines whether the view appears directly in the sidebar or is hidden in the "More Views" menu. - `true` - Pinned and visible in the sidebar. - `false` - Hidden and accessible via the "More Views" menu. ' example: true name: type: string nullable: true description: 'The user-facing name for custom navigation views. Omit this field for built-in views. ' example: Alert Words 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**: Paragraph - **3**: Dropdown - **4**: Date - **5**: Link - **6**: Users - **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 (Dropdown) and 7 (External account) support storing additional configuration for the field type in the `field_data` attribute. For field type 3 (Dropdown), 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. Must be false for `Users` [profile field types](/help/custom-profile-fields#profile-field-types). This field is only included when its value is `true`. **Changes**: Before Zulip 12.0 (feature level 476), the "Paragraph" field type was not supported. New in Zulip 6.0 (feature level 146). ' default: false required: type: boolean description: 'Whether an organization administrator has configured this profile field as required. Because the required property is mutable, clients cannot assume that a required custom profile field has a value. The Zulip web application displays a prominent banner to any user who has not set a value for a required field. **Changes**: New in Zulip 9.0 (feature level 244). ' editable_by_user: type: boolean description: 'Whether regular users can edit this profile field on their own account. Note that organization administrators can edit custom profile fields for any user regardless of this setting. **Changes**: New in Zulip 10.0 (feature level 296). ' default: true use_for_user_matching: type: boolean description: 'Whether this custom profile field should be used to match users in typeahead suggestions. Only allowed for Short Text and External Account [profile field types](/help/custom-profile-fields#profile-field-types). This field is only included when its value is `true`. **Changes**: New in Zulip 12.0 (feature level 455). ' default: false required: - id - type - order - name - hint - required - editable_by_user CanSendMessageGroup: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value][setting-values] defining the set of users who have permission to post in this channel. Note that a user must have metadata access to a channel and permission to administer the channel in order to modify this setting. Note that using this permission to send a message to a new topic requires also having permission to create new topics in the channel. **Changes**: New in Zulip 10.0 (feature level 333). Previously `stream_post_policy` field used to control the permission to post in the channel. [setting-values]: /api/group-setting-values ' 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_template: type: string description: 'The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html) compliant URL template for the playground. The template contains exactly one variable named `code`, which determines how the extracted code should be substituted in the playground URL. **Changes**: New in Zulip 8.0 (feature level 196). This replaced the `url_prefix` parameter, which was used to construct URLs by just concatenating url_prefix and code. ' 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). ' JsonSuccessBase: description: '**Changes**: As of Zulip 7.0 (feature level 167), if any parameters sent in the request are not supported by this endpoint, a successful JSON response will include an [`ignored_parameters_unsupported`][ignored_params] array. A typical successful JSON response may look like: [ignored_params]: /api/rest-error-handling#ignored-parameters ' allOf: - $ref: '#/components/schemas/JsonResponseBase' - required: - result - msg properties: result: enum: - success msg: type: string ignored_parameters_unsupported: $ref: '#/components/schemas/IgnoredParametersUnsupported' EventIdSchema: type: integer description: 'The ID of the event. Events appear in increasing order but may not be consecutive. ' RateLimitedError: allOf: - $ref: '#/components/schemas/CodedErrorBase' - additionalProperties: false description: '### Rate limit exceeded A typical failed JSON response for when a rate limit is exceeded. Zulip sets a few [HTTP response headers][rate-limit-headers] to help with preventing rate limit errors. The value of `retry-after` in the response indicates how many seconds the client must wait before making additional requests. **Changes**: Before Zulip 4.0 (feature level 36), the `code` key was not present in rate limit errors. [rate-limit-headers]: /api/http-headers#rate-limiting-response-headers ' properties: result: {} msg: {} code: {} retry-after: type: integer description: 'How many seconds the client must wait before making additional requests. ' example: code: RATE_LIMIT_HIT msg: API usage exceeded rate limit result: error retry-after: 28.706807374954224 BasicBotBase: type: object properties: user_id: type: integer description: 'The user ID of the bot. ' default_sending_stream: type: string nullable: true description: 'The default sending channel of the bot. If `null`, the bot doesn''t have a default sending channel. ' default_events_register_stream: type: string nullable: true description: 'The default channel for which the bot receives events/register data. If `null`, the bot doesn''t have such a default channel. ' default_all_public_streams: type: boolean description: 'Whether the bot can send messages to all channels by default. ' services: type: array description: 'An array containing extra configuration fields only relevant for outgoing webhook bots and embedded bots. This 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 with extra configuration details for the bot. The fields in the object depend on the type of bot. ' oneOf: - type: object additionalProperties: false description: 'When the bot is an outgoing webhook. ' 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: 'An 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/BotConfiguration' WebhookUrlOption: type: array description: 'An array of optional URL parameter options for the incoming webhook integration. In the web app, these are used when [generating a URL for an integration](/help/generate-integration-url). **Changes**: Before Zulip 12.0 (feature level 485), `input_type` was named `validator`. New in Zulip 11.0 (feature level 403). Previously, these optional URL parameter options were included in the `config_options` object. ' items: type: object additionalProperties: false properties: key: type: string description: 'The name of the URL parameter. ' label: type: string description: 'The label used for the input field in the UI. ' input_type: type: string description: 'The type of input field this URL parameter maps to in the UI. ' 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 enum: - unicode_emoji - realm_emoji - zulip_extra_emoji description: "A string indicating the type of emoji. Each emoji `reaction_type`\nhas an independent namespace for values of `emoji_code`.\n\nMust be one of the following values:\n\n- `unicode_emoji` : In this namespace, `emoji_code` will be a\n dash-separated hex encoding of the sequence of Unicode codepoints\n that define this emoji in the Unicode specification.\n\n- `realm_emoji` : In this namespace, `emoji_code` will be the ID of\n the uploaded [custom emoji](/help/custom-emoji).\n\n- `zulip_extra_emoji` : These are special emoji included with Zulip.\n In this namespace, `emoji_code` will be the name of the emoji (e.g.\n \"zulip\").\n" CanRemoveSubscribersGroup: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value][setting-values] defining the set of users who have permission to remove subscribers from this channel. Organization administrators can unsubscribe others from a channel as though they were in this group without being explicitly listed here. Note that a user must have metadata access to a channel and permission to administer the channel in order to modify this setting. **Changes**: Prior to Zulip 10.0 (feature level 349), channel administrators could not unsubscribe other users if they were not an organization administrator or part of `can_remove_subscribers_group`. Realm administrators were not allowed to unsubscribe other users from a private channel if they were not subscribed to that channel. Prior to Zulip 10.0 (feature level 320), this value was always the integer ID of a system group. Before Zulip 8.0 (feature level 197), the `can_remove_subscribers_group` setting was named `can_remove_subscribers_group_id`. New in Zulip 6.0 (feature level 142). [setting-values]: /api/group-setting-values ' ScheduledMessageBase: type: object description: 'Object containing details of the scheduled message. ' properties: scheduled_message_id: type: integer description: 'The unique ID of the scheduled message, which can be used to modify or delete the scheduled message. This is different from the unique ID that the message will have after it is sent. ' type: type: string description: 'The type of the scheduled message. Either `"stream"` or `"private"`. ' enum: - stream - private to: oneOf: - type: integer - type: array items: type: integer description: 'The scheduled message''s tentative target audience. For channel messages, it will be the unique ID of the target channel. For direct messages, it will be an array with the target users'' IDs. ' topic: type: string description: 'Only present if `type` is `"stream"`. The topic for the channel message. ' content: type: string description: 'The content/body of the scheduled message, in [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format. See [Markdown message formatting](/api/message-formatting) for details on Zulip''s HTML format. ' rendered_content: type: string description: 'The content/body of the scheduled message rendered in HTML. ' scheduled_delivery_timestamp: type: integer description: 'The UNIX timestamp for when the message will be sent by the server, in UTC seconds. ' example: 1595479019 failed: type: boolean description: 'Whether the server has tried to send the scheduled message and it failed to successfully send. Clients that support unscheduling and editing scheduled messages should display scheduled messages with `"failed": true` with an indicator that the server failed to send the message at the scheduled time, so that the user is aware of the failure and can get the content of the scheduled message. **Changes**: New in Zulip 7.0 (feature level 181). ' additionalProperties: false required: - scheduled_message_id - type - to - content - rendered_content - scheduled_delivery_timestamp - failed JsonResponseBase: type: object properties: result: type: string RealmDomain: type: object additionalProperties: false properties: domain: type: string description: 'The allowed domain. ' allow_subdomains: type: boolean description: 'Whether subdomains are allowed for this domain. ' required: - domain - allow_subdomains ScheduledMessage: allOf: - $ref: '#/components/schemas/ScheduledMessageBase' - additionalProperties: false properties: scheduled_message_id: {} type: {} to: {} topic: {} content: {} rendered_content: {} scheduled_delivery_timestamp: {} failed: {} CanDeleteAnyMessageGroup: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value][setting-values] defining the set of users who have permission to delete any message in the channel. Note that a user must [have content access](/help/channel-permissions) to a channel in order to delete any message in the channel. Users present in the organization-level `can_delete_any_message_group` setting can always delete any message in the channel if they [have content access](/help/channel-permissions) to that channel. **Changes**: New in Zulip 11.0 (feature level 407). Prior to this change, only the users in `can_delete_any_message_group` were able delete any message in the organization. [setting-values]: /api/group-setting-values ' 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: {} last_moved_timestamp: {} reactions: {} recipient_id: {} sender_email: {} sender_full_name: {} sender_id: {} sender_realm_str: {} stream_id: {} subject: {} submessages: {} timestamp: {} topic_links: {} type: {} Bot: allOf: - $ref: '#/components/schemas/BasicBotBase' - description: 'Object containing details of a bot. **Changes**: Removed `avatar_url`, `bot_type`, `email`, `full_name`, `is_active` and `owner_id` fields from the dictionary in Zulip 12.0 (feature level 474). Clients can get all these data from the corresponding user object. Removed `api_key` field from the dictionary in Zulip 12.0 (feature level 474). Clients now use [`GET /bots/{bot_id}/api_key`](/api/get-bot-api-key) to get api key for the bot. ' additionalProperties: false properties: user_id: {} default_sending_stream: nullable: true default_events_register_stream: nullable: true default_all_public_streams: {} services: {} 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_bot: {} bot_type: nullable: true bot_owner_id: nullable: true role: {} timezone: {} avatar_url: nullable: true avatar_version: {} is_imported_stub: {} is_deleted: {} profile_data: $ref: '#/components/schemas/ProfileData' 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. ' ChannelFolder: type: object additionalProperties: false description: 'Object containing the channel folder''s attributes. ' properties: id: type: integer description: 'The unique ID of the channel folder. ' name: type: string description: 'The name of the channel folder. ' order: type: integer description: 'This value determines in which order the channel folder should be displayed in the UI. The value is 0 indexed, and a channel folder with a lower value should be displayed before channel folders with higher values. **Changes**: New in Zulip 11.0 (feature level 414). ' date_created: type: integer nullable: true description: 'The UNIX timestamp for when the channel folder was created, in UTC seconds. ' creator_id: type: integer nullable: true description: 'The ID of the user who created the channel folder. ' description: type: string description: 'The description of the channel folder. Can be an empty string. See [Markdown message formatting](/api/message-formatting) for details on Zulip''s HTML format. ' rendered_description: type: string description: 'The description of the channel folder rendered as HTML, intended to be used for UI that displays the channel folder description. Clients 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_archived: type: boolean description: 'Whether the channel folder is archived or not. ' RealmEmoji: type: object additionalProperties: false description: 'Object containing details about an emoji. 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. ' CanDeleteOwnMessageGroup: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value][setting-values] defining the set of users who have permission to delete the messages that they have sent in the channel. [update-group-setting]: /api/group-setting-values#updating-group-setting-values Note that a user must [have content access](/help/channel-permissions) to a channel in order to delete their own message in the channel. Users with permission to delete any message in the channel and users present in the organization-level `can_delete_own_message_group` setting can always delete their own messages in the channel if they [have content access](/help/channel-permissions) to that channel. **Changes**: New in Zulip 11.0 (feature level 407). Prior to this change, only the users in the organization-level `can_delete_any_message_group` and `can_delete_own_message_group` settings were able delete their own messages in the organization. [setting-values]: /api/group-setting-values ' CodedErrorBase: allOf: - $ref: '#/components/schemas/JsonResponseBase' - required: - result - msg - code properties: result: enum: - error msg: type: string code: type: string description: 'A string that identifies the error. ' GroupSettingValue: oneOf: - type: integer description: 'The ID of the [user group](/help/user-groups) with this permission. ' - type: object additionalProperties: false properties: direct_members: description: 'The list of IDs of individual users in the collection of users with this permission. **Changes**: Prior to Zulip 10.0 (feature level 303), this list would include deactivated users who had the permission before being deactivated. ' type: array items: type: integer direct_subgroups: description: 'The list of IDs of the groups in the collection of users with this permission. ' type: array items: type: integer description: 'An object with these fields: ' 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 ' ProfileData: 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. See [Markdown message formatting](/api/message-formatting) for details on Zulip''s HTML format. ' Reminder: type: object additionalProperties: false description: 'Object containing details of the scheduled message. ' properties: reminder_id: type: integer description: 'The unique ID of the reminder, which can be used to delete the reminder. This is different from the unique ID that the message would have after being sent. ' type: type: string description: 'The type of the reminder. Always set to `"private"`. ' enum: - private to: type: array items: type: integer description: 'Contains the ID of the user who scheduled the reminder, and to which the reminder will be sent. ' content: type: string description: 'The content/body of the reminder, in [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format. See [Markdown message formatting](/api/message-formatting) for details on Zulip''s HTML format. ' rendered_content: type: string description: 'The content/body of the reminder 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 reminder and it failed to successfully send. Clients that support unscheduling reminders 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. ' reminder_target_message_id: type: integer description: 'The ID of the message that the reminder is created for. ' required: - reminder_id - type - to - content - rendered_content - scheduled_delivery_timestamp - failed - reminder_target_message_id Event_types: description: "A JSON-encoded array indicating which types of events you're interested\nin. Values that you might find useful include:\n\n- **message** (messages)\n- **subscription** (changes in your subscriptions)\n- **realm_user** (changes to users in the organization and\n their properties, such as their name).\n\nIf you do not specify this parameter, you will receive all\nevents, and have to filter out the events not relevant to\nyour client in your client code. For most applications, one\nis only interested in messages, so one specifies:\n`\"event_types\": [\"message\"]`\n\nEvent types not supported by the server are ignored, in order to simplify\nthe implementation of client apps that support multiple server versions.\n" type: array items: type: string example: - message CanAdministerChannelGroup: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value][setting-values] defining the set of users who have permission to administer this channel. Organization administrators can administer every channel as though they were in this group without being explicitly listed here. Note that a user must have metadata access to a channel and permission to administer the channel in order to modify this setting. **Changes**: Prior to Zulip 10.0 (feature level 349) a user needed to [have content access](/help/channel-permissions) to a channel in order to modify it. The exception to this rule was that organization administrators can edit channel names and descriptions without having full access to the channel. New in Zulip 10.0 (feature level 325). Prior to this change, the permission to administer channels was limited to realm administrators. [setting-values]: /api/group-setting-values ' ModernPresenceFormat: type: object description: '`{user_id}`: Presence data (modern format) for the user with the specified ID. ' additionalProperties: false properties: active_timestamp: type: integer description: 'The UNIX timestamp of the last time a client connected to Zulip reported that the user was actually present (e.g. via focusing a browser window or interacting with a computer running the desktop app). Clients should display users with a current `active_timestamp` as fully present. ' idle_timestamp: type: integer description: 'The UNIX timestamp of the last time the user had a client connected to Zulip, including idle clients where the user hasn''t interacted with the system recently. The Zulip server has no way of distinguishing whether an idle web app user is at their computer, but hasn''t interacted with the Zulip tab recently, or simply left their desktop computer on when they left. Thus, clients should display users with a current `idle_timestamp` but no current `active_timestamp` as potentially present. ' BotConfiguration: type: object description: 'A dictionary of string key/value pairs, which describe the configuration for the bot. These are usually details like API keys, and are unique to the integration/bot. Can be an empty dictionary. ' additionalProperties: description: '`{config_key}`: Description/value of the configuration data key. ' type: string UserBase: type: object description: 'A dictionary containing basic data on a given Zulip user. **Changes**: Removed `is_billing_admin` field in Zulip 10.0 (feature level 363), as it was replaced by the `can_manage_billing_group` realm setting. ' 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 when the user joined. For users imported from other applications and users created via the API, this is set to the account creation time until the user logs in for the first time, after which it is updated to that login time. For imported users, clients can use the `is_imported_stub` flag to determine how to display this field: when `is_imported_stub` is `true`, the user has not yet logged in and this value is the account creation time during import; when `is_imported_stub` is `false`, this value reflects when the user first logged in. **Changes**: Starting with Zulip 12.0 (feature level 475), this field is updated when an imported stub user or a user created via the API logs in for the first time. ' 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_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 IANA identifier of the user''s [profile time zone](/help/change-your-timezone), which is used primarily to display the user''s local time to other users. ' 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}`. ' is_imported_stub: type: boolean description: 'Indicates whether this user object is a stub account imported from another chat system. Stub accounts are used to represent the senders for imported messages. Stub accounts can be converted to regular Zulip accounts when the user starts using Zulip, preserving that imported user''s message history. **Changes**: New in Zulip 12.0 (feature level 433). ' example: false is_deleted: type: boolean description: 'A boolean specifying whether the user has been permanently deleted. Deleted users are a subset of deactivated users (`is_active=false`) who have had their account data removed. This field is only present when `true`. **Changes**: New in Zulip 12.0 (feature level 490). ' CanResolveTopicsGroup: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value][setting-values] defining the set of users who have permission to resolve topics in the channel. Users who have similar realm-level permissions can resolve topics in a channel regardless of the value of this setting. **Changes**: New in Zulip 11.0 (feature level 402). [setting-values]: /api/group-setting-values ' UserGroup: type: object additionalProperties: false description: 'Object containing the user group''s attributes. ' properties: name: type: string description: 'The name of the user group. ' date_created: type: integer nullable: true description: 'The UNIX timestamp for when the user group was created, in UTC seconds. A `null` value means the user group has no recorded date, which is often because the user group is very old, or because it was created via a data import tool or [management command][management-commands]. **Changes**: New in Zulip 10.0 (feature level 292). [management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html ' creator_id: type: integer nullable: true description: 'The ID of the user who created this user group. A `null` value means the user group has no recorded creator, which is often because the user group is very old, or because it was created via a data import tool or [management command][management-commands]. **Changes**: New in Zulip 10.0 (feature level 292). [management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html ' 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. **Changes**: Prior to Zulip 10.0 (feature level 303), this list also included deactivated users who were members of the user group before being deactivated. ' 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). ' can_add_members_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value][setting-values] defining the set of users who have permission to add members to this user group. **Changes**: New in Zulip 10.0 (feature level 305). Previously, this permission was controlled by the `can_manage_group` setting. Will be one of the following: [setting-values]: /api/group-setting-values ' can_join_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value][setting-values] defining the set of users who have permission to join this user group. **Changes**: New in Zulip 10.0 (feature level 301). Will be one of the following: [setting-values]: /api/group-setting-values ' can_leave_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value][setting-values] defining the set of users who have permission to leave this user group. **Changes**: New in Zulip 10.0 (feature level 308). Will be one of the following: [setting-values]: /api/group-setting-values ' can_manage_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value][setting-values] defining the set of users who have permission to [manage this user group][manage-user-groups]. **Changes**: New in Zulip 10.0 (feature level 283). Will be one of the following: [setting-values]: /api/group-setting-values [manage-user-groups]: /help/manage-user-groups ' can_mention_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value][setting-values] defining the set of users who have permission to [mention this user group][mentions]. **Changes**: Before Zulip 9.0 (feature level 258), this setting was always the integer form of a [group-setting value][setting-values]. Before Zulip 8.0 (feature level 198), this setting was named `can_mention_group_id`. New in Zulip 8.0 (feature level 191). Previously, groups could be mentioned only if they were not [system groups][system-groups]. Will be one of the following: [setting-values]: /api/group-setting-values [system-groups]: /api/group-setting-values#system-groups [mentions]: /help/mention-a-user-or-group ' can_remove_members_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value][setting-values] defining the set of users who have permission to remove members from this user group. **Changes**: New in Zulip 10.0 (feature level 324). Previously, this permission was controlled by the `can_manage_group` setting. Will be one of the following: [setting-values]: /api/group-setting-values ' deactivated: type: boolean description: 'Whether the user group is deactivated. Deactivated groups cannot be used as a subgroup of another group or used for any other purpose. **Changes**: New in Zulip 10.0 (feature level 290). ' EmojiReaction: allOf: - $ref: '#/components/schemas/EmojiBase' - additionalProperties: false properties: emoji_code: {} emoji_name: {} reaction_type: {} user_id: type: integer description: 'The ID of the user who added the reaction. **Changes**: New in Zulip 3.0 (feature level 2), which deprecated the `user` object. ' Subscription: type: object additionalProperties: false properties: stream_id: type: integer description: 'The unique ID of a channel. ' name: type: string description: 'The name of a channel. ' description: type: string description: 'The [description](/help/change-the-channel-description) of the channel in [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format, intended to be used to prepopulate UI for editing a channel''s description. See [Markdown message formatting](/api/message-formatting) for details on Zulip''s HTML format. See also `rendered_description`. ' rendered_description: type: string description: 'The [description](/help/change-the-channel-description) of the channel rendered as HTML, intended to be used when displaying the channel 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 channel was created, in UTC seconds. **Changes**: New in Zulip 4.0 (feature level 30). ' creator_id: type: integer nullable: true description: 'The ID of the user who created this channel. A `null` value means the channel has no recorded creator, which is often because the channel is very old, was created during realm creation or because it was created via a data import tool or [management command][management-commands]. **Changes**: New in Zulip 9.0 (feature level 254). [management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html ' invite_only: type: boolean description: 'Specifies whether the channel is private or not. Only people who have been invited can access a private channel. ' subscribers: type: array items: type: integer description: 'A list of user IDs of users who are also subscribed to a given channel. Included only if `include_subscribers` is `true`. ' partial_subscribers: type: array items: type: integer description: 'If [`include_subscribers="partial"`](/api/get-subscriptions#parameter-include_subscribers) was requested, the server may, at its discretion, send a `partial_subscribers` list rather than a `subscribers` list for channels with a large number of subscribers. The `partial_subscribers` list contains an arbitrary subset of the channel''s subscribers that is guaranteed to include all bot user subscribers as well as all users who have been active in the last 14 days, but otherwise can be chosen arbitrarily by the server. **Changes**: New in Zulip 11.0 (feature level 412). ' desktop_notifications: type: boolean nullable: true description: 'A boolean specifying whether desktop notifications are enabled for the given channel. A `null` value means the value of this setting should be inherited from the user-level default setting, `enable_stream_desktop_notifications`, for this channel. ' email_notifications: type: boolean nullable: true description: 'A boolean specifying whether email notifications are enabled for the given channel. A `null` value means the value of this setting should be inherited from the user-level default setting, `enable_stream_email_notifications`, for this channel. ' wildcard_mentions_notify: type: boolean nullable: true description: 'A boolean specifying whether wildcard mentions trigger notifications as though they were personal mentions in this channel. A `null` value means the value of this setting should be inherited from the user-level default setting, wildcard_mentions_notify, for this channel. ' push_notifications: type: boolean nullable: true description: 'A boolean specifying whether push notifications are enabled for the given channel. A `null` value means the value of this setting should be inherited from the user-level default setting, `enable_stream_push_notifications`, for this channel. ' audible_notifications: type: boolean nullable: true description: 'A boolean specifying whether audible notifications are enabled for the given channel. A `null` value means the value of this setting should be inherited from the user-level default setting, `enable_stream_audible_notifications`, for this channel. ' pin_to_top: type: boolean description: 'A boolean specifying whether the given channel has been pinned to the top. ' is_muted: type: boolean description: 'Whether the user has muted the channel. Muted channels do not count towards your total unread count and do not show up in the `Combined feed` view (previously known as `All messages`). **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 channel 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 channel. **Changes**: Deprecated in Zulip 3.0 (feature level 1). Clients should use `stream_post_policy` instead. ' is_web_public: type: boolean description: 'Whether the channel 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 channel. ' stream_post_policy: type: integer deprecated: true description: 'A deprecated representation of a superset of the users who have permission to post messages to the channel available for backwards-compatibility. Clients should use `can_send_message_group` instead. It is an enum with the following possible values, corresponding to roles/system groups: - 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**: Deprecated in Zulip 10.0 (feature level 333) and replaced by `can_send_message_group`, which supports finer resolution of configurations, resulting in this property being inaccurate following that transition. New in Zulip 3.0 (feature level 1), replacing the previous `is_announcement_only` boolean. [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 channel will be stored\nbefore being automatically deleted by the [message retention\npolicy](/help/message-retention-policy). There are two special values:\n\n- `null`, the default, means the channel will inherit the organization\n level setting.\n- `-1` encodes retaining messages in this channel forever.\n\n**Changes**: New in Zulip 3.0 (feature level 17).\n" history_public_to_subscribers: type: boolean description: 'Whether the history of the channel is public to its subscribers. Currently always true for public channels (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 channel. Intended to help clients determine whether they need to display UI like the "show all topics" widget that would suggest the channel has older history that can be accessed. Is `null` for channels with no message history. ' folder_id: $ref: '#/components/schemas/FolderId' topics_policy: $ref: '#/components/schemas/TopicsPolicy' is_recently_active: type: boolean description: 'Whether the channel has recent message activity. Clients should use this to implement [hiding inactive channels](/help/manage-inactive-channels). **Changes**: New in Zulip 10.0 (feature level 323). Previously, clients implemented the demote_inactive_streams from local message history, resulting in a choppy loading experience. ' stream_weekly_traffic: type: integer nullable: true description: 'The average number of messages sent to the channel per week, as estimated based on recent weeks, rounded to the nearest integer. If `null`, the channel was recently created and there is insufficient data to estimate the average traffic. ' can_add_subscribers_group: $ref: '#/components/schemas/ChannelCanAddSubscribersGroup' can_remove_subscribers_group: $ref: '#/components/schemas/CanRemoveSubscribersGroup' can_administer_channel_group: $ref: '#/components/schemas/CanAdministerChannelGroup' can_delete_any_message_group: $ref: '#/components/schemas/CanDeleteAnyMessageGroup' can_delete_own_message_group: $ref: '#/components/schemas/CanDeleteOwnMessageGroup' can_move_messages_out_of_channel_group: $ref: '#/components/schemas/CanMoveMessagesOutOfChannelGroup' can_move_messages_within_channel_group: $ref: '#/components/schemas/CanMoveMessagesWithinChannelGroup' can_send_message_group: $ref: '#/components/schemas/CanSendMessageGroup' can_subscribe_group: $ref: '#/components/schemas/CanSubscribeGroup' can_resolve_topics_group: $ref: '#/components/schemas/CanResolveTopicsGroup' can_create_topic_group: $ref: '#/components/schemas/CanCreateTopicGroup' is_archived: type: boolean description: 'A boolean indicating whether the channel is [archived](/help/archive-a-channel). **Changes**: New in Zulip 10.0 (feature level 315). Previously, subscriptions only included active channels. Note that some endpoints will never return archived channels unless the client declares explicit support for them via the `archived_channels` client capability. ' subscriber_count: type: number description: 'The total number of non-deactivated users (including bots) who are subscribed to the channel. Clients are responsible for updating this value using `peer_add` and `peer_remove` events. The server''s internals cannot guarantee this value is correctly synced with `peer_add` and `peer_remove` events for the channel. As a result, if a (rare) race occurs between a change in the channel''s subscribers and fetching this value, it is possible for a client that is correctly following the events protocol to end up with a permanently off-by-one error in the channel''s subscriber count. Clients are recommended to fetch full subscriber data for a channel in contexts where it is important to avoid this risk. The official web application, for example, uses this field primarily while waiting to fetch a given channel''s full subscriber list from the server. **Changes**: New in Zulip 11.0 (feature level 394). ' GroupPermissionSetting: description: 'Configuration for a group permission setting specifying the groups to which the setting can be set to and the default values for the setting. **Changes**: Removed `allow_owners_group` field in Zulip 10.0 (feature level 326), as we now support anonymous user groups. Previously, the `role:owners` system group was not offered when `allow_owners_group` was false. Removed unnecessary `id_field_name` field in Zulip 10.0 (feature level 326). Previously, this always had the value of `"{setting_name}_id"`; it was an internal implementation detail of the server not intended to be included in the API. ' additionalProperties: false type: object properties: require_system_group: type: boolean description: 'Whether the setting can only be set to a system user group. ' allow_internet_group: type: boolean description: 'Whether the setting can be set to `role:internet` system group. ' allow_nobody_group: type: boolean description: 'Whether the setting can be set to `role:nobody` system group. ' allow_everyone_group: type: boolean description: 'Whether the setting can be set to `role:everyone` system group. If false, guest users cannot exercise this permission even if they are part of the [group-setting value](/api/group-setting-values) for this setting. ' default_group_name: type: string description: "Name of the default system group for the setting.\n\nFor some channel settings, this can also be `channel_creator`.\nIn that case:\n\n- If the channel's [`creator_id`][channel-response] is not `null`, default for the\n setting is an anonymous group with the channel creator as\n the only member.\n- If the channel's [`creator_id`][channel-response] is `null`, default for the setting\n is `role:nobody` system group.\n\n**Changes**: In Zulip 12.0 (feature level 427), renamed\n`stream_creator_or_nobody` value to `channel_creator`.\n\n[channel-response]: /api/get-stream-by-id#response\n" default_for_system_groups: type: string nullable: true description: 'Name of the default group for the setting for system groups. This is non-null only for group-level settings. ' allowed_system_groups: type: array description: 'An array of names of system groups to which the setting can be set to. If the list is empty, the setting can be set to system groups based on the other boolean fields. **Changes**: New in Zulip 8.0 (feature level 225). ' items: type: string LegacyPresenceFormat: 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. ' BasicChannelBase: type: object description: 'Object containing basic details about the channel. ' properties: stream_id: type: integer description: 'The unique ID of the channel. ' name: type: string description: 'The name of the channel. ' is_archived: type: boolean description: 'A boolean indicating whether the channel is [archived](/help/archive-a-channel). **Changes**: New in Zulip 10.0 (feature level 315). Previously, this endpoint never returned archived channels. ' description: type: string description: 'The short description of the channel in [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format, intended to be used to prepopulate UI for editing a channel''s description. See [Markdown message formatting](/api/message-formatting) for details on Zulip''s HTML format. ' date_created: type: integer description: 'The UNIX timestamp for when the channel was created, in UTC seconds. **Changes**: New in Zulip 4.0 (feature level 30). ' creator_id: type: integer nullable: true description: 'The ID of the user who created this channel. A `null` value means the channel has no recorded creator, which is often because the channel is very old, was created during realm creation or because it was created via a data import tool or [management command][management-commands]. **Changes**: New in Zulip 9.0 (feature level 254). [management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html ' invite_only: type: boolean description: 'Specifies whether the channel is private or not. Only people who have been invited can access a private channel. ' rendered_description: type: string description: 'The short description of the channel rendered as HTML, intended to be used when displaying the channel 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 channel has been configured to allow unauthenticated access to its message history from the web. **Changes**: New in Zulip 2.1.0. ' stream_post_policy: type: integer deprecated: true description: 'A deprecated representation of a superset of the users who have permission to post messages to the channel available for backwards-compatibility. Clients should use `can_send_message_group` instead. It is an enum with the following possible values, corresponding to roles/system groups: - 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**: Deprecated in Zulip 10.0 (feature level 333) and replaced by `can_send_message_group`, which supports finer resolution of configurations, resulting in this property being inaccurate following that transition. New in Zulip 3.0 (feature level 1), replacing the previous `is_announcement_only` boolean. [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 channel will be stored\nbefore being automatically deleted by the [message retention\npolicy](/help/message-retention-policy). There are two special values:\n\n- `null`, the default, means the channel will inherit the organization\n level setting.\n- `-1` encodes retaining messages in this channel forever.\n\n**Changes**: New in Zulip 3.0 (feature level 17).\n" history_public_to_subscribers: type: boolean description: 'Whether the history of the channel is public to its subscribers. Currently always true for public channels (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. ' topics_policy: $ref: '#/components/schemas/TopicsPolicy' first_message_id: type: integer nullable: true description: 'The ID of the first message in the channel. Intended to help clients determine whether they need to display UI like the "show all topics" widget that would suggest the channel has older history that can be accessed. Is `null` for channels with no message history. **Changes**: New in Zulip 2.1.0. ' folder_id: $ref: '#/components/schemas/FolderId' is_recently_active: type: boolean description: 'Whether the channel has recent message activity. Clients should use this to implement [hide inactive channels](/help/manage-inactive-channels) if `demote_inactive_streams` is enabled. **Changes**: New in Zulip 10.0 (feature level 323). Previously, clients implemented the demote_inactive_streams from local message history, resulting in a choppy loading experience. ' is_announcement_only: type: boolean deprecated: true description: 'Whether the given channel is announcement only or not. **Changes**: Deprecated in Zulip 3.0 (feature level 1). Clients should use `stream_post_policy` instead. ' can_add_subscribers_group: $ref: '#/components/schemas/ChannelCanAddSubscribersGroup' can_remove_subscribers_group: $ref: '#/components/schemas/CanRemoveSubscribersGroup' can_administer_channel_group: $ref: '#/components/schemas/CanAdministerChannelGroup' can_delete_any_message_group: $ref: '#/components/schemas/CanDeleteAnyMessageGroup' can_delete_own_message_group: $ref: '#/components/schemas/CanDeleteOwnMessageGroup' can_move_messages_out_of_channel_group: $ref: '#/components/schemas/CanMoveMessagesOutOfChannelGroup' can_move_messages_within_channel_group: $ref: '#/components/schemas/CanMoveMessagesWithinChannelGroup' can_send_message_group: $ref: '#/components/schemas/CanSendMessageGroup' can_subscribe_group: $ref: '#/components/schemas/CanSubscribeGroup' can_resolve_topics_group: $ref: '#/components/schemas/CanResolveTopicsGroup' can_create_topic_group: $ref: '#/components/schemas/CanCreateTopicGroup' subscriber_count: type: number description: 'The total number of non-deactivated users (including bots) who are subscribed to the channel. Clients are responsible for updating this value using `peer_add` and `peer_remove` events. The server''s internals cannot guarantee this value is correctly synced with `peer_add` and `peer_remove` events for the channel. As a result, if a (rare) race occurs between a change in the channel''s subscribers and fetching this value, it is possible for a client that is correctly following the events protocol to end up with a permanently off-by-one error in the channel''s subscriber count. Clients are recommended to fetch full subscriber data for a channel in contexts where it is important to avoid this risk. The official web application, for example, uses this field primarily while waiting to fetch a given channel''s full subscriber list from the server. **Changes**: New in Zulip 11.0 (feature level 394). ' OnboardingStep: type: object additionalProperties: false description: 'Dictionary containing details of a single onboarding step. ' properties: type: type: string description: 'The type of the onboarding step. Valid value is `"one_time_notice"`. **Changes**: Removed type `"hotspot"` in Zulip 9.0 (feature level 259). New in Zulip 8.0 (feature level 233). ' name: type: string description: 'The name of the onboarding step. ' parameters: 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 responses: SimpleSuccess: description: Success. content: application/json: schema: $ref: '#/components/schemas/JsonSuccess' securitySchemes: BasicAuth: type: http scheme: basic description: 'Basic authentication, with the user''s email as the username, and the API key as the password. The API key can be fetched using the `/fetch_api_key` or `/dev_fetch_api_key` endpoints. '