Register an event queue

POST https://z.labs.greyorange.com/api/v1/register

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 to request events from the Zulip server using long-polling.

The server will queue events for up to 10 minutes of inactivity. After 10 minutes, your event queue will be garbage-collected. The server will send heartbeat events every minute, which makes it easy to implement a robust client that does not miss events unless the client loses network connectivity with the Zulip server for 10 minutes or longer.

Once the server garbage-collects your event queue, the server will return an error with a code of BAD_EVENT_QUEUE_ID if you try to fetch events from the event queue. Your software will need to handle that error condition by re-initializing itself (e.g. this is what triggers your browser reloading the Zulip web app when your laptop comes back online after being offline for more than 10 minutes).

When prototyping with this API, we recommend first calling register with no event_types parameter to see all the available data from all supported event types. Before using your client in production, you should set appropriate event_types and fetch_event_types filters so that your client only requests the data it needs. A few minutes doing this often saves 90% of the total bandwidth and other resources consumed by a client using this API.

See the events system developer documentation 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.

Usage examples

#!/usr/bin/env python3

import zulip

# Pass the path to your zuliprc file here.
client = zulip.Client(config_file="~/zuliprc")

# Register the queue
result = client.register(
    event_types=["message", "realm_emoji"],
)
print(result)

More examples and documentation can be found here.

const zulipInit = require("zulip-js");

// Pass the path to your zuliprc file here.
const config = { zuliprc: "zuliprc" };

(async () => {
    const client = await zulipInit(config);

    // Register a queue
    const params = {
        event_types: ["message"],
    };

    console.log(await client.queues.register(params));
})();

curl -sSX POST https://z.labs.greyorange.com/api/v1/register \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode 'event_types=["message"]'

Parameters

apply_markdown boolean optional

Example: true

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)

Defaults to false.


client_gravatar boolean optional

Example: false

Whether the client supports computing gravatars URLs. If enabled, avatar_url will be included in the response only if there is a Zulip avatar, and will be null for users who are using gravatar as their avatar. This option significantly reduces the compressed size of user data, since gravatar URLs are long, random strings and thus do not compress well. The client_gravatar field is set to true if clients can compute their own gravatars.

Changes: The default value of this parameter was false prior to Zulip 5.0 (feature level 92).

Defaults to true.


slim_presence boolean optional

Example: true

Setting this to true will make presence dictionaries be keyed by user_id instead of email.

Changes: New in Zulip 3.0 (Unstable with no feature level yet).

Defaults to false.


event_types (string)[] optional

Example: ["message"]

A JSON-encoded array indicating which types of events you're interested in. Values that you might find useful include:

  • message (messages)
  • subscription (changes in your subscriptions)
  • realm_user (changes to users in the organization and their properties, such as their name).

If you do not specify this parameter, you will receive all events, and have to filter out the events not relevant to your client in your client code. For most applications, one is only interested in messages, so one specifies: event_types=['message']

Event types not supported by the server are ignored, in order to simplify the implementation of client apps that support multiple server versions.


all_public_streams boolean optional

Example: true

Whether you would like to request message events from all public streams. Useful for workflow bots that you'd like to see all new messages sent to public streams. (You can also subscribe the user to private streams).

Defaults to false.


include_subscribers boolean optional

Example: true

Whether each returned stream object should include a subscribers field containing a list of the user IDs of its subscribers.

(This may be significantly slower in organizations with thousands of users subscribed to many streams.)

Changes: New in Zulip 2.1.0.

Defaults to false.


client_capabilities object optional

Example: {"notification_settings_null": true}

Dictionary containing details on features the client supports that are relevant to the format of responses sent by the server.

  • notification_settings_null: Boolean for whether the client can handle the current API with null values for stream-level notification settings (which means the stream is not customized and should inherit the user's global notification settings for stream messages).
    New in Zulip 2.1.0; in earlier Zulip releases, stream-level notification settings were simple booleans.

  • bulk_message_deletion: Boolean for whether the client's handler for the delete_message event type has been updated to process the new bulk format (with a message_ids, rather than a singleton message_id). Otherwise, the server will send delete_message events in a loop.
    New in Zulip 3.0 (feature level 13). This capability is for backwards-compatibility; it will be required in a future server release.

  • user_avatar_url_field_optional: Boolean for whether the client required avatar URLs for all users, or supports using GET /avatar/{user_id} to access user avatars. If the client has this capability, the server may skip sending a avatar_url field in the realm_user at its sole discretion to optimize network performance. This is an important optimization in organizations with 10,000s of users.
    New in Zulip 3.0 (feature level 18).

  • stream_typing_notifications: Boolean for whether the client supports stream typing notifications.
    New in Zulip 4.0 (feature level 58). This capability is for backwards-compatibility; it will be required in a future server release.

  • user_settings_object: Boolean for whether the client supports the modern user_settings event type. If False, the server will additionally send the legacy update_display_settings and update_global_notifications event types for backwards-compatibility with clients that predate this API migration.

    Because the feature level 89 API changes were merged together, clients can safely make a request with this client capability and requesting all of the user_settings, update_display_settings, and update_global_notifications event types, and get exactly one copy of settings data on any server version. (And then use the zulip_feature_level in the /register response or the presence/absence of a user_settings key to determine where to look).
    New in Zulip 5.0 (feature level 89). This capability is for backwards-compatibility; it will be removed in a future server release.


fetch_event_types (string)[] optional

Example: ["message"]

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 None.

Event types not supported by the server are ignored, in order to simplify the implementation of client apps that support multiple server versions.


narrow ((string)[])[] optional

Example: [["stream", "Denmark"]]

A JSON-encoded array of arrays of length 2 indicating the narrow for which you'd like to receive events for. For instance, to receive events for the stream Denmark, you would specify narrow=[['stream', 'Denmark']]. Another example is narrow=[['is', 'private']] for private messages. Default is [].


Response

Return values

  • queue_id: string

    The ID of the queue that has been allocated for your client.

  • last_event_id: integer

    The initial value of last_event_id to pass to GET /api/v1/events.

  • zulip_feature_level: integer

    The server's current Zulip feature level.

  • zulip_version: string

    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, it will be a Git reference to the commit, like 5.0-dev-1650-gc3fd37755f.

  • zulip_merge_base: string

    The git merge-base between zulip_verson and official branches in the public Zulip server and web app repository, 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: (string)[]

    Present if alert_words is present in fetch_event_types.

    An array of strings, each an alert word that the current user has configured.

  • custom_profile_fields: (object)[]

    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' full profiles.

    • id: integer

      The ID of the custom profile field. This will be referenced in custom the profile fields section of user objects.

    • type: integer

      An integer indicating the type of the custom profile field, which determines how it is configured and displayed to users.

      See the Add custom profile fields article for details on what each type means.

      • 1: Short text
      • 2: Long text
      • 3: List of options
      • 4: Date picker
      • 5: Link
      • 6: Person picker
      • 7: External account
    • order: integer

      Custom profile fields are displayed in both settings UI and UI showing users' profiles in increasing order.

    • name: string

      The name of the custom profile field.

    • hint: string

      The help text to be displayed for the custom profile field in user-facing settings UI for configuring custom profile fields.

    • field_data: string

      Field types 3 (List of options) and 7 (External account) support storing additional configuration for the field type in the field_data attribute.

      For field type 3 (List of options), this attribute is a JSON dictionary defining the choices and the order they will be displayed in the dropdown UI for individual users to select an option.

      The interface for field type 7 is not yet stabilized.

  • custom_profile_field_types: object

    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 a 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.

    • {FIELD_TYPE}: object

      Dictionary which contains the details of the field type with the field type as the name of the property itself. The current supported field types are as follows:

      • SHORT_TEXT
      • LONG_TEXT
      • DATE for date-based fields.
      • CHOICE for a list of options.
      • URL for links.
      • EXTERNAL_ACCOUNT for external accounts.
      • USER for selecting a user for the field.

      • id: integer

        The id of the custom profile field type.

      • name: string

        The name of the custom profile field type.

  • demo_organization_scheduled_deletion_date: integer

    Present if the realm is a demo organization.

    The UNIX timestamp (UTC) when the demo organization will be automatically deleted. Clients should use this to display a prominent warning to the user that the organization will be deleted at the indicated time.

    Changes: New in Zulip 5.0 (feature level 94).

  • drafts: (object)[]

    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.

    • id: integer

      The unique ID of the draft. It will only used whenever the drafts are fetched. This field should not be specified when the draft is being created or edited.

    • type: string

      The type of the draft. Either unaddressed (empty string), "stream", or "private" (for PMs and private group messages).

    • to: (integer)[]

      An array of the tentative target audience IDs. For "stream" messages, this should contain exactly 1 ID, the ID of the target stream. For private messages, this should be an array of target user IDs. For unaddressed drafts, this is ignored, and clients should send an empty array.

    • topic: string

      For stream message drafts, the tentative topic name. For private or unaddressed messages, this will be ignored and should ideally be the empty string. Should not contain null bytes.

    • content: string

      The body of the draft. Should not contain null bytes.

    • timestamp: number

      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.

  • hotspots: (object)[]

    Present if hotspots is present in fetch_event_types.

    An array of dictionaries, where each dictionary contains details about a single onboarding hotspot that should be shown to new users.

    We expect that only official Zulip clients will interact with these data.

    • delay: number

      The delay after which the user should be shown the hotspot.

    • name: string

      The name of the hotspot.

    • title: string

      The title of the hotspot, as will be displayed to the user.

    • description: string

      The description of the hotspot, as will be displayed to the user.

  • max_message_id: integer

    Present if message is present in fetch_event_types.

    The highest message ID among all messages the user has received as of the moment of this request.

    Deprecated: This field may be removed in future versions as it no longer has a clear purpose. Clients wishing to fetch the latest messages should pass anchor="latest" to GET /messages.

  • max_stream_name_length: integer

    Present if realm is present in fetch_event_types.

    The maximum allowed length for a stream name. Clients should use these properties rather than hardcoding field sizes, as they may change in a future Zulip release.

    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 value 60.

  • max_stream_description_length: integer

    Present if realm is present in fetch_event_types.

    The maximum allowed length for a stream description. Clients should use these properties rather than hardcoding field sizes, as they may change in a future Zulip release.

    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 value 1024.

  • max_topic_length: integer

    Present if realm is present in fetch_event_types.

    The maximum allowed length for a topic. Clients should use these properties rather than hardcoding field sizes, as they may change in a future Zulip release.

    Changes: New in Zulip 4.0 (feature level 53). Previously, this always had value 60.

  • max_message_length: integer

    Present if realm is present in fetch_event_types.

    The maximum allowed length for a message. Clients should use these properties rather than hardcoding field sizes, as they may change in a future Zulip release.

    Changes: New in Zulip 4.0 (feature level 53). Previously, this always had value 10000.

  • muted_topics: ((string | integer)[])[]

    Present if muted_topics is present in fetch_event_types.

    Array of tuples, where each tuple describes a muted topic. The first element of tuple is the stream name in which the topic has to be muted, the second element is the topic name to be muted and the third element is an integer UNIX timestamp representing when the topic was muted.

  • muted_users: (object)[]

    Present if muted_users is present in fetch_event_types.

    A list of dictionaries where each dictionary describes a muted user.

    Changes: New in Zulip 4.0 (feature level 48).

    • id: integer

      The ID of the muted user.

    • timestamp: integer

      An integer UNIX timestamp representing when the user was muted.

  • presences: object

    Present if presence is present in fetch_event_types.

    A dictionary where each entry describes the presence details for another user in the Zulip organization.

    Users who have been offline for multiple weeks may not appear in this object.

    • {user_id} or {user_email}: object

      Depending on the value of slim_presence. Each entry contains the details of the presence of the user with the specific id or email.

      • client: string

        The client's platform name.

      • status: string

        The status of the user on this client. It is either idle or active.

      • timestamp: integer

        The UNIX timestamp of when this client sent the user's presence to the server with the precision of a second.

      • pushable: boolean

        Whether the client is capable of showing mobile/push notifications to the user.

  • server_timestamp: number

    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: (object)[]

    Present if realm_domains is present in fetch_event_types.

    An array of dictionaries where each dictionary describes a domain within which users can join the organization without and invitation.

    • domain: string

      The new allowed domain.

    • allow_subdomains: boolean

      Whether subdomains are allowed for this domain.

  • realm_emoji: object | (integer)[]

    Present if realm_emoji is present in fetch_event_types.

    An array of dictionaries where each dictionary describes a custom emoji that has been uploaded in this Zulip organization.

  • realm_linkifiers: (object)[]

    Present if realm_linkifiers is present in fetch_event_types.

    Array of objects where each object describes a single linkifier.

    Changes: New in Zulip 4.0 (feature level 54). Clients can access these data on older server versions via the previous realm_filters key.

    • pattern: string

      The string regex pattern which represents the pattern that should be linkified on matching.

    • url_format: string

      The URL with which the pattern matching string should be linkified.

    • id: integer

      The ID of the linkifier.

  • realm_filters: ((integer | string)[])[]

    Legacy property for linkifiers. Present if realm_filters is present in fetch_event_types.

    An array of tuples (fixed-length arrays) where each tuple describes a single linkifier. The first element of the tuple is a string regex pattern which represents the pattern that should be linkified on matching.

    The second element is the URL with which the pattern matching string should be linkified with and the third element is the id of the realm filter.

    Changes: Deprecated in Zulip 4.0 (feature level 54), replaced by the realm_linkifiers key instead.

  • realm_playgrounds: (object)[]

    Present if realm_playgrounds is present in fetch_event_types.

    An array of dictionaries where each dictionary describes a code playground configured for this Zulip organization.

    Changes: New in Zulip 4.0 (feature level 49).

    • id: integer

      The unique ID for the realm playground.

    • name: string

      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: string

      The name of the Pygments language lexer for that programming language.

    • url_prefix: string

      The url prefix for the playground.

  • realm_user_groups: (object)[]

    Present if realm_user_groups is present in fetch_event_types.

    An array of dictionaries where each dictionary describes a user group in the Zulip organization.

    • name: string

      The name of the user group.

    • description: string

      The description of the user group.

    • members: (integer)[]

      Array containing the id of the users who are members of this user group.

    • id: integer

      The ID of the user group.

    • is_system_group: boolean

      Whether the user group is a system group which cannot be directly modified by users.

      Changes: New in Zulip 5.0 (feature level 93).

  • realm_bots: (object)[]

    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).

    • user_id: integer

      The user id of the bot.

    • full_name: string

      The full name of the bot.

    • api_key: string

      The API key of the bot which it uses to make API requests.

    • default_sending_stream: string | null

      The default sending stream of the bot. Null if the bot doesn't have a default sending stream.

    • default_events_register_stream: string | null

      The default stream for which the bot receives events/register data. Null if the bot doesn't have such a default stream.

    • default_all_public_streams: boolean

      Whether the bot can send messages to all streams by default.

    • avatar_url: string

      The URL of the bot's avatar.

    • owner_id: integer | null

      The user id of the bot's owner.

      Null if the bot has no owner.

    • services: (object | object)[]

      The "Services" array contains extra configuration fields only relevant for Outgoing webhook bots and Embedded bots. It is always a single-element array.

      We consider this part of the Zulip API to be unstable; it is used only for UI elements for administering bots and is likely to change.

    • email: string

      The email of the bot.

    • bot_type: integer | null

      An integer describing the type of bot:

      • 1 for a Generic bot.
      • 2 for an Incoming webhook bot.
      • 3 for an Outgoing webhook bot.
      • 4 for an Embedded bot.
    • is_active: boolean

      A boolean describing whether the user account has been deactivated.

  • realm_embedded_bots: (object)[]

    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.

    • name: string

      The name of the bot.

    • config: object

      A "string: string" dictionary which describes the configuration for the embedded bot (usually details like API keys).

      • String describing the config data.
  • realm_incoming_webhook_bots: (object)[]

    Present if realm_incoming_webhook_bots is present in fetch_event_types.

    An array of dictionaries where each dictionary describes an type of incoming webhook integration that is available to be configured on this Zulip server.

    Clients only need these data if they contain UI for creating or administering bots.

    • name: string

      The name of the bot.

    • config: object

      A "string: string" dictionary which describes the configuration for the embedded bot (usually details like API keys).

      • String describing the config data.
  • recent_private_conversations: (object)[]

    Present if recent_private_conversations is present in fetch_event_types.

    An array of dictionaries containing data on all private message and group private message conversations that the user has received (or sent) messages in, organized by conversation. This data set is designed to support UI elements such as the "Private messages" widget in the web application showing recent private message conversations that the user has participated in.

    "Recent" is defined as the server's discretion; the original implementation interpreted that as "the 1000 most recent private messages the user received".

    • max_message_id: integer

      The highest message id of the conversation, intended to support sorting the conversations by recency.

    • user_ids: (integer)[]

      The list of users other than the current user in the private message conversation. This will be an empty list for private messages sent to oneself.

  • subscriptions: (object)[]

    Present if subscription is present in fetch_event_types.

    A array of dictionaries where each dictionary describes the properties of a stream the user is subscribed to (as well as that user's personal per-stream settings).

    • stream_id: integer

      The unique ID of a stream.

    • name: string

      The name of a stream.

    • description: string

      The description of the stream in text/markdown format, intended to be used to prepopulate UI for editing a stream's description.

      See also rendered_description.

    • rendered_description: string

      The description of the stream rendered as HTML, intended to be used when displaying the stream description in a UI.

      One should use the standard Zulip rendered_markdown CSS when displaying this content so that emoji, LaTeX, and other syntax work correctly. And any client-side security logic for user-generated message content should be applied when displaying this HTML as though it were the body of a Zulip message.

      See also description.

    • date_created: integer

      The UNIX timestamp for when the stream was created, in UTC seconds.

      Changes: New in Zulip 4.0 (feature level 30).

    • invite_only: boolean

      Specifies whether the stream is private or not. Only people who have been invited can access a private stream.

    • subscribers: (integer)[]

      A list of user IDs of users who are also subscribed to a given stream. Included only if include_subscribers is true.

    • desktop_notifications: boolean | null

      A boolean specifying whether desktop notifications are enabled for the given stream.

      A null value means the value of this setting should be inherited from the user-level default setting, enable_stream_desktop_notifications, for this stream.

    • email_notifications: boolean | null

      A boolean specifying whether email notifications are enabled for the given stream.

      A null value means the value of this setting should be inherited from the user-level default setting, enable_stream_email_notifications, for this stream.

    • wildcard_mentions_notify: boolean | null

      A boolean specifying whether wildcard mentions trigger notifications as though they were personal mentions in this stream.

      A null value means the value of this setting should be inherited from the user-level default setting, wildcard_mentions_notify, for this stream.

    • push_notifications: boolean | null

      A boolean specifying whether push notifications are enabled for the given stream.

      A null value means the value of this setting should be inherited from the user-level default setting, enable_stream_push_notifications, for this stream.

    • audible_notifications: boolean | null

      A boolean specifying whether audible notifications are enabled for the given stream.

      A null value means the value of this setting should be inherited from the user-level default setting, enable_stream_audible_notifications, for this stream.

    • pin_to_top: boolean

      A boolean specifying whether the given stream has been pinned to the top.

    • email_address: string

      Email address of the given stream, used for sending emails to the stream.

    • is_muted: boolean

      Whether the user has muted the stream. Muted streams do not count towards your total unread count and do not show up in All messages view (previously known as Home view).

      Changes: Prior to Zulip 2.1, this feature was represented by the more confusingly named in_home_view (with the opposite value, in_home_view=!is_muted).

    • in_home_view: boolean

      Legacy property for if the given stream is muted, with inverted meeting.

      Deprecated; clients should use is_muted where available.

    • is_announcement_only: boolean

      Whether only organization administrators can post to the stream.

      Changes: Deprecated in Zulip 3.0 (feature level 1), use stream_post_policy instead.

    • is_web_public: boolean

      Whether the stream has been configured to allow unauthenticated access to its message history from the web.

    • role: integer

      The user's role within the stream (distinct from the user's organization-level role). Valid values are:

      • 20 => Stream administrator.
      • 50 => Subscriber.

      Changes: New in Zulip 4.0 (feature level 31).

    • color: string

      The user's personal color for the stream.

    • stream_post_policy: integer

      Policy for which users can post messages to the stream.

      • 1 => Any user can post.
      • 2 => Only administrators can post.
      • 3 => Only full members can post.
      • 4 => Only moderators can post.

      Changes: New in Zulip 3.0, replacing the previous is_announcement_only boolean.

    • message_retention_days: integer | null

      Number of days that messages sent to this stream will be stored before being automatically deleted by the message retention policy. There are two special values:

      • null, the default, means the stream will inherit the organization level setting.
      • -1 encodes retaining messages in this stream forever.

      Changes: New in Zulip 3.0 (feature level 17).

    • history_public_to_subscribers: boolean

      Whether the history of the stream is public to its subscribers.

      Currently always true for public streams (i.e. invite_only=False implies history_public_to_subscribers=True), but clients should not make that assumption, as we may change that behavior in the future.

    • first_message_id: integer | null

      The id of the first message in the stream.

      Intended to help clients determine whether they need to display UI like the "more topics" widget that would suggest the stream has older history that can be accessed.

      Null is used for streams with no message history.

    • stream_weekly_traffic: integer | null

      The average number of messages sent to the stream in recent weeks, rounded to the nearest integer.

      Null means the stream was recently created and there is insufficient data to estimate the average traffic.

  • unsubscribed: (object)[]

    Present if subscription is present in fetch_event_types.

    A array of dictionaries where each dictionary describes one of the streams the user has unsubscribed from but was previously subscribed to along with the subscription details.

    Unlike never_subscribed, the user might have messages in their personal message history that were sent to these streams.

    • stream_id: integer

      The unique ID of a stream.

    • name: string

      The name of a stream.

    • description: string

      The description of the stream in text/markdown format, intended to be used to prepopulate UI for editing a stream's description.

      See also rendered_description.

    • rendered_description: string

      The description of the stream rendered as HTML, intended to be used when displaying the stream description in a UI.

      One should use the standard Zulip rendered_markdown CSS when displaying this content so that emoji, LaTeX, and other syntax work correctly. And any client-side security logic for user-generated message content should be applied when displaying this HTML as though it were the body of a Zulip message.

      See also description.

    • date_created: integer

      The UNIX timestamp for when the stream was created, in UTC seconds.

      Changes: New in Zulip 4.0 (feature level 30).

    • invite_only: boolean

      Specifies whether the stream is private or not. Only people who have been invited can access a private stream.

    • subscribers: (integer)[]

      A list of user IDs of users who are also subscribed to a given stream. Included only if include_subscribers is true.

    • desktop_notifications: boolean | null

      A boolean specifying whether desktop notifications are enabled for the given stream.

      A null value means the value of this setting should be inherited from the user-level default setting, enable_stream_desktop_notifications, for this stream.

    • email_notifications: boolean | null

      A boolean specifying whether email notifications are enabled for the given stream.

      A null value means the value of this setting should be inherited from the user-level default setting, enable_stream_email_notifications, for this stream.

    • wildcard_mentions_notify: boolean | null

      A boolean specifying whether wildcard mentions trigger notifications as though they were personal mentions in this stream.

      A null value means the value of this setting should be inherited from the user-level default setting, wildcard_mentions_notify, for this stream.

    • push_notifications: boolean | null

      A boolean specifying whether push notifications are enabled for the given stream.

      A null value means the value of this setting should be inherited from the user-level default setting, enable_stream_push_notifications, for this stream.

    • audible_notifications: boolean | null

      A boolean specifying whether audible notifications are enabled for the given stream.

      A null value means the value of this setting should be inherited from the user-level default setting, enable_stream_audible_notifications, for this stream.

    • pin_to_top: boolean

      A boolean specifying whether the given stream has been pinned to the top.

    • email_address: string

      Email address of the given stream, used for sending emails to the stream.

    • is_muted: boolean

      Whether the user has muted the stream. Muted streams do not count towards your total unread count and do not show up in All messages view (previously known as Home view).

      Changes: Prior to Zulip 2.1, this feature was represented by the more confusingly named in_home_view (with the opposite value, in_home_view=!is_muted).

    • in_home_view: boolean

      Legacy property for if the given stream is muted, with inverted meeting.

      Deprecated; clients should use is_muted where available.

    • is_announcement_only: boolean

      Whether only organization administrators can post to the stream.

      Changes: Deprecated in Zulip 3.0 (feature level 1), use stream_post_policy instead.

    • is_web_public: boolean

      Whether the stream has been configured to allow unauthenticated access to its message history from the web.

    • role: integer

      The user's role within the stream (distinct from the user's organization-level role). Valid values are:

      • 20 => Stream administrator.
      • 50 => Subscriber.

      Changes: New in Zulip 4.0 (feature level 31).

    • color: string

      The user's personal color for the stream.

    • stream_post_policy: integer

      Policy for which users can post messages to the stream.

      • 1 => Any user can post.
      • 2 => Only administrators can post.
      • 3 => Only full members can post.
      • 4 => Only moderators can post.

      Changes: New in Zulip 3.0, replacing the previous is_announcement_only boolean.

    • message_retention_days: integer | null

      Number of days that messages sent to this stream will be stored before being automatically deleted by the message retention policy. There are two special values:

      • null, the default, means the stream will inherit the organization level setting.
      • -1 encodes retaining messages in this stream forever.

      Changes: New in Zulip 3.0 (feature level 17).

    • history_public_to_subscribers: boolean

      Whether the history of the stream is public to its subscribers.

      Currently always true for public streams (i.e. invite_only=False implies history_public_to_subscribers=True), but clients should not make that assumption, as we may change that behavior in the future.

    • first_message_id: integer | null

      The id of the first message in the stream.

      Intended to help clients determine whether they need to display UI like the "more topics" widget that would suggest the stream has older history that can be accessed.

      Null is used for streams with no message history.

    • stream_weekly_traffic: integer | null

      The average number of messages sent to the stream in recent weeks, rounded to the nearest integer.

      Null means the stream was recently created and there is insufficient data to estimate the average traffic.

  • never_subscribed: (object)[]

    Present if subscription is present in fetch_event_types.

    A array of dictionaries where each dictionary describes one of the streams that is visible to the user and the user has never been subscribed to.

    Important for clients containing UI where one can browse streams to subscribe to.

    • stream_id: integer

      The unique ID of the stream.

    • name: string

      The name of the stream.

    • description: string

      The short description of the stream in text/markdown format, intended to be used to prepopulate UI for editing a stream's description.

    • date_created: integer

      The UNIX timestamp for when the stream was created, in UTC seconds.

      Changes: New in Zulip 4.0 (feature level 30).

    • invite_only: boolean

      Specifies whether the stream is private or not. Only people who have been invited can access a private stream.

    • rendered_description: string

      The short description of the stream rendered as HTML, intended to be used when displaying the stream description in a UI.

      One should use the standard Zulip rendered_markdown CSS when displaying this content so that emoji, LaTeX, and other syntax work correctly. And any client-side security logic for user-generated message content should be applied when displaying this HTML as though it were the body of a Zulip message.

    • is_web_public: boolean

      Whether the stream has been configured to allow unauthenticated access to its message history from the web.

    • stream_post_policy: integer

      Policy for which users can post messages to the stream.

      • 1 => Any user can post.
      • 2 => Only administrators can post.
      • 3 => Only full members can post.
      • 4 => Only moderators can post.

      Changes: New in Zulip 3.0, replacing the previous is_announcement_only boolean.

    • message_retention_days: integer | null

      Number of days that messages sent to this stream will be stored before being automatically deleted by the message retention policy. There are two special values:

      • null, the default, means the stream will inherit the organization level setting.
      • -1 encodes retaining messages in this stream forever.

      Changes: New in Zulip 3.0 (feature level 17).

    • history_public_to_subscribers: boolean

      Whether the history of the stream is public to its subscribers.

      Currently always true for public streams (i.e. invite_only=False implies history_public_to_subscribers=True), but clients should not make that assumption, as we may change that behavior in the future.

    • first_message_id: integer | null

      The id of the first message in the stream.

      Intended to help clients determine whether they need to display UI like the "more topics" widget that would suggest the stream has older history that can be accessed.

      Null is used for streams with no message history.

    • is_announcement_only: boolean

      Whether the given stream is announcement only or not.

      Changes: Deprecated in Zulip 3.0 (feature level 1), use stream_post_policy instead.

    • stream_weekly_traffic: integer | null

      The average number of messages sent to the stream in recent weeks, rounded to the nearest integer.

      Null means the stream was recently created and there is insufficient data to estimate the average traffic.

    • subscribers: (integer)[]

      A list of user IDs of users who are subscribed to the stream. Included only if include_subscribers is true.

      If a user is not allowed to know the subscribers for a stream, we will send an empty array. API authors should use other data to determine whether users like guest users are forbidden to know the subscribers.

  • unread_msgs: (object)[]

    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).

    • count: integer

      The total number of unread messages to display; this includes private and group private messages, as well as all messages to unmuted topics on unmuted streams.

    • pms: (object)[]

      An array of dictionaries where each entry contains details of unread private messages with a specific user.

      • other_user_id: integer

        The user id of the other participant in this non-group private message conversation. Will be your own user ID for messages that you sent to only yourself.

      • sender_id: integer

        Old name for other_user_id. Clients should access this field in Zulip server versions that do not yet support other_user_id.

        Changes: Deprecated in Zulip 5.0 (feature level 119). We expect to provide a next version of the full unread_msgs API before removing this legacy name.

      • message_ids: (integer)[]

        The message ids of the recent unread PM messages sent by the other user.

    • streams: (object)[]

      An array of dictionaries where each dictionary contains details of all unread messages of a single subscribed stream, including muted streams.

      Changes: Prior to Zulip 5.0 (feature level 90), the dictionaries included an additional sender_ids key listing the set of IDs of users who had sent the unread messages.

      • topic: string

        The topic under which the message was sent.

      • stream_id: integer

        The id of the stream to which the message was sent.

      • unread_message_ids: (integer)[]

        The message ids of the recent unread messages sent in this stream.

    • huddles: (object)[]

      An array of dictionaries where each dictionary contains details of all unread group private messages of a single group.

      • user_ids_string: string

        A string containing the IDs of all users in the group private message conversation separated by commas (,). Example: "1,2,3".

      • message_ids: (integer)[]

        The message ids of the recent unread messages which have been sent in this group.

    • mentions: (integer)[]

      Array containing the ids of all messages in which the user has been mentioned. For muted streams, wildcard mentions will not be considered for this array.

    • old_unreads_missing: boolean

      True if 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).

    • stream_id: integer

      The unique ID of the stream.

    • name: string

      The name of the stream.

    • description: string

      The short description of the stream in text/markdown format, intended to be used to prepopulate UI for editing a stream's description.

    • date_created: integer

      The UNIX timestamp for when the stream was created, in UTC seconds.

      Changes: New in Zulip 4.0 (feature level 30).

    • invite_only: boolean

      Specifies whether the stream is private or not. Only people who have been invited can access a private stream.

    • rendered_description: string

      The short description of the stream rendered as HTML, intended to be used when displaying the stream description in a UI.

      One should use the standard Zulip rendered_markdown CSS when displaying this content so that emoji, LaTeX, and other syntax work correctly. And any client-side security logic for user-generated message content should be applied when displaying this HTML as though it were the body of a Zulip message.

    • is_web_public: boolean

      Whether the stream has been configured to allow unauthenticated access to its message history from the web.

    • stream_post_policy: integer

      Policy for which users can post messages to the stream.

      • 1 => Any user can post.
      • 2 => Only administrators can post.
      • 3 => Only full members can post.
      • 4 => Only moderators can post.

      Changes: New in Zulip 3.0, replacing the previous is_announcement_only boolean.

    • message_retention_days: integer | null

      Number of days that messages sent to this stream will be stored before being automatically deleted by the message retention policy. There are two special values:

      • null, the default, means the stream will inherit the organization level setting.
      • -1 encodes retaining messages in this stream forever.

      Changes: New in Zulip 3.0 (feature level 17).

    • history_public_to_subscribers: boolean

      Whether the history of the stream is public to its subscribers.

      Currently always true for public streams (i.e. invite_only=False implies history_public_to_subscribers=True), but clients should not make that assumption, as we may change that behavior in the future.

    • first_message_id: integer | null

      The id of the first message in the stream.

      Intended to help clients determine whether they need to display UI like the "more topics" widget that would suggest the stream has older history that can be accessed.

      Null is used for streams with no message history.

    • is_announcement_only: boolean

      Whether the given stream is announcement only or not.

      Changes: Deprecated in Zulip 3.0 (feature level 1), use stream_post_policy instead.

  • starred_messages: (integer)[]

    Present if starred_messages is present in fetch_event_types.

    Array containing the ids of all messages which have been starred by the user.

  • streams: (object)[]

    Present if stream is present in fetch_event_types.

    Array of dictionaries where each dictionary contains details about a single stream in the organization that is visible to the user.

    For organization administrators, this will include all private streams in the organization.

    • stream_id: integer

      The unique ID of the stream.

    • name: string

      The name of the stream.

    • description: string

      The short description of the stream in text/markdown format, intended to be used to prepopulate UI for editing a stream's description.

    • date_created: integer

      The UNIX timestamp for when the stream was created, in UTC seconds.

      Changes: New in Zulip 4.0 (feature level 30).

    • invite_only: boolean

      Specifies whether the stream is private or not. Only people who have been invited can access a private stream.

    • rendered_description: string

      The short description of the stream rendered as HTML, intended to be used when displaying the stream description in a UI.

      One should use the standard Zulip rendered_markdown CSS when displaying this content so that emoji, LaTeX, and other syntax work correctly. And any client-side security logic for user-generated message content should be applied when displaying this HTML as though it were the body of a Zulip message.

    • is_web_public: boolean

      Whether the stream has been configured to allow unauthenticated access to its message history from the web.

    • stream_post_policy: integer

      Policy for which users can post messages to the stream.

      • 1 => Any user can post.
      • 2 => Only administrators can post.
      • 3 => Only full members can post.
      • 4 => Only moderators can post.

      Changes: New in Zulip 3.0, replacing the previous is_announcement_only boolean.

    • message_retention_days: integer | null

      Number of days that messages sent to this stream will be stored before being automatically deleted by the message retention policy. There are two special values:

      • null, the default, means the stream will inherit the organization level setting.
      • -1 encodes retaining messages in this stream forever.

      Changes: New in Zulip 3.0 (feature level 17).

    • history_public_to_subscribers: boolean

      Whether the history of the stream is public to its subscribers.

      Currently always true for public streams (i.e. invite_only=False implies history_public_to_subscribers=True), but clients should not make that assumption, as we may change that behavior in the future.

    • first_message_id: integer | null

      The id of the first message in the stream.

      Intended to help clients determine whether they need to display UI like the "more topics" widget that would suggest the stream has older history that can be accessed.

      Null is used for streams with no message history.

    • is_announcement_only: boolean

      Whether the given stream is announcement only or not.

      Changes: Deprecated in Zulip 3.0 (feature level 1), use stream_post_policy instead.

  • realm_default_streams: (object)[]

    Present if default_streams is present in fetch_event_types.

    An array of dictionaries where each dictionary contains details about a single default stream for the Zulip organization.

    • stream_id: integer

      The unique ID of the stream.

    • name: string

      The name of the stream.

    • description: string

      The short description of the stream in text/markdown format, intended to be used to prepopulate UI for editing a stream's description.

    • date_created: integer

      The UNIX timestamp for when the stream was created, in UTC seconds.

      Changes: New in Zulip 4.0 (feature level 30).

    • invite_only: boolean

      Specifies whether the stream is private or not. Only people who have been invited can access a private stream.

    • rendered_description: string

      The short description of the stream rendered as HTML, intended to be used when displaying the stream description in a UI.

      One should use the standard Zulip rendered_markdown CSS when displaying this content so that emoji, LaTeX, and other syntax work correctly. And any client-side security logic for user-generated message content should be applied when displaying this HTML as though it were the body of a Zulip message.

    • is_web_public: boolean

      Whether the stream has been configured to allow unauthenticated access to its message history from the web.

    • stream_post_policy: integer

      Policy for which users can post messages to the stream.

      • 1 => Any user can post.
      • 2 => Only administrators can post.
      • 3 => Only full members can post.
      • 4 => Only moderators can post.

      Changes: New in Zulip 3.0, replacing the previous is_announcement_only boolean.

    • message_retention_days: integer | null

      Number of days that messages sent to this stream will be stored before being automatically deleted by the message retention policy. There are two special values:

      • null, the default, means the stream will inherit the organization level setting.
      • -1 encodes retaining messages in this stream forever.

      Changes: New in Zulip 3.0 (feature level 17).

    • history_public_to_subscribers: boolean

      Whether the history of the stream is public to its subscribers.

      Currently always true for public streams (i.e. invite_only=False implies history_public_to_subscribers=True), but clients should not make that assumption, as we may change that behavior in the future.

    • first_message_id: integer | null

      The id of the first message in the stream.

      Intended to help clients determine whether they need to display UI like the "more topics" widget that would suggest the stream has older history that can be accessed.

      Null is used for streams with no message history.

    • is_announcement_only: boolean

      Whether the given stream is announcement only or not.

      Changes: Deprecated in Zulip 3.0 (feature level 1), use stream_post_policy instead.

  • realm_default_stream_groups: (object)[]

    Present if default_stream_groups is present in fetch_event_types.

    An array of dictionaries where each dictionary contains details about a single default stream group configured for this Zulip organization.

    Default stream groups are an experimental feature.

    • name: string

      Name of the default stream group.

    • description: string

      Description of the default stream group.

    • id: integer

      id of the default stream group.

    • streams: (object)[]

      Array containing details about the streams in the default stream group.

      • stream_id: integer

        The unique ID of the stream.

      • name: string

        The name of the stream.

      • description: string

        The short description of the stream in text/markdown format, intended to be used to prepopulate UI for editing a stream's description.

      • date_created: integer

        The UNIX timestamp for when the stream was created, in UTC seconds.

        Changes: New in Zulip 4.0 (feature level 30).

      • invite_only: boolean

        Specifies whether the stream is private or not. Only people who have been invited can access a private stream.

      • rendered_description: string

        The short description of the stream rendered as HTML, intended to be used when displaying the stream description in a UI.

        One should use the standard Zulip rendered_markdown CSS when displaying this content so that emoji, LaTeX, and other syntax work correctly. And any client-side security logic for user-generated message content should be applied when displaying this HTML as though it were the body of a Zulip message.

      • is_web_public: boolean

        Whether the stream has been configured to allow unauthenticated access to its message history from the web.

      • stream_post_policy: integer

        Policy for which users can post messages to the stream.

        • 1 => Any user can post.
        • 2 => Only administrators can post.
        • 3 => Only full members can post.
        • 4 => Only moderators can post.

        Changes: New in Zulip 3.0, replacing the previous is_announcement_only boolean.

      • message_retention_days: integer | null

        Number of days that messages sent to this stream will be stored before being automatically deleted by the message retention policy. There are two special values:

        • null, the default, means the stream will inherit the organization level setting.
        • -1 encodes retaining messages in this stream forever.

        Changes: New in Zulip 3.0 (feature level 17).

      • history_public_to_subscribers: boolean

        Whether the history of the stream is public to its subscribers.

        Currently always true for public streams (i.e. invite_only=False implies history_public_to_subscribers=True), but clients should not make that assumption, as we may change that behavior in the future.

      • first_message_id: integer | null

        The id of the first message in the stream.

        Intended to help clients determine whether they need to display UI like the "more topics" widget that would suggest the stream has older history that can be accessed.

        Null is used for streams with no message history.

      • is_announcement_only: boolean

        Whether the given stream is announcement only or not.

        Changes: Deprecated in Zulip 3.0 (feature level 1), use stream_post_policy instead.

  • stop_words: (string)[]

    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: object

    Present if user_status is present in fetch_event_types.

    A dictionary which contains the status 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.

    A status that does not have an emoji associated with it is encoded with emoji_name="".

    • emoji_code: string

      A unique identifier, defining the specific emoji codepoint requested, within the namespace of the reaction_type.

      For example, for unicode_emoji, this will be an encoding of the Unicode codepoint; for realm_emoji, it'll be the ID of the realm emoji.

    • emoji_name: string

      Name of the emoji.

    • reaction_type: string

      One of the following values:

      • unicode_emoji: Unicode emoji (emoji_code will be its Unicode codepoint).
      • realm_emoji: Custom emoji. (emoji_code will be its ID).
      • zulip_extra_emoji: Special emoji included with Zulip. Exists to namespace the zulip emoji.
    • {user_id}: object

      Object containing the status details of a user with the key of the object being the id of the user.

      • away: boolean

        Whether the user has marked themself "away".

      • status_text: string

        The text content of the status message.

      • emoji_name: string

        The emoji name for the emoji associated with the new status.

        Changes: New in Zulip 5.0 (feature level 86).

      • emoji_code: string

        The emoji code for the emoji associated with the new status.

        Changes: New in Zulip 5.0 (feature level 86).

      • reaction_type: string

        The emoji type for the emoji associated with the new status.

        Changes: New in Zulip 5.0 (feature level 86).

  • user_settings: object

    Present if user_settings is present in fetch_event_types.

    A dictionary containing the user's personal settings.

    Changes: New in Zulip 5.0 (feature level 89). Previously, these settings appeared in the top-level object, where they are available for clients without the user_settings_object client capability for backwards-compatibility.

    • twenty_four_hour_time: boolean

      Whether time should be displayed in 24-hour notation.

    • dense_mode: boolean

      This setting has no effect at present. It is reserved for use in controlling the default font size in Zulip.

    • starred_message_counts: boolean

      Whether clients should display the number of starred messages.

    • fluid_layout_width: boolean

      Whether to use the maximum available screen width for the web app's center panel (message feed, recent topics) on wide screens.

    • high_contrast_mode: boolean

      This setting is reserved for use to control variations in Zulip's design to help visually impaired users.

    • color_scheme: integer

      Controls which color 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: boolean

      Whether to translate emoticons to emoji in messages the user sends.

    • default_language: string

      What default language to use for the account.

      This controls both the Zulip UI as well as email notifications sent to the user.

      The value needs to be a standard language code that the Zulip server has translation data for; for example, "en" for English or "de" for German.

    • default_view: string

      The default view used when opening a new Zulip web app window or hitting the Esc keyboard shortcut repeatedly.

      • "recent_topics" - Recent topics view
      • "all_messages" - All messages view
    • escape_navigates_to_default_view: boolean

      Whether the escape key navigates to the configured default view.

      Changes: New in Zulip 5.0 (feature level 107).

    • left_side_userlist: boolean

      Whether the users list on left sidebar in narrow windows.

      This feature is not heavily used and is likely to be reworked.

    • emojiset: string

      The user's configured emoji set, used to display emoji to the user everywhere they appear in the UI.

      • "google" - Google modern
      • "google-blob" - Google classic
      • "twitter" - Twitter
      • "text" - Plain text
    • demote_inactive_streams: integer

      Whether to demote inactive streams in the left sidebar.

      • 1 - Automatic
      • 2 - Always
      • 3 - Never
    • timezone: string

      The user's configured time zone.

      Time zone values supported by the server are served at /static/generated/timezones.json.

    • enter_sends: boolean

      Whether the user setting for sending on pressing Enter in the compose box is enabled.

    • enable_drafts_synchronization: boolean

      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: boolean

      Enable visual desktop notifications for stream messages.

    • enable_stream_email_notifications: boolean

      Enable email notifications for stream messages.

    • enable_stream_push_notifications: boolean

      Enable mobile notifications for stream messages.

    • enable_stream_audible_notifications: boolean

      Enable audible desktop notifications for stream messages.

    • notification_sound: string

      Notification sound name.

    • enable_desktop_notifications: boolean

      Enable visual desktop notifications for private messages and @-mentions.

    • enable_sounds: boolean

      Enable audible desktop notifications for private messages and @-mentions.

    • email_notifications_batching_period_seconds: integer

      The duration (in seconds) for which the server should wait to batch email notifications before sending them.

    • enable_offline_email_notifications: boolean

      Enable email notifications for private messages and @-mentions received when the user is offline.

    • enable_offline_push_notifications: boolean

      Enable mobile notification for private messages and @-mentions received when the user is offline.

    • enable_online_push_notifications: boolean

      Enable mobile notification for private messages and @-mentions received when the user is online.

    • enable_digest_emails: boolean

      Enable digest emails when the user is away.

    • enable_marketing_emails: boolean

      Enable marketing emails. Has no function outside Zulip Cloud.

    • enable_login_emails: boolean

      Enable email notifications for new logins to account.

    • message_content_in_email_notifications: boolean

      Include the message's content in email notifications for new messages.

    • pm_content_in_desktop_notifications: boolean

      Include content of private messages in desktop notifications.

    • wildcard_mentions_notify: boolean

      Whether wildcard mentions (E.g. @all) should send notifications like a personal mention.

    • desktop_icon_count_display: integer

      Unread count badge (appears in desktop sidebar and browser tab)

      • 1 - All unreads
      • 2 - Private messages and mentions
      • 3 - None
    • realm_name_in_notifications: boolean

      Include organization name in subject of message notification emails.

    • presence_enabled: boolean

      Display the presence status to other users when online.

    • available_notification_sounds: (string)[]

      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: (object)[]

      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 for details on the meaning of this setting.

      • key: string

        The key or the name of the emoji set which will be the value of emojiset if this emoji set is chosen.

      • text: string

        The text describing the emoji set.

    • send_private_typing_notifications: boolean

      Whether the user has chosen to send typing notifications when composing private messages. The client should send typing notifications for private messages if and only if this setting is enabled.

      Changes: New in Zulip 5.0 (feature level 105).

    • send_stream_typing_notifications: boolean

      Whether the user has chosen to send typing notifications when composing stream messages. The client should send typing notifications for stream messages if and only if this setting is enabled.

      Changes: New in Zulip 5.0 (feature level 105).

    • send_read_receipts: boolean

      Whether other users are allowed to see whether you've read messages.

      Changes: New in Zulip 5.0 (feature level 105).

  • has_zoom_token: boolean

    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. Clients need to know whether initiating Zoom OAuth is required before creating a Zoom call.

  • giphy_api_key: string

    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 before using this API key.

    Changes: Added in Zulip 4.0 (feature level 47).

  • enable_desktop_notifications: boolean

    Present if update_global_notifications is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    The current value of this global notification setting for the user. See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • enable_digest_emails: boolean

    Present if update_global_notifications is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    The current value of this global notification setting for the user. See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • enable_login_emails: boolean

    Present if update_global_notifications is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    The current value of this global notification setting for the user. See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • enable_marketing_emails: boolean

    Present if update_global_notifications is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    The current value of this global notification setting for the user. See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • email_notifications_batching_period_seconds: integer

    Present if update_global_notifications is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    The current value of this global notification setting for the user. See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • enable_offline_email_notifications: boolean

    Present if update_global_notifications is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    The current value of this global notification setting for the user. See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • enable_offline_push_notifications: boolean

    Present if update_global_notifications is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    The current value of this global notification setting for the user. See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • enable_online_push_notifications: boolean

    Present if update_global_notifications is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    The current value of this global notification setting for the user. See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • enable_sounds: boolean

    Present if update_global_notifications is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    The current value of this global notification setting for the user. See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • enable_stream_desktop_notifications: boolean

    Present if update_global_notifications is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    The current value of this global notification setting for the user. See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • enable_stream_email_notifications: boolean

    Present if update_global_notifications is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    The current value of this global notification setting for the user. See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • enable_stream_push_notifications: boolean

    Present if update_global_notifications is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    The current value of this global notification setting for the user. See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • enable_stream_audible_notifications: boolean

    Present if update_global_notifications is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    The current value of this global notification setting for the user. See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • wildcard_mentions_notify: boolean

    Present if update_global_notifications is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    The current value of this global notification setting for the user. See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • message_content_in_email_notifications: boolean

    Present if update_global_notifications is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    The current value of this global notification setting for the user. See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • notification_sound: string

    Present if update_global_notifications is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    The current value of this global notification setting for the user. See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • pm_content_in_desktop_notifications: boolean

    Present if update_global_notifications is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    The current value of this global notification setting for the user. See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • desktop_icon_count_display: integer

    Present if update_global_notifications is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    The current value of this global notification setting for the user. See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • realm_name_in_notifications: boolean

    Present if update_global_notifications is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    The current value of this global notification setting for the user. See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • presence_enabled: boolean

    Present if update_global_notifications is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    The current value of this global notification setting for the user. See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • available_notification_sounds: (string)[]

    Present if update_global_notifications is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    Array containing the names of the notification sound options supported by this Zulip server. Only relevant to support UI for configuring notification sounds.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • color_scheme: integer

    Present if update_display_settings is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    The color scheme selected by the user.

    See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • default_language: string

    Present if update_display_settings is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    The default language chosen by the user.

    See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • demote_inactive_streams: integer

    Present if update_display_settings is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    Whether the user has chosen to demote inactive streams.

    See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • dense_mode: boolean

    Present if update_display_settings is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    Whether the user has switched on dense mode. Dense mode is an experimental feature that is only available in development environments.

    See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • emojiset: string

    Present if update_display_settings is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    The name of the emoji set that the user has chosen.

    See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • enable_drafts_synchronization: boolean

    Present if update_display_settings is present in fetch_event_types.

    Whether drafts synchronization is enabled for the user. If disabled, clients will receive an error when trying to use the drafts endpoints.

    See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

    New in Zulip 5.0 (feature level 87).

  • fluid_layout_width: boolean

    Present if update_display_settings is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    Whether the user has chosen for the layout width to be fluid.

    See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • default_view: string

    Present if update_display_settings is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    The default view in Zulip, represented as the URL suffix after # to be rendered when Zulip loads.

    Currently supported values are all_messages and recent_topics.

    See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • high_contrast_mode: boolean

    Present if update_display_settings is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    Whether has switched on high contrast mode.

    See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • left_side_userlist: boolean

    Present if update_display_settings is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    Whether the user has chosen for the userlist to be displayed on the left side of the screen (for desktop app and web app) in narrow windows.

    See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • starred_message_counts: boolean

    Present if update_display_settings is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    Whether the user has chosen the number of starred messages to be displayed similar to unread counts.

    See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • timezone: string

    Present if update_display_settings is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    The time zone configured for the user. This is used primarily to display the user's time zone to other users.

    See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • translate_emoticons: boolean

    Present if update_display_settings is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    Whether the user has chosen for emoticons to be translated into emoji in the Zulip compose box.

    See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • twenty_four_hour_time: boolean

    Present if update_display_settings is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    Whether the user has chosen a twenty four hour time display (true) or a twelve hour one (false).

    See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

  • emojiset_choices: (object)[]

    Present if update_display_settings is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    Array of dictionaries where each dictionary describes an emoji set supported by this version of the Zulip server.

    Only relevant to clients with configuration UI for choosing an emoji set; the currently selected emoji set is available in the emojiset key.

    See PATCH /settings for details on the meaning of this setting.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

    • key: string

      The key or the name of the emoji set which will be the value of emojiset if this emoji set is chosen.

    • text: string

      The text describing the emoji set.

  • realm_add_custom_emoji_policy: integer

    Present if realm is present in fetch_event_types.

    The policy for which users can upload new custom emoji in this organization.

    • 1 = Members only
    • 2 = Administrators only
    • 3 = Full members only
    • 4 = Moderators only

    Changes: New in Zulip 5.0 (feature level 85) replacing the previous realm_add_emoji_by_admins_only boolean.

  • realm_allow_edit_history: boolean

    Present if realm is present in fetch_event_types.

    Whether this organization is configured to allow users to access message edit history.

  • realm_delete_own_message_policy: integer

    Present if realm is present in fetch_event_types.

    The policy defining which users can delete messages that they had sent.

    • 1 = members only
    • 2 = admins only
    • 3 = full members only
    • 4 = admins and moderators only
    • 5 = everyone

    Changes: New in Zulip 5.0 (feature level 101), replacing the previous allow_message_deleting boolean; true corresponded to everyone, and false to admins only.

  • realm_bot_creation_policy: integer

    Present if realm is present in fetch_event_types.

    The policy for which users can create bot users in this organization.

  • realm_create_public_stream_policy: integer

    Present if realm is present in fetch_event_types.

    The policy for which users can create public streams in this organization.

    • 1 = members only
    • 2 = admins only
    • 3 = full members only
    • 4 = admins and moderators only

    Changes: Before Zulip 5.0 (feature level 102), permission to create streams was controlled by the realm_create_stream_policy setting.

  • realm_create_private_stream_policy: integer

    Present if realm is present in fetch_event_types.

    The policy for which users can create private streams in this organization.

    • 1 = members only
    • 2 = admins only
    • 3 = full members only
    • 4 = admins and moderators only

    Changes: Before Zulip 5.0 (feature level 102), permission to create streams was controlled by the realm_create_stream_policy setting.

  • realm_create_web_public_stream_policy: integer

    Present if realm is present in fetch_event_types.

    Has no effect and should not be displayed in settings UI unless the Zulip server has the WEB_PUBLIC_STREAMS_ENABLED server-level setting enabled and the organization has enabled the enable_spectator_access realm setting.

    The policy for which users can create web public streams in this organization. Allowed values are:

    • 2 = admins only
    • 4 = admins and moderators only
    • 6 = nobody
    • 7 = owners only

    Changes: Added in Zulip 5.0 (feature level 103).

  • realm_invite_to_stream_policy: integer

    Present if realm is present in fetch_event_types.

    The policy for which users can add other users to streams in this organization.

  • realm_wildcard_mention_policy: integer

    Present if realm is present in fetch_event_types.

    The policy for who can use wildcard mentions in large streams.

    • 1 => Any user can use wildcard mentions in large streams.
    • 2 => Only members can use wildcard mentions in large streams.
    • 3 => Only full members can use wildcard mentions in large streams.
    • 4 => Only stream and organization administrators can use wildcard mentions in large streams.
    • 5 => Only organization administrators can use wildcard mentions in large streams.
    • 6 => Nobody can use wildcard mentions in large streams.
    • 7 => Only organization administrators and moderators can use wildcard mentions in large streams.

    All users will receive a warning/reminder when using mentions in large streams, even when permitted to do so.

    Changes: New in Zulip 4.0 (feature level 33). Moderators option added in Zulip 4.0 (feature level 62).

  • realm_default_language: string

    Present if realm is present in fetch_event_types.

    The default UI language for new users joining this organization.

  • realm_description: string

    Present if realm is present in fetch_event_types.

    The description of the organization, used on login and registration pages.

  • realm_digest_emails_enabled: boolean

    Present if realm is present in fetch_event_types.

    Whether the organization has enabled weekly digest emails.

  • realm_disallow_disposable_email_addresses: boolean

    Present if realm is present in fetch_event_types.

    Whether the organization disallows disposable email addresses.

  • realm_email_address_visibility: integer

    Present if realm is present in fetch_event_types.

    The policy for which users in this organization can see the real email addresses of other users.

    • 1 = everyone
    • 2 = members only
    • 3 = administrators only
    • 4 = nobody (though note that administrators can change this setting).
    • 5 = moderators only
  • realm_email_changes_disabled: boolean

    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: boolean

    Present if realm is present in fetch_event_types.

    Whether an invitation is required to join this organization.

  • realm_invite_to_realm_policy: integer

    Present if realm is present in fetch_event_types.

    Policy for who can invite new users to join the organization:

    • 1 = Members only
    • 2 = Administrators only
    • 3 = Full members only
    • 4 = Moderators only
    • 6 = Nobody

    Changes: New in Zulip 4.0 (feature level 50) replacing the previous realm_invite_by_admins_only boolean.

  • realm_move_messages_between_streams_policy: integer

    Present if realm is present in fetch_event_types.

    The policy for which users can move messages from one stream to another.

    • 1 = Members only
    • 2 = Administrators only
    • 3 = Full members only
    • 4 = Moderators only

    Changes: New in Zulip 4.0 (feature level 56)

  • realm_inline_image_preview: boolean

    Present if realm is present in fetch_event_types.

    Whether this organization has been configured to enable previews of linked images.

  • realm_inline_url_embed_preview: boolean

    Present if realm is present in fetch_event_types.

    Whether this organization has been configured to enable previews of linked websites.

  • realm_mandatory_topics: boolean

    Present if realm is present in fetch_event_types.

    Whether topics are required for messages in this organization.

  • realm_message_retention_days: integer

    Present if realm is present in fetch_event_types.

    The default 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: string

    Present if realm is present in fetch_event_types.

    The name of the organization, used in login pages etc.

  • realm_name_changes_disabled: boolean

    Present if realm is present in fetch_event_types.

    Indicates whether users are allowed to change 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: boolean

    Present if realm is present in fetch_event_types.

    Indicates whether users are allowed to change 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: boolean

    Present if realm is present in fetch_event_types.

    Whether new users joining this organization are required to have an email address in one of the realm_domains configured for the organization.

  • realm_send_welcome_emails: boolean

    Present if realm is present in fetch_event_types.

    Whether or not this organization is configured to send the standard Zulip welcome emails to new users joining the organization.

  • realm_message_content_allowed_in_email_notifications: boolean

    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: boolean

    Present if realm is present in fetch_event_types.

    Whether web-public streams and related anonymous access APIs/features are enabled in this organization.

    Can only be enabled if the WEB_PUBLIC_STREAMS_ENABLED [server setting][server-settings] is enabled on the Zulip server. See also the create_web_public_stream_policy realm setting.

    Changes: New in Zulip 5.0 (feature level 109).

  • realm_video_chat_provider: integer

    Present if realm is present in fetch_event_types.

    The configured video call provider for the organization.

  • realm_giphy_rating: integer

    Present if realm is present in fetch_event_types.

    The configured GIPHY rating for the organization.

    Changes: New in Zulip 4.0 (feature level 55).

  • realm_waiting_period_threshold: integer

    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 for the purpose of settings that restrict access to new members.

  • realm_digest_weekday: integer

    Present if realm is present in fetch_event_types.

    The day of the week when the organization will send its weekly digest email to inactive users.

  • realm_private_message_policy: integer

    Present if realm is present in fetch_event_types.

    Policy for who can send private messages in this organization.

    • 1 = Everyone
    • 2 = Nobody
  • realm_user_group_edit_policy: integer

    Present if realm is present in fetch_event_types.

    The organization's policy for who can manage user groups .

    • 1 = All members can create and edit user groups
    • 2 = Only organization administrators can create and edit user groups
    • 3 = Only full members can create and edit user groups.
    • 4 = Only organization administrators and moderators can create and edit user groups.
  • realm_default_code_block_language: string | null

    Present if realm is present in fetch_event_types.

    The default pygments language code to be used for a code blocks in this organization. Null if no default has been set.

  • realm_message_content_delete_limit_seconds: integer | null

    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.

    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: object

    Present if realm is present in fetch_event_types.

    Dictionary of 'authentication_method_name': 'boolean' with each entry describing whether the authentication name can be used for authenticating into the organization.

    • Boolean describing whether the authentication method (i.e its key) is enabled in this organization.
  • realm_allow_message_editing: boolean

    Present if realm is present in fetch_event_types.

    Whether this organizations message edit policy allows editing the content of messages.

  • realm_edit_topic_policy: integer

    Present if realm is present in fetch_event_types.

    The policy for which users can edit topics of any message.

    • 1 = members only
    • 2 = admins only
    • 3 = full members only
    • 4 = moderators only
    • 5 = everyone

    Changes: New in Zulip 5.0 (feature level 75), replacing the previous allow_community_topic_editing boolean.

  • realm_message_content_edit_limit_seconds: integer

    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.

  • realm_community_topic_editing_limit_seconds: integer

    Present if realm is present in fetch_event_types.

    Messages sent more than this many seconds ago cannot have their topics edited by other users with this organization's message edit policy.

    Changes: New in Zulip 3.0 (feature level 11). Previously this value was hardcoded to 86400 seconds (1 day).

  • realm_icon_url: string

    Present if realm is present in fetch_event_types.

    The URL of the organization's profile icon.

  • realm_icon_source: string

    Present if realm is present in fetch_event_types.

    String indicating whether the organization's profile icon was uploaded by a user or is the default. Useful for UI allowing editing the organization's icon.

    • "G" means generated by Gravatar (the default).
    • "U" means uploaded by an organization administrator.
  • max_icon_file_size_mib: integer

    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: string

    Present if realm is present in fetch_event_types.

    The URL of the organization's wide logo configured in the organization profile.

  • realm_logo_source: string

    Present if realm is present in fetch_event_types.

    String indicating whether the organization's profile wide logo 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: string

    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.

  • realm_night_logo_source: string

    Present if realm is present in fetch_event_types.

    String indicating whether the organization's dark theme profile wide logo 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: integer

    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: string

    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: string

    Present if realm is present in fetch_event_types.

    The URL for the organization.

  • realm_available_video_chat_providers: object

    Present if realm is present in fetch_event_types.

    Dictionary where each entry describes a supported video 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 video call provider.

    • {provider_name}: object

      Dictionary containing the details of the video call provider with the name of the chat provider as the key.

      • name: string

        The name of the video call provider.

      • id: integer

        The ID of the video call provider.

  • realm_presence_disabled: boolean

    Present if realm is present in fetch_event_types.

    Whether online presence of other users is shown in this organization.

  • settings_send_digest_emails: boolean

    Present if realm is present in fetch_event_types.

    Whether this Zulip server is configured to allow organizations to enable digest emails.

    Relevant for administrative settings UI that can change the digest email settings.

  • realm_is_zephyr_mirror_realm: boolean

    Present if realm is present in fetch_event_types.

    Whether the organization is a Zephyr mirror realm.

  • realm_email_auth_enabled: boolean

    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: boolean

    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 before presenting a login page).

  • realm_push_notifications_enabled: boolean

    Present if realm is present in fetch_event_types.

    Whether push notifications are enabled for this organization. Typically false for self-hosted servers that have not configured the Mobile push notifications service.

  • realm_upload_quota_mib: integer | null

    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.

    Null if there is no limit.

    Changes: New in Zulip 5.0 (feature level 72). Previously, this was called realm_upload_quota.

  • realm_plan_type: integer

    Present if realm is present in fetch_event_types.

    The plan type of the organization.

    • 1 = Self-hosted organization (SELF_HOSTED)
    • 2 = Zulip Cloud free plan (LIMITED)
    • 3 = Zulip Cloud Standard plan (STANDARD)
    • 4 = Zulip Cloud Standard plan, sponsored for free (STANDARD_FREE)
  • zulip_plan_is_not_limited: boolean

    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: string

    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: object

    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.

    • {site_name}: object

      Dictionary containing the details of the default external account provider with the name of the website as the key.

      • name: string

        The name of the external account provider

      • text: string

        The text describing the external account.

      • hint: string

        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: string

        The regex pattern of the URL of a profile page on the external site.

  • jitsi_server_url: string

    Present if realm is present in fetch_event_types.

    The base URL the organization uses to create Jitsi video calls.

  • development_environment: boolean

    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: integer

    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: integer

    Present if realm is present in fetch_event_types.

    This Zulip server's configured minimum required length for passwords. Necessary for password change UI to show whether the password will be accepted.

  • password_min_guesses: integer

    Present if realm is present in fetch_event_types.

    This Zulip server's configured minimum zxcvbn minimum guesses. Necessary for password change UI to show whether the password will be accepted.

  • giphy_rating_options: object

    Dictionary where each entry describes a valid rating that is configured on this server and could be selected by an organization administrator.

    Useful for administrative settings UI that allows changing the allowed rating of GIFs.

    • {rating_name}: object

      Dictionary containing the details of the rating with the name of the rating as the key.

      • name: string

        The description of the rating option.

      • id: integer

        The ID of the rating option.

  • max_file_upload_size_mib: integer

    Present if realm is present in fetch_event_types.

    The maximum file size that can be uploaded to this Zulip server.

  • max_avatar_file_size_mib: integer

    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: boolean

    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: boolean

    Present if realm is present in fetch_event_types.

    Whether the server is configured with support for inline URL previews. Clients containing administrative UI for changing realm_inline_url_embed_preview should consult this field before offering that feature.

  • server_avatar_changes_disabled: boolean

    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: boolean

    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: boolean

    Present if realm is present in fetch_event_types.

    Whether the server is running an old version based on the Zulip server release lifecycle, 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: boolean

    Present if realm is present in fetch_event_types.

    The value of the WEB_PUBLIC_STREAMS_ENABLED Zulip server level setting. A server that has disabled this setting intends to not offer web public streams 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 we-public streams (realm_enable_spectator_access).

    Changes: New in Zulip 5.0 (feature level 110).

  • event_queue_longpoll_timeout_seconds: integer

    Present if realm is present in fetch_event_types.

    Recommended client-side HTTP request timeout for GET /events calls. This is guaranteed to be somewhat greater than the heartbeat frequency. It is important that clients respect this parameter, so that increases in the heartbeat frequency do not break clients.

    Changes: New in Zulip 5.0 (feature level 74). Previously, this was hardcoded to 90 seconds, and clients should use that as a fallback value when interacting with servers where this field is not present.

  • realm_notifications_stream_id: integer

    Present if realm is present in fetch_event_types.

    The ID of the stream to which notifications announcing the creation of new streams are sent. -1 if such notifications are disabled.

    Since these notifications are sent by the server, this field is primarily relevant to clients containing UI for changing it.

  • realm_signup_notifications_stream_id: integer

    Present if realm is present in fetch_event_types.

    The ID of the stream to which notifications announcing that new users have joined the organization are sent. -1 if such notifications are disabled.

    Since these notifications are sent by the server, this field is primarily relevant to clients containing UI for changing it.

  • realm_user_settings_defaults: object

    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).

    • twenty_four_hour_time: boolean

      Whether time should be displayed in 24-hour notation.

      Changes: New in Zulip 5.0 (feature level 99). This value was previously available as realm_default_twenty_four_hour_time in the top-level response object (only when realm was present in fetch_event_types).

    • dense_mode: boolean

      This setting has no effect at present. It is reserved for use in controlling the default font size in Zulip.

    • starred_message_counts: boolean

      Whether clients should display the number of starred messages.

    • fluid_layout_width: boolean

      Whether to use the maximum available screen width for the web app's center panel (message feed, recent topics) on wide screens.

    • high_contrast_mode: boolean

      This setting is reserved for use to control variations in Zulip's design to help visually impaired users.

    • color_scheme: integer

      Controls which color 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: boolean

      Whether to translate emoticons to emoji in messages the user sends.

    • default_language: string

      What default language to use for the account.

      This controls both the Zulip UI as well as email notifications sent to the user.

      The value needs to be a standard language code that the Zulip server has translation data for; for example, "en" for English or "de" for German.

    • default_view: string

      The default view used when opening a new Zulip web app window or hitting the Esc keyboard shortcut repeatedly.

      • "recent_topics" - Recent topics view
      • "all_messages" - All messages view
    • escape_navigates_to_default_view: boolean

      Whether the escape key navigates to the configured default view.

      Changes: New in Zulip 5.0 (feature level 107).

    • left_side_userlist: boolean

      Whether the users list on left sidebar in narrow windows.

      This feature is not heavily used and is likely to be reworked.

    • emojiset: string

      The user's configured emoji set, used to display emoji to the user everywhere they appear in the UI.

      • "google" - Google modern
      • "google-blob" - Google classic
      • "twitter" - Twitter
      • "text" - Plain text
    • demote_inactive_streams: integer

      Whether to demote inactive streams in the left sidebar.

      • 1 - Automatic
      • 2 - Always
      • 3 - Never
    • enable_stream_desktop_notifications: boolean

      Enable visual desktop notifications for stream messages.

    • enable_stream_email_notifications: boolean

      Enable email notifications for stream messages.

    • enable_stream_push_notifications: boolean

      Enable mobile notifications for stream messages.

    • enable_stream_audible_notifications: boolean

      Enable audible desktop notifications for stream messages.

    • notification_sound: string

      Notification sound name.

    • enable_desktop_notifications: boolean

      Enable visual desktop notifications for private messages and @-mentions.

    • enable_sounds: boolean

      Enable audible desktop notifications for private messages and @-mentions.

    • enable_offline_email_notifications: boolean

      Enable email notifications for private messages and @-mentions received when the user is offline.

    • enable_offline_push_notifications: boolean

      Enable mobile notification for private messages and @-mentions received when the user is offline.

    • enable_online_push_notifications: boolean

      Enable mobile notification for private messages and @-mentions received when the user is online.

    • enable_digest_emails: boolean

      Enable digest emails when the user is away.

    • enable_marketing_emails: boolean

      Enable marketing emails. Has no function outside Zulip Cloud.

    • enable_login_emails: boolean

      Enable email notifications for new logins to account.

    • message_content_in_email_notifications: boolean

      Include the message's content in email notifications for new messages.

    • pm_content_in_desktop_notifications: boolean

      Include content of private messages in desktop notifications.

    • wildcard_mentions_notify: boolean

      Whether wildcard mentions (E.g. @all) should send notifications like a personal mention.

    • desktop_icon_count_display: integer

      Unread count badge (appears in desktop sidebar and browser tab)

      • 1 - All unreads
      • 2 - Private messages and mentions
      • 3 - None
    • realm_name_in_notifications: boolean

      Include organization name in subject of message notification emails.

    • presence_enabled: boolean

      Display the presence status to other users when online.

    • enter_sends: boolean

      Whether the user setting for sending on pressing Enter in the compose box is enabled.

    • enable_drafts_synchronization: boolean

      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: integer

      The duration (in seconds) for which the server should wait to batch email notifications before sending them.

    • available_notification_sounds: (string)[]

      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: (object)[]

      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 for details on the meaning of this setting.

      • key: string

        The key or the name of the emoji set which will be the value of emojiset if this emoji set is chosen.

      • text: string

        The text describing the emoji set.

    • send_private_typing_notifications: boolean

      Whether typing notifications be sent when composing private messages.

      Changes: New in Zulip 5.0 (feature level 105).

    • send_stream_typing_notifications: boolean

      Whether typing notifications be sent when composing stream messages.

      Changes: New in Zulip 5.0 (feature level 105).

    • send_read_receipts: boolean

      Whether other users are allowed to see whether you've read messages.

      Changes: New in Zulip 5.0 (feature level 105).

  • realm_users: (object)[]

    Present if realm_user is present in fetch_event_types.

    A array of dictionaries where each entry describes a user whose account has not been deactivated. Note that unlike the usual User dictionary, this does not contain the is_active key, as all the users present in this array have active accounts.

    See also cross_realm_bots and realm_non_active_users.

    • email: string

      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.

    • is_bot: boolean

      A boolean specifying whether the user is a bot or full account.

    • avatar_url: string | null

      URL for the user's avatar. Will be null if the client_gravatar query parameter was set to True and the user's avatar is hosted by the Gravatar provider (i.e. the user has never uploaded an avatar).

      Changes: 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: integer

      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}.

    • full_name: string

      Full name of the user or bot, used for all display purposes.

    • is_admin: boolean

      A boolean specifying whether the user is an organization administrator.

    • is_owner: boolean

      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_billing_admin: boolean

      A boolean specifying whether the user is a billing administrator.

      Changes: New in Zulip 5.0 (feature level 73).

    • role: integer

      Organization-level role of the user. Possible values are:

      • Organization owner => 100
      • Organization administrator => 200
      • Organization moderator => 300
      • Member => 400
      • Guest => 600

      Changes: New in Zulip 4.0 (feature level 59).

    • bot_type: integer | null

      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.
    • user_id: integer

      The unique ID of the user.

    • bot_owner_id: integer | null

      If the user is a bot (i.e. is_bot is True), bot_owner 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.

    • is_active: boolean

      A boolean specifying whether the user account has been deactivated.

    • is_guest: boolean

      A boolean specifying whether the user is a guest user.

    • timezone: string

      The time zone of the user.

    • date_joined: string

      The time the user account was created.

    • delivery_email: string

      The user's real email address. This field is present only if email address visibility is limited and you are an administrator with access to real email addresses under the configured policy.

    • profile_data: object

      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.

      • {id}: object

        Object with data about what value user filled in the custom profile field with id id.

        • value: string

          User's personal value for this custom profile field.

        • rendered_value: string

          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.

  • realm_non_active_users: (object)[]

    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.

    • email: string

      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.

    • is_bot: boolean

      A boolean specifying whether the user is a bot or full account.

    • avatar_url: string | null

      URL for the user's avatar. Will be null if the client_gravatar query parameter was set to True and the user's avatar is hosted by the Gravatar provider (i.e. the user has never uploaded an avatar).

      Changes: 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: integer

      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}.

    • full_name: string

      Full name of the user or bot, used for all display purposes.

    • is_admin: boolean

      A boolean specifying whether the user is an organization administrator.

    • is_owner: boolean

      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_billing_admin: boolean

      A boolean specifying whether the user is a billing administrator.

      Changes: New in Zulip 5.0 (feature level 73).

    • role: integer

      Organization-level role of the user. Possible values are:

      • Organization owner => 100
      • Organization administrator => 200
      • Organization moderator => 300
      • Member => 400
      • Guest => 600

      Changes: New in Zulip 4.0 (feature level 59).

    • bot_type: integer | null

      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.
    • user_id: integer

      The unique ID of the user.

    • bot_owner_id: integer | null

      If the user is a bot (i.e. is_bot is True), bot_owner 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.

    • is_active: boolean

      A boolean specifying whether the user account has been deactivated.

    • is_guest: boolean

      A boolean specifying whether the user is a guest user.

    • timezone: string

      The time zone of the user.

    • date_joined: string

      The time the user account was created.

    • delivery_email: string

      The user's real email address. This field is present only if email address visibility is limited and you are an administrator with access to real email addresses under the configured policy.

    • profile_data: object

      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.

      • {id}: object

        Object with data about what value user filled in the custom profile field with id id.

        • value: string

          User's personal value for this custom profile field.

        • rendered_value: string

          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.

  • avatar_source: string

    Present if realm_user is present in fetch_event_types.

    The avatar data source type for the current user.

    Value values are G (gravatar) and U (uploaded by user).

  • avatar_url_medium: string

    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: string

    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: boolean

    Present if realm_user is present in fetch_event_types.

    Whether the current user is allowed to create at least one type of stream with the organization's stream creation policy. Its value will always equal can_create_public_streams || can_create_private_streams.

    Changes: Deprecated in Zulip 5.0 (feature level 102), when the new create_private_stream_policy and create_public_stream_policy properties introduced the possibility that a user could only create one type of stream.

    This field will be removed in a future release.

  • can_create_public_streams: boolean

    Present if realm_user is present in fetch_event_types.

    Whether the current user is allowed to create public streams with the organization's stream creation policy.

    Changes: New in Zulip 5.0 (feature level 102). In older versions, the deprecated can_create_streams property should be used to determine whether the user can create public streams.

  • can_create_private_streams: boolean

    Present if realm_user is present in fetch_event_types.

    Whether the current user is allowed to create private streams with the organization's stream creation policy.

    Changes: New in Zulip 5.0 (feature level 102). In older versions, the deprecated can_create_streams property should be used to determine whether the user can create private streams.

  • can_create_web_public_streams: boolean

    Present if realm_user is present in fetch_event_types.

    Whether the current user is allowed to create public streams with the organization's stream creation policy.

    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: boolean

    Present if realm_user is present in fetch_event_types.

    Whether the current user is allowed to subscribe other users to streams with the organization's streams policy.

  • can_invite_others_to_realm: boolean

    Present if realm_user is present in fetch_event_types.

    Whether the current user is allowed to invite others to the organization.

    Changes: New in Zulip 4.0 (feature level 51).

  • is_admin: boolean

    Present if realm_user is present in fetch_event_types.

    Whether the current user is an organization administrator.

  • is_owner: boolean

    Present if realm_user is present in fetch_event_types.

    Whether the current user is an organization owner.

  • is_billing_admin: boolean

    Present if realm_user is present in fetch_event_types.

    Whether the current user is a billing administrator.

    Changes: New in Zulip 5.0 (feature level 73).

  • is_moderator: boolean

    Present if realm_user is present in fetch_event_types.

    Whether the current user is an organization moderator.

    Changes: New in Zulip 4.0 (feature level 60).

  • is_guest: boolean

    Present if realm_user is present in fetch_event_types.

    Whether the current user is a guest user.

  • enter_sends: boolean

    Present if update_display_settings is present in fetch_event_types and only for clients that did not include user_settings_object in their client_capabilities` when registering the event queue.

    Whether the user setting for sending on pressing Enter in the compose box is enabled.

    Changes: Deprecated in Zulip 5.0 (feature level 89). Clients connecting to newer servers should declare the user_settings_object client capability and process the user_settings event type instead. Prior to Zulip 5.0 (feature level 84) this field was present in response if 'realm_user' was present in fetch_event_types, not update_display_settings.

  • user_id: integer

    Present if realm_user is present in fetch_event_types.

    The unique ID for the current user.

  • email: string

    Present if realm_user is present in fetch_event_types.

    The Zulip display email address for the current user. See also delivery_email; these may be the same or different depending on the organization's email_address_visibility policy.

  • delivery_email: string

    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: string

    Present if realm_user is present in fetch_event_types.

    The full name of the current user.

  • cross_realm_bots: (object)[]

    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.

    • email: string

      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.

    • is_bot: boolean

      A boolean specifying whether the user is a bot or full account.

    • avatar_url: string | null

      URL for the user's avatar. Will be null if the client_gravatar query parameter was set to True and the user's avatar is hosted by the Gravatar provider (i.e. the user has never uploaded an avatar).

      Changes: 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: integer

      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}.

    • full_name: string

      Full name of the user or bot, used for all display purposes.

    • is_admin: boolean

      A boolean specifying whether the user is an organization administrator.

    • is_owner: boolean

      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_billing_admin: boolean

      A boolean specifying whether the user is a billing administrator.

      Changes: New in Zulip 5.0 (feature level 73).

    • role: integer

      Organization-level role of the user. Possible values are:

      • Organization owner => 100
      • Organization administrator => 200
      • Organization moderator => 300
      • Member => 400
      • Guest => 600

      Changes: New in Zulip 4.0 (feature level 59).

    • bot_type: integer | null

      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.
    • user_id: integer

      The unique ID of the user.

    • bot_owner_id: integer | null

      If the user is a bot (i.e. is_bot is True), bot_owner 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.

    • is_active: boolean

      A boolean specifying whether the user account has been deactivated.

    • is_guest: boolean

      A boolean specifying whether the user is a guest user.

    • timezone: string

      The time zone of the user.

    • date_joined: string

      The time the user account was created.

    • delivery_email: string

      The user's real email address. This field is present only if email address visibility is limited and you are an administrator with access to real email addresses under the configured policy.

    • profile_data: object

      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.

      • {id}: object

        Object with data about what value user filled in the custom profile field with id id.

        • value: string

          User's personal value for this custom profile field.

        • rendered_value: string

          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.

    • is_system_bot: boolean

      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).

Example response

A typical successful JSON response may look like:

{
    "last_event_id": -1,
    "msg": "",
    "queue_id": "1517975029:0",
    "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_merge_base": "5.0-dev-1646-gea6b21cd8c",
    "zulip_version": "5.0-dev-1650-gc3fd37755f"
}