Get events from an event queue
GET https://oscafrica.zulipchat.com/api/v1/events
This endpoint allows you to receive new events from
a registered event queue.
Long-lived clients should use the
event_queue_longpoll_timeout_seconds property returned by
POST /register as the client-side HTTP request timeout for
calls to this endpoint. It is guaranteed to be higher than
heartbeat frequency and should be respected by clients to
avoid breaking when heartbeat frequency increases.
Usage examples
#!/usr/bin/env python3
import sys
import zulip
# Pass the path to your zuliprc file here.
client = zulip.Client(config_file="~/zuliprc")
# If you already have a queue registered, and thus have a `queue_id`
# on hand, you may use `client.get_events()` and pass in the below
# parameters, like so:
result = client.get_events(queue_id=queue_id, last_event_id=-1)
print(result)
More examples and documentation can be found here.
const zulipInit = require("zulip-js");
// Pass the path to your zuliprc file here.
const config = { zuliprc: "zuliprc" };
(async () => {
const client = await zulipInit(config);
// Retrieve events from a queue with given "queue_id"
const eventParams = {
queue_id,
last_event_id: -1,
};
console.log(await client.events.retrieve(eventParams));
})();
curl -sSX GET -G https://oscafrica.zulipchat.com/api/v1/events \
-u BOT_EMAIL_ADDRESS:BOT_API_KEY \
--data-urlencode queue_id=fb67bf8a-c031-47cc-84cf-ed80accacda8 \
--data-urlencode last_event_id=-1
Parameters
queue_id string required
Example: "fb67bf8a-c031-47cc-84cf-ed80accacda8"
The ID of an event queue that was previously registered via
POST /api/v1/register (see Register a queue).
last_event_id integer optional
Example: -1
dont_block boolean optional
Example: true
Set to true if the client is requesting a nonblocking reply. If not
specified, the request will block until either a new event is available
or a few minutes have passed, in which case the server will send the
client a heartbeat event.
Defaults to false.
Note: The parameters documented above are optional in the sense that
even if you haven't registered a queue by explicitly requesting the
POST /register endpoint, you could pass the parameters for
the POST /register endpoint to this
endpoint and a queue would be registered in the absence of a queue_id.
Response
Return values
-
events: array
An array of event objects (possibly zero-length if dont_block is
set) with IDs newer than last_event_id. Event IDs are
guaranteed to be increasing, but they are not guaranteed to be
consecutive.
-
queue_id: string
The ID of the registered queue.
Events by type
attachment:
channel_folder:
drafts:
navigation_view:
reaction:
realm:
realm_bot:
realm_domains:
realm_emoji:
realm_user:
realm_user_settings_defaults:
reminders:
saved_snippets:
scheduled_messages:
stream:
subscription:
typing:
typing_edit_message:
update_message_flags:
user_group:
user_settings:
Event sent to a user's clients when that user's set of configured
alert words have changed.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
alert_words: (string)[]
An array of strings, where each string is an alert word (or phrase)
configured by the user.
Example
{
"alert_words": [
"alert_word"
],
"id": 0,
"type": "alert_words"
}
Event sent to clients that have requested the
update_display_settings event type and did not include
user_settings_object in their client_capabilities when
registering the event queue.
Changes: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the user_settings_object
client capability and process the user_settings event type instead.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
user: string
The Zulip API email of the user.
-
setting_name: string
Name of the changed display setting.
-
setting: boolean | integer | string
New value of the changed setting.
-
language_name: string
Present only if the setting to be changed is
default_language. Contains the name of the
new default language in English.
Example
{
"id": 0,
"setting": false,
"setting_name": "high_contrast_mode",
"type": "update_display_settings",
"user": "iago@zulip.com"
}
Event sent to a user's clients when that user's notification
settings have changed with an additional
rule that it is only sent to clients that did not include
user_settings_object in their client_capabilities when
registering the event queue.
Changes: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the user_settings_object
client capability and process the user_settings event type instead.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
user: string
The Zulip API email of the user.
-
notification_name: string
Name of the changed notification setting.
-
setting: boolean | integer | string
New value of the changed setting.
Example
{
"id": 0,
"notification_name": "enable_sounds",
"setting": true,
"type": "update_global_notifications",
"user": "iago@zulip.com"
}
Event sent to a user's clients when that user's settings
have changed.
Changes: New in Zulip 5.0 (feature level 89), replacing the
previous update_display_settings and update_global_notifications
event types, which are still present for backwards compatibility reasons.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
property: string
Name of the changed setting.
-
value: boolean | integer | string
New value of the changed setting.
-
language_name: string
Present only if the setting to be changed is
default_language. Contains the name of the
new default language in English.
Example
{
"id": 0,
"op": "update",
"property": "high_contrast_mode",
"type": "user_settings",
"value": false
}
Event sent generally to all users who can access the modified
user for changes in the set of users or those users metadata.
Changes: Prior to Zulip 8.0 (feature level 228), this event
was sent to all users in the organization.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
person: object | object | object | object | object | object | object | object | object
Object containing the changed details of the user.
It has multiple forms depending on the value changed.
Changes: Removed is_billing_admin field in Zulip 10.0
(feature level 363), as it was replaced by the
can_manage_billing_group realm setting.
-
When a user changes their full name.
-
When a user changes their avatar.
-
user_id: integer
The ID of the user who is affected by this change.
-
avatar_url: string
The URL of the new avatar for the user.
-
avatar_source: string
The new avatar data source type for the user.
Value values are G (gravatar) and U (uploaded by user).
-
avatar_url_medium: string
The new medium-size avatar URL for user.
-
avatar_version: integer
The version number for the user's avatar. This is useful
for cache-busting.
-
When a user changes their profile time zone.
-
user_id: integer
The ID of modified user.
-
email: string
The Zulip API email of the user.
Deprecated: This field will be removed in a future
release as it is redundant with the user_id.
-
timezone: string
The IANA identifier of the new profile time zone for the user.
-
When the owner of a bot changes.
-
When the role of a user changes.
-
When the value of a user's delivery email as visible to you changes,
either due to the email address changing or your access to the user's
email changing via an update to their email_address_visibility
setting.
Changes: Prior to Zulip 7.0 (feature level 163), this event was
sent only to the affected user, and this event would only be triggered
by changing the affected user's delivery email.
-
user_id: integer
The ID of the user affected by this change.
-
delivery_email: string | null
The new delivery email of the user.
This value can be null if the affected user
changed their email_address_visibility setting
such that you cannot access their real email.
Changes: Before Zulip 7.0 (feature level 163),
null was not a possible value for this event as
it was only sent to the affected user when their
email address was changed.
-
When the user updates one of their custom profile
fields.
-
user_id: integer
The ID of the user affected by this change.
-
custom_profile_field: object
Object containing details about the custom
profile data change.
-
id: integer
The ID of the custom profile field which user updated.
-
value: string | null
User's personal value for this custom profile field,
or null if unset.
-
rendered_value: string
The value rendered in HTML. Will only be present for
custom profile field types that support Markdown rendering.
This user-generated HTML content should be rendered
using the same CSS and client-side security protections
as are used for message content.
-
When the Zulip API email address of a user changes,
either due to the user's email address changing, or
due to changes in the user's
email address visibility.
-
user_id: integer
The ID of the user affected by this change.
-
new_email: string
The new value of email for the user. The client
should update any data structures associated
with this user to use this new value as the
user's Zulip API email address.
-
When a user is deactivated or reactivated. Only
users who can access the modified user under the
organization's can_access_all_users_group policy
will receive this event.
Clients receiving a deactivation event should
remove the user from all user groups in their data
structures, because deactivated users cannot be
members of groups.
Changes: Prior to Zulip 10.0 (feature level
303), reactivation events were sent to users who
could not access the reactivated user due to a
can_access_all_users_group policy. Also,
previously, Clients were not required to update
group membership records during user deactivation.
New in Zulip 8.0 (feature level 222). Previously the server
sent a realm_user event with op field set to remove
when deactivating a user and a realm_user event with op
field set to add when reactivating a user.
Example
{
"id": 0,
"op": "update",
"person": {
"avatar_source": "G",
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=3",
"avatar_url_medium": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&s=500&version=3",
"avatar_version": 3,
"user_id": 10
},
"type": "realm_user"
}
Event sent to a user's clients when that user's channel subscriptions
have changed (either the set of subscriptions or their properties).
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
subscriptions: (object)[]
A list of dictionaries where each dictionary contains
information about one of the subscribed channels.
Changes: Removed email_address field from the dictionary
in Zulip 8.0 (feature level 226).
Removed role field from the dictionary
in Zulip 6.0 (feature level 133).
-
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
A deprecated representation of a superset of the users who
have permission to post messages to the channel available
for backwards-compatibility. Clients should use
can_send_message_group instead.
It is an enum with the following possible values, corresponding
to roles/system groups:
- 1 = Any user can post.
- 2 = Only administrators can post.
- 3 = Only full members can post.
- 4 = Only moderators can post.
Changes: Deprecated in Zulip 10.0 (feature level 333) and
replaced by can_send_message_group, which supports finer
resolution of configurations, resulting in this property being
inaccurate following that transition.
New in Zulip 3.0 (feature level 1), replacing the previous
is_announcement_only boolean.
-
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.
-
folder_id: integer | null
The ID of the folder to which the channel belongs.
Is null if channel does not belong to any folder.
Changes: New in Zulip 11.0 (feature level 389).
-
topics_policy: string
Setting defining the policy for sending messages to the empty topic in
this channel.
- inherit - Channel will inherit the organization-level setting,
realm_topics_policy.
- allow_empty_topic - Topics are not required to send messages in the channel.
- disable_empty_topic - Topics are required to send messages in the channel.
- empty_topic_only - Only the empty topic is available in this channel.
The empty_topic_only policy can only be enabled in a channel if all
messages in the channel are already in the empty topic.
Changes: In Zulip 11.0 (feature level 404), empty_topic_only option
was added.
New in Zulip 11.0 (feature level 392).
-
is_recently_active: boolean
Whether the channel has recent message activity. Clients should use this to implement
sorting inactive channels to the bottom.
Changes: New in Zulip 10.0 (feature level 323). Previously, clients implemented the
demote_inactive_streams from local message history, resulting in a choppy loading
experience.
-
stream_weekly_traffic: 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_add_subscribers_group: integer | object
A group-setting value defining the set of users
who have permission to add subscribers to this channel.
Users who can administer the channel or have similar realm-level
permissions can add subscribers to a public channel regardless
of the value of this setting.
Users in this group need not be subscribed to a private channel to
add subscribers to it.
Note that a user must have content access
to a channel and permission to administer the channel in order to
modify this setting.
Changes: New in Zulip 10.0 (feature level 342). Previously, there was no
channel-level setting for this permission.
-
can_remove_subscribers_group: integer | object
A group-setting value defining the set of users
who have permission to remove subscribers from this channel.
Organization administrators can unsubscribe others from a channel as though
they were in this group without being explicitly listed here.
Note that a user must have metadata access to a channel and permission
to administer the channel in order to modify this setting.
Changes: Prior to Zulip 10.0 (feature level 349), channel administrators
could not unsubscribe other users if they were not an organization
administrator or part of can_remove_subscribers_group. Realm administrators
were not allowed to unsubscribe other users from a private channel if they
were not subscribed to that channel.
Prior to Zulip 10.0 (feature level 320), this value was always the integer
ID of a system group.
Before Zulip 8.0 (feature level 197), the can_remove_subscribers_group
setting was named can_remove_subscribers_group_id.
New in Zulip 6.0 (feature level 142).
-
can_administer_channel_group: integer | object
A group-setting value defining the set of users
who have permission to administer this channel.
Organization administrators can administer every channel as though they were
in this group without being explicitly listed here.
Note that a user must have metadata access to a channel and permission
to administer the channel in order to modify this setting.
Changes: Prior to Zulip 10.0 (feature level 349) a user needed to
have content access to a channel in
order to modify it. The exception to this rule was that organization
administrators can edit channel names and descriptions without
having full access to the channel.
New in Zulip 10.0 (feature level 325). Prior to this
change, the permission to administer channels was limited to realm
administrators.
-
can_move_messages_out_of_channel_group: integer | object
A group-setting value defining the set of users
who have permission to move messages out of this channel.
Note that a user must have content access to a
channel in order to move messages out of the channel.
Channel administrators and users present in the organization-level
can_move_messages_between_channels_group setting can always move messages
out of the channel if they have content access to
the channel.
Changes: New in Zulip 11.0 (feature level 396). Prior to this
change, only the users in can_move_messages_between_channels_group were able
move messages between channels.
-
can_move_messages_within_channel_group: integer | object
A group-setting value defining the set of users
who have permission to move messages within this channel.
Note that a user must have content access to a
channel in order to move messages within the channel.
Channel administrators and users present in the organization-level
can_move_messages_between_topics_group setting can always move messages
within the channel if they have content access to
the channel.
Changes: New in Zulip 11.0 (feature level 396). Prior to this
change, only the users in can_move_messages_between_topics_group were able
move messages between topics of a channel.
-
can_send_message_group: integer | object
A group-setting value defining the set of users
who have permission to post in this channel.
Note that a user must have metadata access to a channel and permission
to administer the channel in order to modify this setting.
Changes: New in Zulip 10.0 (feature level 333). Previously
stream_post_policy field used to control the permission to
post in the channel.
-
can_subscribe_group: integer | object
A group-setting value defining the set of users
who have permission to subscribe themselves to this channel.
Everyone, excluding guests, can subscribe to any public channel
irrespective of this setting.
Users in this group can subscribe to a private channel as well.
Note that a user must have content access
to a channel and permission to administer the channel in order to
modify this setting.
Changes: New in Zulip 10.0 (feature level 357).
-
can_resolve_topics_group: integer | object
A group-setting value defining the set of users
who have permission to resolve topics in the channel.
Users who have similar realm-level permissions can resolve topics
in a channel regardless of the value of this setting.
Changes: New in Zulip 11.0 (feature level 402).
-
is_archived: boolean
A boolean indicating whether the channel is archived.
Changes: New in Zulip 10.0 (feature level 315).
Previously, subscriptions only included active
channels. Note that some endpoints will never return archived
channels unless the client declares explicit support for
them via the archived_channels client capability.
-
subscriber_count: number
The total number of non-deactivated users (including bots) who
are subscribed to the channel. Clients are responsible for updating
this value using peer_add and peer_remove events.
The server's internals cannot guarantee this value is correctly
synced with peer_add and peer_remove events for the channel. As
a result, if a (rare) race occurs between a change in the channel's
subscribers and fetching this value, it is possible for a client
that is correctly following the events protocol to end up with a
permanently off-by-one error in the channel's subscriber count.
Clients are recommended to fetch full subscriber data for a channel
in contexts where it is important to avoid this risk. The official
web application, for example, uses this field primarily while
waiting to fetch a given channel's full subscriber list from the
server.
Changes: New in Zulip 11.0 (feature level 394).
Example
{
"id": 0,
"op": "add",
"subscriptions": [
{
"audible_notifications": null,
"can_add_subscribers_group": 2,
"can_remove_subscribers_group": 2,
"can_subscribe_group": 2,
"color": "#76ce90",
"creator_id": null,
"description": "",
"desktop_notifications": null,
"email_notifications": null,
"first_message_id": null,
"folder_id": 1,
"history_public_to_subscribers": true,
"in_home_view": true,
"invite_only": false,
"is_announcement_only": false,
"is_archived": false,
"is_muted": false,
"is_recently_active": true,
"is_web_public": false,
"message_retention_days": null,
"name": "test",
"pin_to_top": false,
"push_notifications": null,
"rendered_description": "",
"stream_id": 9,
"stream_post_policy": 1,
"stream_weekly_traffic": null,
"subscribers": [
10
],
"wildcard_mentions_notify": null
}
],
"type": "subscription"
}
Event sent to a user's clients when that user has been unsubscribed
from one or more channels.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
subscriptions: (object)[]
A list of dictionaries, where each dictionary contains
information about one of the newly unsubscribed channels.
-
stream_id: integer
The ID of the channel.
-
name: string
The name of the channel.
Example
{
"id": 0,
"op": "remove",
"subscriptions": [
{
"name": "test",
"stream_id": 9
}
],
"type": "subscription"
}
Event sent to a user's clients when a property of the user's
subscription to a channel has been updated. This event is used
only for personal properties like is_muted or pin_to_top.
See the stream op: update event
for updates to global properties of a channel.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
stream_id: integer
The ID of the channel whose subscription details have changed.
-
property: string
The property of the subscription which has changed. For details on the
various subscription properties that a user can change, see
POST /users/me/subscriptions/properties.
Clients should generally handle an unknown property received here without
crashing, since that will naturally happen when connecting to a Zulip
server running a new version that adds a new subscription property.
Changes: As of Zulip 6.0 (feature level 139), updates to the is_muted
property or the deprecated in_home_view property will send two subscription
update events, one for each property, to support clients fully migrating to
use the is_muted property. Prior to this feature level, updates to either
property only sent one event with the deprecated in_home_view property.
-
value: integer | boolean | string
The new value of the changed property.
Example
{
"id": 0,
"op": "update",
"property": "pin_to_top",
"stream_id": 11,
"type": "subscription",
"value": true
}
Event sent when another user subscribes to a channel, or their
subscription is newly visible to the current user.
When a user subscribes to a channel, the current user will receive this
event only if they have permission to see the channel's subscriber
list. When the current user gains permission
to see a given channel's subscriber list, they will receive this event
for the existing subscriptions to the channel.
Changes: Prior to Zulip 8.0 (feature level 220), this event was
incorrectly not sent to guest users when subscribers to web-public
channels and subscribed public channels changed.
Prior to Zulip 8.0 (feature level 205), this event was not sent when
a user gained access to a channel due to their role
changing.
Prior to Zulip 6.0 (feature level 134), this event was not sent when a
private channel was made public.
In Zulip 4.0 (feature level 35), the singular user_id and stream_id
integers included in this event were replaced with plural user_ids and
stream_ids integer arrays.
In Zulip 3.0 (feature level 19), the stream_id field was added to
identify the channel the user subscribed to, replacing the name field.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
stream_ids: (integer)[]
The IDs of channels that have new or updated subscriber data.
Changes: New in Zulip 4.0 (feature level 35), replacing
the stream_id integer.
-
user_ids: (integer)[]
The IDs of the users who are newly visible as subscribed to
the specified channels.
Changes: New in Zulip 4.0 (feature level 35), replacing
the user_id integer.
Example
{
"id": 0,
"op": "peer_add",
"stream_ids": [
9
],
"type": "subscription",
"user_ids": [
12
]
}
Event sent to other users when users have been unsubscribed
from channels. Sent to all users if the channel is public or to only
the existing subscribers if the channel is private.
Changes: Prior to Zulip 8.0 (feature level 220), this event was
incorrectly not sent to guest users when subscribers to web-public
channels and subscribed public channels changed.
In Zulip 4.0 (feature level 35), the singular user_id and
stream_id integers included in this event were replaced
with plural user_ids and stream_ids integer arrays.
In Zulip 3.0 (feature level 19), the stream_id field was
added to identify the channel the user unsubscribed from,
replacing the name field.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
stream_ids: (integer)[]
The IDs of the channels from which the users have been
unsubscribed from.
When a user is deactivated, the server will send this event
removing the user's subscriptions before the realm_user event
for the user's deactivation.
Changes: Before Zulip 10.0 (feature level 377), this event
was not sent on user deactivation. Clients supporting older
server versions and maintaining peer subscriber data need to
remove all channel subscriptions for a user when processing the
realm_user event with op="remove".
Changes: New in Zulip 4.0 (feature level 35), replacing
the stream_id integer.
-
user_ids: (integer)[]
The IDs of the users who have been unsubscribed.
Changes: New in Zulip 4.0 (feature level 35), replacing
the user_id integer.
Example
{
"id": 0,
"op": "peer_remove",
"stream_ids": [
9
],
"type": "subscription",
"user_ids": [
12
]
}
Event type for messages.
Changes: In Zulip 3.1 (feature level 26), the
sender_short_name field was removed from message
objects.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
message: object
Object containing details of the message.
-
avatar_url: string | null
The URL of the message sender's avatar. Can be null only if
the current user has access to the sender's real email address
and client_gravatar was true.
If null, then the sender has not uploaded an avatar in Zulip,
and the client can compute the gravatar URL by hashing the
sender's email address, which corresponds in this case to their
real email address.
Changes: Before Zulip 7.0 (feature level 163), access to a
user's real email address was a realm-level setting. As of this
feature level, email_address_visibility is a user setting.
-
client: string
A Zulip "client" string, describing what Zulip client
sent the message.
-
content: string
The content/body of the message.
-
content_type: string
The HTTP content_type for the message content. This
will be text/html or text/x-markdown, depending on
whether apply_markdown was set.
-
display_recipient: string | (object)[]
Data on the recipient of the message;
either the name of a channel or a dictionary containing basic data on
the users who received the message.
-
edit_history: (object)[]
An array of objects, with each object documenting the
changes in a previous edit made to the message,
ordered chronologically from most recent to least recent
edit.
Not present if the message has never been edited or moved,
or if viewing message edit history
is not allowed in the organization.
Every object will contain user_id and timestamp.
The other fields are optional, and will be present or not
depending on whether the channel, topic, and/or message
content were modified in the edit event. For example, if
only the topic was edited, only prev_topic and topic
will be present in addition to user_id and timestamp.
Changes: In Zulip 10.0 (feature level 284), removed the
prev_rendered_content_version field as it is an internal
server implementation detail not used by any client.
-
prev_content: string
Only present if message's content was edited.
The content of the message immediately prior to this
edit event.
-
prev_rendered_content: string
Only present if message's content was edited.
The rendered HTML representation of prev_content.
-
prev_stream: integer
Only present if message's channel was edited.
The channel ID of the message immediately prior to this
edit event.
Changes: New in Zulip 3.0 (feature level 1).
-
prev_topic: string
Only present if message's topic was edited.
The topic of the message immediately prior to this
edit event.
Changes: New in Zulip 5.0 (feature level 118).
Previously, this field was called prev_subject;
clients are recommended to rename prev_subject to
prev_topic if present for compatibility with
older Zulip servers.
-
stream: integer
Only present if message's channel was edited.
The ID of the channel containing the message
immediately after this edit event.
Changes: New in Zulip 5.0 (feature level 118).
-
timestamp: integer
The UNIX timestamp for the edit.
-
topic: string
Only present if message's topic was edited.
The topic of the message immediately after this edit event.
Changes: New in Zulip 5.0 (feature level 118).
-
user_id: integer | null
The ID of the user that made the edit.
Will be null only for edit history
events predating March 2017.
Clients can display edit history events where this
is null as modified by either the sender (for content
edits) or an unknown user (for topic edits).
-
id: integer
The unique message ID. Messages should always be
displayed sorted by ID.
-
is_me_message: boolean
Whether the message is a /me status message
-
last_edit_timestamp: integer
The UNIX timestamp for when the message's content was last edited, in
UTC seconds.
Not present if the message's content has never been edited.
Clients should use this field, rather than parsing the edit_history
array, to display an indicator that the message has been edited.
Changes: Prior to Zulip 10.0 (feature level 365), this was the
time when the message was last edited or moved.
-
last_moved_timestamp: integer
The UNIX timestamp for when the message was last moved to a different
channel or topic, in UTC seconds.
Not present if the message has never been moved, or if the only topic
moves for the message are resolving or unresolving
the message's topic.
Clients should use this field, rather than parsing the edit_history
array, to display an indicator that the message has been moved.
Changes: New in Zulip 10.0 (feature level 365). Previously,
parsing the edit_history array was required in order to correctly
display moved message indicators.
-
reactions: (object)[]
Data on any reactions to the message.
-
emoji_name: string
Name of the emoji.
-
emoji_code: string
A unique identifier, defining the specific emoji codepoint requested,
within the namespace of the reaction_type.
-
reaction_type: string
A string indicating the type of emoji. Each emoji reaction_type
has an independent namespace for values of emoji_code.
Must be one of the following values:
-
unicode_emoji : In this namespace, emoji_code will be a
dash-separated hex encoding of the sequence of Unicode codepoints
that define this emoji in the Unicode specification.
-
realm_emoji : In this namespace, emoji_code will be the ID of
the uploaded custom emoji.
-
zulip_extra_emoji : These are special emoji included with Zulip.
In this namespace, emoji_code will be the name of the emoji (e.g.
"zulip").
-
user_id: integer
The ID of the user who added the reaction.
Changes: New in Zulip 3.0 (feature level 2). The user
object is deprecated and will be removed in the future.
In Zulip 10.0 (feature level 328), the deprecated user object
was removed which contained the following properties: id, email,
full_name and is_mirror_dummy.
-
recipient_id: integer
A unique ID for the set of users receiving the
message (either a channel or group of users). Useful primarily
for hashing.
Changes: Before Zulip 10.0 (feature level 327), recipient_id
was the same across all incoming 1:1 direct messages. Now, each
incoming message uniquely shares a recipient_id with outgoing
messages in the same conversation.
-
sender_email: string
The Zulip API email address of the message's sender.
-
sender_full_name: string
The full name of the message's sender.
-
sender_id: integer
The user ID of the message's sender.
-
sender_realm_str: string
A string identifier for the realm the sender is in. Unique only within
the context of a given Zulip server.
E.g. on example.zulip.com, this will be example.
-
stream_id: integer
Only present for channel messages; the ID of the channel.
-
subject: string
The topic of the message. Currently always "" for direct messages,
though this could change if Zulip adds support for topics in direct
message conversations.
The field name is a legacy holdover from when topics were
called "subjects" and will eventually change.
For clients that don't support the empty_topic_name client capability,
the empty string value is replaced with the value of realm_empty_topic_display_name
found in the POST /register response, for channel messages.
Changes: Before Zulip 10.0 (feature level 334), empty_topic_name
client capability didn't exist and empty string as the topic name for
channel messages wasn't allowed.
-
submessages: (object)[]
Data used for certain experimental Zulip integrations.
-
msg_type: string
The type of the message.
-
content: string
The new content of the submessage.
-
message_id: integer
The ID of the message to which the submessage has been added.
-
sender_id: integer
The ID of the user who sent the message.
-
id: integer
The ID of the submessage.
-
timestamp: integer
The UNIX timestamp for when the message was sent,
in UTC seconds.
-
topic_links: (object)[]
Data on any links to be included in the topic
line (these are generated by custom linkification
filters that match content in the
message's topic.)
Changes: This field contained a list of urls before
Zulip 4.0 (feature level 46).
New in Zulip 3.0 (feature level 1). Previously, this field was called
subject_links; clients are recommended to rename subject_links to topic_links
if present for compatibility with older Zulip servers.
-
type: string
The type of the message: "stream" or "private".
-
flags: (string)[]
The user's message flags for the message.
Clients should inspect the flags field rather than assuming that
new messages are unread; muted users, messages
sent by the current user, and more subtle scenarios can result
in a new message that the server has already marked as read for
the user.
Changes: In Zulip 8.0 (feature level 224), the wildcard_mentioned
flag was deprecated in favor of the stream_wildcard_mentioned and
topic_wildcard_mentioned flags. The wildcard_mentioned flag exists
for backwards compatibility with older clients and equals
stream_wildcard_mentioned || topic_wildcard_mentioned. Clients
supporting older server versions should treat this field as a previous
name for the stream_wildcard_mentioned flag as topic wildcard mentions
were not available prior to this feature level.
Example
{
"flags": [],
"id": 1,
"message": {
"avatar_url": null,
"client": "test suite",
"content": "<p>First message ...<a href=\"user_uploads/2/ce/2Xpnnwgh8JWKxBXtTfD6BHKV/zulip.txt\">zulip.txt</a></p>",
"content_type": "text/html",
"display_recipient": "Denmark",
"id": 31,
"is_me_message": false,
"reactions": [],
"recipient_id": 23,
"sender_email": "user10@zulip.testserver",
"sender_full_name": "King Hamlet",
"sender_id": 10,
"sender_realm_str": "zulip",
"stream_id": 1,
"subject": "test",
"submessages": [],
"timestamp": 1594825416,
"topic_links": [],
"type": "stream"
},
"type": "message"
}
Event sent to a user's clients when the user completes the OAuth flow
for the Zoom integration. Clients need
to know whether initiating Zoom OAuth is required before creating a Zoom
call.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
value: boolean
A boolean specifying whether the user has zoom
token or not.
Example
{
"id": 0,
"type": "has_zoom_token",
"value": true
}
A simple event sent when the set of invitations changes.
This event is sent to organization administrators and the creator of
the changed invitation; this tells clients they need to refetch
data from GET /invites if they are displaying UI containing active
invitations.
Changes: Before Zulip 8.0 (feature level 209), this event was
only sent to organization administrators.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
Example
{
"id": 0,
"type": "invites_changed"
}
Event sent to all users in a Zulip organization when a new
user joins or when a guest user gains access to a user.
Processing this event is important to being able to display
basic details on other users given only their ID.
If the current user is a guest whose access to a newly created user
is limited by a can_access_all_users_group policy, and the event
queue was registered with the user_list_incomplete client
capability, then the event queue will not receive an event for such
a new user. If a newly created user is inaccessible to the current
user via such a policy, but the client lacks user_list_incomplete
client capability, then this event will be delivered to the queue,
with an "Unknown user" object with the usual format but placeholder
data whose only variable content is the user ID.
Changes: Before Zulip 8.0 (feature level 232), the
user_list_incomplete client capability did not exist, and so all
clients whose access to a new user was prevented by
can_access_all_users_group policy would receive a fake "Unknown
user" event for such a user.
Starting with Zulip 8.0 (feature level 228),
this event is also sent when a guest user gains access to
a user.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
person: object
A dictionary containing basic data on a given Zulip user.
Changes: Removed is_billing_admin field in Zulip 10.0 (feature level 363), as it was
replaced by the can_manage_billing_group realm setting.
-
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_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 IANA identifier of the user's profile time zone,
which is used primarily to display the user's local time to other users.
-
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.
Example
{
"id": 0,
"op": "add",
"person": {
"avatar_url": "https://secure.gravatar.com/avatar/c6b5578d4964bd9c5fae593c6868912a?d=identicon&version=1",
"avatar_version": 1,
"date_joined": "2020-07-15T15:04:02.030833+00:00",
"delivery_email": null,
"email": "foo@zulip.com",
"full_name": "full name",
"is_active": true,
"is_admin": false,
"is_bot": false,
"is_guest": false,
"is_owner": false,
"profile_data": {},
"role": 400,
"timezone": "",
"user_id": 38
},
"type": "realm_user"
}
Event sent to guest users when they lose access to a user.
Changes: As of Zulip 8.0 (feature level 228), this event is no
longer deprecated.
In Zulip 8.0 (feature level 222), this event was deprecated and no
longer sent to clients. Prior to this feature level, it was sent to all
users in a Zulip organization when a user was deactivated.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
person: object
Object containing details of the deactivated user.
-
user_id: integer
The ID of the deactivated user.
-
full_name: string
The full name of the user.
Deprecated: We expect to remove this field in the future.
Example
{
"id": 0,
"op": "remove",
"person": {
"full_name": "Foo Bot",
"user_id": 35
},
"type": "realm_user"
}
Event sent to all users in an organization when a user comes back
online after being offline for a while.
In addition to handling these events, a client that wants to
maintain presence data must poll the main presence
endpoint. Most updates to
presence data, refreshing the timestamps of users who are already
online, do not appear in the event queue. This design is an
optimization by allowing those updates to be batched up, because
there is no urgency in the information that an already-online user
is still online.
These events are provided because when a user transitions from
offline to online, that is information the client may want to show
promptly in the UI to avoid showing a confusing state (for example,
if the newly-online user sends a message or otherwise demonstrates
they're online).
If the CAN_ACCESS_ALL_USERS_GROUP_LIMITS_PRESENCE server-level
setting is set to true, then the event is only sent to users
who can access the user who came back online.
Changes: Prior to Zulip 8.0 (feature level 228), this event
was sent to all users in the organization.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
user_id: integer
The ID of the modified user.
-
email: string
The Zulip API email of the user.
Deprecated: This field will be removed in a future
release as it is redundant with the user_id.
-
server_timestamp: number
The timestamp of when the Zulip server received the user's
presence as a UNIX timestamp.
-
presence: object
Object containing the details of the user's most recent presence.
-
{client_name}: object
Object containing the details of the user's
presence.
Changes: Starting with Zulip 7.0 (feature level 178), this
will always be "website" as the server no longer stores which
client submitted presence updates.
Previously, the object key was the client's platform name, for
example website or ZulipDesktop.
-
client: string
The client's platform name.
Changes: Starting with Zulip 7.0 (feature level 178), this
will always be "website" as the server no longer stores which
client submitted presence updates.
-
status: string
The status of the user on this client. Will be either idle
or active.
-
timestamp: integer
The UNIX timestamp of when this client sent the user's presence
to the server with the precision of a second.
-
pushable: boolean
Whether the client is capable of showing mobile/push notifications
to the user.
Changes: Starting with Zulip 7.0 (feature level 178), this
will always be false as the server no longer stores which
client submitted presence updates.
Example
{
"email": "user10@zulip.testserver",
"id": 0,
"presence": {
"website": {
"client": "website",
"pushable": false,
"status": "idle",
"timestamp": 1594825445
}
},
"server_timestamp": 1594825445.3200784,
"type": "presence",
"user_id": 10
}
Event sent when a new channel is created to users who can see
the new channel exists (for private channels, only subscribers and
organization administrators will receive this event).
This event is also sent when a user gains access to a channel they
previously could not access, such as
when their role changes, a
private channel is made public, or a guest user is subscribed
to a public (or private) channel.
This event is also sent when a channel is unarchived but only
to clients that did not declare the archived_channels client
capability.
Note that organization administrators who are not subscribed will
not be able to see content on the channel; just that it exists.
Changes: Prior to Zulip 11.0 (feature level 378), this
event was sent to all the users who could see the channel when it
was unarchived.
Prior to Zulip 8.0 (feature level 220), this event was incorrectly
not sent to guest users a web-public channel was created.
Prior to Zulip 8.0 (feature level 205), this event was not sent
when a user gained access to a channel due to their role changing.
Prior to Zulip 8.0 (feature level 192), this event was not sent
when guest users gained access to a public channel by being
subscribed.
Prior to Zulip 6.0 (feature level 134), this event was not sent
when a private channel was made public.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
streams: (object)[]
Array of objects, each containing
details about the newly added channel(s).
-
stream_id: integer
The unique ID of the channel.
-
name: string
The name of the channel.
-
is_archived: boolean
A boolean indicating whether the channel is archived.
Changes: New in Zulip 10.0 (feature level 315).
Previously, this endpoint never returned archived channels.
-
description: string
The short description of the channel in text/markdown format,
intended to be used to prepopulate UI for editing a channel's
description.
-
date_created: integer
The UNIX timestamp for when the channel was created, in UTC seconds.
Changes: New in Zulip 4.0 (feature level 30).
-
creator_id: integer | null
The ID of the user who created this channel.
A null value means the channel has no recorded creator, which is often
because the channel is very old, or because it was created via a data
import tool or management command.
Changes: New in Zulip 9.0 (feature level 254).
-
invite_only: boolean
Specifies whether the channel is private or not.
Only people who have been invited can access a private channel.
-
rendered_description: string
The short description of the channel rendered as HTML, intended to
be used when displaying the channel description in a UI.
One should use the standard Zulip rendered_markdown CSS when
displaying this content so that emoji, LaTeX, and other syntax
work correctly. And any client-side security logic for
user-generated message content should be applied when displaying
this HTML as though it were the body of a Zulip message.
-
is_web_public: boolean
Whether the channel has been configured to allow unauthenticated
access to its message history from the web.
Changes: New in Zulip 2.1.0.
-
stream_post_policy: integer
A deprecated representation of a superset of the users who
have permission to post messages to the channel available
for backwards-compatibility. Clients should use
can_send_message_group instead.
It is an enum with the following possible values, corresponding
to roles/system groups:
- 1 = Any user can post.
- 2 = Only administrators can post.
- 3 = Only full members can post.
- 4 = Only moderators can post.
Changes: Deprecated in Zulip 10.0 (feature level 333) and
replaced by can_send_message_group, which supports finer
resolution of configurations, resulting in this property being
inaccurate following that transition.
New in Zulip 3.0 (feature level 1), replacing the previous
is_announcement_only boolean.
-
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.
-
topics_policy: string
Setting defining the policy for sending messages to the empty topic in
this channel.
- inherit - Channel will inherit the organization-level setting,
realm_topics_policy.
- allow_empty_topic - Topics are not required to send messages in the channel.
- disable_empty_topic - Topics are required to send messages in the channel.
- empty_topic_only - Only the empty topic is available in this channel.
The empty_topic_only policy can only be enabled in a channel if all
messages in the channel are already in the empty topic.
Changes: In Zulip 11.0 (feature level 404), empty_topic_only option
was added.
New in Zulip 11.0 (feature level 392).
-
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.
-
folder_id: integer | null
The ID of the folder to which the channel belongs.
Is null if channel does not belong to any folder.
Changes: New in Zulip 11.0 (feature level 389).
-
is_recently_active: boolean
Whether the channel has recent message activity. Clients should use this to implement
sorting inactive channels to the bottom
if demote_inactive_streams is enabled.
Changes: New in Zulip 10.0 (feature level 323). Previously, clients implemented the
demote_inactive_streams from local message history, resulting in a choppy loading
experience.
-
is_announcement_only: 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_add_subscribers_group: integer | object
A group-setting value defining the set of users
who have permission to add subscribers to this channel.
Users who can administer the channel or have similar realm-level
permissions can add subscribers to a public channel regardless
of the value of this setting.
Users in this group need not be subscribed to a private channel to
add subscribers to it.
Note that a user must have content access
to a channel and permission to administer the channel in order to
modify this setting.
Changes: New in Zulip 10.0 (feature level 342). Previously, there was no
channel-level setting for this permission.
-
can_remove_subscribers_group: integer | object
A group-setting value defining the set of users
who have permission to remove subscribers from this channel.
Organization administrators can unsubscribe others from a channel as though
they were in this group without being explicitly listed here.
Note that a user must have metadata access to a channel and permission
to administer the channel in order to modify this setting.
Changes: Prior to Zulip 10.0 (feature level 349), channel administrators
could not unsubscribe other users if they were not an organization
administrator or part of can_remove_subscribers_group. Realm administrators
were not allowed to unsubscribe other users from a private channel if they
were not subscribed to that channel.
Prior to Zulip 10.0 (feature level 320), this value was always the integer
ID of a system group.
Before Zulip 8.0 (feature level 197), the can_remove_subscribers_group
setting was named can_remove_subscribers_group_id.
New in Zulip 6.0 (feature level 142).
-
can_administer_channel_group: integer | object
A group-setting value defining the set of users
who have permission to administer this channel.
Organization administrators can administer every channel as though they were
in this group without being explicitly listed here.
Note that a user must have metadata access to a channel and permission
to administer the channel in order to modify this setting.
Changes: Prior to Zulip 10.0 (feature level 349) a user needed to
have content access to a channel in
order to modify it. The exception to this rule was that organization
administrators can edit channel names and descriptions without
having full access to the channel.
New in Zulip 10.0 (feature level 325). Prior to this
change, the permission to administer channels was limited to realm
administrators.
-
can_move_messages_out_of_channel_group: integer | object
A group-setting value defining the set of users
who have permission to move messages out of this channel.
Note that a user must have content access to a
channel in order to move messages out of the channel.
Channel administrators and users present in the organization-level
can_move_messages_between_channels_group setting can always move messages
out of the channel if they have content access to
the channel.
Changes: New in Zulip 11.0 (feature level 396). Prior to this
change, only the users in can_move_messages_between_channels_group were able
move messages between channels.
-
can_move_messages_within_channel_group: integer | object
A group-setting value defining the set of users
who have permission to move messages within this channel.
Note that a user must have content access to a
channel in order to move messages within the channel.
Channel administrators and users present in the organization-level
can_move_messages_between_topics_group setting can always move messages
within the channel if they have content access to
the channel.
Changes: New in Zulip 11.0 (feature level 396). Prior to this
change, only the users in can_move_messages_between_topics_group were able
move messages between topics of a channel.
-
can_send_message_group: integer | object
A group-setting value defining the set of users
who have permission to post in this channel.
Note that a user must have metadata access to a channel and permission
to administer the channel in order to modify this setting.
Changes: New in Zulip 10.0 (feature level 333). Previously
stream_post_policy field used to control the permission to
post in the channel.
-
can_subscribe_group: integer | object
A group-setting value defining the set of users
who have permission to subscribe themselves to this channel.
Everyone, excluding guests, can subscribe to any public channel
irrespective of this setting.
Users in this group can subscribe to a private channel as well.
Note that a user must have content access
to a channel and permission to administer the channel in order to
modify this setting.
Changes: New in Zulip 10.0 (feature level 357).
-
can_resolve_topics_group: integer | object
A group-setting value defining the set of users
who have permission to resolve topics in the channel.
Users who have similar realm-level permissions can resolve topics
in a channel regardless of the value of this setting.
Changes: New in Zulip 11.0 (feature level 402).
-
subscriber_count: number
The total number of non-deactivated users (including bots) who
are subscribed to the channel. Clients are responsible for updating
this value using peer_add and peer_remove events.
The server's internals cannot guarantee this value is correctly
synced with peer_add and peer_remove events for the channel. As
a result, if a (rare) race occurs between a change in the channel's
subscribers and fetching this value, it is possible for a client
that is correctly following the events protocol to end up with a
permanently off-by-one error in the channel's subscriber count.
Clients are recommended to fetch full subscriber data for a channel
in contexts where it is important to avoid this risk. The official
web application, for example, uses this field primarily while
waiting to fetch a given channel's full subscriber list from the
server.
Changes: New in Zulip 11.0 (feature level 394).
-
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.
Example
{
"id": 0,
"op": "create",
"streams": [
{
"can_add_subscribers_group": 2,
"can_remove_subscribers_group": 2,
"can_subscribe_group": 2,
"creator_id": 11,
"date_created": 1691057093,
"description": "",
"first_message_id": null,
"folder_id": 1,
"history_public_to_subscribers": false,
"invite_only": true,
"is_announcement_only": false,
"is_archived": false,
"is_recently_active": true,
"is_web_public": false,
"message_retention_days": null,
"name": "private",
"rendered_description": "",
"stream_id": 12,
"stream_post_policy": 1,
"stream_weekly_traffic": null,
"subscriber_count": 0
}
],
"type": "stream"
}
Event sent when a user loses access to a channel they previously
could access because they are
unsubscribed from a private channel or their role
has changed.
This event is also sent when a channel is archived but only
to clients that did not declare the archived_channels client
capability.
Changes: Prior to Zulip 11.0 (feature level 378), this
event was sent to all the users who could see the channel when it
was archived.
Prior to Zulip 8.0 (feature level 205), this event was not sent
when a user lost access to a channel due to their role changing.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
streams: (object)[]
Array of objects, each containing ID of the channel that was deleted.
Changes: Deprecated in Zulip 10.0 (feature level 343)
and will be removed in a future release. Previously, these
objects additionally contained all the standard fields for a
channel object.
-
stream_ids: (integer)[]
Array containing the IDs of the channels that were deleted.
Changes: New in Zulip 10.0 (feature level 343). Previously,
these IDs were available only via the legacy streams array.
Example
{
"id": 0,
"op": "delete",
"stream_ids": [
1,
2
],
"streams": [
{
"stream_id": 1
},
{
"stream_id": 2
}
],
"type": "stream"
}
Event sent to all users who can see that a channel exists
when a property of that channel changes. See
GET /streams response
for details on the various properties of a channel.
This event is also sent when archiving or unarchiving a
channel to all the users who can see that channel exists
but only to the clients that declared the archived_channels
client capability.
Changes: Prior to Zulip 11.0 (feature level 378),
this event was never sent when archiving or unarchiving
a channel.
Before Zulip 9.0 (feature level 256), this event was never
sent when the first_message_id property of a channel was
updated because the oldest message that had been sent to it
changed.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
stream_id: integer
The ID of the channel whose details have changed.
-
name: string
The name of the channel whose details have changed.
-
property: string
The property of the channel which has changed. See
GET /streams response for details
on the various properties of a channel.
Clients should handle an "unknown" property received here without
crashing, since that can happen when connecting to a server running a
newer version of Zulip with new features.
-
value: object | integer | boolean | string | null
The new value of the changed property.
Changes: Starting with Zulip 11.0 (feature level 389),
this value can be null when a channel is removed from the folder.
Starting with Zulip 10.0 (feature level 320), this
field can be an object for can_remove_subscribers_group property,
which is a group-setting value, when the setting
is set to a combination of users and groups.
-
rendered_description: string
Note: Only present if the changed property was description.
The short description of the channel rendered as HTML, intended to
be used when displaying the channel description in a UI.
One should use the standard Zulip rendered_markdown CSS when
displaying this content so that emoji, LaTeX, and other syntax
work correctly. And any client-side security logic for
user-generated message content should be applied when displaying
this HTML as though it were the body of a Zulip message.
-
history_public_to_subscribers: boolean
Note: Only present if the changed property was invite_only.
Whether the history of the channel is public to its subscribers.
Currently always true for public channels (i.e. "invite_only": false implies
"history_public_to_subscribers": true), but clients should not make that
assumption, as we may change that behavior in the future.
-
is_web_public: boolean
Note: Only present if the changed property was invite_only.
Whether the channel's history is now readable by web-public spectators.
Changes: New in Zulip 5.0 (feature level 71).
Example
{
"history_public_to_subscribers": true,
"id": 0,
"is_web_public": false,
"name": "test",
"op": "update",
"property": "invite_only",
"stream_id": 11,
"type": "stream",
"value": true
}
Event sent when a reaction is added to a message.
Sent to all users who were recipients of the message.
-
emoji_name: string
Name of the emoji.
-
emoji_code: string
A unique identifier, defining the specific emoji codepoint requested,
within the namespace of the reaction_type.
-
reaction_type: string
A string indicating the type of emoji. Each emoji reaction_type
has an independent namespace for values of emoji_code.
Must be one of the following values:
-
unicode_emoji : In this namespace, emoji_code will be a
dash-separated hex encoding of the sequence of Unicode codepoints
that define this emoji in the Unicode specification.
-
realm_emoji : In this namespace, emoji_code will be the ID of
the uploaded custom emoji.
-
zulip_extra_emoji : These are special emoji included with Zulip.
In this namespace, emoji_code will be the name of the emoji (e.g.
"zulip").
-
user_id: integer
The ID of the user who added the reaction.
Changes: New in Zulip 3.0 (feature level 2). The user
object is deprecated and will be removed in the future.
-
user: object
Dictionary with data on the user who added the
reaction, including the user ID as the user_id
field.
Changes: This field was re-added in Zulip 10.0 (feature
level 339) after having been removed in Zulip 10.0 (feature
level 328). It remains deprecated; it was re-added because the
React Native mobile app was still using it.
Deprecated and to be removed in a future release once core
clients have migrated to use the adjacent user_id field, which
was introduced in Zulip 3.0 (feature level 2). Clients
supporting older Zulip server versions should use the user ID
mentioned in the description above as they would the user_id
field.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
message_id: integer
The ID of the message to which a reaction was
added.
Example
{
"emoji_code": "1f389",
"emoji_name": "tada",
"id": 0,
"message_id": 32,
"op": "add",
"reaction_type": "unicode_emoji",
"type": "reaction",
"user": {
"email": "user10@zulip.testserver",
"full_name": "King Hamlet",
"user_id": 10
},
"user_id": 10
}
Event sent when a reaction is removed from a message.
Sent to all users who were recipients of the message.
-
emoji_name: string
Name of the emoji.
-
emoji_code: string
A unique identifier, defining the specific emoji codepoint requested,
within the namespace of the reaction_type.
-
reaction_type: string
A string indicating the type of emoji. Each emoji reaction_type
has an independent namespace for values of emoji_code.
Must be one of the following values:
-
unicode_emoji : In this namespace, emoji_code will be a
dash-separated hex encoding of the sequence of Unicode codepoints
that define this emoji in the Unicode specification.
-
realm_emoji : In this namespace, emoji_code will be the ID of
the uploaded custom emoji.
-
zulip_extra_emoji : These are special emoji included with Zulip.
In this namespace, emoji_code will be the name of the emoji (e.g.
"zulip").
-
user_id: integer
The ID of the user who added the reaction.
Changes: New in Zulip 3.0 (feature level 2). The user
object is deprecated and will be removed in the future.
-
user: object
Dictionary with data on the user who added the
reaction, including the user ID as the user_id
field.
Changes: This field was re-added in Zulip 10.0 (feature
level 339) after having been removed in Zulip 10.0 (feature
level 328). It remains deprecated; it was re-added because the
React Native mobile app was still using it.
Deprecated and to be removed in a future release once core
clients have migrated to use the adjacent user_id field, which
was introduced in Zulip 3.0 (feature level 2). Clients
supporting older Zulip server versions should use the user ID
mentioned in the description above as they would the user_id
field.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
message_id: integer
The ID of the message from which the reaction was
removed.
Example
{
"emoji_code": "1f389",
"emoji_name": "tada",
"id": 0,
"message_id": 52,
"op": "remove",
"reaction_type": "unicode_emoji",
"type": "reaction",
"user": {
"email": "user10@zulip.testserver",
"full_name": "King Hamlet",
"user_id": 10
},
"user_id": 10
}
Event sent to a user's clients when the user uploads a new file
in a Zulip message. Useful to implement live update in UI showing all files
the current user has uploaded.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
attachment: object
Dictionary containing details of a file uploaded by a user.
-
id: integer
The unique ID for the attachment.
-
name: string
Name of the uploaded file.
-
path_id: string
A representation of the path of the file within the
repository of user-uploaded files. If the path_id of a
file is {realm_id}/ab/cdef/temp_file.py, its URL will be:
{server_url}/user_uploads/{realm_id}/ab/cdef/temp_file.py.
-
size: integer
Size of the file in bytes.
-
create_time: integer
Time when the attachment was uploaded as a UNIX timestamp
multiplied by 1000 (matching the format of getTime() in JavaScript).
Changes: Changed in Zulip 3.0 (feature level 22). This field was
previously a floating point number.
-
messages: (object)[]
Contains basic details on any Zulip messages that have been
sent referencing this uploaded file.
This includes messages sent by any user in the Zulip
organization who sent a message containing a link to the
uploaded file.
-
date_sent: integer
Time when the message was sent as a UNIX timestamp
multiplied by 1000 (matching the format of getTime() in JavaScript).
Changes: Changed in Zulip 3.0 (feature level 22). This
field was previously strangely called name and was a floating
point number.
-
id: integer
The unique message ID. Messages should always be
displayed sorted by ID.
-
upload_space_used: integer
The total size of all files uploaded by in the organization,
in bytes.
Example
{
"attachment": {
"create_time": 1594825414000,
"id": 1,
"messages": [],
"name": "zulip.txt",
"path_id": "2/ce/2Xpnnwgh8JWKxBXtTfD6BHKV/zulip.txt",
"size": 6
},
"id": 0,
"op": "add",
"type": "attachment",
"upload_space_used": 6
}
Event sent to a user's clients when details of a file that user
uploaded are changed. Most updates will be changes in the list of
messages that reference the uploaded file.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
attachment: object
Dictionary containing details of a file uploaded by a user.
-
id: integer
The unique ID for the attachment.
-
name: string
Name of the uploaded file.
-
path_id: string
A representation of the path of the file within the
repository of user-uploaded files. If the path_id of a
file is {realm_id}/ab/cdef/temp_file.py, its URL will be:
{server_url}/user_uploads/{realm_id}/ab/cdef/temp_file.py.
-
size: integer
Size of the file in bytes.
-
create_time: integer
Time when the attachment was uploaded as a UNIX timestamp
multiplied by 1000 (matching the format of getTime() in JavaScript).
Changes: Changed in Zulip 3.0 (feature level 22). This field was
previously a floating point number.
-
messages: (object)[]
Contains basic details on any Zulip messages that have been
sent referencing this uploaded file.
This includes messages sent by any user in the Zulip
organization who sent a message containing a link to the
uploaded file.
-
date_sent: integer
Time when the message was sent as a UNIX timestamp
multiplied by 1000 (matching the format of getTime() in JavaScript).
Changes: Changed in Zulip 3.0 (feature level 22). This
field was previously strangely called name and was a floating
point number.
-
id: integer
The unique message ID. Messages should always be
displayed sorted by ID.
-
upload_space_used: integer
The total size of all files uploaded by in the organization,
in bytes.
Example
{
"attachment": {
"create_time": 1594825414000,
"id": 1,
"messages": [],
"name": "zulip.txt",
"path_id": "2/ce/2Xpnnwgh8JWKxBXtTfD6BHKV/zulip.txt",
"size": 6
},
"id": 0,
"op": "update",
"type": "attachment",
"upload_space_used": 6
}
Event sent to a user's clients when the user deletes a file
they had uploaded. Useful primarily for UI showing all the files
the current user has uploaded.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
attachment: object
Dictionary containing the ID of the deleted attachment.
-
upload_space_used: integer
The total size of all files uploaded by in the organization,
in bytes.
Example
{
"attachment": {
"id": 1
},
"id": 0,
"op": "remove",
"type": "attachment",
"upload_space_used": 0
}
Event sent when a submessage is added to a message.
Submessages are an experimental API used for widgets such as the
/poll widget in Zulip.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
msg_type: string
The type of the message.
-
content: string
The new content of the submessage.
-
message_id: integer
The ID of the message to which the submessage has been added.
-
sender_id: integer
The ID of the user who sent the message.
-
submessage_id: integer
The ID of the submessage.
Example
{
"content": "{\"type\":\"vote\",\"key\":\"58,1\",\"vote\":1}",
"id": 28,
"message_id": 970461,
"msg_type": "widget",
"sender_id": 58,
"submessage_id": 4737,
"type": "submessage"
}
Event sent to all users who can access the modified
user when the status of a user changes.
Changes: Prior to Zulip 8.0 (feature level 228),
this event was sent to all users in the organization.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
away: boolean
Whether the user has marked themself "away" with this status.
Changes: Deprecated in Zulip 6.0 (feature level 148);
starting with that feature level, away is a legacy way to
access the user's presence_enabled setting, with
away = !presence_enabled. To be removed in a future release.
-
status_text: string
The text content of the status message.
This will be "" for users who set a status without selecting
or writing a message.
-
emoji_name: string
The emoji name for
the emoji the user selected for their new status.
This will be "" for users who set a status without selecting
an emoji.
Changes: New in Zulip 5.0 (feature level 86).
-
emoji_code: string
The emoji code for
the emoji the user selected for their new status.
This will be "" for users who set a status without selecting
an emoji.
Changes: New in Zulip 5.0 (feature level 86).
-
reaction_type: string
The emoji type for
the emoji the user selected for their new status.
This will be "" for users who set a status without selecting
an emoji.
Changes: New in Zulip 5.0 (feature level 86).
-
user_id: integer
The ID of the user whose status changed.
Example
{
"away": true,
"emoji_code": "1f697",
"emoji_name": "car",
"id": 0,
"reaction_type": "unicode_emoji",
"status_text": "out to lunch",
"type": "user_status",
"user_id": 10
}
Event sent to all users in a Zulip organization when new custom
profile field types are configured for that Zulip organization.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
fields: (object)[]
An array of dictionaries where each dictionary contains
details of a single new custom profile field for the Zulip
organization.
-
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).
Example
{
"fields": [
{
"editable_by_user": true,
"field_data": "",
"hint": "",
"id": 1,
"name": "Phone number",
"order": 1,
"required": true,
"type": 1
},
{
"editable_by_user": true,
"field_data": "",
"hint": "What are you known for?",
"id": 2,
"name": "Biography",
"order": 2,
"required": true,
"type": 2
},
{
"editable_by_user": true,
"field_data": "",
"hint": "Or drink, if you'd prefer",
"id": 3,
"name": "Favorite food",
"order": 3,
"required": false,
"type": 1
},
{
"display_in_profile_summary": true,
"editable_by_user": true,
"field_data": "{\"0\":{\"text\":\"Vim\",\"order\":\"1\"},\"1\":{\"text\":\"Emacs\",\"order\":\"2\"}}",
"hint": "",
"id": 4,
"name": "Favorite editor",
"order": 4,
"required": true,
"type": 3
},
{
"editable_by_user": false,
"field_data": "",
"hint": "",
"id": 5,
"name": "Birthday",
"order": 5,
"required": false,
"type": 4
},
{
"display_in_profile_summary": true,
"editable_by_user": true,
"field_data": "",
"hint": "Or your personal blog's URL",
"id": 6,
"name": "Favorite website",
"order": 6,
"required": false,
"type": 5
},
{
"editable_by_user": false,
"field_data": "",
"hint": "",
"id": 7,
"name": "Mentor",
"order": 7,
"required": true,
"type": 6
},
{
"editable_by_user": true,
"field_data": "{\"subtype\":\"github\"}",
"hint": "Enter your GitHub username",
"id": 8,
"name": "GitHub",
"order": 8,
"required": true,
"type": 7
}
],
"id": 0,
"type": "custom_profile_fields"
}
Event sent to all users in a Zulip organization when an organization
administrator changes the organization's configured default channel groups.
Default channel groups are an experimental feature that is not yet
stabilized.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
default_stream_groups: (object)[]
An array of dictionaries where each dictionary
contains details about a single default channel group.
-
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: (integer)[]
An array of IDs of all the channels in the default stream group.
Changes: Before Zulip 10.0 (feature level 330), we sent array
of dictionaries where each dictionary contained details about a
single stream in the default stream group.
Example
{
"default_stream_groups": [
{
"description": "New description",
"id": 2,
"name": "group1",
"streams": [
3,
1,
5
]
}
],
"id": 0,
"type": "default_stream_groups"
}
Event sent to all users in a Zulip organization when the
default channels in the organization are changed by an
organization administrator.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
default_streams: (integer)[]
An array of IDs of all the default channels
in the organization.
Changes: Before Zulip 10.0 (feature level 330),
we sent array of dictionaries where each dictionary
contained details about a single default stream for
the Zulip organization.
Example
{
"default_streams": [
2,
3
],
"id": 0,
"type": "default_streams"
}
Event sent when a message has been deleted.
Sent to all users who currently are subscribed to the
messages' recipient. May also be sent to additional users
who had access to it, including, in particular, an
administrator user deleting messages in a stream that they
are not subscribed to.
This means that clients can assume that they will always
receive an event of this type for deletions that the
client itself initiated.
This event is also sent when the user loses access to a message,
such as when it is moved to a channel that
the user does not have permission to access.
Changes: Before Zulip 9.0 (feature level 274), this
event was only sent to subscribers of the message's recipient.
Before Zulip 5.0 (feature level 77), events
for direct messages contained additional sender_id and
recipient_id fields.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
message_ids: (integer)[]
Only present for clients that support the bulk_message_deletion
client capability.
A sorted list containing the IDs of the newly deleted messages.
Changes: Before Zulip 11.0 (feature level 393), this list was
not guaranteed to be sorted.
-
message_id: integer
Only present for clients that do not support the bulk_message_deletion
client capability.
The ID of the newly deleted message.
-
message_type: string
The type of message. Either "stream" or "private".
-
stream_id: integer
Only present if message_type is "stream".
The ID of the channel to which the message was sent.
-
topic: string
Only present if message_type is "stream".
The topic to which the message was sent.
For clients that don't support the empty_topic_name client capability,
if the actual topic name was empty string, this field's value will instead
be the value of realm_empty_topic_display_name found in the
POST /register response.
Changes: Before 10.0 (feature level 334), empty_topic_name
client capability didn't exist and empty string as the topic name for
channel messages wasn't allowed.
Example
{
"id": 0,
"message_id": 37,
"message_type": "private",
"type": "delete_message"
}
Event sent to a user's clients when that user's set of
configured muted topics have changed.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
muted_topics: ((string | integer)[])[]
Array of tuples, where each tuple describes a muted topic.
The first element of the tuple is the channel name in which the topic
has to be muted, the second element is the topic name to be muted
and the third element is an integer UNIX timestamp representing
when the topic was muted.
Changes: Deprecated in Zulip 6.0 (feature level
134). Starting with this version, clients that explicitly
requested the replacement user_topic event type when
registering their event queue will not receive this legacy
event type.
Before Zulip 3.0 (feature level 1), the muted_topics
array objects were 2-item tuples and did not include the timestamp
information for when the topic was muted.
Example
{
"id": 0,
"muted_topics": [
[
"Denmark",
"topic",
1594825442
]
],
"type": "muted_topics"
}
Event sent to a user's clients when the user mutes/unmutes
a topic, or otherwise modifies their personal per-topic
configuration.
Changes: New in Zulip 6.0 (feature level 134). Previously,
clients were notified about changes in muted topic
configuration via the muted_topics event type.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
stream_id: integer
The ID of the channel to which the topic belongs.
-
topic_name: string
The name of the topic.
For clients that don't support the empty_topic_name client capability,
if the actual topic name is empty string, this field's value will instead
be the value of realm_empty_topic_display_name found in the
POST /register response.
Changes: Before 10.0 (feature level 334), empty_topic_name
client capability didn't exist and empty string as the topic name for
channel messages wasn't allowed.
-
last_updated: integer
An integer UNIX timestamp representing when the user-topic
relationship was last changed.
-
visibility_policy: integer
An integer indicating the user's visibility
preferences for the topic, such as whether the topic
is muted.
- 0 = None. Used to indicate that the user no
longer has a special visibility policy for this topic.
- 1 = Muted. Used to record muted topics.
- 2 = Unmuted. Used to record unmuted topics.
- 3 = Followed. Used to record followed topics.
Changes: In Zulip 7.0 (feature level 219), added followed as
a visibility policy option.
In Zulip 7.0 (feature level 170), added unmuted as a visibility
policy option.
Example
{
"id": 1,
"last_updated": 1594825442,
"stream_id": 1,
"topic_name": "topic",
"type": "user_topic",
"visibility_policy": 1
}
Event sent to a user's clients when that user's set of
configured muted users have changed.
Changes: New in Zulip 4.0 (feature level 48).
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
muted_users: (object)[]
A list of dictionaries where each dictionary describes
a muted user.
Example
{
"id": 0,
"muted_users": [
{
"id": 1,
"timestamp": 1594825442
},
{
"id": 22,
"timestamp": 1654865392
}
],
"type": "muted_users"
}
Heartbeat events are sent by the server to avoid
longpolling connections being affected by networks that
kill idle HTTP connections.
Clients do not need to do anything to process these
events, beyond the common last_event_id accounting.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
Example
{
"id": 0,
"type": "heartbeat"
}
Event sent when the set of onboarding steps to show for the current user
has changed (e.g. because the user dismissed one).
Clients that feature a similar tutorial experience to the Zulip web app
may want to handle these events.
Changes: Before Zulip 8.0 (feature level 233), this event was named
hotspots. Prior to this feature level, one-time notice onboarding
steps were not supported.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
onboarding_steps: (object)[]
An array of dictionaries where each dictionary contains details about a
single onboarding step.
Changes: Before Zulip 8.0 (feature level 233), this array was named
hotspots. Prior to this feature level, one-time notice onboarding
steps were not supported, and the type field in these objects did not
exist as all onboarding steps were implicitly hotspots.
-
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.
Example
{
"id": 0,
"onboarding_steps": [
{
"name": "visibility_policy_banner",
"type": "one_time_notice"
}
],
"type": "onboarding_steps"
}
Event sent when a message's content, topic and/or
channel has been edited or when a message's content
has a rendering update, such as for an
inline URL preview.
Sent to all users who had received the original
message.
Changes: In Zulip 10.0 (feature level 284), removed the
prev_rendered_content_version field as it is an internal
server implementation detail not used by any client.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
user_id: integer | null
The ID of the user who sent the message.
Is null when event is for a rendering update of the original message,
such as for an inline URL preview.
Changes: As of Zulip 5.0 (feature level 114), this field
is present for all update_message events. Previously, this
field was omitted for inline URL preview
updates.
-
rendering_only: boolean
Whether the event only updates the rendered content of the message.
This field should be used by clients to determine if the event
only provides a rendering update to the message content,
such as for an inline URL preview.
When true, the event does not reflect a user-generated edit
and does not modify the message history.
Changes: New in Zulip 5.0 (feature level 114). Clients can
correctly identify these rendering update event with earlier
Zulip versions by checking whether the user_id field was omitted.
-
message_id: integer
The ID of the message which was edited or updated.
This field should be used to apply content edits to the client's
cached message history, or to apply rendered content updates.
If the channel or topic was changed, the set of moved messages is
encoded in the separate message_ids field, which is guaranteed
to include message_id.
-
message_ids: (integer)[]
A sorted list of IDs of messages to which any channel or topic
changes encoded in this event should be applied.
This list always includes message_id, even when there are no
channel or topic changes to apply.
These messages are guaranteed to have all been previously sent
to channel stream_id with topic orig_subject, and have been
moved to new_stream_id with topic subject (if those fields
are present in the event).
Clients processing these events should update all cached message
history associated with the moved messages (including adjusting
unread_msgs data structures, where the client may not have the
message itself in its history) to reflect the new channel and
topic.
Content changes should be applied only to the single message
indicated by message_id.
Changes: Before Zulip 11.0 (feature level 393), this list
was not guaranteed to be sorted.
-
flags: (string)[]
The user's personal message flags for the
message with ID message_id following the edit.
A client application should compare these to the original flags
to identify cases where a mention or alert word was added by the
edit.
Changes: In Zulip 8.0 (feature level 224), the wildcard_mentioned
flag was deprecated in favor of the stream_wildcard_mentioned and
topic_wildcard_mentioned flags. The wildcard_mentioned flag exists
for backwards compatibility with older clients and equals
stream_wildcard_mentioned || topic_wildcard_mentioned. Clients
supporting older server versions should treat this field as a previous
name for the stream_wildcard_mentioned flag as topic wildcard mentions
were not available prior to this feature level.
-
edit_timestamp: integer
The time when this message edit operation was processed by the
server.
Changes: As of Zulip 5.0 (feature level 114), this field
is present for all update_message events. Previously, this
field was omitted for inline URL preview
updates.
-
stream_name: string
Only present if the message was edited and originally sent to a channel.
The name of the channel that the message was sent to. Clients
are recommended to use the stream_id field instead.
-
stream_id: integer
Only present if the message was edited and originally sent to a channel.
The pre-edit channel for all of the messages with IDs in
message_ids.
Changes: As of Zulip 5.0 (feature level 112), this field
is present for all edits to a channel message. Previously, it
was not present when only the content of the channel message was
edited.
-
new_stream_id: integer
Only present if message(s) were moved to a different channel.
The post-edit channel for all of the messages with IDs in
message_ids.
-
propagate_mode: string
Only present if this event moved messages to a different
topic and/or channel.
The choice the editing user made about which messages should be
affected by a channel/topic edit:
"change_one": Just change the one indicated in message_id."change_later": Change messages in the same topic that had
been sent after this one."change_all": Change all messages in that topic.
This parameter should be used to decide whether to change
navigation and compose box state in response to the edit. For
example, if the user was previously in topic narrow, and the
topic was edited with "change_later" or "change_all", the Zulip
web app will automatically navigate to the new topic narrow.
Similarly, a message being composed to the old topic should
have its recipient changed to the new topic.
This navigation makes it much more convenient to move content
between topics without disruption or messages continuing
to be sent to the pre-edit topic by accident.
-
orig_subject: string
Only present if this event moved messages to a different
topic and/or channel.
The pre-edit topic for all of the messages with IDs in
message_ids.
For clients that don't support the empty_topic_name client capability,
if the actual pre-edit topic name is empty string, this field's value will instead
be the value of realm_empty_topic_display_name found in the
POST /register response.
Changes: Before 10.0 (feature level 334), empty_topic_name
client capability didn't exist and empty string as the topic name for
channel messages wasn't allowed.
-
subject: string
Only present if this event moved messages to a different topic;
this field will not be present when moving messages to the same
topic name in a different channel.
The post-edit topic for all of the messages with IDs in
message_ids.
For clients that don't support the empty_topic_name client capability,
if the actual post-edit topic name is empty string, this field's value will instead
be the value of realm_empty_topic_display_name found in the
POST /register response.
Changes: Before 10.0 (feature level 334), empty_topic_name
client capability didn't exist and empty string as the topic name for
channel messages wasn't allowed.
-
topic_links: (object)[]
Only present if this event moved messages to a different topic;
this field will not be present when moving messages to the same
topic name in a different channel.
Data on any links to be included in the topic
line (these are generated by
custom linkification filter
that match content in the message's topic.), corresponding
to the post-edit topic.
Changes: This field contained a list of urls before
Zulip 4.0 (feature level 46).
New in Zulip 3.0 (feature level 1). Previously, this field
was called subject_links; clients are recommended to
rename subject_links to topic_links if present for
compatibility with older Zulip servers.
-
orig_content: string
Only present if this event changed the message content.
The original content of the message with ID message_id
immediately prior to this edit, in the original markdown.
-
orig_rendered_content: string
Only present if this event changed the message content.
The original content of the message with ID message_id
immediately prior to this edit, rendered as HTML.
-
content: string
Only present if this event changed the message content or
updated the message content for an
inline URL preview.
The new content of the message with ID message_id, in the
original Markdown.
-
rendered_content: string
Only present if this event changed the message content or
updated the message content for an
inline URL preview.
The new content of the message with ID message_id,
rendered in HTML.
-
is_me_message: boolean
Only present if this event changed the message content.
Whether the message with ID message_id is now a
/me status message.
Example
{
"content": "new content",
"edit_timestamp": 1594825451,
"flags": [],
"id": 0,
"is_me_message": false,
"message_id": 58,
"message_ids": [
57,
58
],
"orig_content": "hello",
"orig_rendered_content": "<p>hello</p>",
"orig_subject": "test",
"propagate_mode": "change_all",
"rendered_content": "<p>new content</p>",
"rendering_only": false,
"stream_id": 5,
"stream_name": "Verona",
"subject": "new_topic",
"topic_links": [],
"type": "update_message",
"user_id": 10
}
Event sent when a user starts typing a message.
Sent to all clients for users who would receive the
message being typed, with the additional rule that typing
notifications for channel messages are only sent to clients
that included stream_typing_notifications in their
client capabilities when registering
the event queue.
See POST /typing endpoint for more details.
Changes: Typing notifications for channel messages are new in
Zulip 4.0 (feature level 58).
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
message_type: string
Type of message being composed. Must be "stream" or "direct".
Changes: In Zulip 8.0 (feature level 215), replaced the
value "private" with "direct".
New in Zulip 4.0 (feature level 58). Previously, all typing
notifications were implicitly direct messages.
-
sender: object
Object describing the user who is typing the message.
-
recipients: (object)[]
Only present if message_type is "direct".
Array of dictionaries describing the set of users who would be
recipients of the message being typed. Each dictionary contains
details about one of the recipients. The sending user is guaranteed
to appear among the recipients.
-
stream_id: integer
Only present if message_type is "stream".
The unique ID of the channel to which message is being typed.
Changes: New in Zulip 4.0 (feature level 58). Previously,
typing notifications were only for direct messages.
-
topic: string
Only present if message_type is "stream".
Topic within the channel where the message is being typed.
For clients that don't support the empty_topic_name client capability,
if the actual topic name is empty string, this field's value will instead
be the value of realm_empty_topic_display_name found in the
POST /register response.
Changes: Before 10.0 (feature level 334), empty_topic_name
client capability didn't exist and empty string as the topic name for
channel messages wasn't allowed.
New in Zulip 4.0 (feature level 58). Previously, typing notifications
were only for direct messages.
Example
{
"id": 0,
"message_type": "direct",
"op": "start",
"recipients": [
{
"email": "user8@zulip.testserver",
"user_id": 8
},
{
"email": "user10@zulip.testserver",
"user_id": 10
}
],
"sender": {
"email": "user10@zulip.testserver",
"user_id": 10
},
"type": "typing"
}
Event sent when a user stops typing a message.
Sent to all clients for users who would receive the message
that was previously being typed, with the additional rule
that typing notifications for channel messages are only sent to
clients that included stream_typing_notifications in their
client capabilities when registering
the event queue.
See POST /typing endpoint for more details.
Changes: Typing notifications for channel messages are new in
Zulip 4.0 (feature level 58).
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
message_type: string
Type of message being composed. Must be "stream" or "direct".
Changes: In Zulip 8.0 (feature level 215), replaced the
value "private" with "direct".
New in Zulip 4.0 (feature level 58). Previously all typing
notifications were implicitly direct messages.
-
sender: object
Object describing the user who was previously typing the message.
-
recipients: (object)[]
Only present if message_type is "direct".
Array of dictionaries describing the set of users who would be
recipients of the message that was previously being typed. Each
dictionary contains details about one of the recipients. The
sending user is guaranteed to appear among the recipients.
-
stream_id: integer
Only present if message_type is "stream".
The unique ID of the channel to which message is being typed.
Changes: New in Zulip 4.0 (feature level 58). Previously,
typing notifications were only for direct messages.
-
topic: string
Only present if message_type is "stream".
Topic within the channel where the message is being typed.
Changes: New in Zulip 4.0 (feature level 58). Previously,
typing notifications were only for direct messages.
Example
{
"id": 0,
"message_type": "direct",
"op": "stop",
"recipients": [
{
"email": "user8@zulip.testserver",
"user_id": 8
},
{
"email": "user10@zulip.testserver",
"user_id": 10
}
],
"sender": {
"email": "user10@zulip.testserver",
"user_id": 10
},
"type": "typing"
}
Event sent when a user starts editing a message.
Event sent when a user starts typing in a textarea to edit the
content of a message. See the edit message typing notifications
endpoint.
Clients requesting typing_edit_message event type that have
receives_typing_notifications enabled will receive this event if
they would have been notified if the message's content edit were to
be saved (E.g., because they were a direct message recipient or
are a subscribe to the channel).
Changes: New in Zulip 10.0 (feature level 351). Previously,
typing notifications were not available when editing messages.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
sender_id: integer
The ID of the user who is typing the edit of the
message.
Clients should be careful to display this user as the person who
is typing, not that of the sender of the message, in case a
collaborative editing feature be might be added in the future.
-
message_id: integer
Indicates the message id of the message that is being edited.
-
recipient: object
Object containing details about recipients of message edit typing notification.
-
type: string
Type of message being composed. Must be "channel" or "direct".
-
channel_id: integer
Only present if type is "channel".
The unique ID of the channel to which message is being edited.
-
topic: string
Only present if type is "channel".
Topic within the channel where the message is being edited.
-
user_ids: (integer)[]
Present only if type is direct.
The user IDs of every recipient of this direct message.
Example
{
"id": 0,
"message_id": 7,
"op": "start",
"recipient": {
"type": "direct",
"user_ids": [
8,
10
]
},
"sender_id": 10,
"type": "typing_edit_message"
}
Event sent when a user stops typing in a textarea to edit the
content of a message. See the edit message typing notifications
endpoint.
Clients requesting typing_edit_message event type that have
receives_typing_notifications enabled will receive this event if
they would have been notified if the message's content edit were to
be saved (E.g., because they were a direct message recipient or
are a subscribe to the channel).
Changes: New in Zulip 10.0 (feature level 351). Previously,
typing notifications were not available when editing messages.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
sender_id: integer
The ID of the user who sent the message.
-
message_id: integer
Indicates the message id of the message that is being edited.
-
recipient: object
Object containing details about recipients of message edit typing notification.
-
type: string
Type of message being composed. Must be "channel" or "direct".
-
channel_id: integer
Only present if type is "channel".
The unique ID of the channel to which message is being edited.
-
topic: string
Only present if type is "channel".
Topic within the channel where the message is being edited.
-
user_ids: (integer)[]
Present only if type is direct.
The user IDs of every recipient of this direct message.
Example
{
"id": 0,
"message_id": 31,
"op": "stop",
"recipient": {
"type": "direct",
"user_ids": [
8,
10
]
},
"sender_id": 10,
"type": "typing_edit_message"
}
Event sent to a user when message flags are added
to messages.
This can reflect a direct user action, or can be the indirect
consequence of another action. Whatever the cause, if there's a change
in the set of message flags that the user has for a message, then an
update_message_flags event will be sent with the change. Note
that this applies when the user already had access to the message, and
continues to have access to it. When a message newly appears or
disappears, a message or
delete_message event is sent instead.
Some examples of actions that trigger an update_message_flags
event:
- The
"starred" flag is added when the user chooses to star a
message.
- The
"read" flag is added when the user marks messages as read by
scrolling through them, or uses Mark all messages as read
on a conversation.
- The
"read" flag is added when the user mutes a
message's sender.
- The
"read" flag is added after the user unsubscribes from a channel,
or messages are moved to a not-subscribed channel, provided the user
can still access the messages at all. Note a
delete_message event is sent in the case where the
user can no longer access the messages.
In some cases, a change in message flags that's caused by another change
may happen a short while after the original change, rather than
simultaneously. For example, when messages that were unread are moved to
a channel where the user is not subscribed, the resulting change in
message flags (and the corresponding update_message_flags event with
flag "read") may happen later than the message move itself. The delay
in that example is typically at most a few hundred milliseconds and can
in rare cases be minutes or longer.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
operation: string
Old name for the op field in this event type.
Deprecated in Zulip 4.0 (feature level 32), and
replaced by the op field.
-
flag: string
The flag that was added.
-
messages: (integer)[]
Array containing the IDs of all messages to which
the flag was added.
-
all: boolean
Whether the specified flag was added to all messages.
This field is only relevant for the "read" flag, and
will be false for all other flags.
When true for the "read" flag, then the messages
array will be empty.
Example
{
"all": false,
"flag": "starred",
"id": 0,
"messages": [
63
],
"op": "add",
"operation": "add",
"type": "update_message_flags"
}
Event sent to a user when message flags are
removed from messages.
See the description for the update_message_flags op:
add event for
more details about these events.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
operation: string
Old name for the op field in this event type.
Deprecated in Zulip 4.0 (feature level 32), and
replaced by the op field.
-
flag: string
The flag to be removed.
-
messages: (integer)[]
Array containing the IDs of the messages from which the flag
was removed.
-
all: boolean
Will be false for all specified flags.
Deprecated and will be removed in a future release.
-
message_details: object
Only present if the specified flag is "read".
A set of data structures describing the messages that
are being marked as unread with additional details to
allow clients to update the unread_msgs data
structure for these messages (which may not be
otherwise known to the client).
Changes: New in Zulip 5.0 (feature level 121). Previously,
marking already read messages as unread was not
supported by the Zulip API.
Example
{
"all": false,
"flag": "starred",
"id": 0,
"message_details": {
"63": {
"stream_id": 22,
"topic": "lunch",
"type": "stream"
}
},
"messages": [
63
],
"op": "remove",
"operation": "remove",
"type": "update_message_flags"
}
Event sent to users in an organization when a user group is created.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
group: object
Object containing the user group's attributes.
-
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:
-
can_remove_members_group: integer | object
A group-setting value defining the set of users who
have permission to remove members from this user group.
Changes: New in Zulip 10.0 (feature level 324). Previously, this
permission was controlled by the can_manage_group setting.
Will be one of the following:
-
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).
Example
{
"group": {
"can_add_members_group": 16,
"can_join_group": 16,
"can_leave_group": 15,
"can_manage_group": 16,
"can_mention_group": 11,
"can_remove_members_group": 16,
"creator_id": 9,
"date_created": 1717484476,
"description": "Backend team",
"id": 2,
"is_system_group": false,
"members": [
12
],
"name": "backend"
},
"id": 0,
"op": "add",
"type": "user_group"
}
Event sent to all users in a Zulip organization
when a property of a user group is changed.
For group deactivation, this event is only sent
if include_deactivated_groups client capability
is set to true.
This event is also sent when deactivating or reactivating
a user for settings set to anonymous user groups which the
user is direct member of. When deactivating the user, event
is only sent to users who cannot access the deactivated user.
Changes: Starting with Zulip 10.0 (feature level 303), this
event can also be sent when deactivating or reactivating a user.
Prior to Zulip 10.0 (feature level 294), this event was sent to
all clients when a user group was deactivated.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
group_id: integer
The ID of the user group whose details have changed.
-
data: object
Dictionary containing the changed details of the user group.
-
name: string
The new name of the user group. Only present if the group's name changed.
-
description: string
The new description of the group. Only present if the description
changed.
-
can_add_members_group: integer | object
A group-setting value defining the set of users who
have permission to add members to this group. Only present if this user
group permission setting changed.
Changes: New in Zulip 10.0 (feature level 305). Previously, this
permission was controlled by the can_manage_group setting.
Will be one of the following:
-
can_join_group: integer | object
A group-setting value defining the set of users who
have permission to join this group. Only present if this user group
permission setting changed.
Changes: New in Zulip 10.0 (feature level 301).
Will be one of the following:
-
can_leave_group: integer | object
A group-setting value defining the set of users who
have permission to leave this group. Only present if this user group
permission setting changed.
Changes: New in Zulip 10.0 (feature level 308).
Will be one of the following:
-
can_manage_group: integer | object
A group-setting value defining the set of users who
have permission to manage this group. Only present
if this user group permission setting changed.
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. Only present
if this user group permission setting changed.
Changes: Before Zulip 9.0 (feature level 258), this setting was
always the integer form of a group-setting value.
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:
-
can_remove_members_group: integer | object
A group-setting value defining the set of users who
have permission to remove members from this group. Only present if this
user group permission setting changed.
Changes: New in Zulip 10.0 (feature level 324). Previously, this
permission was controlled by the can_manage_group setting.
Will be one of the following:
-
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).
Example
{
"data": {
"description": "Mention this group to get the security team's attention."
},
"group_id": 2,
"id": 0,
"op": "update",
"type": "user_group"
}
Event sent to all users when users have been added to a user group.
This event is also sent when reactivating a user for all the user
groups the reactivated user was a member of before being deactivated.
Changes: Starting with Zulip 10.0 (feature level 303), this
event can also be sent when reactivating a user.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
group_id: integer
The ID of the user group with new members.
-
user_ids: (integer)[]
Array containing the IDs of the users who have been added
to the user group.
Example
{
"group_id": 2,
"id": 0,
"op": "add_members",
"type": "user_group",
"user_ids": [
10
]
}
Event sent to all users when users have been removed from
a user group.
This event is also sent when deactivating a user, for all
the user groups the deactivated user is a member of, but only
to the users who cannot access the deactivated user.
Changes: Starting with Zulip 10.0 (feature level 303),
this event can also be sent when deactivating a user.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
group_id: integer
The ID of the user group whose details have changed.
-
user_ids: (integer)[]
Array containing the IDs of the users who have been removed
from the user group.
Example
{
"group_id": 2,
"id": 0,
"op": "remove_members",
"type": "user_group",
"user_ids": [
10
]
}
Event sent to all users when subgroups have been added to
a user group.
Changes: New in Zulip 6.0 (feature level 127).
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
group_id: integer
The ID of the user group whose details have changed.
-
direct_subgroup_ids: (integer)[]
Array containing the IDs of the subgroups that have been added
to the user group.
Changes: New in Zulip 6.0 (feature level 131).
Previously, this was called subgroup_ids, but
clients can ignore older events as this feature level
predates subgroups being fully implemented.
Example
{
"direct_subgroup_ids": [
10
],
"group_id": 2,
"id": 0,
"op": "add_subgroups",
"type": "user_group"
}
Event sent to all users when subgroups have been removed from
a user group.
Changes: New in Zulip 6.0 (feature level 127).
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
group_id: integer
The ID of the user group whose details have changed.
-
direct_subgroup_ids: (integer)[]
Array containing the IDs of the subgroups that have been
removed from the user group.
Changes: New in Zulip 6.0 (feature level 131).
Previously, this was called subgroup_ids, but
clients can ignore older events as this feature level
predates subgroups being fully implemented.
Example
{
"direct_subgroup_ids": [
10
],
"group_id": 2,
"id": 0,
"op": "remove_subgroups",
"type": "user_group"
}
Event sent when a user group is deactivated but only to clients
with include_deactivated_groups client capability set to false.
Changes: Prior to Zulip 10.0 (feature level 294), this
event was sent when a user group was deleted.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
group_id: integer
The ID of the group which has been deleted.
Example
{
"group_id": 2,
"id": 0,
"op": "remove",
"type": "user_group"
}
Event sent to all users in a Zulip organization when the
set of configured linkifiers
for the organization has changed.
Processing this event is important for doing Markdown local echo
correctly.
Clients will not receive this event unless the event queue is
registered with the client capability
{"linkifier_url_template": true}.
See POST /register
for how client capabilities can be specified.
Changes: Before Zulip 7.0 (feature level 176), the
linkifier_url_template client capability was not required. The
requirement was added because linkifiers were updated to contain
a URL template instead of a URL format string, which was not a
backwards-compatible change.
New in Zulip 4.0 (feature level 54), replacing the deprecated
realm_filters event type.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
realm_linkifiers: (object)[]
An ordered array of dictionaries where each dictionary contains
details about a single linkifier.
Clients should always process linkifiers in the order given;
this is important if the realm has linkifiers with overlapping
patterns. The order can be modified using PATCH
/realm/linkifiers.
-
pattern: string
The Python regular expression
that represents the pattern that should be linkified by this linkifier.
-
url_template: string
The RFC 6570 compliant
URL template to be used for linkifying matches.
Changes: New in Zulip 7.0 (feature level 176). This replaced url_format,
which contained a URL format string.
-
id: integer
The ID of the linkifier.
Example
{
"id": 0,
"realm_linkifiers": [
{
"id": 1,
"pattern": "#(?P<id>[123])",
"url_template": "https://realm.com/my_realm_filter/{id}"
}
],
"type": "realm_linkifiers"
}
Legacy event type that is no longer sent to clients. Previously, sent
to all users in a Zulip organization when the set of configured
linkifiers for the organization was
changed.
Changes: Prior to Zulip 7.0 (feature level 176), this event type
was sent to clients.
Deprecated in Zulip 4.0 (feature level 54), and replaced by the
realm_linkifiers event type, which has a clearer name and format.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
realm_filters: ((integer | string)[])[]
An array of tuples, where each tuple described a linkifier. The first
element of the tuple was a string regex pattern which represented the
pattern to be linkified on matching, for example "#(?P<id>[123])".
The second element was the URL format string that the pattern should be
linkified with. A URL format string for the above example would be
"https://realm.com/my_realm_filter/%(id)s". And the third element
was the ID of the realm filter.
Example
{
"id": 0,
"realm_filters": [],
"type": "realm_filters"
}
Event sent to all users in a Zulip organization when the
set of configured code playgrounds
for the organization has changed.
Changes: New in Zulip 4.0 (feature level 49).
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
realm_playgrounds: (object)[]
An array of dictionaries where each dictionary contains
data about a single playground entry.
-
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.
Example
{
"id": 0,
"realm_playgrounds": [
{
"id": 1,
"name": "Python playground",
"pygments_language": "Python",
"url_template": "https://python.example.com"
}
],
"type": "realm_playgrounds"
}
Event sent to all users in a Zulip organization when
a custom emoji has been updated,
typically when a new emoji has been added or an old one
has been deactivated. The event contains all custom emoji
configured for the organization, not just the updated
custom emoji.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
realm_emoji: object
An object in which each key describes a realm emoji.
Example
{
"id": 0,
"op": "update",
"realm_emoji": {
"1": {
"author_id": 11,
"deactivated": false,
"id": "1",
"name": "green_tick",
"source_url": "/user_avatars/2/emoji/images/1.png"
},
"2": {
"author_id": 11,
"deactivated": true,
"id": "2",
"name": "my_emoji",
"source_url": "/user_avatars/2/emoji/images/2.png"
}
},
"type": "realm_emoji"
}
Event sent to all users in a Zulip organization when the set of
allowed domains for new users
has changed.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
realm_domain: object
Object containing details of the newly added domain.
Example
{
"id": 0,
"op": "add",
"realm_domain": {
"allow_subdomains": false,
"domain": "zulip.org"
},
"type": "realm_domains"
}
Event sent to all users in a Zulip organization when the set of
allowed domains for new users
has changed.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
realm_domain: object
Object containing details of the edited domain.
-
domain: string
The domain whose settings have changed.
-
allow_subdomains: boolean
Whether subdomains are allowed for this domain.
Example
{
"id": 0,
"op": "change",
"realm_domain": {
"allow_subdomains": true,
"domain": "zulip.org"
},
"type": "realm_domains"
}
Event sent to all users in a Zulip organization when the set of
allowed domains for new users
has changed.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
domain: string
The domain to be removed.
Example
{
"domain": "zulip.org",
"id": 0,
"op": "remove",
"type": "realm_domains"
}
Event sent to the user who requested a
data export
when the status of the data export changes.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
exports: (object)[]
An array of dictionaries where each dictionary contains
details about a data export of the organization.
Changes: Prior to Zulip 10.0 (feature level 304), export_type
parameter was not present as only public data export was supported via API.
-
id: integer
The ID of the data export.
-
acting_user_id: integer
The ID of the user who created the data export.
-
export_time: number
The UNIX timestamp of when the data export was started.
-
deleted_timestamp: number | null
The UNIX timestamp of when the data export was deleted.
Will be null if the data export has not been deleted.
-
failed_timestamp: number | null
The UNIX timestamp of when the data export failed.
Will be null if the data export succeeded, or if it's
still being generated.
-
export_url: string | null
The URL to download the generated data export.
Will be null if the data export failed, or if it's
still being generated.
-
pending: boolean
Whether the data export is pending, which indicates it
is still being generated, or if it succeeded, failed or
was deleted before being generated.
Depending on the size of the organization, it can take
anywhere from seconds to an hour to generate the data
export.
-
export_type: integer
Whether the data export is a public or a standard data export.
- 1 = Public data export.
- 2 = Standard data export.
Changes: New in Zulip 10.0 (feature level 304). Previously,
the export type was not included in these objects because only
public data exports could be created or listed via the API or UI.
Example
{
"exports": [
{
"acting_user_id": 10,
"deleted_timestamp": null,
"export_time": 1594825443.656797,
"export_type": 1,
"export_url": null,
"failed_timestamp": 1594825444.436336,
"id": 107,
"pending": false
}
],
"id": 1,
"type": "realm_export"
}
Event sent to administrators when the data export
consent status for a user changes, whether due
to a user changing their consent preferences or a user being created
or reactivated (since user creation/activation events do not contain
these data).
Changes: New in Zulip 10.0 (feature level 312). Previously,
there was not event available to administrators with these data.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
user_id: integer
The ID of the user whose setting was changed.
-
consented: boolean
Whether the user has consented for their private data export.
Example
{
"consented": true,
"type": "realm_export_consent",
"user_id": 1
}
Event sent to users who can administer a newly created bot
user. Clients will also receive a realm_user event that
contains basic details (but not the API key).
The realm_user events are sufficient for clients that
only need to interact with the bot; this realm_bot event
type is relevant only for administering bots.
Only organization administrators and the user who owns the bot will
receive this event.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
bot: object
Object containing details of a bot.
-
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.
Example
{
"bot": {
"api_key": "6hc6MC9mpNFvoo0gSOWnZEq4aJEn8UNK",
"avatar_url": "https://secure.gravatar.com/avatar/af8abc2537d283b212a6bd4d1289956d?d=identicon&version=1",
"bot_type": 1,
"default_all_public_streams": false,
"default_events_register_stream": null,
"default_sending_stream": null,
"email": "test-bot@zulip.testserver",
"full_name": "Foo Bot",
"is_active": true,
"owner_id": 10,
"services": [],
"user_id": 36
},
"id": 1,
"op": "add",
"type": "realm_bot"
}
Event sent to users who can administer a bot user when the bot is
configured. Clients may also receive a realm_user event that
for changes in public data about the bot (name, etc.).
The realm_user events are sufficient for clients that
only need to interact with the bot; this realm_bot event
type is relevant only for administering bots.
Only organization administrators and the user who owns the bot will
receive this event.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
bot: object
Object containing details about the changed bot.
It contains two properties: the user ID of the bot and
the property to be changed. The changed property is one
of the remaining properties listed below.
-
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.
-
is_active: boolean
A boolean describing whether the user account has been deactivated.
Changes: New in Zulip 8.0 (feature level 222). Previously
we sent realm_user event with op field set to remove
when deactivating a bot and realm_user event with op
field set to add when reactivating a bot.
Example
{
"bot": {
"services": [
{
"base_url": "http://hostname.domain2.com",
"interface": 2,
"token": "grr8I2APXRmVL0FRTMRYAE4DRPQ5Wlaw"
}
],
"user_id": 37
},
"id": 0,
"op": "update",
"type": "realm_bot"
}
Event sent to all users when a bot has been deactivated.
Changes: Deprecated and no longer sent since Zulip 8.0 (feature level 222).
Previously, this event was sent to all users in a Zulip organization when a
bot was deactivated.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
bot: object
Object containing details about the deactivated bot.
Example
{
"bot": {
"full_name": "Foo Bot",
"user_id": 35
},
"id": 1,
"op": "remove",
"type": "realm_bot"
}
Event sent to all users when a bot has been deactivated.
Note that this is very similar to the bot_remove event
and one of them will be removed soon.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
bot: object
Object containing details about the deactivated bot.
Example
{
"bot": {
"user_id": 35
},
"id": 1,
"op": "delete",
"type": "realm_bot"
}
The simpler of two possible event types sent to all users
in a Zulip organization when the configuration of the
organization (realm) has changed.
Often individual settings are migrated from this format to
the realm/update_dict event format when additional realm
settings are added whose values are coupled to each other
in some way. The specific values supported by this event
type are documented in the realm/update_dict
documentation.
A correct client implementation should convert these
events into the corresponding realm/update_dict
event and then process that.
Changes: Removed extra_data optional property in Zulip 10.0
(feature level 306). The extra_data used to include an
upload_quota field when changed property was plan_type. The
server now sends a standard realm/update_dict event for plan
changes.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
property: string
The name of the property that was changed.
-
value: string | boolean | integer | null
The new value of the property.
Example
{
"id": 0,
"op": "update",
"property": "disallow_disposable_email_addresses",
"type": "realm",
"value": false
}
Event sent to all users in a Zulip organization when the
organization (realm) is deactivated. Its main purpose is to
flush active longpolling connections so clients can immediately
show the organization as deactivated.
Clients cannot rely on receiving this event, because they will
no longer be able to authenticate to the Zulip API due to the
deactivation, and thus can miss it if they did not have an active
longpolling connection at the moment of deactivation.
Correct handling of realm deactivations requires that clients
parse authentication errors from GET /events; if that is done
correctly, the client can ignore this event type and rely on its
handling of the GET /events request it will do immediately
after processing this batch of events.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
realm_id: integer
The ID of the deactivated realm.
Example
{
"id": 0,
"op": "deactivated",
"realm_id": 2,
"type": "realm"
}
Event sent to all the users whenever the Zulip server restarts.
Specifically, this event is sent whenever the Tornado process
for the user is restarted; in particular, this will always happen
when the Zulip server is upgraded.
Clients should use this event to update their tracking of the
server's capabilities, and to decide if they wish to get a new
event queue after a server upgrade. Clients doing so must
implement a random delay strategy to spread such restarts over 5
minutes or more to avoid creating a synchronized thundering herd
effect.
Changes: Removed the immediate flag, which was only used by
web clients in development, in Zulip 9.0 (feature level 240).
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
zulip_version: string
The Zulip version number, in the format where this appears
in the server_settings and
register responses.
Changes: New in Zulip 4.0 (feature level 59).
-
zulip_merge_base: string
The Zulip merge base number, in the format where this appears
in the server_settings and
register responses.
Changes: New in Zulip 5.0 (feature level 88).
-
zulip_feature_level: integer
The Zulip feature level of the server
after the restart.
Clients should use this to update their tracking of the
server's capabilities, and may choose to refetch their state
and create a new event queue when the API feature level has
changed in a way that the client finds significant. Clients
choosing to do so must implement a random delay strategy to
spread such restarts over 5 or more minutes to avoid creating
a synchronized thundering herd effect.
Changes: New in Zulip 4.0 (feature level 59).
-
server_generation: integer
The timestamp at which the server started.
Example
{
"id": 0,
"server_generation": 1619334181,
"type": "restart",
"zulip_feature_level": 57,
"zulip_merge_base": "5.0-dev-1646-gea6b21cd8c",
"zulip_version": "5.0-dev-1650-gc3fd37755f"
}
An event which signals the official Zulip web/desktop app to update,
by reloading the page and fetching a new queue; this will generally
follow a restart event. Clients which do not obtain their code
from the server (e.g. mobile and terminal clients, which store their
code locally) should ignore this event.
Clients choosing to reload the application must implement a random
delay strategy to spread such restarts over 5 or more minutes to
avoid creating a synchronized thundering herd effect.
Changes: New in Zulip 9.0 (feature level 240).
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
immediate: boolean
Whether the client should fetch a new event queue immediately,
rather than using a backoff strategy to avoid thundering herds.
A Zulip development server uses this parameter to reload
clients immediately.
Example
{
"id": 0,
"immediate": true,
"type": "web_reload_client"
}
The more general of two event types that may be used when
sending an event to all users in a Zulip organization when
the configuration of the organization (realm) has changed.
Unlike the simpler realm/update event format, this
event type supports multiple properties being changed in a
single event.
This event is also sent when deactivating or reactivating a user
for settings set to anonymous user groups which the user is direct
member of. When deactivating the user, event is only sent to users
who cannot access the deactivated user.
Changes: Starting with Zulip 10.0 (feature level 303), this
event can also be sent when deactivating or reactivating a user.
In Zulip 7.0 (feature level 163), the realm setting
email_address_visibility was removed. It was replaced by a user
setting with
a realm user default, with the encoding of different
values preserved. Clients can support all versions by supporting the
current API and treating every user as having the realm's
email_address_visibility value.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
property: string
Always "default". Present for backwards-compatibility with older
clients that predate the update_dict event style.
Deprecated and will be removed in a future release.
-
data: object
An object containing the properties that have changed.
Changes: In Zulip 10.0 (feature level 316), edit_topic_policy
property was removed and replaced by can_move_messages_between_topics_group
realm setting.
In Zulip 7.0 (feature level 183), the
community_topic_editing_limit_seconds property was removed.
It was documented as potentially returned as a changed property
in this event, but in fact it was only ever returned in the
POST /register response.
Before Zulip 6.0 (feature level 150), on changing any of
allow_message_editing, message_content_edit_limit_seconds, or
edit_topic_policy settings, this object included all the three settings
irrespective of which of these settings were changed. Now, a separate event
is sent for each changed setting.
-
allow_message_editing: boolean
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.
-
authentication_methods: object
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 243), the values in this
dictionary were changed. Previously, the values were a simple boolean
indicating whether the backend is enabled or not.
-
can_access_all_users_group: integer | object
A group-setting value defining the
set of users who are allowed to access all users in the
organization.
Changes: Prior to Zulip 10.0 (feature level 314), this value used
to be of type integer and did not accept anonymous user groups.
New in Zulip 8.0 (feature level 225).
-
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
user_group_edit_policy field used to control the permission
to create user groups.
-
can_create_bots_group: integer | object
A group-setting value defining
the set of users who have permission to create all types of bot users
in the organization. See also can_create_write_only_bots_group.
Changes: New in Zulip 10.0 (feature level 344). Previously, this
permission was controlled by the enum bot_creation_policy. Values
were 1=Members, 2=Generic bots limited to administrators, 3=Administrators.
-
can_create_write_only_bots_group: integer | object
A group-setting value defining
the set of users who have permission to create bot users that
can only send messages in the organization, i.e. incoming webhooks,
in addition to the users who are present in can_create_bots_group.
Changes: New in Zulip 10.0 (feature level 344). Previously, this
permission was controlled by the enum bot_creation_policy. Values
were 1=Members, 2=Generic bots limited to administrators, 3=Administrators.
-
can_create_public_channel_group: 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.
-
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.
-
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.
Changes: New in Zulip 10.0 (feature level 280). Previously
realm_create_web_public_stream_policy field used to control
the permission to create web-public channels.
-
can_add_custom_emoji_group: integer | object
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.
-
can_add_subscribers_group: integer | object
A group-setting value defining the set of
users who have permission to add subscribers to channels in the organization.
Changes: New in Zulip 10.0 (feature level 341). Previously, this
permission was controlled by the enum invite_to_stream_policy. Values
were 1=Members, 2=Admins, 3=Full members, 4=Moderators.
-
can_delete_any_message_group: integer | object
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.
-
can_delete_own_message_group: integer | object
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.
-
can_set_topics_policy_group: integer | object
A group-setting value defining the set of
users who have permission to change per-channel topics_policy setting. Note that
the user must be a member of both this group and the can_administer_channel_group
of the channel whose topics_policy they want to change.
Organization administrators can always change the topics_policy setting of
every channel.
Changes: New in Zulip 11.0 (feature level 392).
-
can_invite_users_group: integer | object
A group-setting value defining the set of
users who have permission to send email invitations for inviting other users
to the organization.
Changes: New in Zulip 10.0 (feature level 321). Previously, this
permission was controlled by the enum invite_to_realm_policy. Values
were 1=Members, 2=Admins, 3=Full members, 4=Moderators, 6=Nobody.
Before Zulip 4.0 (feature level 50), the invite_by_admins_only boolean
setting controlled this permission; true corresponded to Admins, and
false to Members.
-
can_mention_many_users_group: integer | object
A group-setting value defining the set of
users who have permission to use wildcard mentions in large channels.
All users will receive a warning/reminder when using mentions in large
channels, even when permitted to do so.
Changes: New in Zulip 10.0 (feature level 352). Previously, this
permission was controlled by the enum wildcard_mention_policy.
-
can_move_messages_between_channels_group: integer | object
A group-setting value defining the set of
users who have permission to move messages from one channel to another
in the organization.
Changes: New in Zulip 10.0 (feature level 310). Previously, this
permission was controlled by the enum move_messages_between_streams_policy.
Values were 1=Members, 2=Admins, 3=Full members, 4=Moderators, 6=Nobody.
In Zulip 7.0 (feature level 159), Nobody was added as an option to
move_messages_between_streams_policy enum.
-
can_move_messages_between_topics_group: integer | object
A group-setting value defining the set of
users who have permission to move messages from one topic to another
within a channel in the organization.
Changes: New in Zulip 10.0 (feature level 316). Previously, this
permission was controlled by the enum edit_topic_policy. Values were
1=Members, 2=Admins, 3=Full members, 4=Moderators, 5=Everyone, 6=Nobody.
In Zulip 7.0 (feature level 159), Nobody was added as an option to
edit_topic_policy enum.
-
can_resolve_topics_group: integer | object
A group-setting value defining
the set of users who have permission to resolve topics
in the organization.
Changes: New in Zulip 10.0 (feature level 367). Previously, permission to
resolve topics was controlled by the more general
can_move_messages_between_topics_group permission for moving messages.
-
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.
-
can_manage_billing_group: integer | object
A group-setting value defining the set of
users who have permission to manage plans and billing in the organization.
Changes: New in Zulip 10.0 (feature level 363). Previously, only owners
and users with is_billing_admin property set to true were allowed to
manage plans and billing.
-
can_summarize_topics_group: integer | object
A group-setting value defining the
set of users who are allowed to use AI summarization.
Changes: New in Zulip 10.0 (feature level 350).
-
create_multiuse_invite_group: integer | object
A group-setting value defining the
set of users who are allowed to create reusable invitation
links
to the organization.
Changes: Prior to Zulip 10.0 (feature level 314), this value used
to be of type integer and did not accept anonymous user groups.
New in Zulip 8.0 (feature level 209).
-
default_code_block_language: string
The default pygments language code to be used for code blocks in this
organization. If an empty string, no default has been set.
Changes: Prior to Zulip 8.0 (feature level 195), a server bug meant
that both null and an empty string could represent that no default was
set for this realm setting in the POST /register
response. The documentation for both that endpoint and this event
incorrectly stated that the only representation for no default language
was null. This event in fact uses the empty string to indicate that no
default has been set in all server versions.
-
default_language: string
The default language for the organization.
-
description: string
The description of the organization, used on login and registration pages.
-
digest_emails_enabled: boolean
Whether the organization has enabled weekly digest emails.
-
digest_weekday: integer
The day of the week when the organization will send
its weekly digest email to inactive users.
-
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).
-
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).
-
disallow_disposable_email_addresses: boolean
Whether the organization disallows disposable email
addresses.
-
email_changes_disabled: boolean
Whether users are allowed to change their own email address in this
organization. This is typically disabled for organizations that
synchronize accounts from LDAP or a similar corporate database.
-
enable_read_receipts: boolean
Whether read receipts is enabled in the organization or not.
If disabled, read receipt data will be unavailable to clients, regardless
of individual users' personal read receipt settings. See also the
send_read_receipts setting within realm_user_settings_defaults.
Changes: New in Zulip 6.0 (feature level 137).
-
emails_restricted_to_domains: boolean
Whether new users joining
this organization are required to have an email
address in one of the realm_domains configured for the organization.
-
enable_guest_user_dm_warning: boolean
Whether clients should show a warning when a user is composing
a DM to a guest user in this organization.
Changes: New in Zulip 10.0 (feature level 348).
-
enable_guest_user_indicator: boolean
Whether clients should display "(guest)" after the names of
guest users to prominently highlight their status.
Changes: New in Zulip 8.0 (feature level 216).
-
enable_spectator_access: boolean
Whether web-public channels 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).
-
giphy_rating: integer
Maximum rating of the GIFs that will be retrieved from GIPHY.
Changes: New in Zulip 4.0 (feature level 55).
-
icon_source: string
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.
-
icon_url: string
The URL of the organization's profile icon.
-
inline_image_preview: boolean
Whether this organization has been configured to enable
previews of linked images.
-
inline_url_embed_preview: boolean
Whether this organization has been configured to enable
previews of linked websites.
-
invite_required: boolean
Whether an invitation is required to join this organization.
-
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.
Changes: New in Zulip 8.0 (feature level 212). Previously, this was only
available as a server-level configuration, and required a server restart to
change.
-
logo_source: string
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.
-
logo_url: string
The URL of the organization's wide logo configured in the
organization profile.
-
mandatory_topics: boolean
Whether topics are required for messages in this organization.
Changes: Deprecated in Zulip 11.0 (feature level 392). This configuration is
now controlled by topics_policy realm setting.
-
topics_policy: string
Configuration defining the default policy for sending messages in empty topics.
- allow_empty_topic - Topics are not required to send messages in the channels.
- disable_empty_topic - Topics are required to send messages in the channels.
Changes: New in Zulip 11.0 (feature level 392). Previously, this configuration was
controlled by a boolean realm setting, mandatory_topics.
-
max_file_upload_size_mib: integer
The new maximum file size that can be uploaded to this Zulip organization.
Changes: New in Zulip 10.0 (feature level 306). Previously, this field of
the core state did not support being updated via the events system, as it was
typically hardcoded for a given Zulip installation.
-
message_content_allowed_in_email_notifications: boolean
Whether notification emails in this organization are allowed to
contain Zulip the message content, or simply indicate that a new
message was sent.
-
message_content_delete_limit_seconds: integer | null
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).
-
message_content_edit_limit_seconds: integer | null
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.
-
message_edit_history_visibility_policy: string
Which type of message edit history is configured to allow users to
access message edit history.
- "all" = All edit history is visible.
- "moves" = Only moves are visible.
- "none" = No edit history is visible.
Changes: New in Zulip 10.0 (feature level 358), replacing the previous
allow_edit_history boolean setting; true corresponds to all,
and false to none.
-
moderation_request_channel_id: integer
The ID of the private channel to which messages flagged by users for
moderation are sent. Moderators can use this channel to review and
act on reported content.
Will be -1 if moderation requests are disabled.
Clients should check whether moderation requests are disabled to
determine whether to present a "report message" feature in their UI
within a given organization.
Changes: New in Zulip 10.0 (feature level 331). Previously,
no "report message" features existed in Zulip.
-
move_messages_within_stream_limit_seconds: integer | null
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.
-
move_messages_between_streams_limit_seconds: integer | null
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.
-
name: string
The name of the organization, used in login pages etc.
-
name_changes_disabled: boolean
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.
-
night_logo_source: string
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.
-
night_logo_url: string
The URL of the organization's dark theme wide-format logo configured in the
organization profile.
-
new_stream_announcements_stream_id: integer
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 notifications_stream_id
to new_stream_announcements_stream_id.
-
org_type: integer
The organization type
for the realm.
- 0 = Unspecified
- 10 = Business
- 20 = Open-source project
- 30 = Education (non-profit)
- 35 = Education (for-profit)
- 40 = Research
- 50 = Event or conference
- 60 = Non-profit (registered)
- 70 = Government
- 80 = Political group
- 90 = Community
- 100 = Personal
- 1000 = Other
Changes: New in Zulip 6.0 (feature level 128).
-
plan_type: integer
The plan type of the organization.
- 1 = Self-hosted organization (SELF_HOSTED)
- 2 = Zulip Cloud free plan (LIMITED)
- 3 = Zulip Cloud Standard plan (STANDARD)
- 4 = Zulip Cloud Standard plan, sponsored for free (STANDARD_FREE)
-
presence_disabled: boolean
Whether online presence of other users is shown in this
organization.
-
push_notifications_enabled: boolean
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: New in Zulip 8.0 (feature level 231).
Previously, this value was never updated via events.
-
push_notifications_enabled_end_timestamp: integer | null
If the server expects the realm's push notifications access to end at a
definite time in the future, the time at which this is expected to happen.
Mobile clients should use this field to display warnings to users when the
indicated timestamp is near.
Changes: New in Zulip 8.0 (feature level 231).
-
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.
-
send_welcome_emails: boolean
Whether or not this organization is configured to send the standard Zulip
welcome emails to new users joining the organization.
-
signup_announcements_stream_id: integer
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
signup_notifications_stream_id to signup_announcements_stream_id.
-
upload_quota_mib: integer | null
The new upload quota for the Zulip organization.
If null, there is no limit.
Changes: New in Zulip 10.0 (feature level 306). Previously,
this was present changed via an upload_quota field in extra_data property
of realm/update event format for plan_type events.
-
video_chat_provider: integer
The configured video call provider for the
organization.
- 0 = None
- 1 = Jitsi Meet
- 3 = Zoom (User OAuth integration)
- 4 = BigBlueButton
- 5 = Zoom (Server to Server OAuth integration)
Note that only one of the Zoom integrations can
be configured on a Zulip server.
Changes: In Zulip 10.0 (feature level 353), added the Zoom Server
to Server OAuth option.
In Zulip 3.0 (feature level 1), added the None option
to disable video call UI.
-
waiting_period_threshold: integer
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.
-
want_advertise_in_communities_directory: boolean
Whether the organization has given permission to be advertised in the
Zulip communities directory.
Changes: New in Zulip 6.0 (feature level 129).
-
zulip_update_announcements_stream_id: integer
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).
Example
{
"data": {
"message_content_edit_limit_seconds": 600
},
"id": 0,
"op": "update_dict",
"property": "default",
"type": "realm"
}
Event sent to all users in a Zulip organization when the
default settings for new users
of the organization (realm) have changed.
See PATCH /realm/user_settings_defaults
for details on possible properties.
Changes: New in Zulip 5.0 (feature level 95).
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
property: string
The name of the property that was changed.
-
value: boolean | integer | string
The new value of the property.
Example
{
"id": 0,
"op": "update",
"property": "left_side_userlist",
"type": "realm_user_settings_defaults",
"value": false
}
Event containing details of newly created drafts.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
drafts: (object)[]
An array containing objects for the newly created drafts.
-
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.
Example
{
"drafts": [
{
"content": "Hello there!",
"id": 17,
"timestamp": 15954790200,
"to": [
6
],
"topic": "",
"type": "private"
}
],
"op": "add",
"type": "drafts"
}
Event containing details for an edited draft.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
draft: object
A dictionary for representing a message draft.
-
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.
Example
{
"draft": {
"content": "Hello everyone!",
"id": 17,
"timestamp": 15954790200,
"to": [
6,
7,
8,
9,
10
],
"topic": "",
"type": "private"
},
"op": "update",
"type": "drafts"
}
Event containing the ID of a deleted draft.
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
draft_id: integer
The ID of the draft that was just deleted.
Example
{
"draft_id": 17,
"op": "remove",
"type": "drafts"
}
Event containing details of a newly configured navigation view.
Changes: New in Zulip 11.0 (feature level 390).
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
navigation_view: object
Represents a user's personal configuration for a specific
navigation view (displayed most visibly at the top of the web
application's left sidebar).
Navigation views can be either an override to the default
behavior of a built-in view, or a custom view.
Changes: New in Zulip 11.0 (feature level 390).
-
fragment: string
A unique identifier for the view, used to determine navigation
behavior when clicked.
Clients should use this value to navigate to the corresponding URL hash.
-
is_pinned: boolean
Determines whether the view appears directly in the sidebar or
is hidden in the "More Views" menu.
true - Pinned and visible in the sidebar.false - Hidden and accessible via the "More Views" menu.
-
name: string | null
The user-facing name for custom navigation views. Omit this
field for built-in views.
Example
{
"navigation_view": {
"fragment": "narrow/is/alerted",
"is_pinned": true,
"name": "Alert Words"
},
"op": "add",
"type": "navigation_view"
}
Event containing details of an update to an existing navigation view.
Changes: New in Zulip 11.0 (feature level 390).
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
fragment: string
The unique URL hash of the navigation view being updated.
-
data: object
A dictionary containing the updated properties of the navigation view.
-
name: string | null
The user-facing name for custom navigation views. Omit this field for built-in views.
-
is_pinned: boolean | null
Determines whether the view is pinned (true) or hidden in the menu (false).
Example
{
"data": {
"is_pinned": false
},
"fragment": "narrow/is/alerted",
"op": "update",
"type": "navigation_view"
}
Event containing the fragment of a deleted navigation view.
Changes: New in Zulip 11.0 (feature level 390).
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
fragment: string
The unique URL hash of the navigation view that was just deleted.
Example
{
"fragment": "narrow/is/mentioned",
"op": "remove",
"type": "navigation_view"
}
Event containing details of a newly created saved snippet.
Changes: New in Zulip 10.0 (feature level 297).
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
saved_snippet: object
Object containing the details of the saved snippet.
-
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.
Example
{
"op": "add",
"saved_snippet": {
"content": "Welcome to the organization.",
"date_created": 1681662420,
"id": 1,
"title": "Example"
},
"type": "saved_snippets"
}
Event containing details of the edited saved snippet.
Clients should update the existing saved snippet with the
ID provided in the saved_snippet object.
Changes: New in Zulip 10.0 (feature level 368).
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
saved_snippet: object
Object containing the details of the saved snippet.
-
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.
Example
{
"op": "update",
"saved_snippet": {
"content": "Welcome to the organization.",
"date_created": 1681662420,
"id": 1,
"title": "Example"
},
"type": "saved_snippets"
}
Event containing the ID of a deleted saved snippet.
Changes: New in Zulip 10.0 (feature level 297).
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
saved_snippet_id: integer
The ID of the saved snippet that was just deleted.
Changes: New in Zulip 10.0 (feature level 297).
Example
{
"op": "remove",
"saved_snippet_id": 17,
"type": "saved_snippets"
}
Event sent to a user's clients when a reminder is scheduled.
Changes: New in Zulip 11.0 (feature level 399).
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
reminders: (object)[]
An array of objects containing details of the newly created
reminders.
-
reminder_id: integer
The unique ID of the reminder, which can be used to
delete the reminder.
This is different from the unique ID that the message would have
after being sent.
-
type: string
The type of the reminder. Always set to "private".
-
to: (integer)[]
Contains the ID of the user who scheduled the reminder,
and to which the reminder will be sent.
-
content: string
The content/body of the reminder, in text/markdown format.
-
rendered_content: string
The content/body of the reminder 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 reminder
and it failed to successfully send.
Clients that support unscheduling reminders
should display scheduled messages with "failed": true with an
indicator that the server failed to send the message at the
scheduled time, so that the user is aware of the failure and can
get the content of the scheduled message.
-
reminder_target_message_id: integer
The ID of the message that the reminder is created for.
Example
{
"op": "add",
"reminders": [
{
"content": "Hello there!",
"failed": false,
"reminder_id": 17,
"reminder_target_message_id": 42,
"rendered_content": "<p>Hello there!</p>",
"scheduled_delivery_timestamp": 1681662420,
"to": [
6
],
"type": "private"
}
],
"type": "reminders"
}
Event sent to a user's clients when a reminder
is deleted.
Changes: New in Zulip 11.0 (feature level 399).
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
reminder_id: integer
The ID of the reminder that was deleted.
Example
{
"op": "remove",
"reminder_id": 17,
"type": "reminders"
}
Event sent to a user's clients when scheduled messages
are created.
Changes: New in Zulip 7.0 (feature level 179).
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
scheduled_messages: (object)[]
An array of objects containing details of the newly created
scheduled messages.
-
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).
Example
{
"op": "add",
"scheduled_messages": [
{
"content": "Hello there!",
"failed": false,
"rendered_content": "<p>Hello there!</p>",
"scheduled_delivery_timestamp": 1681662420,
"scheduled_message_id": 17,
"to": [
6
],
"type": "private"
}
],
"type": "scheduled_messages"
}
Event sent to a user's clients when a scheduled message
is edited.
Changes: New in Zulip 7.0 (feature level 179).
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
scheduled_message: object
Object containing details of the scheduled message.
-
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).
Example
{
"op": "update",
"scheduled_message": {
"content": "Hello there!",
"failed": false,
"rendered_content": "<p>Hello there!</p>",
"scheduled_delivery_timestamp": 1681662420,
"scheduled_message_id": 17,
"to": [
6
],
"type": "private"
},
"type": "scheduled_messages"
}
Event sent to a user's clients when a scheduled message
is deleted.
Changes: New in Zulip 7.0 (feature level 179).
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
scheduled_message_id: integer
The ID of the scheduled message that was deleted.
Example
{
"op": "remove",
"scheduled_message_id": 17,
"type": "scheduled_messages"
}
Event sent to users in an organization when a channel folder is created.
Changes: New in Zulip 11.0 (feature level 389).
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
channel_folder: object
Object containing the channel folder's attributes.
-
name: string
The name of the channel folder.
-
date_created: integer | null
The UNIX timestamp for when the channel folder was created,
in UTC seconds.
-
creator_id: integer | null
The ID of the user who created this channel folder.
-
description: string
The description of the channel folder.
-
rendered_description: string
The description of the channel folder rendered as HTML,
intended to be used when displaying the channel folder
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.
-
id: integer
The ID of the channel folder.
-
is_archived: boolean
Whether the channel folder is archived or not.
Example
{
"channel_folder": {
"creator_id": 9,
"date_created": 1717484476,
"description": "Channels for frontend discussions",
"id": 2,
"is_archived": false,
"name": "fronted",
"rendered_description": "<p>Channels for frontend discussions</p>"
},
"id": 0,
"op": "add",
"type": "channel_folder"
}
Event sent to users in an organization when a channel folder is updated.
Changes: New in Zulip 11.0 (feature level 389).
-
id: integer
The ID of the event. Events appear in increasing order but may not be consecutive.
-
type: string
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in POST /register.
-
channel_folder_id: number
ID of the updated channel folder.
-
data: object
Dictionary containing the changed details of the channel folder.
-
name: string
The new name of the channel folder. Only present if the channel
folder's name changed.
-
description: string
The new description of the channel folder. Only present if the
description changed.
-
rendered_description: string
The new rendered description of the channel folder. Only present
if the description changed.
-
is_archived: boolean
Whether the channel folder is archived or not. Only present if
the channel folder is archived or unarchived.
Example
{
"data": {
"name": "New frontend"
},
"id": 0,
"op": "update",
"type": "channel_folder"
}
Example response(s)
Changes: As of Zulip 7.0 (feature level 167), if any
parameters sent in the request are not supported by this
endpoint, a successful JSON response will include an
ignored_parameters_unsupported array.
A typical successful JSON response may look like:
{
"events": [
{
"id": 0,
"message": {
"avatar_url": "https://url/for/othello-bots/avatar",
"client": "website",
"content": "I come not, friends, to steal away your hearts.",
"content_type": "text/x-markdown",
"display_recipient": "Denmark",
"id": 12345678,
"recipient_id": 12314,
"sender_email": "othello-bot@example.com",
"sender_full_name": "Othello Bot",
"sender_id": 13215,
"sender_realm_str": "example",
"timestamp": 1375978403,
"topic_links": [],
"type": "stream"
},
"type": "message"
},
{
"id": 1,
"message": {
"avatar_url": "https://url/for/othello-bots/avatar",
"client": "website",
"content": "With mirth and laughter let old wrinkles come.",
"content_type": "text/x-markdown",
"display_recipient": [
{
"email": "hamlet@example.com",
"full_name": "Hamlet of Denmark",
"id": 31572
}
],
"id": 12345679,
"recipient_id": 18391,
"sender_email": "othello-bot@example.com",
"sender_full_name": "Othello Bot",
"sender_id": 13215,
"sender_realm_str": "example",
"subject": "",
"timestamp": 1375978404,
"topic_links": [],
"type": "private"
},
"type": "message"
}
],
"msg": "",
"queue_id": "fb67bf8a-c031-47cc-84cf-ed80accacda8",
"result": "success"
}
BAD_EVENT_QUEUE_ID errors
This error occurs if the target event queue has been garbage collected.
A compliant client will handle this error by re-initializing itself
(e.g. a Zulip web app browser window will reload in this case).
See the /register endpoint docs for details on how to
handle these correctly.
The following is the error response in such case:
{
"code": "BAD_EVENT_QUEUE_ID",
"msg": "Bad event queue ID: fb67bf8a-c031-47cc-84cf-ed80accacda8",
"queue_id": "fb67bf8a-c031-47cc-84cf-ed80accacda8",
"result": "error"
}