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.
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.
-
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).
-
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).
-
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.
-
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.
-
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.
-
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:
-
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:
-
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:
-
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:
-
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:
-
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.
-
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.
-
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
: 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.
-
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).
-
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).
-
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.
-
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.
-
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.
-
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.
-
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_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.
-
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.
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.
-
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
.
-
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.
-
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
.
-
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.
-
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.
-
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.
-
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.
-
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
The ID of the user group whose members are
allowed to create reusable invitation
links
to the organization.
This setting can currently only be set to user groups that are
system groups, except for the system groups named
"role:internet"
and "role:owners"
.
Changes: New in Zulip 8.0 (feature level 209).
-
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).
-
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).
-
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.
-
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_edit_topic_policy
: integer
Present if realm
is present in fetch_event_types
.
The policy for which users can edit topics of any message.
- 1 = Members only
- 2 = Admins only
- 3 = Full members only
- 4 = Moderators only
- 5 = Everyone
- 6 = Nobody
See PATCH /messages/{message_id}
for details and
history of how message editing permissions work.
Changes: Nobody added as an option in Zulip 7.0 (feature level 159).
New in Zulip 5.0 (feature level 75).
-
realm_move_messages_between_streams_policy
: integer
Present if realm
is present in fetch_event_types
.
The policy for which users can move messages
from one channel to another.
- 1 = Members only
- 2 = Administrators only
- 3 = Full members only
- 4 = Moderators only
- 6 = Nobody
See PATCH /messages/{message_id}
for details
and history of how message editing permissions work.
Changes: Nobody added as an option in Zulip 7.0 (feature level 159).
New in Zulip 4.0 (feature level 56).
-
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
.
-
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
The ID of the user group whose members
are allowed to access all users in the organization.
This setting can currently only be set to "role:members"
and "role:everyone"
system groups.
Changes: New in Zulip 8.0 (feature level 225).
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
stream
: object
Configuration for channel level group permission settings.
-
group
: object
Configuration for group level group permission settings.