Register an event queue

POST https://yourZulipDomain.zulipchat.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.

Changes: Before Zulip 7.0 (feature level 183), the realm_community_topic_editing_limit_seconds property was returned by the response. It was removed because it had not been in use since the realm setting move_messages_within_stream_limit_seconds was introduced in feature level 162.

In Zulip 7.0 (feature level 163), the realm setting email_address_visibility was removed. It was replaced by a user setting with a realm user default, with the encoding of different values preserved. Clients can support all versions by supporting the current API and treating every user as having the realm's email_address_visibility value.

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)

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://yourZulipDomain.zulipchat.com/api/v1/register \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode 'event_types=["message"]'

Parameters

Response

Return values

• queue_id: string | null

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

  Will be null only for unauthenticated access in realms that have enabled the public access option.

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

  Changes: As of Zulip 3.0 (feature level 3), this is always present in the endpoint's response. Previously, it was only present if event_types included zulip_version.

  New in Zulip 3.0 (feature level 1).

• zulip_version: 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.

  Changes: As of Zulip 3.0 (feature level 3), this is always present in the endpoint's response. Previously, it was only present if event_types included zulip_version.

• zulip_merge_base: string

  The git merge-base between zulip_version 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' profiles.

  • id: integer

    The ID of the custom profile field. This will be referenced in the custom 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 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
    • 8: Pronouns

    Changes: Field type 8 added in Zulip 6.0 (feature level 151).

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

  • display_in_profile_summary: boolean

    Whether the custom profile field, display or not on the user card.

    Currently it's value not allowed to be true of Long text and Person picker profile field types.

    This field is only included when its value is true.

    Changes: New in Zulip 6.0 (feature level 146).

  • required: boolean

    Whether an organization administrator has configured this profile field as required.

    Because the required property is mutable, clients cannot assume that a required custom profile field has a value. The Zulip web application displays a prominent banner to any user who has not set a value for a required field.

    Changes: New in Zulip 9.0 (feature level 244).

  • editable_by_user: boolean

    Whether regular users can edit this profile field on their own account.

    Note that organization administrators can edit custom profile fields for any user regardless of this setting.

    Changes: New in Zulip 10.0 (feature level 296).

• 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 an ID and the type property of a custom profile field is equal to one of these IDs.

  This attribute is only useful for clients containing UI for changing the set of configured custom profile fields in a Zulip organization.

  • {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.
    • SELECT for a list of options.
    • URL for links.
    • EXTERNAL_ACCOUNT for external accounts.
    • USER for selecting a user for the field.
    • PRONOUNS for a short text field with convenient typeahead for one's preferred pronouns.

    Changes: PRONOUNS type added in Zulip 6.0 (feature level 151).

    • id: integer

      The ID of the custom profile field type.

    • name: string

      The name of the custom profile field type.

• realm_date_created: integer

  The UNIX timestamp (UTC) for when the organization was created.

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

• 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 one-on-one and group direct messages).

  • to: (integer)[]

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

  • topic: string

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

  • content: string

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

  • timestamp: integer

    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.

• onboarding_steps: (object)[]

  Present if onboarding_steps is present in fetch_event_types.

  An array of dictionaries, where each dictionary contains details about a single onboarding step that should be shown to the user.

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

  Changes: Before Zulip 8.0 (feature level 233), this array was named hotspots. Prior to this feature level, one-time notice onboarding steps were not supported, and the type field in these objects did not exist as all onboarding steps were implicitly hotspots.

  • type: string

    The type of the onboarding step. Valid value is "one_time_notice".

    Changes: Removed type "hotspot" in Zulip 9.0 (feature level 259).

    New in Zulip 8.0 (feature level 233).

  • name: string

    The name of the onboarding step.

• 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 channel name, in Unicode code points. Clients should use this property rather than hardcoding field sizes.

  Changes: New in Zulip 4.0 (feature level 53). Previously, this required stream in fetch_event_types, was called stream_name_max_length, and always had a value of 60.

• max_stream_description_length: integer

  Present if realm is present in fetch_event_types.

  The maximum allowed length for a channel description, in Unicode code points. Clients should use this property rather than hardcoding field sizes.

  Changes: New in Zulip 4.0 (feature level 53). Previously, this required stream in fetch_event_types, was called stream_description_max_length, and always had a value of 1024.

• max_topic_length: integer

  Present if realm is present in fetch_event_types.

  The maximum allowed length for a topic, in Unicode code points. Clients should use this property rather than hardcoding field sizes.

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

• max_message_length: integer

  Present if realm is present in fetch_event_types.

  The maximum allowed length for a message, in Unicode code points. Clients should use this property rather than hardcoding field sizes.

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

• server_presence_ping_interval_seconds: integer

  For clients implementing the presence system, the time interval the client should use for sending presence requests to the server (and thus receive presence updates from the server).

  It is important for presence implementations to use both this and server_presence_offline_threshold_seconds correctly, so that a Zulip server can change these values to manage the trade-off between load and freshness of presence data.

  Changes: New in Zulip 7.0 (feature level 164). Clients should use 60 for older Zulip servers, since that's the value that was hardcoded in the Zulip mobile apps prior to this parameter being introduced.

• server_presence_offline_threshold_seconds: integer

  How old a presence timestamp for a given user can be before the user should be displayed as offline by clients displaying Zulip presence data. See the related server_presence_ping_interval_seconds for details.

  Changes: New in Zulip 7.0 (feature level 164). Clients should use 140 for older Zulip servers, since that's the value that was hardcoded in the Zulip client apps prior to this parameter being introduced.

• server_typing_started_expiry_period_milliseconds: integer

  For clients implementing typing notifications protocol, the time interval in milliseconds that the client should wait for additional typing start events from the server before removing an active typing indicator.

  Changes: New in Zulip 8.0 (feature level 204). Clients should use 15000 for older Zulip servers, since that's the value that was hardcoded in the Zulip apps prior to this parameter being introduced.

• server_typing_stopped_wait_period_milliseconds: integer

  For clients implementing typing notifications protocol, the time interval in milliseconds that the client should wait when a user stops interacting with the compose UI before sending a stop notification to the server.

  Changes: New in Zulip 8.0 (feature level 204). Clients should use 5000 for older Zulip servers, since that's the value that was hardcoded in the Zulip apps prior to this parameter being introduced.

• server_typing_started_wait_period_milliseconds: integer

  For clients implementing typing notifications protocol, the time interval in milliseconds that the client should use to send regular start notifications to the server to indicate that the user is still actively interacting with the compose UI.

  Changes: New in Zulip 8.0 (feature level 204). Clients should use 10000 for older Zulip servers, since that's the value that was hardcoded in the Zulip apps prior to this parameter being introduced.

• scheduled_messages: (object)[]

  Present if scheduled_messages is present in fetch_event_types.

  An array of all undelivered scheduled messages by the user.

  Changes: New in Zulip 7.0 (feature level 179).

  • scheduled_message_id: integer

    The unique ID of the scheduled message, which can be used to modify or delete the scheduled message.

    This is different from the unique ID that the message will have after it is sent.

  • type: string

    The type of the scheduled message. Either "stream" or "private".

  • to: integer | (integer)[]

    The scheduled message's tentative target audience.

    For channel messages, it will be the unique ID of the target channel. For direct messages, it will be an array with the target users' IDs.

  • topic: string

    Only present if type is "stream".

    The topic for the channel message.

  • content: string

    The content/body of the scheduled message, in text/markdown format.

  • rendered_content: string

    The content/body of the scheduled message rendered in HTML.

  • scheduled_delivery_timestamp: integer

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

  • failed: boolean

    Whether the server has tried to send the scheduled message and it failed to successfully send.

    Clients that support unscheduling and editing scheduled messages should display scheduled messages with "failed": true with an indicator that the server failed to send the message at the scheduled time, so that the user is aware of the failure and can get the content of the scheduled message.

    Changes: New in Zulip 7.0 (feature level 181).

• 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 the tuple is the channel name in which the topic has to be muted, the second element is the topic name to be muted and the third element is an integer UNIX timestamp representing when the topic was muted.

  Changes: Deprecated in Zulip 6.0 (feature level 134). Starting with this version, muted_topics will only be present in the response if the user_topic object, which generalizes and replaces this field, is not explicitly requested via fetch_event_types.

  Before Zulip 3.0 (feature level 1), the muted_topics array objects were 2-item tuples and did not include the timestamp information for when the topic was muted.

• 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 of a user in the Zulip organization.

  The format of the entry (modern or legacy) depends on the value of slim_presence.

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

  • Will be one of these two formats (modern or legacy) for user presence data:

    • {user_id}: object

      Presence data (modern format) for the user with the specified ID.

      • active_timestamp: integer

        The UNIX timestamp of the last time a client connected to Zulip reported that the user was actually present (e.g. via focusing a browser window or interacting with a computer running the desktop app).

        Clients should display users with a current active_timestamp as fully present.

      • idle_timestamp: integer

        The UNIX timestamp of the last time the user had a client connected to Zulip, including idle clients where the user hasn't interacted with the system recently.

        The Zulip server has no way of distinguishing whether an idle web app user is at their computer, but hasn't interacted with the Zulip tab recently, or simply left their desktop computer on when they left.

        Thus, clients should display users with a current idle_timestamp but no current active_timestamp as potentially present.

    • {user_email}: object

      Presence data (legacy format) for the user with the specified Zulip API email.

      • {client_name} or "aggregated": object

        Object containing the details of the user's presence.

        Changes: Starting with Zulip 7.0 (feature level 178), this will always contain two keys, "website" and "aggregated", with identical data. The server no longer stores which client submitted presence updates.

        Previously, the {client_name} keys for these objects were the names of the different clients where the user was logged in, for example website or ZulipDesktop.

        • client: string

          The client's platform name.

          Changes: Starting with Zulip 7.0 (feature level 178), this will always be "website" as the server no longer stores which client submitted presence data.

        • status: string

          The status of the user on this client. Will be 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.

          Not present in objects with the "aggregated" key.

          Changes: Starting with Zulip 7.0 (feature level 178), always false when present as the server no longer stores which client submitted presence data.

• presence_last_update_id: integer

  Present if presence is present in fetch_event_types.

  Provides the last_update_id value of the latest presence data fetched by the server and included in the response in presences. This can be used as the value of the presence_last_update_id parameter when polling for presence data at the /users/me/presence endpoint to tell the server to only fetch the relevant newer data in order to skip redundant already-known presence information.

  Changes: New in Zulip 9.0 (feature level 263).

• server_timestamp: 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

  Present if realm_emoji is present in fetch_event_types.

  A dictionary of objects where each object describes a custom emoji that has been uploaded in this Zulip organization.

  • {emoji_id}: object

    Object containing details about the emoji with the specified ID. It has the following properties:

    • id: string

      The ID for this emoji, same as the object's key.

    • name: string

      The user-friendly name for this emoji. Users in the organization can use this emoji by writing this name between colons (:name :).

    • source_url: string

      The path relative to the organization's URL where the emoji's image can be found.

    • still_url: string | null

      Only non-null when the emoji's image is animated.

      The path relative to the organization's URL where a still (not animated) version of the emoji can be found. (This is currently always the first frame of the animation).

      This is useful for clients to display the emoji in contexts where continuously animating it would be a bad user experience (E.g. because it would be distracting).

      Changes: New in Zulip 5.0 (added as optional field in feature level 97 and then made mandatory, but nullable, in feature level 113).

    • deactivated: boolean

      Whether the emoji has been deactivated or not.

    • author_id: integer | null

      The user ID of the user who uploaded the custom emoji. Will be null if the uploader is unknown.

      Changes: New in Zulip 3.0 (feature level 7). Previously was accessible via an author object with an id field.

• realm_linkifiers: (object)[]

  Present if realm_linkifiers is present in fetch_event_types.

  An ordered array of objects where each object describes a single linkifier.

  The order of the array reflects the order that each linkifier should be processed when linkifying messages and topics. By default, new linkifiers are ordered last. This order can be modified with PATCH /realm/linkifiers.

  Clients will receive an empty array unless the event queue is registered with the client capability {"linkifier_url_template": true}. See client_capabilities parameter for how this can be specified.

  Changes: Before Zulip 7.0 (feature level 176), the linkifier_url_template client capability was not required. The requirement was added because linkifiers were updated to contain a URL template instead of a URL format string, which was a not backwards-compatible change.

  New in Zulip 4.0 (feature level 54). Clients can access this data for servers on earlier feature levels via the legacy realm_filters property.

  • pattern: string

    The Python regular expression pattern which represents the pattern that should be linkified on matching.

  • url_template: string

    The RFC 6570 compliant URL template with which the pattern matching string should be linkified.

    Changes: New in Zulip 7.0 (feature level 176). This replaced url_format, which contained a URL format string.

  • id: integer

    The ID of the linkifier.

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

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

  When present, this is always an empty array.

  Changes: Prior to Zulip 7.0 (feature level 176), this was an array of tuples, where each tuple described a linkifier. The first element of the tuple was a string regex pattern which represented the pattern to be linkified on matching, for example "#(?P<id>[123])". The second element was a URL format string that the pattern should be linkified with. A URL format string for the above example would be "https://realm.com/my_realm_filter/%(id)s". And the third element was the ID of the realm filter.

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

• realm_playgrounds: (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_template: string

    The RFC 6570 compliant URL template for the playground. The template contains exactly one variable named code, which determines how the extracted code should be substituted in the playground URL.

    Changes: New in Zulip 8.0 (feature level 196). This replaced the url_prefix parameter, which was used to construct URLs by just concatenating url_prefix and code.

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

  Deactivated groups will only be included if include_deactivated_groups client capability is set to true.

  Changes: Prior to Zulip 10.0 (feature level 294), deactivated groups were included for all the clients.

  • name: string

    The name of the user group.

  • date_created: integer | null

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

    A null value means the user group has no recorded date, which is often because the user group is very old, or because it was created via a data import tool or management command.

    Changes: New in Zulip 10.0 (feature level 292).

  • creator_id: integer | null

    The ID of the user who created this user group.

    A null value means the user group has no recorded creator, which is often because the user group is very old, or because it was created via a data import tool or management command.

    Changes: New in Zulip 10.0 (feature level 292).

  • description: string

    The description of the user group.

  • members: (integer)[]

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

    Changes: Prior to Zulip 10.0 (feature level 303), this list also included deactivated users who were members of the user group before being deactivated.

  • direct_subgroup_ids: (integer)[]

    Array containing the ID of the direct_subgroups of this user group.

    Changes: New in Zulip 6.0 (feature level 131). Introduced in feature level 127 as subgroups, but clients can ignore older events as this feature level predates subgroups being fully implemented.

  • id: 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).

  • can_add_members_group: integer | object

    A group-setting value defining the set of users who have permission to add members to this user group.

    Changes: New in Zulip 10.0 (feature level 305). Previously, this permission was controlled by the can_manage_group setting.

    Will be one of the following:

    • The ID of the user group with this permission.

    • An object with these fields:

      • direct_members: (integer)[]

        The list of IDs of individual users in the collection of users with this permission.

        Changes: Prior to Zulip 10.0 (feature level 303), this list would include deactivated users who had the permission before being deactivated.

      • direct_subgroups: (integer)[]

        The list of IDs of the groups in the collection of users with this permission.

  • can_join_group: integer | object

    A group-setting value defining the set of users who have permission to join this user group.

    Changes: New in Zulip 10.0 (feature level 301).

    Will be one of the following:

    • The ID of the user group with this permission.

    • An object with these fields:

      • direct_members: (integer)[]

        The list of IDs of individual users in the collection of users with this permission.

        Changes: Prior to Zulip 10.0 (feature level 303), this list would include deactivated users who had the permission before being deactivated.

      • direct_subgroups: (integer)[]

        The list of IDs of the groups in the collection of users with this permission.

  • can_leave_group: integer | object

    A group-setting value defining the set of users who have permission to leave this user group.

    Changes: New in Zulip 10.0 (feature level 308).

    Will be one of the following:

    • The ID of the user group with this permission.

    • An object with these fields:

      • direct_members: (integer)[]

        The list of IDs of individual users in the collection of users with this permission.

        Changes: Prior to Zulip 10.0 (feature level 303), this list would include deactivated users who had the permission before being deactivated.

      • direct_subgroups: (integer)[]

        The list of IDs of the groups in the collection of users with this permission.

  • can_manage_group: integer | object

    A group-setting value defining the set of users who have permission to manage this user group.

    Changes: New in Zulip 10.0 (feature level 283).

    Will be one of the following:

    • The ID of the user group with this permission.

    • An object with these fields:

      • direct_members: (integer)[]

        The list of IDs of individual users in the collection of users with this permission.

        Changes: Prior to Zulip 10.0 (feature level 303), this list would include deactivated users who had the permission before being deactivated.

      • direct_subgroups: (integer)[]

        The list of IDs of the groups in the collection of users with this permission.

  • can_mention_group: integer | object

    A group-setting value defining the set of users who have permission to mention this user group.

    Changes: Before Zulip 9.0 (feature level 258), this setting was always the integer form of a group-setting value.

    Before Zulip 8.0 (feature level 198), this setting was named can_mention_group_id.

    New in Zulip 8.0 (feature level 191). Previously, groups could be mentioned only if they were not system groups.

    Will be one of the following:

    • The ID of the user group with this permission.

    • An object with these fields:

      • direct_members: (integer)[]

        The list of IDs of individual users in the collection of users with this permission.

        Changes: Prior to Zulip 10.0 (feature level 303), this list would include deactivated users who had the permission before being deactivated.

      • direct_subgroups: (integer)[]

        The list of IDs of the groups in the collection of users with this permission.

  • deactivated: boolean

    Whether the user group is deactivated. Deactivated groups cannot be used as a subgroup of another group or used for any other purpose.

    Changes: New in Zulip 10.0 (feature level 290).

• 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 channel of the bot. If null, the bot doesn't have a default sending channel.

  • default_events_register_stream: string | null

    The default channel for which the bot receives events/register data. If null, the bot doesn't have such a default channel.

  • default_all_public_streams: boolean

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

  • avatar_url: string

    The URL of the bot's avatar.

  • owner_id: integer | null

    The user ID of the bot's owner.

    If null, the bot has no owner.

  • services: (object | object)[]

    An array containing extra configuration fields only relevant for outgoing webhook bots and embedded bots. This is always a single-element array.

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

    • When the bot is an outgoing webhook.

      • base_url: string

        The URL the outgoing webhook is configured to post to.

      • token: string

        A unique token that the third-party service can use to confirm that the request is indeed coming from Zulip.

      • interface: integer

        An integer indicating what format requests are posted in:

        • 1 = Zulip's native outgoing webhook format.
        • 2 = Emulate the Slack outgoing webhook format.

    • When the bot is an embedded bot.

      • service_name: string

        The name of the bot.

      • config_data: object

        A dictionary of string key/value pairs, which describe the configuration for the bot. These are usually details like API keys, and are unique to the integration/bot. Can be an empty dictionary.

        • {config_key}: string

          Description/value of the configuration data key.

  • 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 dictionary of string key/value pairs, which describe the configuration for the bot. These are usually details like API keys, and are unique to the integration/bot. Can be an empty dictionary.

    • {config_key}: string

      Description/value of the configuration data key.

• 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 a type of incoming webhook integration that is available to be configured on this Zulip server.

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

  • name: string

    A machine-readable unique name identifying the integration, all-lower-case without spaces.

  • display_name: string

    A human-readable display name identifying the integration that this bot implements, intended to be used in menus for selecting which integration to create.

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

  • all_event_types: (string)[]

    For incoming webhook integrations that support the Zulip server filtering incoming events, the list of event types supported by it.

    A null value will be present if this incoming webhook integration doesn't support such filtering.

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

  • config_options: (object)[]

    An array of configuration options where each option is an object containing a unique identifier, a human-readable name, and a validation function name hinting how to verify the correct input format.

    This is an unstable API expected to be used only by the Zulip web apps. Please discuss in chat.zulip.org before using it.

    Changes: New in Zulip 10.0 (feature level 318).

    • key: string

      A key for the configuration option to use in generated URLs.

    • label: string

      A human-readable label of the configuration option.

    • validator: string

      The name of the validator function for the configuration option. Currently generated values are check_bool and check_str.

• recent_private_conversations: (object)[]

  Present if recent_private_conversations is present in fetch_event_types.

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

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

  • 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 direct message conversation. This will be an empty list for direct messages sent to oneself.

• saved_snippets: (object)[]

  Present if saved_snippets is present in fetch_event_types.

  An array of dictionaries containing data on all of the current user's saved snippets.

  Changes: New in Zulip 10.0 (feature level 297).

  • id: integer

    The unique ID of the saved snippet.

  • title: string

    The title of the saved snippet.

  • content: string

    The content of the saved snippet in text/markdown format.

    Clients should insert this content into a message when using a saved snippet.

  • date_created: integer

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

• subscriptions: (object)[]

  Present if subscription is present in fetch_event_types.

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

  Changes: Removed email_address field from the dictionary in Zulip 8.0 (feature level 226).

  Removed role field from the dictionary in Zulip 6.0 (feature level 133).

  • stream_id: integer

    The unique ID of a channel.

  • name: string

    The name of a channel.

  • description: string

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

    See also rendered_description.

  • rendered_description: string

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

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

    See also description.

  • date_created: integer

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

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

  • creator_id: integer | null

    The ID of the user who created this channel.

    A null value means the channel has no recorded creator, which is often because the channel is very old, or because it was created via a data import tool or management command.

    Changes: New in Zulip 9.0 (feature level 254).

  • invite_only: boolean

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

  • subscribers: (integer)[]

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

  • desktop_notifications: boolean | null

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

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

  • email_notifications: boolean | null

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

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

  • wildcard_mentions_notify: boolean | null

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

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

  • push_notifications: boolean | null

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

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

  • audible_notifications: boolean | null

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

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

  • pin_to_top: boolean

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

  • is_muted: boolean

    Whether the user has muted the channel. Muted channels do not count towards your total unread count and do not show up in the Combined feed view (previously known as All messages).

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

  • in_home_view: boolean

    Legacy property for if the given channel is muted, with inverted meaning.

    Changes: Deprecated in Zulip 2.1.0. Clients should use is_muted where available.

  • is_announcement_only: boolean

    Whether only organization administrators can post to the channel.

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

  • is_web_public: boolean

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

  • color: string

    The user's personal color for the channel.

  • stream_post_policy: integer

    Policy for which users can post messages to the channel.

    • 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 (feature level 1), replacing the previous is_announcement_only boolean.

  • message_retention_days: integer | null

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

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

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

  • history_public_to_subscribers: boolean

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

    Currently always true for public channels (i.e. "invite_only": false implies "history_public_to_subscribers": true), but clients should not make that assumption, as we may change that behavior in the future.

  • first_message_id: integer | null

    The ID of the first message in the channel.

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

    Is null for channels with no message history.

  • stream_weekly_traffic: integer | null

    The average number of messages sent to the channel per week, as estimated based on recent weeks, rounded to the nearest integer.

    If null, the channel was recently created and there is insufficient data to estimate the average traffic.

  • can_remove_subscribers_group: integer

    ID of the user group whose members are allowed to unsubscribe others from the channel.

    Changes: Before Zulip 8.0 (feature level 197), the can_remove_subscribers_group setting was named can_remove_subscribers_group_id.

    New in Zulip 6.0 (feature level 142).

  • is_archived: boolean

    A boolean indicating whether the channel is archived.

    Changes: New in Zulip 10.0 (feature level 315). Previously, subscriptions only included active channels. Note that some endpoints will never return archived channels unless the client declares explicit support for them via the archived_channels client capability.

• unsubscribed: (object)[]

  Present if subscription is present in fetch_event_types.

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

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

  Changes: Removed email_address field from the dictionary in Zulip 8.0 (feature level 226).

  Removed role field from the dictionary in Zulip 6.0 (feature level 133).

  • stream_id: integer

    The unique ID of a channel.

  • name: string

    The name of a channel.

  • description: string

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

    See also rendered_description.

  • rendered_description: string

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

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

    See also description.

  • date_created: integer

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

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

  • creator_id: integer | null

    The ID of the user who created this channel.

    A null value means the channel has no recorded creator, which is often because the channel is very old, or because it was created via a data import tool or management command.

    Changes: New in Zulip 9.0 (feature level 254).

  • invite_only: boolean

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

  • subscribers: (integer)[]

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

  • desktop_notifications: boolean | null

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

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

  • email_notifications: boolean | null

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

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

  • wildcard_mentions_notify: boolean | null

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

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

  • push_notifications: boolean | null

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

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

  • audible_notifications: boolean | null

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

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

  • pin_to_top: boolean

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

  • is_muted: boolean

    Whether the user has muted the channel. Muted channels do not count towards your total unread count and do not show up in the Combined feed view (previously known as All messages).

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

  • in_home_view: boolean

    Legacy property for if the given channel is muted, with inverted meaning.

    Changes: Deprecated in Zulip 2.1.0. Clients should use is_muted where available.

  • is_announcement_only: boolean

    Whether only organization administrators can post to the channel.

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

  • is_web_public: boolean

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

  • color: string

    The user's personal color for the channel.

  • stream_post_policy: integer

    Policy for which users can post messages to the channel.

    • 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 (feature level 1), replacing the previous is_announcement_only boolean.

  • message_retention_days: integer | null

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

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

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

  • history_public_to_subscribers: boolean

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

    Currently always true for public channels (i.e. "invite_only": false implies "history_public_to_subscribers": true), but clients should not make that assumption, as we may change that behavior in the future.

  • first_message_id: integer | null

    The ID of the first message in the channel.

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

    Is null for channels with no message history.

  • stream_weekly_traffic: integer | null

    The average number of messages sent to the channel per week, as estimated based on recent weeks, rounded to the nearest integer.

    If null, the channel was recently created and there is insufficient data to estimate the average traffic.

  • can_remove_subscribers_group: integer

    ID of the user group whose members are allowed to unsubscribe others from the channel.

    Changes: Before Zulip 8.0 (feature level 197), the can_remove_subscribers_group setting was named can_remove_subscribers_group_id.

    New in Zulip 6.0 (feature level 142).

  • is_archived: boolean

    A boolean indicating whether the channel is archived.

    Changes: New in Zulip 10.0 (feature level 315). Previously, subscriptions only included active channels. Note that some endpoints will never return archived channels unless the client declares explicit support for them via the archived_channels client capability.

• never_subscribed: (object)[]

  Present if subscription is present in fetch_event_types.

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

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

  • stream_id: integer

    The unique ID of the channel.

  • name: string

    The name of the channel.

  • is_archived: boolean

    A boolean indicating whether the channel is archived.

    Changes: New in Zulip 10.0 (feature level 315). Previously, this endpoint never returned archived channels.

  • description: string

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

  • date_created: integer

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

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

  • creator_id: integer | null

    The ID of the user who created this channel.

    A null value means the channel has no recorded creator, which is often because the channel is very old, or because it was created via a data import tool or management command.

    Changes: New in Zulip 9.0 (feature level 254).

  • invite_only: boolean

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

  • rendered_description: string

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

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

  • is_web_public: boolean

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

    Changes: New in Zulip 2.1.0.

  • stream_post_policy: integer

    Policy for which users can post messages to the channel.

    • 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 (feature level 1), replacing the previous is_announcement_only boolean.

  • message_retention_days: integer | null

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

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

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

  • history_public_to_subscribers: boolean

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

    Currently always true for public channels (i.e. "invite_only": false implies "history_public_to_subscribers": true), but clients should not make that assumption, as we may change that behavior in the future.

  • first_message_id: integer | null

    The ID of the first message in the channel.

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

    Is null for channels with no message history.

    Changes: New in Zulip 2.1.0.

  • is_announcement_only: boolean

    Whether the given channel is announcement only or not.

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

  • can_remove_subscribers_group: integer

    ID of the user group whose members are allowed to unsubscribe others from the channel.

    Changes: Before Zulip 8.0 (feature level 197), the can_remove_subscribers_group setting was named can_remove_subscribers_group_id.

    New in Zulip 6.0 (feature level 142).

  • stream_weekly_traffic: integer | null

    The average number of messages sent to the channel per week, as estimated based on recent weeks, rounded to the nearest integer.

    If null, the channel was recently created and there is insufficient data to estimate the average traffic.

  • subscribers: (integer)[]

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

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

• 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 one-on-one and group direct messages, as well as channel messages that are not muted.

    Changes: Before Zulip 8.0 (feature level 213), the unmute and follow topic features were not handled correctly in calculating this field.

  • pms: (object)[]

    An array of objects where each object contains details of unread one-on-one direct messages with a specific user.

    Note that it is possible for a message that the current user sent to the specified user to be marked as unread and thus appear here.

    • other_user_id: integer

      The user ID of the other participant in this one-on-one direct message conversation. Will be the current user's ID for messages that they sent in a one-on-one direct message conversation with themself.

      Changes: New in Zulip 5.0 (feature level 119), replacing the less clearly named sender_id field.

    • sender_id: integer

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

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

    • unread_message_ids: (integer)[]

      The message IDs of the recent unread direct messages sent by either user in this one-on-one direct message conversation, sorted in ascending order.

  • streams: (object)[]

    An array of dictionaries where each dictionary contains details of all unread messages of a single subscribed channel. This includes muted channels and muted topics, even though those messages are excluded from count.

    Changes: Prior to Zulip 5.0 (feature level 90), these objects included a sender_ids property, which listed the set of IDs of users who had sent the unread messages.

    • topic: string

      The topic under which the messages were sent.

    • stream_id: integer

      The ID of the channel to which the messages were sent.

    • unread_message_ids: (integer)[]

      The message IDs of the recent unread messages sent in this channel, sorted in ascending order.

  • huddles: (object)[]

    An array of objects where each object contains details of unread group direct messages with a specific group of users.

    • user_ids_string: string

      A string containing the IDs of all users in the group direct message conversation, including the current user, separated by commas and sorted numerically; for example: "1,2,3".

    • unread_message_ids: (integer)[]

      The message IDs of the recent unread messages which have been sent in this group direct message conversation, sorted in ascending order.

  • mentions: (integer)[]

    Array containing the IDs of all unread messages in which the user was mentioned directly, and unread non-muted messages in which the user was mentioned through a wildcard.

    Changes: Before Zulip 8.0 (feature level 213), the unmute and follow topic features were not handled correctly in calculating this field.

  • old_unreads_missing: boolean

    Whether this data set was truncated because the user has too many unread messages. When truncation occurs, only the most recent MAX_UNREAD_MESSAGES (currently 50000) messages will be considered when forming this response. When true, we recommend that clients display a warning, as they are likely to produce erroneous results until reloaded with the user having fewer than MAX_UNREAD_MESSAGES unread messages.

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

• starred_messages: (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 channel in the organization that is visible to the user.

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

  Changes: As of Zulip 8.0 (feature level 205), this will include all web-public channels in the organization as well.

  • stream_id: integer

    The unique ID of the channel.

  • name: string

    The name of the channel.

  • is_archived: boolean

    A boolean indicating whether the channel is archived.

    Changes: New in Zulip 10.0 (feature level 315). Previously, this endpoint never returned archived channels.

  • description: string

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

  • date_created: integer

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

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

  • creator_id: integer | null

    The ID of the user who created this channel.

    A null value means the channel has no recorded creator, which is often because the channel is very old, or because it was created via a data import tool or management command.

    Changes: New in Zulip 9.0 (feature level 254).

  • invite_only: boolean

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

  • rendered_description: string

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

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

  • is_web_public: boolean

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

    Changes: New in Zulip 2.1.0.

  • stream_post_policy: integer

    Policy for which users can post messages to the channel.

    • 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 (feature level 1), replacing the previous is_announcement_only boolean.

  • message_retention_days: integer | null

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

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

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

  • history_public_to_subscribers: boolean

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

    Currently always true for public channels (i.e. "invite_only": false implies "history_public_to_subscribers": true), but clients should not make that assumption, as we may change that behavior in the future.

  • first_message_id: integer | null

    The ID of the first message in the channel.

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

    Is null for channels with no message history.

    Changes: New in Zulip 2.1.0.

  • is_announcement_only: boolean

    Whether the given channel is announcement only or not.

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

  • can_remove_subscribers_group: integer

    ID of the user group whose members are allowed to unsubscribe others from the channel.

    Changes: Before Zulip 8.0 (feature level 197), the can_remove_subscribers_group setting was named can_remove_subscribers_group_id.

    New in Zulip 6.0 (feature level 142).

  • stream_weekly_traffic: integer | null

    The average number of messages sent to the channel per week, as estimated based on recent weeks, rounded to the nearest integer.

    If null, no information is provided on the average traffic. This can be because the channel was recently created and there is insufficient data to make an estimate, or because the server wishes to omit this information for this client, this realm, or this endpoint or type of event.

    Changes: New in Zulip 8.0 (feature level 199). Previously, this statistic was available only in subscription objects.

• 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 channel for the Zulip organization.

  • stream_id: integer

    The unique ID of the channel.

  • name: string

    The name of the channel.

  • is_archived: boolean

    A boolean indicating whether the channel is archived.

    Changes: New in Zulip 10.0 (feature level 315). Previously, this endpoint never returned archived channels.

  • description: string

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

  • date_created: integer

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

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

  • creator_id: integer | null

    The ID of the user who created this channel.

    A null value means the channel has no recorded creator, which is often because the channel is very old, or because it was created via a data import tool or management command.

    Changes: New in Zulip 9.0 (feature level 254).

  • invite_only: boolean

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

  • rendered_description: string

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

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

  • is_web_public: boolean

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

    Changes: New in Zulip 2.1.0.

  • stream_post_policy: integer

    Policy for which users can post messages to the channel.

    • 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 (feature level 1), replacing the previous is_announcement_only boolean.

  • message_retention_days: integer | null

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

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

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

  • history_public_to_subscribers: boolean

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

    Currently always true for public channels (i.e. "invite_only": false implies "history_public_to_subscribers": true), but clients should not make that assumption, as we may change that behavior in the future.

  • first_message_id: integer | null

    The ID of the first message in the channel.

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

    Is null for channels with no message history.

    Changes: New in Zulip 2.1.0.

  • is_announcement_only: boolean

    Whether the given channel is announcement only or not.

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

  • can_remove_subscribers_group: integer

    ID of the user group whose members are allowed to unsubscribe others from the channel.

    Changes: Before Zulip 8.0 (feature level 197), the can_remove_subscribers_group setting was named can_remove_subscribers_group_id.

    New in Zulip 6.0 (feature level 142).

• 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 channel group configured for this Zulip organization.

  Default channel groups are an experimental feature.

  • name: string

    Name of the default channel group.

  • description: string

    Description of the default channel group.

  • id: integer

    The ID of the default channel group.

  • streams: (object)[]

    Array containing details about the channels in the default channel group.

    • stream_id: integer

      The unique ID of the channel.

    • name: string

      The name of the channel.

    • is_archived: boolean

      A boolean indicating whether the channel is archived.

      Changes: New in Zulip 10.0 (feature level 315). Previously, this endpoint never returned archived channels.

    • description: string

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

    • date_created: integer

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

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

    • creator_id: integer | null

      The ID of the user who created this channel.

      A null value means the channel has no recorded creator, which is often because the channel is very old, or because it was created via a data import tool or management command.

      Changes: New in Zulip 9.0 (feature level 254).

    • invite_only: boolean

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

    • rendered_description: string

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

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

    • is_web_public: boolean

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

      Changes: New in Zulip 2.1.0.

    • stream_post_policy: integer

      Policy for which users can post messages to the channel.

      • 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 (feature level 1), replacing the previous is_announcement_only boolean.

    • message_retention_days: integer | null

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

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

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

    • history_public_to_subscribers: boolean

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

      Currently always true for public channels (i.e. "invite_only": false implies "history_public_to_subscribers": true), but clients should not make that assumption, as we may change that behavior in the future.

    • first_message_id: integer | null

      The ID of the first message in the channel.

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

      Is null for channels with no message history.

      Changes: New in Zulip 2.1.0.

    • is_announcement_only: boolean

      Whether the given channel is announcement only or not.

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

    • can_remove_subscribers_group: integer

      ID of the user group whose members are allowed to unsubscribe others from the channel.

      Changes: Before Zulip 8.0 (feature level 197), the can_remove_subscribers_group setting was named can_remove_subscribers_group_id.

      New in Zulip 6.0 (feature level 142).

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

  • {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

      If present, the user has marked themself "away".

      Changes: Deprecated in Zulip 6.0 (feature level 148); starting with that feature level, away is a legacy way to access the user's presence_enabled setting, with away = !presence_enabled. To be removed in a future release.

    • status_text: string

      If present, the text content of the user's status message.

    • emoji_name: string

      If present, the name for the emoji to associate with the user's status.

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

    • emoji_code: string

      If present, a unique identifier, defining the specific emoji codepoint requested, within the namespace of the reaction_type.

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

    • reaction_type: string

      If present, a string indicating the type of emoji. Each emoji reaction_type has an independent namespace for values of emoji_code.

      Must be one of the following values:

      • unicode_emoji : In this namespace, emoji_code will be a dash-separated hex encoding of the sequence of Unicode codepoints that define this emoji in the Unicode specification.

      • realm_emoji : In this namespace, emoji_code will be the ID of the uploaded custom emoji.

      • zulip_extra_emoji : These are special emoji included with Zulip. In this namespace, emoji_code will be the name of the emoji (e.g. "zulip").

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

• user_settings: 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.

  • web_mark_read_on_scroll_policy: integer

    Whether or not to mark messages as read when the user scrolls through their feed.

    • 1 - Always
    • 2 - Only in conversation views
    • 3 - Never

    Changes: New in Zulip 7.0 (feature level 175). Previously, there was no way for the user to configure this behavior on the web, and the Zulip web and desktop apps behaved like the "Always" setting when marking messages as read.

  • web_channel_default_view: integer

    Web/desktop app setting controlling the default navigation behavior when clicking on a channel link.

    • 1 - Top topic in the channel
    • 2 - Channel feed

    Changes: New in Zulip 9.0 (feature level 269). Previously, this was not configurable, and every user had the "Channel feed" behavior.

  • starred_message_counts: boolean

    Whether clients should display the number of starred messages.

  • receives_typing_notifications: boolean

    Whether the user is configured to receive typing notifications from other users. The server will only deliver typing notifications events to users who for whom this is enabled.

    Changes: New in Zulip 9.0 (feature level 253). Previously, there were only options to disable sending typing notifications.

  • fluid_layout_width: boolean

    Whether to use the maximum available screen width for the web app's center panel (message feed, recent conversations) 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.

  • web_font_size_px: integer

    User-configured primary font-size for the web application, in pixels.

    Changes: New in Zulip 9.0 (feature level 245). Previously, font size was only adjustable via browser zoom. Note that this setting was not fully implemented at this feature level.

  • web_line_height_percent: integer

    User-configured primary line-height for the web application, in percent, so a value of 120 represents a line-height of 1.2.

    Changes: New in Zulip 9.0 (feature level 245). Previously, line height was not user-configurable. Note that this setting was not fully implemented at this feature level.

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

  • display_emoji_reaction_users: boolean

    Whether to display the names of reacting users on a message.

    When enabled, clients should display the names of reacting users, rather than a count, for messages with few total reactions. The ideal cutoff may depend on the space available for displaying reactions; the official web application displays names when 3 or fewer total reactions are present with this setting enabled.

    Changes: New in Zulip 6.0 (feature level 125).

  • default_language: 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.

  • web_home_view: string

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

    • "recent_topics" - Recent conversations view
    • "inbox" - Inbox view
    • "all_messages" - Combined feed view

    Changes: New in Zulip 8.0 (feature level 219). Previously, this was called default_view, which was new in Zulip 4.0 (feature level 42).

  • web_escape_navigates_to_home_view: boolean

    Whether the escape key navigates to the configured home view.

    Changes: New in Zulip 8.0 (feature level 219). Previously, this was called escape_navigates_to_default_view, which was new in Zulip 5.0 (feature level 107).

  • left_side_userlist: 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 channels in the left sidebar.

    • 1 - Automatic
    • 2 - Always
    • 3 - Never

  • user_list_style: integer

    The style selected by the user for the right sidebar user list.

    • 1 - Compact
    • 2 - With status
    • 3 - With avatar and status

    Changes: New in Zulip 6.0 (feature level 141).

  • web_animate_image_previews: string

    Controls how animated images should be played in the message feed in the web/desktop application.

    • "always" - Always play the animated images in the message feed.
    • "on_hover" - Play the animated images on hover over them in the message feed.
    • "never" - Never play animated images in the message feed.

    Changes: New in Zulip 9.0 (feature level 275).

  • web_stream_unreads_count_display_policy: integer

    Configuration for which channels should be displayed with a numeric unread count in the left sidebar. Channels that do not have an unread count will have a simple dot indicator for whether there are any unread messages.

    • 1 - All channels
    • 2 - Unmuted channels and topics
    • 3 - No channels

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

  • timezone: string

    The IANA identifier of the user's configured time zone.

  • 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 channel messages.

  • enable_stream_email_notifications: boolean

    Enable email notifications for channel messages.

  • enable_stream_push_notifications: boolean

    Enable mobile notifications for channel messages.

  • enable_stream_audible_notifications: boolean

    Enable audible desktop notifications for channel messages.

  • notification_sound: string

    Notification sound name.

  • enable_desktop_notifications: boolean

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

  • enable_sounds: boolean

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

  • enable_followed_topic_desktop_notifications: boolean

    Enable visual desktop notifications for messages sent to followed topics.

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

  • enable_followed_topic_email_notifications: boolean

    Enable email notifications for messages sent to followed topics.

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

  • enable_followed_topic_push_notifications: boolean

    Enable push notifications for messages sent to followed topics.

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

  • enable_followed_topic_audible_notifications: boolean

    Enable audible desktop notifications for messages sent to followed topics.

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

  • 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 direct messages and @-mentions received when the user is offline.

  • enable_offline_push_notifications: boolean

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

  • enable_online_push_notifications: boolean

    Enable mobile notification for direct 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 direct messages in desktop notifications.

  • wildcard_mentions_notify: boolean

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

  • enable_followed_topic_wildcard_mentions_notify: boolean

    Whether wildcard mentions (e.g., @all) in messages sent to followed topics should send notifications like a personal mention.

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

  • desktop_icon_count_display: integer

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

    • 1 - All unread messages
    • 2 - DMs, mentions, and followed topics
    • 3 - DMs and mentions
    • 4 - None

    Changes: In Zulip 8.0 (feature level 227), added DMs, mentions, and followed topics option, renumbering the options to insert it in order.

  • realm_name_in_email_notifications_policy: integer

    Whether to include organization name in subject of message notification emails.

    • 1 - Automatic
    • 2 - Always
    • 3 - Never

    Changes: New in Zulip 7.0 (feature level 168), replacing the previous realm_name_in_notifications boolean; true corresponded to Always, and false to Never.

  • automatically_follow_topics_policy: integer

    Which topics to follow automatically.

    • 1 - Topics the user participates in
    • 2 - Topics the user sends a message to
    • 3 - Topics the user starts
    • 4 - Never

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

  • automatically_unmute_topics_in_muted_streams_policy: integer

    Which topics to unmute automatically in muted channels.

    • 1 - Topics the user participates in
    • 2 - Topics the user sends a message to
    • 3 - Topics the user starts
    • 4 - Never

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

  • automatically_follow_topics_where_mentioned: boolean

    Whether the server will automatically mark the user as following topics where the user is mentioned.

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

  • 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 direct messages. The client should send typing notifications for direct messages if and only if this setting is enabled.

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

  • send_stream_typing_notifications: boolean

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

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

  • send_read_receipts: boolean

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

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

  • allow_private_data_export: boolean

    Whether organization administrators are allowed to export your private data.

    Changes: New in Zulip 10.0 (feature level 293).

  • email_address_visibility: integer

    The policy for which other users in this organization can see the user's real email address.

    • 1 = Everyone
    • 2 = Members only
    • 3 = Administrators only
    • 4 = Nobody
    • 5 = Moderators only

    Changes: New in Zulip 7.0 (feature level 163), replacing the realm-level setting.

  • web_navigate_to_sent_message: boolean

    Web/desktop app setting for whether the user's view should automatically go to the conversation where they sent a message.

    Changes: New in Zulip 9.0 (feature level 268). Previously, this behavior was not configurable.

• user_topics: (object)[]

  Present if user_topic is present in fetch_event_types.

  Changes: New in Zulip 6.0 (feature level 134), deprecating and replacing the previous muted_topics structure.

  • stream_id: integer

    The ID of the channel to which the topic belongs.

  • topic_name: string

    The name of the topic.

  • last_updated: integer

    An integer UNIX timestamp representing when the user-topic relationship was changed.

  • visibility_policy: integer

    An integer indicating the user's visibility configuration for the topic.

    • 1 = Muted. Used to record muted topics.
    • 2 = Unmuted. Used to record unmuted topics.
    • 3 = Followed. Used to record followed topics.

    Changes: In Zulip 7.0 (feature level 219), added followed as a visibility policy option.

    In Zulip 7.0 (feature level 170), added unmuted as a visibility policy option.

• has_zoom_token: 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_email_notifications_policy: 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: In Zulip 7.0 (feature level 168), replaced previous realm_name_in_notifications global notifications setting with realm_name_in_email_notifications_policy.

  Deprecated since Zulip 5.0 (feature level 89); both realm_name_in_notifications and the newer realm_name_in_email_notifications_policy are deprecated. Clients connecting to newer servers should declare the user_settings_object client capability and access the user_settings object instead.

• 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 channels.

  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 and only for clients that did not include user_settings_object in their client_capabilities when registering the event queue.

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

  See PATCH /settings 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.

• web_home_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 home 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: New in Zulip 8.0 (feature level 219). Previously, this was called default_view, which was new in Zulip 4.0 (feature level 42).

  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.

• receives_typing_notifications: boolean

  Whether the user is configured to receive typing notifications from other users. The server will only deliver typing notifications events to users who for whom this is enabled.

  Changes: New in Zulip 9.0 (feature level 253). Previously, there were only options to disable sending typing notifications.

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

• 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_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_can_add_custom_emoji_group: integer | object

  Present if realm is present in fetch_event_types.

  A group-setting value defining the set of users who have permission to add custom emoji in the organization.

  Changes: New in Zulip 10.0 (feature level 307). Previously, this permission was controlled by the enum add_custom_emoji_policy. Values were 1=Members, 2=Admins, 3=Full members, 4=Moderators.

  Before Zulip 5.0 (feature level 85), the realm_add_emoji_by_admins_only boolean setting controlled this permission; true corresponded to Admins, and false to Everyone.

  • The ID of the user group with this permission.

  • An object with these fields:

    • direct_members: (integer)[]

      The list of IDs of individual users in the collection of users with this permission.

      Changes: Prior to Zulip 10.0 (feature level 303), this list would include deactivated users who had the permission before being deactivated.

    • direct_subgroups: (integer)[]

      The list of IDs of the groups in the collection of users with this permission.

• realm_can_delete_any_message_group: integer | object

  Present if realm is present in fetch_event_types.

  A group-setting value defining the set of users who have permission to delete any message in the organization.

  Changes: New in Zulip 10.0 (feature level 281). Previously, this permission was limited to administrators only and was uneditable.

  • The ID of the user group with this permission.

  • An object with these fields:

    • direct_members: (integer)[]

      The list of IDs of individual users in the collection of users with this permission.

      Changes: Prior to Zulip 10.0 (feature level 303), this list would include deactivated users who had the permission before being deactivated.

    • direct_subgroups: (integer)[]

      The list of IDs of the groups in the collection of users with this permission.

• realm_can_delete_own_message_group: integer | object

  Present if realm is present in fetch_event_types.

  A group-setting value defining the set of users who have permission to delete messages that they have sent in the organization.

  Changes: New in Zulip 10.0 (feature level 291). Previously, this permission was controlled by the enum delete_own_message_policy. Values were 1=Members, 2=Admins, 3=Full members, 4=Moderators, 5=Everyone.

  Before Zulip 5.0 (feature level 101), the allow_message_deleting boolean setting controlled this permission; true corresponded to Everyone, and false to Admins.

  • The ID of the user group with this permission.

  • An object with these fields:

    • direct_members: (integer)[]

      The list of IDs of individual users in the collection of users with this permission.

      Changes: Prior to Zulip 10.0 (feature level 303), this list would include deactivated users who had the permission before being deactivated.

    • direct_subgroups: (integer)[]

      The list of IDs of the groups in the collection of users with this permission.

• realm_can_move_messages_between_channels_group: integer | object

  Present if realm is present in fetch_event_types.

  A group-setting value defining the set of users who have permission to move messages from one channel to another in the organization.

  Changes: New in Zulip 10.0 (feature level 310). Previously, this permission was controlled by the enum move_messages_between_streams_policy. Values were 1=Members, 2=Admins, 3=Full members, 4=Moderators, 6=Nobody.

  In Zulip 7.0 (feature level 159), Nobody was added as an option to move_messages_between_streams_policy enum.

  • The ID of the user group with this permission.

  • An object with these fields:

    • direct_members: (integer)[]

      The list of IDs of individual users in the collection of users with this permission.

      Changes: Prior to Zulip 10.0 (feature level 303), this list would include deactivated users who had the permission before being deactivated.

    • direct_subgroups: (integer)[]

      The list of IDs of the groups in the collection of users with this permission.

• realm_can_move_messages_between_topics_group: integer | object

  Present if realm is present in fetch_event_types.

  A group-setting value defining the set of users who have permission to move messages from one topic to another within a channel in the organization.

  Changes: New in Zulip 10.0 (feature level 316). Previously, this permission was controlled by the enum edit_topic_policy. Values were 1=Members, 2=Admins, 3=Full members, 4=Moderators, 5=Everyone, 6=Nobody.

  In Zulip 7.0 (feature level 159), Nobody was added as an option to edit_topic_policy enum.

  • The ID of the user group with this permission.

  • An object with these fields:

    • direct_members: (integer)[]

      The list of IDs of individual users in the collection of users with this permission.

      Changes: Prior to Zulip 10.0 (feature level 303), this list would include deactivated users who had the permission before being deactivated.

    • direct_subgroups: (integer)[]

      The list of IDs of the groups in the collection of users with this permission.

• 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_can_create_groups: integer | object

  A group-setting value defining the set of users who have permission to create user groups in this organization.

  Changes: New in Zulip 10.0 (feature level 299). Previously realm_user_group_edit_policy field used to control the permission to create user groups.

  • The ID of the user group with this permission.

  • An object with these fields:

    • direct_members: (integer)[]

      The list of IDs of individual users in the collection of users with this permission.

      Changes: Prior to Zulip 10.0 (feature level 303), this list would include deactivated users who had the permission before being deactivated.

    • direct_subgroups: (integer)[]

      The list of IDs of the groups in the collection of users with this permission.

• realm_can_manage_all_groups: integer | object

  A group-setting value defining the set of users who have permission to administer all existing groups in this organization.

  Changes: Prior to Zulip 10.0 (feature level 305), only users who were a member of the group or had the moderator role or above could exercise the permission on a given group.

  New in Zulip 10.0 (feature level 299). Previously the user_group_edit_policy field controlled the permission to manage user groups. Valid values were as follows:

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

  • The ID of the user group with this permission.

  • An object with these fields:

    • direct_members: (integer)[]

      The list of IDs of individual users in the collection of users with this permission.

      Changes: Prior to Zulip 10.0 (feature level 303), this list would include deactivated users who had the permission before being deactivated.

    • direct_subgroups: (integer)[]

      The list of IDs of the groups in the collection of users with this permission.

• realm_can_create_public_channel_group: integer | object

  A group-setting value defining the set of users who have permission to create public channels in this organization.

  Changes: New in Zulip 9.0 (feature level 264). Previously realm_create_public_stream_policy field used to control the permission to create public channels.

  • The ID of the user group with this permission.

  • An object with these fields:

    • direct_members: (integer)[]

      The list of IDs of individual users in the collection of users with this permission.

      Changes: Prior to Zulip 10.0 (feature level 303), this list would include deactivated users who had the permission before being deactivated.

    • direct_subgroups: (integer)[]

      The list of IDs of the groups in the collection of users with this permission.

• realm_can_create_private_channel_group: integer | object

  A group-setting value defining the set of users who have permission to create private channels in this organization.

  Changes: New in Zulip 9.0 (feature level 266). Previously realm_create_private_stream_policy field used to control the permission to create private channels.

  • The ID of the user group with this permission.

  • An object with these fields:

    • direct_members: (integer)[]

      The list of IDs of individual users in the collection of users with this permission.

      Changes: Prior to Zulip 10.0 (feature level 303), this list would include deactivated users who had the permission before being deactivated.

    • direct_subgroups: (integer)[]

      The list of IDs of the groups in the collection of users with this permission.

• realm_can_create_web_public_channel_group: integer | object

  A group-setting value defining the set of users who have permission to create web-public channels in this organization.

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

  Changes: New in Zulip 10.0 (feature level 280). Previously realm_create_web_public_stream_policy field used to control the permission to create web-public channels.

  • The ID of the user group with this permission.

  • An object with these fields:

    • direct_members: (integer)[]

      The list of IDs of individual users in the collection of users with this permission.

      Changes: Prior to Zulip 10.0 (feature level 303), this list would include deactivated users who had the permission before being deactivated.

    • direct_subgroups: (integer)[]

      The list of IDs of the groups in the collection of users with this permission.

• realm_create_public_stream_policy: integer

  Present if realm is present in fetch_event_types.

  A deprecated representation of a superset of the users who have permission to create public channels in the organization, available for backwards-compatibility. Clients should use can_create_public_channel_group instead.

  It is an enum with the following possible values, corresponding to roles/system groups:

  • 1 = Members only
  • 2 = Admins only
  • 3 = Full members only
  • 4 = Admins and moderators only

  Changes: Deprecated in Zulip 9.0 (feature level 264) and replaced by realm_can_create_public_channel_group, which supports finer resolution of configurations, resulting in this property being inaccurate following that transition.

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

• realm_create_private_stream_policy: integer

  Present if realm is present in fetch_event_types.

  A deprecated representation of a superset of the users who have permission to create private channels in the organization, available for backwards-compatibility. Clients should use can_create_private_channel_group instead.

  It is an enum with the following possible values, corresponding to roles/system groups:

  • 1 = Members only
  • 2 = Admins only
  • 3 = Full members only
  • 4 = Admins and moderators only

  Changes: Deprecated in Zulip 9.0 (feature level 266) and replaced by realm_can_create_private_channel_group, which supports finer resolution of configurations, resulting in this property being inaccurate following that transition.

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

• realm_create_web_public_stream_policy: integer

  Present if realm is present in fetch_event_types.

  A deprecated representation of a superset of the users who have permission to create web-public channels in the organization, available for backwards-compatibility. Clients should use can_create_web_public_channel_group instead.

  It is an enum with the following possible values, corresponding to roles/system groups:

  • 2 = Admins only
  • 4 = Admins and moderators only
  • 6 = Nobody
  • 7 = Owners only

  Changes: Deprecated in Zulip 10.0 (feature level 280) and replaced by realm_can_create_web_public_channel_group, which supports finer resolution of configurations, resulting in this property being inaccurate following that transition.

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

• 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 channels 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 channels.

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

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

  Changes: In Zulip 6.0 (feature level 133), channel administrators option removed.

  In Zulip 4.0 (feature level 62), moderators option added.

  New in Zulip 4.0 (feature level 33).

• realm_default_language: string

  Present if realm is present in fetch_event_types.

  The organization language for automated messages and invitation emails.

• 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_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_create_multiuse_invite_group: integer | object

  A group-setting value defining the set of users who are allowed to create reusable invitation links to the organization.

  Changes: Prior to Zulip 10.0 (feature level 314), this value used to be of type integer and did not accept anonymous user groups.

  New in Zulip 8.0 (feature level 209).

  • The ID of the user group with this permission.

  • An object with these fields:

    • direct_members: (integer)[]

      The list of IDs of individual users in the collection of users with this permission.

      Changes: Prior to Zulip 10.0 (feature level 303), this list would include deactivated users who had the permission before being deactivated.

    • direct_subgroups: (integer)[]

      The list of IDs of the groups in the collection of users with this permission.

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

  Indicates whether the organization is configured to require users to have unique full names. If true, the server will reject attempts to create a new user, or change the name of an existing user, where doing so would lead to two users whose names are identical modulo case and unicode normalization.

  Changes: New in Zulip 9.0 (feature level 246). Previously, the Zulip server could not be configured to enforce unique names.

• realm_name_changes_disabled: 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 channels and related anonymous access APIs/features are enabled in this organization.

  Can only be enabled if the WEB_PUBLIC_STREAMS_ENABLED server setting is enabled on the Zulip server. See also the can_create_web_public_channel_group realm setting.

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

• realm_want_advertise_in_communities_directory: boolean

  Present if realm is present in fetch_event_types.

  Whether the organization has given permission to be advertised in the Zulip communities directory.

  Useful only to clients supporting changing this setting for the organization.

  Giving permission via this setting does not guarantee that an organization will be listed in the Zulip communities directory.

  Changes: New in Zulip 6.0 (feature level 129).

• realm_video_chat_provider: integer

  Present if realm is present in fetch_event_types.

  The configured video call provider for the organization.

  • 0 = None
  • 1 = Jitsi Meet
  • 3 = Zoom
  • 4 = BigBlueButton

  Changes: None added as an option in Zulip 3.0 (feature level 1) to disable video call UI.

• realm_jitsi_server_url: string | null

  The URL of the custom Jitsi Meet server configured in this organization's settings.

  null, the default, means that the organization is using the should use the server-level configuration, server_jitsi_server_url. A correct client supporting only the modern API should use realm_jitsi_server_url || server_jitsi_server_url to create calls.

  Changes: New in Zulip 8.0 (feature level 212). Previously, this was only available as a server-level configuration, which was available via the jitsi_server_url field.

• realm_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_direct_message_initiator_group: integer | object

  A group-setting value defining the set of users who have permission to start a new direct message conversation involving other non-bot users. Users who are outside this group and attempt to send the first direct message to a given collection of recipient users will receive an error, unless all other recipients are bots or the sender.

  Changes: New in Zulip 9.0 (feature level 270).

  Previously, access to send direct messages was controlled by the private_message_policy realm setting, which supported values of 1 (enabled) and 2 (disabled).

  • The ID of the user group with this permission.

  • An object with these fields:

    • direct_members: (integer)[]

      The list of IDs of individual users in the collection of users with this permission.

      Changes: Prior to Zulip 10.0 (feature level 303), this list would include deactivated users who had the permission before being deactivated.

    • direct_subgroups: (integer)[]

      The list of IDs of the groups in the collection of users with this permission.

• realm_direct_message_permission_group: integer | object

  A group-setting value defining the set of users who have permission to fully use direct messages. Users outside this group can only send direct messages to conversations where all the recipients are in this group, are bots, or are the sender, ensuring that every direct message conversation will be visible to at least one user in this group.

  Changes: New in Zulip 9.0 (feature level 270).

  Previously, access to send direct messages was controlled by the private_message_policy realm setting, which supported values of 1 (enabled) and 2 (disabled).

  • The ID of the user group with this permission.

  • An object with these fields:

    • direct_members: (integer)[]

      The list of IDs of individual users in the collection of users with this permission.

      Changes: Prior to Zulip 10.0 (feature level 303), this list would include deactivated users who had the permission before being deactivated.

    • direct_subgroups: (integer)[]

      The list of IDs of the groups in the collection of users with this permission.

• realm_default_code_block_language: string

  Present if realm is present in fetch_event_types.

  The default pygments language code to be used for code blocks in this organization. If an empty string, no default has been set.

  Changes: Prior to Zulip 8.0 (feature level 195), a server bug meant that both null and an empty string could represent that no default was set for this realm setting. Clients supporting older server versions should treat either value (null or "") as no default being set.

• realm_message_content_delete_limit_seconds: 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 keys mapped to dictionaries that describe the properties of the named authentication method for the organization - its enabled status and availability for use by the organization.

  Clients should use this to implement server-settings UI to change which methods are enabled for the organization. For authentication UI itself, clients should use the pre-authentication metadata returned by GET /server_settings.

  Changes: In Zulip 9.0 (feature level 241), the values in this dictionary were changed. Previously, the values were a simple boolean indicating whether the backend is enabled or not.

  • Dictionary describing the properties of an authentication method for the organization - its enabled status and availability for use by the organization.

    • enabled: boolean

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

    • available: boolean

      Boolean describing whether the authentication method is available for use. If false, the organization is not eligible to enable the authentication method.

    • unavailable_reason: string

      Reason why the authentication method is unavailable. This field is optional and is only present when 'available' is false.

• realm_allow_message_editing: boolean

  Present if realm is present in fetch_event_types.

  Whether this organization's message edit policy allows editing the content of messages.

  See PATCH /messages/{message_id} for details and history of how message editing permissions work.

• realm_message_content_edit_limit_seconds: integer | null

  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.

  Will not be 0. A null value means no limit, so messages can be edited regardless of how long ago they were sent.

  See PATCH /messages/{message_id} for details and history of how message editing permissions work.

  Changes: Before Zulip 6.0 (feature level 138), no limit was represented using the special value 0.

• realm_move_messages_within_stream_limit_seconds: integer | null

  Present if realm is present in fetch_event_types.

  Messages sent more than this many seconds ago cannot be moved within a channel to another topic by users who have permission to do so based on this organization's topic edit policy. This setting does not affect moderators and administrators.

  Will not be 0. A null value means no limit, so message topics can be edited regardless of how long ago they were sent.

  See PATCH /messages/{message_id} for details and history of how message editing permissions work.

  Changes: New in Zulip 7.0 (feature level 162). Previously, this time limit was always 72 hours for users who were not administrators or moderators.

• realm_move_messages_between_streams_limit_seconds: integer | null

  Present if realm is present in fetch_event_types.

  Messages sent more than this many seconds ago cannot be moved between channels by users who have permission to do so based on this organization's message move policy. This setting does not affect moderators and administrators.

  Will not be 0. A null value means no limit, so messages can be moved regardless of how long ago they were sent.

  See PATCH /messages/{message_id} for details and history of how message editing permissions work.

  Changes: New in Zulip 7.0 (feature level 162). Previously, there was no time limit for moving messages between channels for users with permission to do so.

• realm_enable_read_receipts: boolean

  Present if realm is present in fetch_event_types.

  Whether read receipts is enabled in the organization or not.

  If disabled, read receipt data will be unavailable to clients, regardless of individual users' personal read receipt settings. See also the send_read_receipts setting within realm_user_settings_defaults.

  Changes: New in Zulip 6.0 (feature level 137).

• realm_icon_url: 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. Alias of realm_url.

  Changes: Deprecated in Zulip 9.0 (feature level 257). The term "URI" is deprecated in web standards.

• realm_url: string

  Present if realm is present in fetch_event_types.

  The URL for the organization.

  Changes: New in Zulip 9.0 (feature level 257), replacing the deprecated realm_uri.

• realm_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 realm setting video_chat_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 true for Zulip Cloud and self-hosted realms that have a valid registration for the Mobile push notifications service, and false for self-hosted servers that do not.

  Changes: Before Zulip 8.0 (feature level 231), this incorrectly was true for servers that were partly configured to use the Mobile Push Notifications Service but not properly registered.

• realm_push_notifications_enabled_end_timestamp: integer | null

  Present if realm is present in fetch_event_types.

  If the server expects the realm's push notifications access to end at a definite time in the future, the UNIX timestamp (UTC) at which this is expected to happen. Mobile clients should use this field to display warnings to users when the indicated timestamp is near.

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

• realm_upload_quota_mib: 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.

  If null, there is no limit.

  Changes: Before Zulip 9.0 (feature level 251), this field was incorrectly measured in bytes, not MiB.

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

• realm_org_type: integer

  Present if realm is present in fetch_event_types.

  The organization type for the realm. Useful only to clients supporting changing this setting for the organization, or clients implementing onboarding content or other features that varies with organization type.

  • 0 = Unspecified
  • 10 = Business
  • 20 = Open-source project
  • 30 = Education (non-profit)
  • 35 = Education (for-profit)
  • 40 = Research
  • 50 = Event or conference
  • 60 = Non-profit (registered)
  • 70 = Government
  • 80 = Political group
  • 90 = Community
  • 100 = Personal
  • 1000 = Other

  Changes: New in Zulip 6.0 (feature level 128).

• realm_plan_type: 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)

• realm_enable_guest_user_indicator: boolean

  Present if realm is present in fetch_event_types.

  Whether clients should display "(guest)" after the names of guest users to prominently highlight their status.

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

• realm_can_access_all_users_group: integer | object

  A group-setting value defining the set of users who are allowed to access all users in the organization.

  Changes: Prior to Zulip 10.0 (feature level 314), this value used to be of type integer and did not accept anonymous user groups.

  New in Zulip 8.0 (feature level 225).

  • The ID of the user group with this permission.

  • An object with these fields:

    • direct_members: (integer)[]

      The list of IDs of individual users in the collection of users with this permission.

      Changes: Prior to Zulip 10.0 (feature level 303), this list would include deactivated users who had the permission before being deactivated.

    • direct_subgroups: (integer)[]

      The list of IDs of the groups in the collection of users with this permission.

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

  Changes: New in Zulip 2.1.0.

  • {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 to be used to create Jitsi video calls. Equals realm_jitsi_server_url || server_jitsi_server_url.

  Changes: Deprecated in Zulip 8.0 (feature level 212) and will eventually be removed. Previously, the Jitsi server to use was not configurable on a per-realm basis, and this field contained the server's configured Jitsi server. (Which is now provided as server_jitsi_server_url). Clients supporting older versions should fall back to this field when creating calls: using realm_jitsi_server_url || server_jitsi_server_url with newer servers and using jitsi_server_url with servers below feature level 212.

• development_environment: 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

  Present if realm is present in fetch_event_types.

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

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

  A list describing the image formats that uploaded images will be thumbnailed into. Any image with a source starting with /user_uploads/thumbnail/ can have its last path component replaced with any of the names contained in this list, to obtain the desired thumbnail size.

  Changes: New in Zulip 9.0 (feature level 273).

  • name: string

    The file path component of the thumbnail format.

  • max_width: integer

    The maximum width of this format.

  • max_height: integer

    The maximum height of this format.

  • format: string

    The extension of this format.

  • animated: boolean

    If this file format is animated. These formats are only generated for uploaded imates which themselves are animated.

• 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 channels to realms it hosts. (Zulip Cloud defaults to true; self-hosted servers default to false).

  Clients should use this to determine whether to offer UI for the realm-level setting for enabling web-public channels (realm_enable_spectator_access).

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

• server_emoji_data_url: string

  Present if realm is present in fetch_event_types.

  The URL to a JSON file that describes which emoji names map to which emoji codes, for all Unicode emoji this Zulip server accepts.

  The data at the given URL is a JSON object with one property, code_to_names. The value of that property is a JSON object where each key is an emoji code for an available Unicode emoji, and each value is the corresponding emoji names for this emoji, with the canonical name for the emoji always appearing first.

  The HTTP response at that URL will have appropriate HTTP caching headers, such any HTTP implementation should get a cached version if emoji haven't changed since the last request.

  Changes: New in Zulip 6.0 (feature level 140).

• server_jitsi_server_url: string | null

  The URL of the Jitsi server that the Zulip server is configured to use by default; the organization-level setting realm_jitsi_server_url takes precedence over this setting when both are set.

  Changes: New in Zulip 8.0 (feature level 212). Previously, this value was available as the now-deprecated jitsi_server_url.

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

  Present if realm is present in fetch_event_types.

  The ID of the channel to which automated messages announcing the creation of new channels are sent.

  Will be -1 if such automated messages are disabled.

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

  Changes: In Zulip 9.0 (feature level 241), renamed 'realm_notifications_stream_id' to realm_new_stream_announcements_stream_id.

• realm_signup_announcements_stream_id: integer

  Present if realm is present in fetch_event_types.

  The ID of the channel to which automated messages announcing that new users have joined the organization are sent.

  Will be -1 if such automated messages are disabled.

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

  Changes: In Zulip 9.0 (feature level 241), renamed 'realm_signup_notifications_stream_id' to realm_signup_announcements_stream_id.

• realm_zulip_update_announcements_stream_id: integer

  Present if realm is present in fetch_event_types.

  The ID of the channel to which automated messages announcing new features or other end-user updates about the Zulip software are sent.

  Will be -1 if such automated messages are disabled.

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

  Changes: New in Zulip 9.0 (feature level 242).

• realm_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.

  • web_mark_read_on_scroll_policy: integer

    Whether or not to mark messages as read when the user scrolls through their feed.

    • 1 - Always
    • 2 - Only in conversation views
    • 3 - Never

    Changes: New in Zulip 7.0 (feature level 175). Previously, there was no way for the user to configure this behavior on the web, and the Zulip web and desktop apps behaved like the "Always" setting when marking messages as read.

  • web_channel_default_view: integer

    Web/desktop app setting controlling the default navigation behavior when clicking on a channel link.

    • 1 - Top topic in the channel
    • 2 - Channel feed

    Changes: New in Zulip 9.0 (feature level 269). Previously, this was not configurable, and every user had the "Channel feed" behavior.

  • starred_message_counts: boolean

    Whether clients should display the number of starred messages.

  • receives_typing_notifications: boolean

    Whether the user is configured to receive typing notifications from other users. The server will only deliver typing notifications events to users who for whom this is enabled.

    Changes: New in Zulip 9.0 (feature level 253). Previously, there were only options to disable sending typing notifications.

  • fluid_layout_width: boolean

    Whether to use the maximum available screen width for the web app's center panel (message feed, recent conversations) 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.

  • web_font_size_px: integer

    User-configured primary font-size for the web application, in pixels.

    Changes: New in Zulip 9.0 (feature level 245). Previously, font size was only adjustable via browser zoom. Note that this setting was not fully implemented at this feature level.

  • web_line_height_percent: integer

    User-configured primary line-height for the web application, in percent, so a value of 120 represents a line-height of 1.2.

    Changes: New in Zulip 9.0 (feature level 245). Previously, line height was not user-configurable. Note that this setting was not fully implemented at this feature level.

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

  • display_emoji_reaction_users: boolean

    Whether to display the names of reacting users on a message.

    When enabled, clients should display the names of reacting users, rather than a count, for messages with few total reactions. The ideal cutoff may depend on the space available for displaying reactions; the official web application displays names when 3 or fewer total reactions are present with this setting enabled.

    Changes: New in Zulip 6.0 (feature level 125).

  • default_language: 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.

  • web_home_view: string

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

    • "recent_topics" - Recent conversations view
    • "inbox" - Inbox view
    • "all_messages" - Combined feed view

    Changes: New in Zulip 8.0 (feature level 219). Previously, this was called default_view, which was new in Zulip 4.0 (feature level 42).

  • web_escape_navigates_to_home_view: boolean

    Whether the escape key navigates to the configured home view.

    Changes: New in Zulip 8.0 (feature level 219). Previously, this was called escape_navigates_to_default_view, which was new in Zulip 5.0 (feature level 107).

  • left_side_userlist: 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 channels in the left sidebar.

    • 1 - Automatic
    • 2 - Always
    • 3 - Never

  • user_list_style: integer

    The style selected by the user for the right sidebar user list.

    • 1 - Compact
    • 2 - With status
    • 3 - With avatar and status

    Changes: New in Zulip 6.0 (feature level 141).

  • web_animate_image_previews: string

    Controls how animated images should be played in the message feed in the web/desktop application.

    • "always" - Always play the animated images in the message feed.
    • "on_hover" - Play the animated images on hover over them in the message feed.
    • "never" - Never play animated images in the message feed.

    Changes: New in Zulip 9.0 (feature level 275).

  • web_stream_unreads_count_display_policy: integer

    Configuration for which channels should be displayed with a numeric unread count in the left sidebar. Channels that do not have an unread count will have a simple dot indicator for whether there are any unread messages.

    • 1 - All channels
    • 2 - Unmuted channels and topics
    • 3 - No channels

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

  • enable_stream_desktop_notifications: boolean

    Enable visual desktop notifications for channel messages.

  • enable_stream_email_notifications: boolean

    Enable email notifications for channel messages.

  • enable_stream_push_notifications: boolean

    Enable mobile notifications for channel messages.

  • enable_stream_audible_notifications: boolean

    Enable audible desktop notifications for channel messages.

  • notification_sound: string

    Notification sound name.

  • enable_desktop_notifications: boolean

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

  • enable_sounds: boolean

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

  • enable_offline_email_notifications: boolean

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

  • enable_offline_push_notifications: boolean

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

  • enable_online_push_notifications: boolean

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

  • enable_followed_topic_desktop_notifications: boolean

    Enable visual desktop notifications for messages sent to followed topics.

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

  • enable_followed_topic_email_notifications: boolean

    Enable email notifications for messages sent to followed topics.

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

  • enable_followed_topic_push_notifications: boolean

    Enable push notifications for messages sent to followed topics.

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

  • enable_followed_topic_audible_notifications: boolean

    Enable audible desktop notifications for messages sent to followed topics.

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

  • 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 direct messages in desktop notifications.

  • wildcard_mentions_notify: boolean

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

  • enable_followed_topic_wildcard_mentions_notify: boolean

    Whether wildcard mentions (e.g., @all) in messages sent to followed topics should send notifications like a personal mention.

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

  • desktop_icon_count_display: integer

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

    • 1 - All unread messages
    • 2 - DMs, mentions, and followed topics
    • 3 - DMs and mentions
    • 4 - None

    Changes: In Zulip 8.0 (feature level 227), added DMs, mentions, and followed topics option, renumbering the options to insert it in order.

  • realm_name_in_email_notifications_policy: integer

    Whether to include organization name in subject of message notification emails.

    • 1 - Automatic
    • 2 - Always
    • 3 - Never

    Changes: New in Zulip 7.0 (feature level 168), replacing the previous realm_name_in_notifications boolean; true corresponded to Always, and false to Never.

  • automatically_follow_topics_policy: integer

    Which topics to follow automatically.

    • 1 - Topics the user participates in
    • 2 - Topics the user sends a message to
    • 3 - Topics the user starts
    • 4 - Never

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

  • automatically_unmute_topics_in_muted_streams_policy: integer

    Which topics to unmute automatically in muted channels.

    • 1 - Topics the user participates in
    • 2 - Topics the user sends a message to
    • 3 - Topics the user starts
    • 4 - Never

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

  • automatically_follow_topics_where_mentioned: boolean

    Whether the server will automatically mark the user as following topics where the user is mentioned.

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

  • 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 direct messages.

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

  • send_stream_typing_notifications: boolean

    Whether typing notifications be sent when composing channel 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).

  • allow_private_data_export: boolean

    Whether organization administrators are allowed to export your private data.

    Changes: New in Zulip 10.0 (feature level 293).

  • email_address_visibility: integer

    The policy for which other users in this organization can see the user's real email address.

    • 1 = Everyone
    • 2 = Members only
    • 3 = Administrators only
    • 4 = Nobody
    • 5 = Moderators only

    Changes: New in Zulip 7.0 (feature level 163), replacing the realm-level setting.

  • web_navigate_to_sent_message: boolean

    Web/desktop app setting for whether the user's view should automatically go to the conversation where they sent a message.

    Changes: New in Zulip 9.0 (feature level 268). Previously, this behavior was not configurable.

• realm_users: (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.

  If the current user is a guest whose access to users is limited by a can_access_all_users_group policy, and the event queue was registered with the user_list_incomplete client capability, then users that the current user cannot access will not be included in this array. If the current user's access to a user is restricted but the client lacks this capability, then that inaccessible user will appear in the users array as an "Unknown user" object with the usual format but placeholder data whose only variable content is the user ID.

  See also cross_realm_bots and realm_non_active_users.

  Changes: Before Zulip 8.0 (feature level 232), the user_list_incomplete client capability did not exist, and so all clients whose access to a new user was prevented by can_access_all_users_group policy would receive a fake "Unknown user" event for such users.

  • user_id: integer

    The unique ID of the user.

  • delivery_email: string | null

    The user's real email address. This value will be null if you cannot access user's real email address. For bot users, this field is always set to the real email of the bot, because bot users always have email_address_visibility set to everyone.

    Changes: Prior to Zulip 7.0 (feature level 163), this field was present only when email_address_visibility was restricted and you had access to the user's real email. As of this feature level, this field is always present, including the case when email_address_visibility is set to everyone (and therefore not restricted).

  • email: 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.

  • full_name: string

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

  • date_joined: string

    The time the user account was created.

  • is_active: boolean

    A boolean specifying whether the user account has been deactivated.

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

    A boolean specifying whether the user is an organization administrator.

  • is_guest: boolean

    A boolean specifying whether the user is a guest user.

  • is_billing_admin: boolean

    A boolean specifying whether the user is a billing administrator.

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

  • is_bot: boolean

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

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

  • bot_owner_id: integer | null

    If the user is a bot (i.e. is_bot is true), then bot_owner_id is the user ID of the bot's owner (usually, whoever created the bot).

    Will be null for legacy bots that do not have an owner.

    Changes: New in Zulip 3.0 (feature level 1). In previous versions, there was a bot_owner field containing the email address of the bot's owner.

  • role: integer

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

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

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

  • timezone: string

    The time zone of the user.

  • avatar_url: string | null

    URL for the user's avatar.

    Will be null if the client_gravatar query parameter was set to true, the current user has access to this user's real email address, and this user's avatar is hosted by the Gravatar provider (i.e. this user has never uploaded an avatar).

    Changes: Before Zulip 7.0 (feature level 163), access to a user's real email address was a realm-level setting. As of this feature level, email_address_visibility is a user setting.

    In Zulip 3.0 (feature level 18), if the client has the user_avatar_url_field_optional capability, this will be missing at the server's sole discretion.

  • avatar_version: 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}.

  • profile_data: object

    Only present if is_bot is false; bots can't have custom profile fields.

    A dictionary containing custom profile field data for the user. Each entry maps the integer ID of a custom profile field in the organization to a dictionary containing the user's data for that field. Generally the data includes just a single value key; for those custom profile fields supporting Markdown, a rendered_value key will also be present.

    • {id}: object

      Object with data about what value the user filled in the custom profile field with that 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.

  • user_id: integer

    The unique ID of the user.

  • delivery_email: string | null

    The user's real email address. This value will be null if you cannot access user's real email address. For bot users, this field is always set to the real email of the bot, because bot users always have email_address_visibility set to everyone.

    Changes: Prior to Zulip 7.0 (feature level 163), this field was present only when email_address_visibility was restricted and you had access to the user's real email. As of this feature level, this field is always present, including the case when email_address_visibility is set to everyone (and therefore not restricted).

  • email: 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.

  • full_name: string

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

  • date_joined: string

    The time the user account was created.

  • is_active: boolean

    A boolean specifying whether the user account has been deactivated.

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

    A boolean specifying whether the user is an organization administrator.

  • is_guest: boolean

    A boolean specifying whether the user is a guest user.

  • is_billing_admin: boolean

    A boolean specifying whether the user is a billing administrator.

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

  • is_bot: boolean

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

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

  • bot_owner_id: integer | null

    If the user is a bot (i.e. is_bot is true), then bot_owner_id is the user ID of the bot's owner (usually, whoever created the bot).

    Will be null for legacy bots that do not have an owner.

    Changes: New in Zulip 3.0 (feature level 1). In previous versions, there was a bot_owner field containing the email address of the bot's owner.

  • role: integer

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

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

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

  • timezone: string

    The time zone of the user.

  • avatar_url: string | null

    URL for the user's avatar.

    Will be null if the client_gravatar query parameter was set to true, the current user has access to this user's real email address, and this user's avatar is hosted by the Gravatar provider (i.e. this user has never uploaded an avatar).

    Changes: Before Zulip 7.0 (feature level 163), access to a user's real email address was a realm-level setting. As of this feature level, email_address_visibility is a user setting.

    In Zulip 3.0 (feature level 18), if the client has the user_avatar_url_field_optional capability, this will be missing at the server's sole discretion.

  • avatar_version: 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}.

  • profile_data: object

    Only present if is_bot is false; bots can't have custom profile fields.

    A dictionary containing custom profile field data for the user. Each entry maps the integer ID of a custom profile field in the organization to a dictionary containing the user's data for that field. Generally the data includes just a single value key; for those custom profile fields supporting Markdown, a rendered_value key will also be present.

    • {id}: object

      Object with data about what value the user filled in the custom profile field with that 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 channel with the organization's channel 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 channel.

  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 channels with the organization's channel 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 channels.

• can_create_private_streams: boolean

  Present if realm_user is present in fetch_event_types.

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

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

• can_create_web_public_streams: boolean

  Present if realm_user is present in fetch_event_types.

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

  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 channels with the organization's channels 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.

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

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

• 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 API email address for the current user. See also delivery_email; these may be the same or different depending on the user's email_address_visibility policy.

• delivery_email: 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.

  • user_id: integer

    The unique ID of the user.

  • delivery_email: string | null

    The user's real email address. This value will be null if you cannot access user's real email address. For bot users, this field is always set to the real email of the bot, because bot users always have email_address_visibility set to everyone.

    Changes: Prior to Zulip 7.0 (feature level 163), this field was present only when email_address_visibility was restricted and you had access to the user's real email. As of this feature level, this field is always present, including the case when email_address_visibility is set to everyone (and therefore not restricted).

  • email: 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.

  • full_name: string

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

  • date_joined: string

    The time the user account was created.

  • is_active: boolean

    A boolean specifying whether the user account has been deactivated.

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

    A boolean specifying whether the user is an organization administrator.

  • is_guest: boolean

    A boolean specifying whether the user is a guest user.

  • is_billing_admin: boolean

    A boolean specifying whether the user is a billing administrator.

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

  • is_bot: boolean

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

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

  • bot_owner_id: integer | null

    If the user is a bot (i.e. is_bot is true), then bot_owner_id is the user ID of the bot's owner (usually, whoever created the bot).

    Will be null for legacy bots that do not have an owner.

    Changes: New in Zulip 3.0 (feature level 1). In previous versions, there was a bot_owner field containing the email address of the bot's owner.

  • role: integer

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

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

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

  • timezone: string

    The time zone of the user.

  • avatar_url: string | null

    URL for the user's avatar.

    Will be null if the client_gravatar query parameter was set to true, the current user has access to this user's real email address, and this user's avatar is hosted by the Gravatar provider (i.e. this user has never uploaded an avatar).

    Changes: Before Zulip 7.0 (feature level 163), access to a user's real email address was a realm-level setting. As of this feature level, email_address_visibility is a user setting.

    In Zulip 3.0 (feature level 18), if the client has the user_avatar_url_field_optional capability, this will be missing at the server's sole discretion.

  • avatar_version: 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}.

  • profile_data: object

    Only present if is_bot is false; bots can't have custom profile fields.

    A dictionary containing custom profile field data for the user. Each entry maps the integer ID of a custom profile field in the organization to a dictionary containing the user's data for that field. Generally the data includes just a single value key; for those custom profile fields supporting Markdown, a rendered_value key will also be present.

    • {id}: object

      Object with data about what value the user filled in the custom profile field with that 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).

• server_supported_permission_settings: object

  Present if realm is present in fetch_event_types.

  Metadata detailing the valid values for permission settings that use group-setting values. Clients should use these data as explained in the main documentation to determine what values to present as possible values for these settings in UI components.

  This part of the Zulip API is unstable and may change significantly in future versions.

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

  • realm: object

    Configuration for realm level group permission settings.

    • Configuration for a group permission setting specifying the groups to which the setting can be set to and the default values for the setting.

      • require_system_group: boolean

        Whether the setting can only be set to a system user group.

      • allow_internet_group: boolean

        Whether the setting can be set to role:internet system group.

      • allow_owners_group: boolean

        Whether the setting can be set to role:owners system group.

      • allow_nobody_group: boolean

        Whether the setting can be set to role:nobody system group.

      • allow_everyone_group: boolean

        Whether the setting can be set to role:everyone system group.

        If false, guest users cannot exercise this permission even if they are part of the group-setting value for this setting.

      • default_group_name: string

        Name of the default group for the setting.

      • id_field_name: string

        Name for the field used to pass the group ID for the setting.

      • default_for_system_groups: string | null

        Name of the default group for the setting for system groups.

        This is non-null only for group-level settings.

      • allowed_system_groups: (string)[]

        An array of names of system groups to which the setting can be set to.

        If the list is empty, the setting can be set to system groups based on the other boolean fields.

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

  • stream: object

    Configuration for channel level group permission settings.

    • Configuration for a group permission setting specifying the groups to which the setting can be set to and the default values for the setting.

      • require_system_group: boolean

        Whether the setting can only be set to a system user group.

      • allow_internet_group: boolean

        Whether the setting can be set to role:internet system group.

      • allow_owners_group: boolean

        Whether the setting can be set to role:owners system group.

      • allow_nobody_group: boolean

        Whether the setting can be set to role:nobody system group.

      • allow_everyone_group: boolean

        Whether the setting can be set to role:everyone system group.

        If false, guest users cannot exercise this permission even if they are part of the group-setting value for this setting.

      • default_group_name: string

        Name of the default group for the setting.

      • id_field_name: string

        Name for the field used to pass the group ID for the setting.

      • default_for_system_groups: string | null

        Name of the default group for the setting for system groups.

        This is non-null only for group-level settings.

      • allowed_system_groups: (string)[]

        An array of names of system groups to which the setting can be set to.

        If the list is empty, the setting can be set to system groups based on the other boolean fields.

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

  • group: object

    Configuration for group level group permission settings.

    • Configuration for a group permission setting specifying the groups to which the setting can be set to and the default values for the setting.

      • require_system_group: boolean

        Whether the setting can only be set to a system user group.

      • allow_internet_group: boolean

        Whether the setting can be set to role:internet system group.

      • allow_owners_group: boolean

        Whether the setting can be set to role:owners system group.

      • allow_nobody_group: boolean

        Whether the setting can be set to role:nobody system group.

      • allow_everyone_group: boolean

        Whether the setting can be set to role:everyone system group.

        If false, guest users cannot exercise this permission even if they are part of the group-setting value for this setting.

      • default_group_name: string

        Name of the default group for the setting.

      • id_field_name: string

        Name for the field used to pass the group ID for the setting.

      • default_for_system_groups: string | null

        Name of the default group for the setting for system groups.

        This is non-null only for group-level settings.

      • allowed_system_groups: (string)[]

        An array of names of system groups to which the setting can be set to.

        If the list is empty, the setting can be set to system groups based on the other boolean fields.

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

Example response(s)

Changes: As of Zulip 7.0 (feature level 167), if any parameters sent in the request are not supported by this endpoint, a successful JSON response will include an ignored_parameters_unsupported array.

A typical successful JSON response may look like:

{
    "last_event_id": -1,
    "msg": "",
    "queue_id": "fb67bf8a-c031-47cc-84cf-ed80accacda8",
    "realm_emoji": {
        "1": {
            "author_id": 5,
            "deactivated": false,
            "id": "1",
            "name": "green_tick",
            "source_url": "/user_avatars/1/emoji/images/1.png"
        },
        "2": {
            "author_id": 3,
            "deactivated": false,
            "id": "2",
            "name": "animated_img",
            "source_url": "/user_avatars/1/emoji/images/animated_img.gif",
            "still_url": "/user_avatars/1/emoji/images/still/animated_img.png"
        }
    },
    "result": "success",
    "zulip_feature_level": 2,
    "zulip_merge_base": "5.0-dev-1646-gea6b21cd8c",
    "zulip_version": "5.0-dev-1650-gc3fd37755f"
}