Get events from an event queue
GET https://chat.nsg.net.ru/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 above
# 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://chat.nsg.net.ru/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
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.
-
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"
}
update_global_notifications
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.
-
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"
}
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 in an organization for changes
in the set of users or those users metadata.
-
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.
-
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 time zone setting.
-
When the owner of a bot changes.
-
When the role of a user changes.
-
When billing role of a user changes.
-
user_id: integer
The ID of the user affected by this change.
-
is_billing_admin: boolean
A boolean specifying whether the user is now a billing administrator.
Changes: New in Zulip 5.0 (feature level 73).
-
When the delivery email of a user changes.
Note: This event is only visible to admins.
-
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 display email address of a user changes,
either due to the user's email address changing, or
due to changes in the organization'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 display email address.
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 stream 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 streams.
Changes: Removed role field from the dictionary
in Zulip 6.0 (feature level 133).
-
stream_id: integer
The unique ID of a stream.
-
name: string
The name of a stream.
-
description: string
The description of the stream in text/markdown format,
intended to be used to prepopulate UI for editing a stream's
description.
See also rendered_description.
-
rendered_description: string
The description of the stream rendered as HTML, intended to
be used when displaying the stream description in a UI.
One should use the standard Zulip rendered_markdown CSS when
displaying this content so that emoji, LaTeX, and other syntax
work correctly. And any client-side security logic for
user-generated message content should be applied when displaying
this HTML as though it were the body of a Zulip message.
See also description.
-
date_created: integer
The UNIX timestamp for when the stream was created, in UTC seconds.
Changes: New in Zulip 4.0 (feature level 30).
-
invite_only: boolean
Specifies whether the stream is private or not.
Only people who have been invited can access a private stream.
-
subscribers: (integer)[]
A list of user IDs of users who are also subscribed
to a given stream. Included only if include_subscribers is true.
-
desktop_notifications: boolean | null
A boolean specifying whether desktop notifications
are enabled for the given stream.
A null value means the value of this setting
should be inherited from the user-level default
setting, enable_stream_desktop_notifications, for
this stream.
-
email_notifications: boolean | null
A boolean specifying whether email notifications
are enabled for the given stream.
A null value means the value of this setting
should be inherited from the user-level default
setting, enable_stream_email_notifications, for
this stream.
-
wildcard_mentions_notify: boolean | null
A boolean specifying whether wildcard mentions
trigger notifications as though they were personal
mentions in this stream.
A null value means the value of this setting
should be inherited from the user-level default
setting, wildcard_mentions_notify, for
this stream.
-
push_notifications: boolean | null
A boolean specifying whether push notifications
are enabled for the given stream.
A null value means the value of this setting
should be inherited from the user-level default
setting, enable_stream_push_notifications, for
this stream.
-
audible_notifications: boolean | null
A boolean specifying whether audible notifications
are enabled for the given stream.
A null value means the value of this setting
should be inherited from the user-level default
setting, enable_stream_audible_notifications, for
this stream.
-
pin_to_top: boolean
A boolean specifying whether the given stream has been pinned
to the top.
-
email_address: string
Email address of the given stream, used for
sending emails to the stream.
-
is_muted: boolean
Whether the user has muted the stream. Muted streams do
not count towards your total unread count and do not show up in
All messages view (previously known as Home view).
Changes: Prior to Zulip 2.1.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 stream 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 stream.
Changes: Deprecated in Zulip 3.0 (feature level 1). Clients
should use stream_post_policy instead.
-
is_web_public: boolean
Whether the stream has been configured to allow unauthenticated
access to its message history from the web.
-
color: string
The user's personal color for the stream.
-
stream_post_policy: integer
Policy for which users can post messages to the stream.
- 1 => Any user can post.
- 2 => Only administrators can post.
- 3 => Only full members can post.
- 4 => Only moderators can post.
Changes: New in Zulip 3.0 (feature level 1), replacing the previous
is_announcement_only boolean.
-
message_retention_days: integer | null
Number of days that messages sent to this stream will be stored
before being automatically deleted by the message retention
policy. There are two special values:
null, the default, means the stream will inherit the organization
level setting.-1 encodes retaining messages in this stream forever.
Changes: New in Zulip 3.0 (feature level 17).
-
history_public_to_subscribers: boolean
Whether the history of the stream is public to its subscribers.
Currently always true for public streams (i.e. invite_only=False implies
history_public_to_subscribers=True), but clients should not make that
assumption, as we may change that behavior in the future.
-
first_message_id: integer | null
The id of the first message in the stream.
Intended to help clients determine whether they need to display
UI like the "more topics" widget that would suggest the stream
has older history that can be accessed.
Null is used for streams with no message history.
-
stream_weekly_traffic: integer | null
The average number of messages sent to the stream in recent weeks,
rounded to the nearest integer.
Null means the stream was recently created and there is
insufficient data to estimate the average traffic.
-
can_remove_subscribers_group_id: integer
ID of the user group whose members are allowed to unsubscribe others
from the stream.
Changes: New in Zulip 6.0 (feature level 142).
Example
{
"id": 0,
"op": "add",
"subscriptions": [
{
"audible_notifications": null,
"can_remove_subscribers_group_id": 2,
"color": "#76ce90",
"description": "",
"desktop_notifications": null,
"email_address": "test_stream.af64447e9e39374841063747ade8e6b0.show-sender@testserver",
"email_notifications": null,
"first_message_id": null,
"history_public_to_subscribers": true,
"in_home_view": true,
"invite_only": false,
"is_announcement_only": false,
"is_muted": false,
"is_web_public": false,
"message_retention_days": null,
"name": "test_stream",
"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 streams.
-
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 streams.
-
stream_id: integer
The ID of the stream.
-
name: string
The name of the stream.
Example
{
"id": 0,
"op": "remove",
"subscriptions": [
{
"name": "test_stream",
"stream_id": 9
}
],
"type": "subscription"
}
Event sent to a user's clients when a property of the user's
subscription to a stream has been updated. This event is used
only for personal properties like is_muted or pin_to_top.
See the stream update event
for updates to global properties of a stream.
-
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 stream 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
}
subscription op: peer_add
Event sent to other users when users have been subscribed to
streams. Sent to all users if the stream is public or to only
the existing subscribers if the stream is private.
-
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 streams to which the user has subscribed.
-
user_ids: (integer)[]
The IDs of the users who subscribed.
Example
{
"id": 0,
"op": "peer_add",
"stream_id": 9,
"type": "subscription",
"user_id": 12
}
subscription op: peer_remove
Event sent to other users when users have been unsubscribed
from streams. Sent to all users if the stream is public or to only
the existing subscribers if the stream is private.
-
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 streams from which the users have been
unsubscribed from.
-
user_ids: (integer)[]
The IDs of the users who have been unsubscribed.
Example
{
"id": 0,
"op": "peer_remove",
"stream_id": 9,
"type": "subscription",
"user_id": 12
}
Event type for 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.
-
message: object
Object containing details of the message.
-
avatar_url: string | null
The URL of the user's avatar. Can be null only if client_gravatar was passed,
which means that the user has not uploaded an avatar in Zulip, and the
client should compute the gravatar URL by hashing the
user's email address itself for this user.
-
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 stream 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 the message,
ordered chronologically from most recent to least recent
edit.
Not present if the message has never been edited or if the realm has
disabled viewing of message edit history.
Every object will contain user_id and timestamp.
The other fields are optional, and will be present or not
depending on whether the stream, 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.
-
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_rendered_content_version: integer
Only present if message's content was edited.
The Markdown processor version number for the message
immediately prior to this edit event.
-
prev_stream: integer
Only present if message's stream was edited.
The stream ID of the message immediately prior to this
edit event.
-
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 stream was edited.
The ID of the stream 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 was last edited,
in UTC seconds.
Not present if the message has never been edited.
-
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.
-
user: object
Dictionary with data on the user who added the
reaction, including the user ID as the id
field. Note that reactions data received from the
events API has a slightly different
user dictionary format, with the user ID field
called user_id instead.
Changes: 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.
-
recipient_id: integer
A unique ID for the set of users receiving the
message (either a stream or group of users). Useful primarily
for hashing.
-
sender_email: string
The Zulip display 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 stream messages; the ID of the stream.
-
subject: string
The topic of the message. Currently always "" for private messages,
though this could change if Zulip adds support for topics in private
message conversations.
The field name is a legacy holdover from when topics were
called "subjects" and will eventually change.
-
submessages: (string)[]
Data used for certain experimental Zulip integrations.
-
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.
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",
"sender_short_name": "hamlet",
"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 to organization administrators when the
set of invitations changes; this tells clients they need to refetch
data from GET /invites if they are displaying UI containing active
invitations.
-
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. Processing this event is important to being able
to display basic details on other users given only their ID.
-
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.
-
user_id: integer
The unique ID of the user.
-
delivery_email: string
The user's real email address. This field is present only if
email address visibility is
limited and you are an administrator with access to real email addresses
under the configured policy.
-
email: string
The Zulip API email address of the user or bot.
If you do not have permission to view the email address of the target user,
this will be a fake email address that is usable for the Zulip API but nothing else.
-
full_name: string
Full name of the user or bot, used for all display purposes.
-
date_joined: string
The time the user account was created.
-
is_active: boolean
A boolean specifying whether the user account has been deactivated.
-
is_owner: boolean
A boolean specifying whether the user is an organization owner.
If true, is_admin will also be true.
Changes: New in Zulip 3.0 (feature level 8).
-
is_admin: boolean
A boolean specifying whether the user is an organization administrator.
-
is_guest: boolean
A boolean specifying whether the user is a guest user.
-
is_billing_admin: boolean
A boolean specifying whether the user is a billing administrator.
Changes: New in Zulip 5.0 (feature level 73).
-
is_bot: boolean
A boolean specifying whether the user is a bot or full account.
-
bot_type: integer | null
An integer describing the type of bot:
null if the user isn't a bot.1 for a Generic bot.2 for an Incoming webhook bot.3 for an Outgoing webhook bot.4 for an Embedded bot.
-
bot_owner_id: integer | null
If the user is a bot (i.e. is_bot is true), then bot_owner_id
is the user ID of the bot's owner (usually, whoever created the bot).
Will be null for legacy bots that do not have an owner.
Changes: New in Zulip 3.0 (feature level 1). In previous
versions, there was a bot_owner field containing the email
address of the bot's owner.
-
role: integer
Organization-level role of the user.
Possible values are:
- Organization owner => 100
- Organization administrator => 200
- Organization moderator => 300
- Member => 400
- Guest => 600
Changes: New in Zulip 4.0 (feature level 59).
-
timezone: string
The time zone of the user.
-
avatar_url: string | null
URL for the user's avatar. Will be null if the client_gravatar
query parameter was set to True and the user's avatar is hosted by
the Gravatar provider (i.e. the user has never uploaded an avatar).
Changes: In Zulip 3.0 (feature level 18), if the client has the
user_avatar_url_field_optional capability, this will be missing at
the server's sole discretion.
-
avatar_version: integer
Version for the user's avatar. Used for cache-busting requests
for the user's avatar. Clients generally shouldn't need to use this;
most avatar URLs sent by Zulip will already end with ?v={avatar_version}.
-
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",
"email": "foo@zulip.com",
"full_name": "full name",
"is_active": true,
"is_admin": false,
"is_billing_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 all users in a Zulip organization when
a user is 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. While most presence
updates are done via polling the main presence
endpoint, this event is important to avoid
confusing users when someone comes online and immediately sends
a message (one wouldn't want them to still appear offline at
that point!).
-
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 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.
Example
{
"email": "user10@zulip.testserver",
"id": 0,
"presence": {
"ZulipAndroid/1.0": {
"client": "ZulipAndroid/1.0",
"pushable": false,
"status": "idle",
"timestamp": 1594825445
}
},
"server_timestamp": 1594825445.3200784,
"type": "presence",
"user_id": 10
}
Event sent when a new stream is created to users who can see
the new stream exists (for private streams, only subscribers and
organization administrators will receive this event).
Note that organization administrators who are not subscribed will
not be able to see content on the stream; just that it exists.
-
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 stream objects, each containing
details about the newly added stream(s).
-
stream_id: integer
The unique ID of the stream.
-
name: string
The name of the stream.
-
description: string
The short description of the stream in text/markdown format,
intended to be used to prepopulate UI for editing a stream's
description.
-
date_created: integer
The UNIX timestamp for when the stream was created, in UTC seconds.
Changes: New in Zulip 4.0 (feature level 30).
-
invite_only: boolean
Specifies whether the stream is private or not.
Only people who have been invited can access a private stream.
-
rendered_description: string
The short description of the stream rendered as HTML, intended to
be used when displaying the stream description in a UI.
One should use the standard Zulip rendered_markdown CSS when
displaying this content so that emoji, LaTeX, and other syntax
work correctly. And any client-side security logic for
user-generated message content should be applied when displaying
this HTML as though it were the body of a Zulip message.
-
is_web_public: boolean
Whether the stream has been configured to allow unauthenticated
access to its message history from the web.
-
stream_post_policy: integer
Policy for which users can post messages to the stream.
- 1 => Any user can post.
- 2 => Only administrators can post.
- 3 => Only full members can post.
- 4 => Only moderators can post.
Changes: New in Zulip 3.0 (feature level 1), replacing the previous
is_announcement_only boolean.
-
message_retention_days: integer | null
Number of days that messages sent to this stream will be stored
before being automatically deleted by the message retention
policy. There are two special values:
null, the default, means the stream will inherit the organization
level setting.-1 encodes retaining messages in this stream forever.
Changes: New in Zulip 3.0 (feature level 17).
-
history_public_to_subscribers: boolean
Whether the history of the stream is public to its subscribers.
Currently always true for public streams (i.e. invite_only=False implies
history_public_to_subscribers=True), but clients should not make that
assumption, as we may change that behavior in the future.
-
first_message_id: integer | null
The id of the first message in the stream.
Intended to help clients determine whether they need to display
UI like the "more topics" widget that would suggest the stream
has older history that can be accessed.
Null is used for streams with no message history.
-
is_announcement_only: boolean
Whether the given stream is announcement only or not.
Changes: Deprecated in Zulip 3.0 (feature level 1). Clients
should use stream_post_policy instead.
-
can_remove_subscribers_group_id: integer
ID of the user group whose members are allowed to unsubscribe others
from the stream.
Changes: New in Zulip 6.0 (feature level 142).
Example
{
"id": 0,
"op": "create",
"streams": [
{
"can_remove_subscribers_group_id": 2,
"description": "",
"first_message_id": null,
"history_public_to_subscribers": false,
"invite_only": true,
"is_announcement_only": false,
"is_web_public": false,
"message_retention_days": null,
"name": "private",
"rendered_description": "",
"stream_id": 12,
"stream_post_policy": 1
}
],
"type": "stream"
}
Event sent to all users who can see a stream when it is 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.
-
streams: (object)[]
Array of stream objects, each containing
details about a stream that was deleted.
-
stream_id: integer
The unique ID of the stream.
-
name: string
The name of the stream.
-
description: string
The short description of the stream in text/markdown format,
intended to be used to prepopulate UI for editing a stream's
description.
-
date_created: integer
The UNIX timestamp for when the stream was created, in UTC seconds.
Changes: New in Zulip 4.0 (feature level 30).
-
invite_only: boolean
Specifies whether the stream is private or not.
Only people who have been invited can access a private stream.
-
rendered_description: string
The short description of the stream rendered as HTML, intended to
be used when displaying the stream description in a UI.
One should use the standard Zulip rendered_markdown CSS when
displaying this content so that emoji, LaTeX, and other syntax
work correctly. And any client-side security logic for
user-generated message content should be applied when displaying
this HTML as though it were the body of a Zulip message.
-
is_web_public: boolean
Whether the stream has been configured to allow unauthenticated
access to its message history from the web.
-
stream_post_policy: integer
Policy for which users can post messages to the stream.
- 1 => Any user can post.
- 2 => Only administrators can post.
- 3 => Only full members can post.
- 4 => Only moderators can post.
Changes: New in Zulip 3.0 (feature level 1), replacing the previous
is_announcement_only boolean.
-
message_retention_days: integer | null
Number of days that messages sent to this stream will be stored
before being automatically deleted by the message retention
policy. There are two special values:
null, the default, means the stream will inherit the organization
level setting.-1 encodes retaining messages in this stream forever.
Changes: New in Zulip 3.0 (feature level 17).
-
history_public_to_subscribers: boolean
Whether the history of the stream is public to its subscribers.
Currently always true for public streams (i.e. invite_only=False implies
history_public_to_subscribers=True), but clients should not make that
assumption, as we may change that behavior in the future.
-
first_message_id: integer | null
The id of the first message in the stream.
Intended to help clients determine whether they need to display
UI like the "more topics" widget that would suggest the stream
has older history that can be accessed.
Null is used for streams with no message history.
-
is_announcement_only: boolean
Whether the given stream is announcement only or not.
Changes: Deprecated in Zulip 3.0 (feature level 1). Clients
should use stream_post_policy instead.
-
can_remove_subscribers_group_id: integer
ID of the user group whose members are allowed to unsubscribe others
from the stream.
Changes: New in Zulip 6.0 (feature level 142).
Example
{
"id": 0,
"op": "delete",
"streams": [
{
"can_remove_subscribers_group_id": 2,
"description": "",
"first_message_id": null,
"history_public_to_subscribers": false,
"invite_only": true,
"is_announcement_only": false,
"is_web_public": false,
"message_retention_days": null,
"name": "private",
"rendered_description": "",
"stream_id": 12,
"stream_post_policy": 1
}
],
"type": "stream"
}
Event sent to all users who can see that a stream exists
when a property of that stream 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.
-
stream_id: integer
The ID of the stream whose details have changed.
-
name: string
The name of the stream whose details have changed.
-
property: string
The property of the stream which has changed. See
/stream GET for details on the various
properties of a stream.
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: integer | boolean | string
The new value of the changed property.
-
rendered_description: string
Note: Only present if the changed property was description.
The short description of the stream rendered as HTML, intended to
be used when displaying the stream description in a UI.
One should use the standard Zulip rendered_markdown CSS when
displaying this content so that emoji, LaTeX, and other syntax
work correctly. And any client-side security logic for
user-generated message content should be applied when displaying
this HTML as though it were the body of a Zulip message.
-
history_public_to_subscribers: boolean
Note: Only present if the changed property was invite_only.
Whether the history of the stream is public to its subscribers.
Currently always true for public streams (i.e. invite_only=False implies
history_public_to_subscribers=True), but clients should not make that
assumption, as we may change that behavior in the future.
-
is_web_public: boolean
Note: Only present if the changed property was invite_only.
Whether the stream'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_stream",
"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 id
field. Note that reactions data received from the
events API has a slightly different
user dictionary format, with the user ID field
called user_id instead.
Changes: 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 id
field. Note that reactions data received from the
events API has a slightly different
user dictionary format, with the user ID field
called user_id instead.
Changes: 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 in a Zulip organization when the
status of a user 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.
-
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.
Changes: New in Zulip 6.0 (feature level 146).
Example
{
"fields": [
{
"field_data": "",
"hint": "",
"id": 1,
"name": "Phone number",
"order": 1,
"type": 1
},
{
"field_data": "",
"hint": "What are you known for?",
"id": 2,
"name": "Biography",
"order": 2,
"type": 2
},
{
"field_data": "",
"hint": "Or drink, if you'd prefer",
"id": 3,
"name": "Favorite food",
"order": 3,
"type": 1
},
{
"display_in_profile_summary": true,
"field_data": "{\"0\":{\"text\":\"Vim\",\"order\":\"1\"},\"1\":{\"text\":\"Emacs\",\"order\":\"2\"}}",
"hint": "",
"id": 4,
"name": "Favorite editor",
"order": 4,
"type": 3
},
{
"field_data": "",
"hint": "",
"id": 5,
"name": "Birthday",
"order": 5,
"type": 4
},
{
"display_in_profile_summary": true,
"field_data": "",
"hint": "Or your personal blog's URL",
"id": 6,
"name": "Favorite website",
"order": 6,
"type": 5
},
{
"field_data": "",
"hint": "",
"id": 7,
"name": "Mentor",
"order": 7,
"type": 6
},
{
"field_data": "{\"subtype\":\"github\"}",
"hint": "Enter your GitHub username",
"id": 8,
"name": "GitHub",
"order": 8,
"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 stream groups.
Default stream 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 stream group.
-
name: string
Name of the default stream group.
-
description: string
Description of the default stream group.
-
id: integer
id of the default stream group.
-
streams: (object)[]
Array containing details about the streams
in the default stream group.
-
stream_id: integer
The unique ID of the stream.
-
name: string
The name of the stream.
-
description: string
The short description of the stream in text/markdown format,
intended to be used to prepopulate UI for editing a stream's
description.
-
date_created: integer
The UNIX timestamp for when the stream was created, in UTC seconds.
Changes: New in Zulip 4.0 (feature level 30).
-
invite_only: boolean
Specifies whether the stream is private or not.
Only people who have been invited can access a private stream.
-
rendered_description: string
The short description of the stream rendered as HTML, intended to
be used when displaying the stream description in a UI.
One should use the standard Zulip rendered_markdown CSS when
displaying this content so that emoji, LaTeX, and other syntax
work correctly. And any client-side security logic for
user-generated message content should be applied when displaying
this HTML as though it were the body of a Zulip message.
-
is_web_public: boolean
Whether the stream has been configured to allow unauthenticated
access to its message history from the web.
-
stream_post_policy: integer
Policy for which users can post messages to the stream.
- 1 => Any user can post.
- 2 => Only administrators can post.
- 3 => Only full members can post.
- 4 => Only moderators can post.
Changes: New in Zulip 3.0 (feature level 1), replacing the previous
is_announcement_only boolean.
-
message_retention_days: integer | null
Number of days that messages sent to this stream will be stored
before being automatically deleted by the message retention
policy. There are two special values:
null, the default, means the stream will inherit the organization
level setting.-1 encodes retaining messages in this stream forever.
Changes: New in Zulip 3.0 (feature level 17).
-
history_public_to_subscribers: boolean
Whether the history of the stream is public to its subscribers.
Currently always true for public streams (i.e. invite_only=False implies
history_public_to_subscribers=True), but clients should not make that
assumption, as we may change that behavior in the future.
-
first_message_id: integer | null
The id of the first message in the stream.
Intended to help clients determine whether they need to display
UI like the "more topics" widget that would suggest the stream
has older history that can be accessed.
Null is used for streams with no message history.
-
is_announcement_only: boolean
Whether the given stream is announcement only or not.
Changes: Deprecated in Zulip 3.0 (feature level 1). Clients
should use stream_post_policy instead.
-
can_remove_subscribers_group_id: integer
ID of the user group whose members are allowed to unsubscribe others
from the stream.
Changes: New in Zulip 6.0 (feature level 142).
Example
{
"default_stream_groups": [
{
"description": "New description",
"id": 2,
"name": "group1",
"streams": [
{
"can_remove_subscribers_group_id": 2,
"description": "Located in the United Kingdom",
"first_message_id": 1,
"history_public_to_subscribers": true,
"invite_only": false,
"is_announcement_only": false,
"is_web_public": false,
"message_retention_days": null,
"name": "Scotland",
"rendered_description": "<p>Located in the United Kingdom</p>",
"stream_id": 3,
"stream_post_policy": 1
},
{
"can_remove_subscribers_group_id": 2,
"description": "A Scandinavian country",
"first_message_id": 4,
"history_public_to_subscribers": true,
"invite_only": false,
"is_announcement_only": false,
"is_web_public": false,
"message_retention_days": null,
"name": "Denmark",
"rendered_description": "<p>A Scandinavian country</p>",
"stream_id": 1,
"stream_post_policy": 1
},
{
"can_remove_subscribers_group_id": 2,
"description": "A city in Italy",
"first_message_id": 6,
"history_public_to_subscribers": true,
"invite_only": false,
"is_announcement_only": false,
"is_web_public": false,
"message_retention_days": null,
"name": "Verona",
"rendered_description": "<p>A city in Italy</p>",
"stream_id": 5,
"stream_post_policy": 1
}
]
}
],
"id": 0,
"type": "default_stream_groups"
}
Event sent to all users in a Zulip organization when the
default streams 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: (object)[]
An array of dictionaries where each dictionary
contains details about a single default stream.
-
stream_id: integer
The unique ID of the stream.
-
name: string
The name of the stream.
-
description: string
The short description of the stream in text/markdown format,
intended to be used to prepopulate UI for editing a stream's
description.
-
date_created: integer
The UNIX timestamp for when the stream was created, in UTC seconds.
Changes: New in Zulip 4.0 (feature level 30).
-
invite_only: boolean
Specifies whether the stream is private or not.
Only people who have been invited can access a private stream.
-
rendered_description: string
The short description of the stream rendered as HTML, intended to
be used when displaying the stream description in a UI.
One should use the standard Zulip rendered_markdown CSS when
displaying this content so that emoji, LaTeX, and other syntax
work correctly. And any client-side security logic for
user-generated message content should be applied when displaying
this HTML as though it were the body of a Zulip message.
-
is_web_public: boolean
Whether the stream has been configured to allow unauthenticated
access to its message history from the web.
-
stream_post_policy: integer
Policy for which users can post messages to the stream.
- 1 => Any user can post.
- 2 => Only administrators can post.
- 3 => Only full members can post.
- 4 => Only moderators can post.
Changes: New in Zulip 3.0 (feature level 1), replacing the previous
is_announcement_only boolean.
-
message_retention_days: integer | null
Number of days that messages sent to this stream will be stored
before being automatically deleted by the message retention
policy. There are two special values:
null, the default, means the stream will inherit the organization
level setting.-1 encodes retaining messages in this stream forever.
Changes: New in Zulip 3.0 (feature level 17).
-
history_public_to_subscribers: boolean
Whether the history of the stream is public to its subscribers.
Currently always true for public streams (i.e. invite_only=False implies
history_public_to_subscribers=True), but clients should not make that
assumption, as we may change that behavior in the future.
-
first_message_id: integer | null
The id of the first message in the stream.
Intended to help clients determine whether they need to display
UI like the "more topics" widget that would suggest the stream
has older history that can be accessed.
Null is used for streams with no message history.
-
is_announcement_only: boolean
Whether the given stream is announcement only or not.
Changes: Deprecated in Zulip 3.0 (feature level 1). Clients
should use stream_post_policy instead.
-
can_remove_subscribers_group_id: integer
ID of the user group whose members are allowed to unsubscribe others
from the stream.
Changes: New in Zulip 6.0 (feature level 142).
Example
{
"default_streams": [
{
"can_remove_subscribers_group_id": 2,
"description": "Located in the United Kingdom",
"first_message_id": 1,
"history_public_to_subscribers": true,
"invite_only": false,
"is_announcement_only": false,
"is_web_public": false,
"message_retention_days": null,
"name": "Scotland",
"rendered_description": "<p>Located in the United Kingdom</p>",
"stream_id": 3,
"stream_post_policy": 1
}
],
"id": 0,
"type": "default_streams"
}
Event sent when a message has been deleted.
Sent to all users who received the message.
Changes: Before Zulip 5.0 (feature level 77), events
for private 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)[]
The message_ids property will be present for clients that support
the bulk_message_deletion client capability.
An containing the IDs of the newly deleted messages.
-
message_id: integer
The message_id property will be 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'. The other keys
present in the event, necessary to update various frontend data structures
that might be tracking the message, depend on the message type.
-
stream_id: integer
Only present for stream messages.
The ID of the stream to which the message was sent.
-
topic: string
Only present for stream messages.
The topic to which the message was sent.
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 stream name in which the topic
has to be muted, the second element is the topic name to be muted
and the third element is an integer UNIX timestamp representing
when the topic was muted.
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.
Changes: 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 stream to which the topic belongs.
-
topic_name: string
The name of the topic.
-
last_updated: integer
An integer UNIX timestamp representing when the user-topic
relationship was 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 in events to indicate that the user no
longer has a special visibility policy for this
topic (for example, the user just unmuted it).
- 1 = Muted. Used to record muted topics.
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 "hotspots" to show for
the current user have 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.
-
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.
-
hotspots: (object)[]
An array of dictionaries where each
dictionary contains details about a single hotspot.
-
delay: number
The delay after which the user should be shown the hotspot.
-
name: string
The name of the hotspot.
-
title: string
The title of the hotspot, as will be displayed to the user.
-
description: string
The description of the hotspot, as will be displayed to the
user.
Example
{
"hotspots": [
{
"delay": 0.5,
"description": "Messages sent to a stream are seen by everyone subscribed to that stream. Try clicking on one of the stream links below.",
"name": "intro_streams",
"title": "Catch up on a stream"
}
],
"id": 0,
"type": "hotspots"
}
Event sent when a message's content, topic and/or
stream 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.
-
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.
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 stream 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)[]
The list of IDs of messages to which any stream or topic changes
encoded in this event should be applied.
These messages are guaranteed to have all been previously sent
to stream 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 stream and
topic.
Content changes should be applied only to the single message
indicated by message_id.
-
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.
-
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 stream.
The name of the stream 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 stream.
The pre-edit stream 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 stream message. Previously, it
was not present when only the content of the stream message was
edited.
-
new_stream_id: integer
Only present if message(s) were moved to a different stream.
The post-edit stream 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 stream.
The choice the editing user made about which messages should be
affected by a stream/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 stream.
The pre-edit topic for all of the messages with IDs in
message_ids.
-
subject: string
Only present if this event moved messages to a different
topic.
The post-edit topic for all of the messages with IDs in
message_ids.
-
topic_links: (object)[]
Only present if this event moved messages to a different
topic.
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.
-
prev_rendered_content_version: integer
Only present if this event changed the message content.
The Markdown processor version number for the pre-edit message.
Clients should ignore this field.
-
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": [
58,
57
],
"orig_content": "hello",
"orig_rendered_content": "<p>hello</p>",
"orig_subject": "test",
"prev_rendered_content_version": 1,
"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 stream messages are only sent to clients
that included stream_typing_notifications in their
client_capabilities when registering the event queue.
Changes: Typing notifications for stream messages are new in
Zulip 4.0 (feature level 58).
See the typing endpoint docs for more details.
-
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 "private",
as with sending a message.
Changes: New in Zulip 4.0 (feature level 58). Previously,
all typing notifications were implicitly private private.
-
sender: object
Object describing the "sender" (i.e. the user who is typing a message).
-
recipients: (object)[]
Only present if message_type is private.
Array of dictionaries describing the set of users who would be recipients
of the message being typed. Each dictionary contains details on one
one of the recipients users; 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 stream to which message is being typed.
Changes: New in Zulip 4.0 (feature level 58). Previously,
typing notifications were only for private messages.
-
topic: string
Only present if message_type is stream.
Topic within the stream where the message is being typed.
Changes: New in Zulip 4.0 (feature level 58). Previously,
typing notifications were only for private messages.
Example
{
"id": 0,
"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 stream messages are only sent to
clients that included stream_typing_notifications in their
client_capabilities when registering the event queue.
Changes: Typing notifications for stream messages are new in
Zulip 4.0 (feature level 58).
See the typing endpoint docs for more details.
-
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 "private",
as with sending a message.
Changes: New in Zulip 4.0 (feature level 58). Previously,
all typing notifications were implicitly private private.
-
sender: object
Object describing the "sender" (i.e. the user who was previously
typing a message).
-
recipients: (object)[]
Only present for typing notifications for (group) private messages.
Array of dictionaries describing the set of users who would be recipients
of the message that stopped being typed. Each dictionary contains
details on one one of the recipients users; 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 stream to which message is being typed.
Changes: New in Zulip 4.0 (feature level 58). Previously,
typing notifications were only for private messages.
-
topic: string
Only present if message_type is stream.
Topic within the stream where the message is being typed.
Changes: New in Zulip 4.0 (feature level 58). Previously,
typing notifications were only for private messages.
Example
{
"id": 0,
"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"
}
update_message_flags op: add
Event sent to a user when message flags are added
to a message.
-
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 op for this event type.
Deprecated: This is deprecated; please use op instead
starting with Zulip 4.0 (feature level 32).
-
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 flag was added to all messages (E.g. all messages
were marked as read).
If this is true, then the messages array will be empty.
Example
{
"all": false,
"flag": "starred",
"id": 0,
"messages": [
63
],
"op": "add",
"operation": "add",
"type": "update_message_flags"
}
update_message_flags op: remove
Event sent to a user when message flags are
removed from a message.
-
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 op for this event type.
Deprecated: This is deprecated; please use op instead
starting with Zulip 4.0 (feature level 32).
-
flag: string
The flag to be removed.
-
messages: (integer)[]
Array containing the IDs of the messages from which the flag
was removed.
-
all: boolean
Whether the flag was removed from all messages.
If this is true then the messages array will be empty.
-
message_details: object
Present if message and update_message_flags are both present in
event_types and the flag is read and the op is remove.
A set of data structures describing the messages that
are being marked as unread with additional details to
allow a client 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.
-
Additional properties.
-
type: string
The type of this message.
-
mentioned: boolean
A flag which indicates whether the message contains a mention
of the user.
Present only if the message mentions the current user.
-
user_ids: (integer)[]
Present only if type is private.
The user IDs of every recipient of this private message, excluding yourself.
Will be the empty list for a message you had sent to only yourself.
-
stream_id: integer
Present only if type is stream.
The ID of the stream where the message was sent.
-
topic: string
Present only if type is stream.
Name of the topic where the message was sent.
-
unmuted_stream_msg: boolean
Deprecated
Internal implementation detail. Clients should
ignore this field as it will be removed in the future.
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.
-
description: string
The description of the user group.
-
members: (integer)[]
Array containing the id of the users who are
members of this user group.
-
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).
Example
{
"group": {
"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.
-
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.
Example
{
"data": {
"description": "Mention this group to get the security team's attention."
},
"group_id": 2,
"id": 0,
"op": "update",
"type": "user_group"
}
user_group op: add_members
Event sent to all users when users have been added to a user group.
-
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
]
}
user_group op: remove_members
Event sent to all users when users have been removed from
a user group.
-
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
]
}
user_group op: add_subgroups
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"
}
user_group op: remove_subgroups
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 to all users when a user group has been 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 to doing Markdown local echo
correctly.
Changes: New in Zulip 4.0 (feature level 54), replacing the
previous realm_filters event type, which is still sent for
backwards compatibility reasons.
Clients should migrate to requesting and processing the
realm_linkifiers event type when possible, since we plan to remove
the legacy realm_filters logic entirely in a future release.
-
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)[]
Array of dictionaries where each dictionary contains details about
a single realm linkifier.
Example
{
"id": 0,
"realm_linkifiers": [
{
"id": 1,
"pattern": "#(?P<id>[123])",
"url_format": "https://realm.com/my_realm_filter/%(id)s"
}
],
"type": "realm_linkifiers"
}
Legacy event type. Sent to all users in a Zulip organization
when the set of configured linkifiers
for the organization has changed.
Changes: Deprecated in Zulip 4.0 (feature level 54), replaced by
the realm_linkifiers event type, which has a clearer name and format,
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.
-
realm_filters: ((integer | string)[])[]
An array of tuples, where each tuple describes a linkifier.
The first element of the tuple is a
string regex pattern which represents the pattern that should
be linkified on matching. The second element is the URL with which the
pattern matching string should be linkified with and the third element
is the ID of the realm filter.
Example
{
"id": 0,
"realm_filters": [
[
"#(?P<id>[123])",
"https://realm.com/my_realm_filter/%(id)s",
1
]
],
"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_prefix: string
The url prefix for the playground.
Example
{
"id": 0,
"realm_playgrounds": [
{
"id": 1,
"name": "Python playground",
"pygments_language": "Python",
"url_prefix": "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 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
data about a single organization export request.
-
id: integer
The id of the export.
-
acting_user_id: integer
The id of the user who did the export.
-
export_time: number
The UNIX timestamp of when the export was made.
-
deleted_timestamp: number | null
The timestamp of when the export was deleted.
Null if it wasn't.
-
failed_timestamp: number | null
The timestamp of when the export failed.
Null if it didn't.
-
export_url: string | null
The URL of the export. null if there's no URL.
-
pending: boolean
Whether the export is pending or not.
Example
{
"exports": [
{
"acting_user_id": 10,
"deleted_timestamp": null,
"export_time": 1594825443.656797,
"export_url": null,
"failed_timestamp": 1594825444.436336,
"id": 107,
"pending": false
}
],
"id": 1,
"type": "realm_export"
}
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 stream of the bot. Null if the bot doesn't
have a default sending stream.
-
default_events_register_stream: string | null
The default stream for which the bot receives events/register data. Null if
the bot doesn't have such a default stream.
-
default_all_public_streams: boolean
Whether the bot can send messages to all streams by default.
-
avatar_url: string
The URL of the bot's avatar.
-
owner_id: integer | null
The user id of the bot's owner.
Null if the bot has no owner.
-
services: (object | object)[]
The "Services" array contains extra configuration fields only relevant
for Outgoing webhook bots and Embedded bots. It is always a single-element
array.
We consider this part of the Zulip API to be unstable; it is used only for
UI elements for administering bots and is likely to change.
-
email: string
The email of the bot.
-
bot_type: integer | null
An integer describing the type of bot:
1 for a Generic bot.2 for an Incoming webhook bot.3 for an Outgoing webhook bot.4 for an Embedded bot.
-
is_active: boolean
A boolean describing whether the user account has been deactivated.
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 stream of the bot. Null if the bot doesn't
have a default sending stream.
-
default_events_register_stream: string | null
The default stream for which the bot receives events/register data. Null if
the bot doesn't have such a default stream.
-
default_all_public_streams: boolean
Whether the bot can send messages to all streams by default.
-
avatar_url: string
The URL of the bot's avatar.
-
owner_id: integer | null
The user id of the bot's owner.
Null if the bot has no owner.
-
services: (object | object)[]
The "Services" array contains extra configuration fields only relevant
for Outgoing webhook bots and Embedded bots. It is always a single-element
array.
We consider this part of the Zulip API to be unstable; it is used only for
UI elements for administering bots and is likely to change.
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.
-
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": {
"full_name": "Foo 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.
-
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
The new value of the property.
-
extra_data: object
Object containing extra data related to the changed
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 can use this event to know when they should get a new
event queue after a server upgrade. Clients doing so must implement
a random delay strategy to spread such restarts over 10 minutes or
more to avoid creating a synchronized thundering herd effect.
-
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 can safely avoid refetching their state and
creating a new event queue when the API feature level has not
changed, or when they know the specific feature level change
is not relevant to the client (E.g. it just adds a new endpoint
that the client doesn't use).
Changes: New in Zulip 4.0 (feature level 59).
-
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.
-
server_generation: integer
The timestamp at which the server started.
Example
{
"id": 0,
"immediate": true,
"server_generation": 1619334181,
"type": "restart",
"zulip_feature_level": 57,
"zulip_merge_base": "5.0-dev-1646-gea6b21cd8c",
"zulip_version": "5.0-dev-1650-gc3fd37755f"
}
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.
-
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: 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.
-
add_custom_emoji_policy: integer
The policy
for which users can add custom emoji in this organization.
-
allow_edit_history: boolean
Whether this organization is configured to allow users to access
message edit history.
-
allow_message_editing: boolean
Whether this organizations message edit policy
allows editing the content of messages.
-
authentication_methods: object
Dictionary of 'authentication_method_name': 'boolean' with each
entry describing whether the authentication name can be used for
authenticating into the organization.
- Boolean describing whether the authentication method (i.e its key)
is enabled in this organization.
-
bot_creation_policy: integer
The policy
for which users can create bot users in this organization.
-
community_topic_editing_limit_seconds: integer
Messages sent more than this many seconds ago cannot have
their topics edited by other users with this organization's
message edit policy.
Changes: New in Zulip 3.0 (feature level 11). Previously this
value was hardcoded to 86400 seconds (1 day).
-
create_public_stream_policy: integer
The policy
for which users can create public streams in this organization.
Changes: Before Zulip 5.0 (feature level 102), permission to
create streams was controlled by the create_stream_policy setting.
-
create_private_stream_policy: integer
The policy
for which users can create private streams in this organization.
Changes: Before Zulip 5.0 (feature level 102), permission to
create streams was controlled by the create_stream_policy setting.
-
create_web_public_stream_policy: integer
The policy
for which users can create web public streams in this organization.
Changes: New in Zulip 5.0 (feature level 103).
-
default_code_block_language: string | null
The default pygments language code to be used for a code blocks
in this organization. Null if no default has been set.
-
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.
-
disallow_disposable_email_addresses: boolean
Whether the organization disallows disposable email
addresses.
-
edit_topic_policy: integer
The policy for which users can edit topics of any message.
- 1 = members only
- 2 = admins only
- 3 = full members only
- 4 = moderators only
- 5 = everyone
Changes: New in Zulip 5.0 (feature level 75), replacing the
previous allow_community_topic_editing boolean.
-
email_address_visibility: integer
The policy for which users in this organization can see
the real email addresses of other users.
- 1 = Everyone
- 2 = Members only
- 3 = Administrators only
- 4 = Nobody (though note that administrators can change this setting)
- 5 = Moderators only
Changes: Nobody added as an option in Zulip 3.0 (feature level 1).
-
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.
-
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_spectator_access: boolean
Whether web-public streams 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 create_web_public_stream_policy 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.
-
invite_to_realm_policy: integer
The policy
for which users can invite other users to join the organization.
Changes: New in Zulip 4.0 (feature level 50) replacing the
previous invite_by_admins_only boolean.
-
invite_to_stream_policy: integer
The policy
for which users can add other users to streams in this organization.
-
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.
-
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.
Changes: No limit was represented using the
special value 0 before Zulip 6.0 (feature level 138).
-
move_messages_between_streams_policy: integer
The policy for which users can move messages from
one stream to another.
- 1 = Members only
- 2 = Administrators only
- 3 = Full members only
- 4 = Moderators only
Changes: New in Zulip 4.0 (feature level 56)
-
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.
-
notifications_stream_id: integer
The ID of the stream to which automated messages announcing the
creation of new streams 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.
-
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.
-
private_message_policy: integer
Policy
for who can send private messages
in this organization.
Changes: New in Zulip 3.0 (feature level 1).
-
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_notifications_stream_id: integer
The ID of the stream 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.
-
user_group_edit_policy: integer
The organization's policy for
who can manage user groups.
- 1 = All members can create and edit user groups
- 2 = Only organization administrators can create and edit user groups
- 3 = Only full members can create and edit user groups
- 4 = Only organization administrators and moderators can create and edit user groups
-
video_chat_provider: integer
The configured video call provider for the
organization.
- 0 = None
- 1 = Jitsi Meet
- 3 = Zoom
- 4 = BigBlueButton
Changes: None added as an option in Zulip 3.0 (feature level 1)
to disable video call UI.
-
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).
-
wildcard_mention_policy: integer
The policy for who can use wildcard mentions in
large streams.
- 1 => Any user can use wildcard mentions in large streams.
- 2 => Only members can use wildcard mentions in large streams.
- 3 => Only full members can use wildcard mentions in large streams.
- 5 => Only organization administrators can use wildcard mentions in large streams.
- 6 => Nobody can use wildcard mentions in large streams.
- 7 => Only organization administrators and moderators can use wildcard mentions in large streams.
All users will receive a warning/reminder when using
mentions in large streams, even when permitted to do so.
Changes: New in Zulip 4.0 (feature level 33). Moderators option added in
Zulip 4.0 (feature level 62). Stream administrators option removed in
Zulip 6.0 (feature level 133).
-
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).
Example
{
"data": {
"message_content_edit_limit_seconds": 600
},
"id": 0,
"op": "update_dict",
"property": "default",
"type": "realm"
}
realm_user_settings_defaults op: update
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 PMs and private group messages).
-
to: (integer)[]
An array of the tentative target audience IDs. For "stream"
messages, this should contain exactly 1 ID, the ID of the
target stream. For private messages, this should be an array
of target user IDs. For unaddressed drafts, this is ignored,
and clients should send an empty array.
-
topic: string
For stream message drafts, the tentative topic name. For private
or unaddressed messages, this will be ignored and should ideally
be the empty string. Should not contain null bytes.
-
content: string
The body of the draft. Should not contain null bytes.
-
timestamp: number
A Unix timestamp (seconds only) representing when the draft was
last edited. When creating a draft, this key need not be present
and it will be filled in automatically by the server.
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 PMs and private group messages).
-
to: (integer)[]
An array of the tentative target audience IDs. For "stream"
messages, this should contain exactly 1 ID, the ID of the
target stream. For private messages, this should be an array
of target user IDs. For unaddressed drafts, this is ignored,
and clients should send an empty array.
-
topic: string
For stream message drafts, the tentative topic name. For private
or unaddressed messages, this will be ignored and should ideally
be the empty string. Should not contain null bytes.
-
content: string
The body of the draft. Should not contain null bytes.
-
timestamp: number
A Unix timestamp (seconds only) representing when the draft was
last edited. When creating a draft, this key need not be present
and it will be filled in automatically by the server.
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": "update",
"type": "drafts"
}
Example response(s)
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"
}