Get events from an event queue

GET https://zulip.scsok.io/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

Python
JavaScript
curl

#!/usr/bin/env python3

import sys
import zulip

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

# If you already have a queue registered, and thus have a `queue_id`
# on hand, you may use `client.get_events()` and pass in the below
# parameters, like so:
result = client.get_events(queue_id=queue_id, last_event_id=-1)
print(result)

More examples and documentation can be found here.

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

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

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

    // Retrieve events from a queue with given "queue_id"
    const eventParams = {
        queue_id,
        last_event_id: -1,
    };

    console.log(await client.events.retrieve(eventParams));
})();

curl -sSX GET -G https://zulip.scsok.io/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

The highest event ID in this queue that you've received and wish to acknowledge. See the code for call_on_each_event in the zulip Python module for an example implementation of correctly processing each event exactly once.

dont_block boolean optional

Example: true

Set to true if the client is requesting a nonblocking reply. If not specified, the request will block until either a new event is available or a few minutes have passed, in which case the server will send the client a heartbeat event.

Defaults to false.

Note: The parameters documented above are optional in the sense that even if you haven't registered a queue by explicitly requesting the POST /register endpoint, you could pass the parameters for the POST /register endpoint to this endpoint and a queue would be registered in the absence of a queue_id.

Response

Return values

events: array

An array of event objects (possibly zero-length if dont_block is set) with IDs newer than last_event_id. Event IDs are guaranteed to be increasing, but they are not guaranteed to be consecutive.
queue_id: string

The ID of the registered queue.

Events by `type`

alert_words

attachment:

op: add

op: remove

op: update

custom_profile_fields

default_stream_groups

default_streams

delete_message

drafts:

op: add

op: remove

op: update

has_zoom_token

heartbeat

invites_changed

message

muted_topics

muted_users

onboarding_steps

presence

reaction:

op: add

op: remove

realm:

op: deactivated

op: update

op: update_dict

realm_bot:

op: add

op: delete

op: remove

op: update

realm_domains:

op: add

op: change

op: remove

realm_emoji:

op: update

realm_export

realm_filters

realm_linkifiers

realm_playgrounds

realm_user:

op: add

op: remove

op: update

realm_user_settings_defaults:

op: update

restart

scheduled_messages:

op: add

op: remove

op: update

stream:

op: create

op: delete

op: update

submessage

subscription:

op: add

op: peer_add

op: peer_remove

op: remove

op: update

typing:

op: start

op: stop

update_display_settings

update_global_notifications

update_message

update_message_flags:

op: add

op: remove

user_group:

op: add

op: add_members

op: add_subgroups

op: remove

op: remove_members

op: remove_subgroups

op: update

user_settings:

op: update

user_status

user_topic

web_reload_client

alert_words

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

update_display_settings

Event sent to clients that have requested the update_display_settings event type and did not include user_settings_object in their client_capabilities when registering the event queue.

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

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
user: string

The Zulip API email of the user.
setting_name: string

Name of the changed display setting.
setting: boolean | integer | string

New value of the changed setting.
language_name: string

Present only if the setting to be changed is default_language. Contains the name of the new default language in English.

Example

{
    "id": 0,
    "setting": false,
    "setting_name": "high_contrast_mode",
    "type": "update_display_settings",
    "user": "iago@zulip.com"
}

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.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
user: string

The Zulip API email of the user.
notification_name: string

Name of the changed notification setting.
setting: boolean | integer | string

New value of the changed setting.

Example

{
    "id": 0,
    "notification_name": "enable_sounds",
    "setting": true,
    "type": "update_global_notifications",
    "user": "iago@zulip.com"
}

user_settings op: update

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
}

realm_user op: update

Event sent generally to all users who can access the modified user for changes in the set of users or those users metadata.

Changes: Prior to Zulip 8.0 (feature level 228), this event was sent to all users in the organization.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
person: object | object | object | object | object | object | object | object | object | object

Object containing the changed details of the user. It has multiple forms depending on the value changed.
- When a user changes their full name.
  - user_id: integer
    
    The ID of modified user.
  - full_name: string
    
    The new full name for the user.
- 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.
  - user_id: integer
    
    The ID of modified user.
  - email: string
    
    The Zulip API email of the user.
    
    Deprecated: This field will be removed in a future release as it is redundant with the user_id.
  - timezone: string
    
    The new time zone of the user.
- When the owner of a bot changes.
  - user_id: integer
    
    The ID of the user/bot whose owner has changed.
  - bot_owner_id: integer
    
    The user ID of the new bot owner.
- When the role of a user changes.
  - user_id: integer
    
    The ID of the user affected by this change.
  - role: integer
    
    The new role of the user.
- 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 value of a user's delivery email as visible to you changes, either due to the email address changing or your access to the user's email changing via an update to their email_address_visibility setting.
  
  Changes: Prior to Zulip 7.0 (feature level 163), this event was sent only to the affected user, and this event would only be triggered by changing the affected user's delivery email.
  - user_id: integer
    
    The ID of the user affected by this change.
  - delivery_email: string | null
    
    The new delivery email of the user.
    
    This value can be null if the affected user changed their email_address_visibility setting such that you cannot access their real email.
    
    Changes: Before Zulip 7.0 (feature level 163), null was not a possible value for this event as it was only sent to the affected user when their email address was changed.
- When the user updates one of their custom profile fields.
  - user_id: integer
    
    The ID of the user affected by this change.
  - custom_profile_field: object
    
    Object containing details about the custom profile data change.
    - id: integer
      
      The ID of the custom profile field which user updated.
    - value: string | null
      
      User's personal value for this custom profile field, or null if unset.
    - rendered_value: string
      
      The value rendered in HTML. Will only be present for custom profile field types that support Markdown rendering.
      
      This user-generated HTML content should be rendered using the same CSS and client-side security protections as are used for message content.
- When the Zulip API email address of a user changes, either due to the user's email address changing, or due to changes in the user's email address visibility.
  - user_id: integer
    
    The ID of the user affected by this change.
  - new_email: string
    
    The new value of email for the user. The client should update any data structures associated with this user to use this new value as the user's Zulip API email address.
- When a user is deactivated or reactivated.
  
  Changes: New in Zulip 8.0 (feature level 222). Previously the server sent a realm_user event with op field set to remove when deactivating a user and a realm_user event with op field set to add when reactivating a user.
  - user_id: integer
    
    The ID of the user affected by this change.
  - is_active: boolean
    
    A boolean describing whether the user account has been deactivated.

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

subscription op: add

Event sent to a user's clients when that user's channel subscriptions have changed (either the set of subscriptions or their properties).

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
subscriptions: (object)[]

A list of dictionaries where each dictionary contains information about one of the subscribed channels.

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

Removed role field from the dictionary in Zulip 6.0 (feature level 133).
- stream_id: integer
  
  The unique ID of a channel.
- name: string
  
  The name of a channel.
- description: string
  
  The description of the channel in text/markdown format, intended to be used to prepopulate UI for editing a channel's description.
  
  See also rendered_description.
- rendered_description: string
  
  The description of the channel rendered as HTML, intended to be used when displaying the channel description in a UI.
  
  One should use the standard Zulip rendered_markdown CSS when displaying this content so that emoji, LaTeX, and other syntax work correctly. And any client-side security logic for user-generated message content should be applied when displaying this HTML as though it were the body of a Zulip message.
  
  See also description.
- date_created: integer
  
  The UNIX timestamp for when the channel was created, in UTC seconds.
  
  Changes: New in Zulip 4.0 (feature level 30).
- creator_id: integer | null
  
  The ID of the user who created this channel.
  
  A null value means the channel has no recorded creator, which is often because the channel is very old, or because it was created via a data import tool or management command.
  
  Changes: New in Zulip 9.0 (feature level 254).
- invite_only: boolean
  
  Specifies whether the channel is private or not. Only people who have been invited can access a private channel.
- subscribers: (integer)[]
  
  A list of user IDs of users who are also subscribed to a given channel. Included only if include_subscribers is true.
- desktop_notifications: boolean | null
  
  A boolean specifying whether desktop notifications are enabled for the given channel.
  
  A null value means the value of this setting should be inherited from the user-level default setting, enable_stream_desktop_notifications, for this channel.
- email_notifications: boolean | null
  
  A boolean specifying whether email notifications are enabled for the given channel.
  
  A null value means the value of this setting should be inherited from the user-level default setting, enable_stream_email_notifications, for this channel.
- wildcard_mentions_notify: boolean | null
  
  A boolean specifying whether wildcard mentions trigger notifications as though they were personal mentions in this channel.
  
  A null value means the value of this setting should be inherited from the user-level default setting, wildcard_mentions_notify, for this channel.
- push_notifications: boolean | null
  
  A boolean specifying whether push notifications are enabled for the given channel.
  
  A null value means the value of this setting should be inherited from the user-level default setting, enable_stream_push_notifications, for this channel.
- audible_notifications: boolean | null
  
  A boolean specifying whether audible notifications are enabled for the given channel.
  
  A null value means the value of this setting should be inherited from the user-level default setting, enable_stream_audible_notifications, for this channel.
- pin_to_top: boolean
  
  A boolean specifying whether the given channel has been pinned to the top.
- is_muted: boolean
  
  Whether the user has muted the channel. Muted channels do not count towards your total unread count and do not show up in the Combined feed view (previously known as All messages).
  
  Changes: Prior to Zulip 2.1.0, this feature was represented by the more confusingly named in_home_view (with the opposite value, in_home_view=!is_muted).
- in_home_view: boolean
  
  Legacy property for if the given channel is muted, with inverted meaning.
  
  Changes: Deprecated in Zulip 2.1.0. Clients should use is_muted where available.
- is_announcement_only: boolean
  
  Whether only organization administrators can post to the channel.
  
  Changes: Deprecated in Zulip 3.0 (feature level 1). Clients should use stream_post_policy instead.
- is_web_public: boolean
  
  Whether the channel has been configured to allow unauthenticated access to its message history from the web.
- color: string
  
  The user's personal color for the channel.
- stream_post_policy: integer
  
  Policy for which users can post messages to the channel.
  - 1 = Any user can post.
  - 2 = Only administrators can post.
  - 3 = Only full members can post.
  - 4 = Only moderators can post.
  Changes: New in Zulip 3.0 (feature level 1), replacing the previous is_announcement_only boolean.
- message_retention_days: integer | null
  
  Number of days that messages sent to this channel will be stored before being automatically deleted by the message retention policy. There are two special values:
  - null, the default, means the channel will inherit the organization level setting.
  - -1 encodes retaining messages in this channel forever.
  Changes: New in Zulip 3.0 (feature level 17).
- history_public_to_subscribers: boolean
  
  Whether the history of the channel is public to its subscribers.
  
  Currently always true for public channels (i.e. "invite_only": false implies "history_public_to_subscribers": true), but clients should not make that assumption, as we may change that behavior in the future.
- first_message_id: integer | null
  
  The ID of the first message in the channel.
  
  Intended to help clients determine whether they need to display UI like the "show all topics" widget that would suggest the channel has older history that can be accessed.
  
  Is null for channels with no message history.
- stream_weekly_traffic: integer | null
  
  The average number of messages sent to the channel per week, as estimated based on recent weeks, rounded to the nearest integer.
  
  If null, the channel was recently created and there is insufficient data to estimate the average traffic.
- can_remove_subscribers_group: integer
  
  ID of the user group whose members are allowed to unsubscribe others from the channel.
  
  Changes: Before Zulip 8.0 (feature level 197), the can_remove_subscribers_group setting was named can_remove_subscribers_group_id.
  
  New in Zulip 6.0 (feature level 142).

Example

{
    "id": 0,
    "op": "add",
    "subscriptions": [
        {
            "audible_notifications": null,
            "can_remove_subscribers_group": 2,
            "color": "#76ce90",
            "creator_id": null,
            "description": "",
            "desktop_notifications": null,
            "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",
            "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"
}

subscription op: remove

Event sent to a user's clients when that user has been unsubscribed from one or more channels.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
subscriptions: (object)[]

A list of dictionaries, where each dictionary contains information about one of the newly unsubscribed channels.
- stream_id: integer
  
  The ID of the channel.
- name: string
  
  The name of the channel.

Example

{
    "id": 0,
    "op": "remove",
    "subscriptions": [
        {
            "name": "test",
            "stream_id": 9
        }
    ],
    "type": "subscription"
}

subscription op: update

Event sent to a user's clients when a property of the user's subscription to a channel has been updated. This event is used only for personal properties like is_muted or pin_to_top. See the stream op: update event for updates to global properties of a channel.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
stream_id: integer

The ID of the channel whose subscription details have changed.
property: string

The property of the subscription which has changed. For details on the various subscription properties that a user can change, see POST /users/me/subscriptions/properties.

Clients should generally handle an unknown property received here without crashing, since that will naturally happen when connecting to a Zulip server running a new version that adds a new subscription property.

Changes: As of Zulip 6.0 (feature level 139), updates to the is_muted property or the deprecated in_home_view property will send two subscription update events, one for each property, to support clients fully migrating to use the is_muted property. Prior to this feature level, updates to either property only sent one event with the deprecated in_home_view property.
value: integer | boolean | string

The new value of the changed property.

Example

{
    "id": 0,
    "op": "update",
    "property": "pin_to_top",
    "stream_id": 11,
    "type": "subscription",
    "value": true
}

subscription op: peer_add

Event sent when another user subscribes to a channel, or their subscription is newly visible to the current user.

When a user subscribes to a channel, the current user will receive this event only if they have permission to see the channel's subscriber list. When the current user gains permission to see a given channel's subscriber list, they will receive this event for the existing subscriptions to the channel.

Changes: Prior to Zulip 8.0 (feature level 220), this event was incorrectly not sent to guest users when subscribers to web-public channels and subscribed public channels changed.

Prior to Zulip 8.0 (feature level 205), this event was not sent when a user gained access to a channel due to their role changing.

Prior to Zulip 6.0 (feature level 134), this event was not sent when a private channel was made public.

In Zulip 4.0 (feature level 35), the singular user_id and stream_id integers included in this event were replaced with plural user_ids and stream_ids integer arrays.

In Zulip 3.0 (feature level 19), the stream_id field was added to identify the channel the user subscribed to, replacing the name field.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
stream_ids: (integer)[]

The IDs of channels that have new or updated subscriber data.

Changes: New in Zulip 4.0 (feature level 35), replacing the stream_id integer.
user_ids: (integer)[]

The IDs of the users who are newly visible as subscribed to the specified channels.

Changes: New in Zulip 4.0 (feature level 35), replacing the user_id integer.

Example

{
    "id": 0,
    "op": "peer_add",
    "stream_ids": [
        9
    ],
    "type": "subscription",
    "user_ids": [
        12
    ]
}

subscription op: peer_remove

Event sent to other users when users have been unsubscribed from channels. Sent to all users if the channel is public or to only the existing subscribers if the channel is private.

Changes: Prior to Zulip 8.0 (feature level 220), this event was incorrectly not sent to guest users when subscribers to web-public channels and subscribed public channels changed.

In Zulip 4.0 (feature level 35), the singular user_id and stream_id integers included in this event were replaced with plural user_ids and stream_ids integer arrays.

In Zulip 3.0 (feature level 19), the stream_id field was added to identify the channel the user unsubscribed from, replacing the name field.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
stream_ids: (integer)[]

The IDs of the channels from which the users have been unsubscribed from.

Changes: New in Zulip 4.0 (feature level 35), replacing the stream_id integer.
user_ids: (integer)[]

The IDs of the users who have been unsubscribed.

Changes: New in Zulip 4.0 (feature level 35), replacing the user_id integer.

Example

{
    "id": 0,
    "op": "peer_remove",
    "stream_ids": [
        9
    ],
    "type": "subscription",
    "user_ids": [
        12
    ]
}

message

Event type for messages.

Changes: In Zulip 3.1 (feature level 26), the sender_short_name field was removed from message objects.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
message: object

Object containing details of the message.
- avatar_url: string | null
  
  The URL of the message sender's avatar. Can be null only if the current user has access to the sender's real email address and client_gravatar was true.
  
  If null, then the sender has not uploaded an avatar in Zulip, and the client can compute the gravatar URL by hashing the sender's email address, which corresponds in this case to their real email address.
  
  Changes: Before Zulip 7.0 (feature level 163), access to a user's real email address was a realm-level setting. As of this feature level, email_address_visibility is a user setting.
- client: string
  
  A Zulip "client" string, describing what Zulip client sent the message.
- content: string
  
  The content/body of the message.
- content_type: string
  
  The HTTP content_type for the message content. This will be text/html or text/x-markdown, depending on whether apply_markdown was set.
- display_recipient: string | (object)[]
  
  Data on the recipient of the message; either the name of a channel or a dictionary containing basic data on the users who received the message.
- edit_history: (object)[]
  
  An array of objects, with each object documenting the changes in a previous edit made to the message, ordered chronologically from most recent to least recent edit.
  
  Not present if the message has never been edited or 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 channel, topic, and/or message content were modified in the edit event. For example, if only the topic was edited, only prev_topic and topic will be present in addition to user_id and timestamp.
  - 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 channel was edited.
    
    The channel ID of the message immediately prior to this edit event.
    
    Changes: New in Zulip 3.0 (feature level 1).
  - prev_topic: string
    
    Only present if message's topic was edited.
    
    The topic of the message immediately prior to this edit event.
    
    Changes: New in Zulip 5.0 (feature level 118). Previously, this field was called prev_subject; clients are recommended to rename prev_subject to prev_topic if present for compatibility with older Zulip servers.
  - stream: integer
    
    Only present if message's channel was edited.
    
    The ID of the channel containing the message immediately after this edit event.
    
    Changes: New in Zulip 5.0 (feature level 118).
  - timestamp: integer
    
    The UNIX timestamp for the edit.
  - topic: string
    
    Only present if message's topic was edited.
    
    The topic of the message immediately after this edit event.
    
    Changes: New in Zulip 5.0 (feature level 118).
  - user_id: integer | null
    
    The ID of the user that made the edit.
    
    Will be null only for edit history events predating March 2017.
    
    Clients can display edit history events where this is null as modified by either the sender (for content edits) or an unknown user (for topic edits).
- id: integer
  
  The unique message ID. Messages should always be displayed sorted by ID.
- is_me_message: boolean
  
  Whether the message is a /me status message
- last_edit_timestamp: integer
  
  The UNIX timestamp for when the message 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.
    - id: integer
      
      ID of the user.
    - email: string
      
      Zulip API email of the user.
    - full_name: string
      
      Full name of the user.
    - is_mirror_dummy: boolean
      
      Whether the user is a mirror dummy.
- recipient_id: integer
  
  A unique ID for the set of users receiving the message (either a channel or group of users). Useful primarily for hashing.
- sender_email: string
  
  The Zulip API email address of the message's sender.
- sender_full_name: string
  
  The full name of the message's sender.
- sender_id: integer
  
  The user ID of the message's sender.
- sender_realm_str: string
  
  A string identifier for the realm the sender is in. Unique only within the context of a given Zulip server.
  
  E.g. on example.zulip.com, this will be example.
- stream_id: integer
  
  Only present for channel messages; the ID of the channel.
- subject: string
  
  The topic of the message. Currently always "" for direct messages, though this could change if Zulip adds support for topics in direct message conversations.
  
  The field name is a legacy holdover from when topics were called "subjects" and will eventually change.
- submessages: (object)[]
  
  Data used for certain experimental Zulip integrations.
  - msg_type: string
    
    The type of the message.
  - content: string
    
    The new content of the submessage.
  - message_id: integer
    
    The ID of the message to which the submessage has been added.
  - sender_id: integer
    
    The ID of the user who sent the message.
  - id: integer
    
    The ID of the submessage.
- timestamp: integer
  
  The UNIX timestamp for when the message was sent, in UTC seconds.
- topic_links: (object)[]
  
  Data on any links to be included in the topic line (these are generated by custom linkification filters that match content in the message's topic.)
  
  Changes: This field contained a list of urls before Zulip 4.0 (feature level 46).
  
  New in Zulip 3.0 (feature level 1). Previously, this field was called subject_links; clients are recommended to rename subject_links to topic_links if present for compatibility with older Zulip servers.
  - text: string
    
    The original link text present in the topic.
  - url: string
    
    The expanded target url which the link points to.
- type: string
  
  The type of the message: "stream" or "private".
flags: (string)[]

The user's message flags for the message.

Clients should inspect the flags field rather than assuming that new messages are unread; muted users, messages sent by the current user, and more subtle scenarios can result in a new message that the server has already marked as read for the user.

Changes: In Zulip 8.0 (feature level 224), the wildcard_mentioned flag was deprecated in favor of the stream_wildcard_mentioned and topic_wildcard_mentioned flags. The wildcard_mentioned flag exists for backwards compatibility with older clients and equals stream_wildcard_mentioned || topic_wildcard_mentioned. Clients supporting older server versions should treat this field as a previous name for the stream_wildcard_mentioned flag as topic wildcard mentions were not available prior to this feature level.

Example

{
    "flags": [],
    "id": 1,
    "message": {
        "avatar_url": null,
        "client": "test suite",
        "content": "<p>First message ...<a href=\"user_uploads/2/ce/2Xpnnwgh8JWKxBXtTfD6BHKV/zulip.txt\">zulip.txt</a></p>",
        "content_type": "text/html",
        "display_recipient": "Denmark",
        "id": 31,
        "is_me_message": false,
        "reactions": [],
        "recipient_id": 23,
        "sender_email": "user10@zulip.testserver",
        "sender_full_name": "King Hamlet",
        "sender_id": 10,
        "sender_realm_str": "zulip",
        "stream_id": 1,
        "subject": "test",
        "submessages": [],
        "timestamp": 1594825416,
        "topic_links": [],
        "type": "stream"
    },
    "type": "message"
}

has_zoom_token

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
}

invites_changed

A simple event sent when the set of invitations changes. This event is sent to organization administrators and the creator of the changed invitation; this tells clients they need to refetch data from GET /invites if they are displaying UI containing active invitations.

Changes: Before Zulip 8.0 (feature level 209), this event was only sent to organization administrators.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.

Example

{
    "id": 0,
    "type": "invites_changed"
}

realm_user op: add

Event sent to all users in a Zulip organization when a new user joins or when a guest user gains access to a user. Processing this event is important to being able to display basic details on other users given only their ID.

If the current user is a guest whose access to a newly created user is limited by a can_access_all_users_group policy, and the event queue was registered with the user_list_incomplete client capability, then the event queue will not receive an event for such a new user. If a newly created user is inaccessible to the current user via such a policy, but the client lacks user_list_incomplete client capability, then this event will be delivered to the queue, with an "Unknown user" object with the usual format but placeholder data whose only variable content is the user ID.

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

Starting with Zulip 8.0 (feature level 228), this event is also sent when a guest user gains access to a user.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
person: object

A dictionary containing basic data on a given Zulip user.
- user_id: integer
  
  The unique ID of the user.
- delivery_email: string | null
  
  The user's real email address. This value will be null if you cannot access user's real email address. For bot users, this field is always set to the real email of the bot, because bot users always have email_address_visibility set to everyone.
  
  Changes: Prior to Zulip 7.0 (feature level 163), this field was present only when email_address_visibility was restricted and you had access to the user's real email. As of this feature level, this field is always present, including the case when email_address_visibility is set to everyone (and therefore not restricted).
- email: string
  
  The Zulip API email address of the user or bot.
  
  If you do not have permission to view the email address of the target user, this will be a fake email address that is usable for the Zulip API but nothing else.
- full_name: string
  
  Full name of the user or bot, used for all display purposes.
- date_joined: string
  
  The time the user account was created.
- is_active: boolean
  
  A boolean specifying whether the user account has been deactivated.
- is_owner: boolean
  
  A boolean specifying whether the user is an organization owner. If true, is_admin will also be true.
  
  Changes: New in Zulip 3.0 (feature level 8).
- is_admin: boolean
  
  A boolean specifying whether the user is an organization administrator.
- is_guest: boolean
  
  A boolean specifying whether the user is a guest user.
- is_billing_admin: boolean
  
  A boolean specifying whether the user is a billing administrator.
  
  Changes: New in Zulip 5.0 (feature level 73).
- is_bot: boolean
  
  A boolean specifying whether the user is a bot or full account.
- bot_type: integer | null
  
  An integer describing the type of bot:
  - null if the user isn't a bot.
  - 1 for a Generic bot.
  - 2 for an Incoming webhook bot.
  - 3 for an Outgoing webhook bot.
  - 4 for an Embedded bot.
- bot_owner_id: integer | null
  
  If the user is a bot (i.e. is_bot is true), then bot_owner_id is the user ID of the bot's owner (usually, whoever created the bot).
  
  Will be null for legacy bots that do not have an owner.
  
  Changes: New in Zulip 3.0 (feature level 1). In previous versions, there was a bot_owner field containing the email address of the bot's owner.
- role: integer
  
  Organization-level role of the user. Possible values are:
  - 100 = Organization owner
  - 200 = Organization administrator
  - 300 = Organization moderator
  - 400 = Member
  - 600 = Guest
  Changes: New in Zulip 4.0 (feature level 59).
- timezone: string
  
  The time zone of the user.
- avatar_url: string | null
  
  URL for the user's avatar.
  
  Will be null if the client_gravatar query parameter was set to true, the current user has access to this user's real email address, and this user's avatar is hosted by the Gravatar provider (i.e. this user has never uploaded an avatar).
  
  Changes: Before Zulip 7.0 (feature level 163), access to a user's real email address was a realm-level setting. As of this feature level, email_address_visibility is a user setting.
  
  In Zulip 3.0 (feature level 18), if the client has the user_avatar_url_field_optional capability, this will be missing at the server's sole discretion.
- avatar_version: integer
  
  Version for the user's avatar. Used for cache-busting requests for the user's avatar. Clients generally shouldn't need to use this; most avatar URLs sent by Zulip will already end with ?v={avatar_version}.
- profile_data: object
  
  Only present if is_bot is false; bots can't have custom profile fields.
  
  A dictionary containing custom profile field data for the user. Each entry maps the integer ID of a custom profile field in the organization to a dictionary containing the user's data for that field. Generally the data includes just a single value key; for those custom profile fields supporting Markdown, a rendered_value key will also be present.
  - {id}: object
    
    Object with data about what value the user filled in the custom profile field with that ID.
    - value: string
      
      User's personal value for this custom profile field.
    - rendered_value: string
      
      The value rendered in HTML. Will only be present for custom profile field types that support Markdown rendering.
      
      This user-generated HTML content should be rendered using the same CSS and client-side security protections as are used for message content.

Example

{
    "id": 0,
    "op": "add",
    "person": {
        "avatar_url": "https://secure.gravatar.com/avatar/c6b5578d4964bd9c5fae593c6868912a?d=identicon&version=1",
        "avatar_version": 1,
        "date_joined": "2020-07-15T15:04:02.030833+00:00",
        "delivery_email": null,
        "email": "foo@zulip.com",
        "full_name": "full name",
        "is_active": true,
        "is_admin": false,
        "is_billing_admin": false,
        "is_bot": false,
        "is_guest": false,
        "is_owner": false,
        "profile_data": {},
        "role": 400,
        "timezone": "",
        "user_id": 38
    },
    "type": "realm_user"
}

realm_user op: remove

Event sent to guest users when they lose access to a user.

Changes: As of Zulip 8.0 (feature level 228), this event is no longer deprecated.

In Zulip 8.0 (feature level 222), this event was deprecated and no longer sent to clients. Prior to this feature level, it was sent to all users in a Zulip organization when a user was deactivated.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
person: object

Object containing details of the deactivated user.
- user_id: integer
  
  The ID of the deactivated user.
- full_name: string
  
  The full name of the user.
  
  Deprecated: We expect to remove this field in the future.

Example

{
    "id": 0,
    "op": "remove",
    "person": {
        "full_name": "Foo Bot",
        "user_id": 35
    },
    "type": "realm_user"
}

presence

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

If the CAN_ACCESS_ALL_USERS_GROUP_LIMITS_PRESENCE server-level setting is set to true, then the event is only sent to users who can access the user who came back online.

Changes: Prior to Zulip 8.0 (feature level 228), this event was sent to all users in the organization.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
user_id: integer

The ID of the modified user.
email: string

The Zulip API email of the user.

Deprecated: This field will be removed in a future release as it is redundant with the user_id.
server_timestamp: number

The timestamp of when the Zulip server received the user's presence as a UNIX timestamp.
presence: object

Object containing the details of the user's most recent presence.
- {client_name}: object
  
  Object containing the details of the user's presence.
  
  Changes: Starting with Zulip 7.0 (feature level 178), this will always be "website" as the server no longer stores which client submitted presence updates.
  
  Previously, the object key was the client's platform name, for example website or ZulipDesktop.
  - client: string
    
    The client's platform name.
    
    Changes: Starting with Zulip 7.0 (feature level 178), this will always be "website" as the server no longer stores which client submitted presence updates.
  - status: string
    
    The status of the user on this client. Will be either idle or active.
  - timestamp: integer
    
    The UNIX timestamp of when this client sent the user's presence to the server with the precision of a second.
  - pushable: boolean
    
    Whether the client is capable of showing mobile/push notifications to the user.
    
    Changes: Starting with Zulip 7.0 (feature level 178), this will always be false as the server no longer stores which client submitted presence updates.

Example

{
    "email": "user10@zulip.testserver",
    "id": 0,
    "presence": {
        "website": {
            "client": "website",
            "pushable": false,
            "status": "idle",
            "timestamp": 1594825445
        }
    },
    "server_timestamp": 1594825445.3200784,
    "type": "presence",
    "user_id": 10
}

stream op: create

Event sent when a new channel is created to users who can see the new channel exists (for private channels, only subscribers and organization administrators will receive this event).

This event is also sent when a user gains access to a channel they previously could not access, such as when their role changes, a private channel is made public, or a guest user is subscribed to a public (or private) channel.

Note that organization administrators who are not subscribed will not be able to see content on the channel; just that it exists.

Changes: Prior to Zulip 8.0 (feature level 220), this event was incorrectly not sent to guest users a web-public channel was created.

Prior to Zulip 8.0 (feature level 205), this event was not sent when a user gained access to a channel due to their role changing.

Prior to Zulip 8.0 (feature level 192), this event was not sent when guest users gained access to a public channel by being subscribed.

Prior to Zulip 6.0 (feature level 134), this event was not sent when a private channel was made public.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
streams: (object)[]

Array of objects, each containing details about the newly added channel(s).
- stream_id: integer
  
  The unique ID of the channel.
- name: string
  
  The name of the channel.
- description: string
  
  The short description of the channel in text/markdown format, intended to be used to prepopulate UI for editing a channel's description.
- date_created: integer
  
  The UNIX timestamp for when the channel was created, in UTC seconds.
  
  Changes: New in Zulip 4.0 (feature level 30).
- creator_id: integer | null
  
  The ID of the user who created this channel.
  
  A null value means the channel has no recorded creator, which is often because the channel is very old, or because it was created via a data import tool or management command.
  
  Changes: New in Zulip 9.0 (feature level 254).
- invite_only: boolean
  
  Specifies whether the channel is private or not. Only people who have been invited can access a private channel.
- rendered_description: string
  
  The short description of the channel rendered as HTML, intended to be used when displaying the channel description in a UI.
  
  One should use the standard Zulip rendered_markdown CSS when displaying this content so that emoji, LaTeX, and other syntax work correctly. And any client-side security logic for user-generated message content should be applied when displaying this HTML as though it were the body of a Zulip message.
- is_web_public: boolean
  
  Whether the channel has been configured to allow unauthenticated access to its message history from the web.
  
  Changes: New in Zulip 2.1.0.
- stream_post_policy: integer
  
  Policy for which users can post messages to the channel.
  - 1 = Any user can post.
  - 2 = Only administrators can post.
  - 3 = Only full members can post.
  - 4 = Only moderators can post.
  Changes: New in Zulip 3.0 (feature level 1), replacing the previous is_announcement_only boolean.
- message_retention_days: integer | null
  
  Number of days that messages sent to this channel will be stored before being automatically deleted by the message retention policy. There are two special values:
  - null, the default, means the channel will inherit the organization level setting.
  - -1 encodes retaining messages in this channel forever.
  Changes: New in Zulip 3.0 (feature level 17).
- history_public_to_subscribers: boolean
  
  Whether the history of the channel is public to its subscribers.
  
  Currently always true for public channels (i.e. "invite_only": false implies "history_public_to_subscribers": true), but clients should not make that assumption, as we may change that behavior in the future.
- first_message_id: integer | null
  
  The ID of the first message in the channel.
  
  Intended to help clients determine whether they need to display UI like the "show all topics" widget that would suggest the channel has older history that can be accessed.
  
  Is null for channels with no message history.
  
  Changes: New in Zulip 2.1.0.
- is_announcement_only: boolean
  
  Whether the given channel is announcement only or not.
  
  Changes: Deprecated in Zulip 3.0 (feature level 1). Clients should use stream_post_policy instead.
- can_remove_subscribers_group: integer
  
  ID of the user group whose members are allowed to unsubscribe others from the channel.
  
  Changes: Before Zulip 8.0 (feature level 197), the can_remove_subscribers_group setting was named can_remove_subscribers_group_id.
  
  New in Zulip 6.0 (feature level 142).
- stream_weekly_traffic: integer | null
  
  The average number of messages sent to the channel per week, as estimated based on recent weeks, rounded to the nearest integer.
  
  If null, no information is provided on the average traffic. This can be because the channel was recently created and there is insufficient data to make an estimate, or because the server wishes to omit this information for this client, this realm, or this endpoint or type of event.
  
  Changes: New in Zulip 8.0 (feature level 199). Previously, this statistic was available only in subscription objects.

Example

{
    "id": 0,
    "op": "create",
    "streams": [
        {
            "can_remove_subscribers_group": 2,
            "creator_id": 11,
            "date_created": 1691057093,
            "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,
            "stream_weekly_traffic": null
        }
    ],
    "type": "stream"
}

stream op: delete

Event sent to all users who can see a channel when it is deactivated.

This event is also sent when a user loses access to a channel they previously could access because they are unsubscribed from a private channel or their role has changed.

Changes: Prior to Zulip 8.0 (feature level 205), this event was not sent when a user lost access to a channel due to their role changing.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
streams: (object)[]

Array of objects, each containing details about a channel that was deleted.
- stream_id: integer
  
  The unique ID of the channel.
- name: string
  
  The name of the channel.
- description: string
  
  The short description of the channel in text/markdown format, intended to be used to prepopulate UI for editing a channel's description.
- date_created: integer
  
  The UNIX timestamp for when the channel was created, in UTC seconds.
  
  Changes: New in Zulip 4.0 (feature level 30).
- creator_id: integer | null
  
  The ID of the user who created this channel.
  
  A null value means the channel has no recorded creator, which is often because the channel is very old, or because it was created via a data import tool or management command.
  
  Changes: New in Zulip 9.0 (feature level 254).
- invite_only: boolean
  
  Specifies whether the channel is private or not. Only people who have been invited can access a private channel.
- rendered_description: string
  
  The short description of the channel rendered as HTML, intended to be used when displaying the channel description in a UI.
  
  One should use the standard Zulip rendered_markdown CSS when displaying this content so that emoji, LaTeX, and other syntax work correctly. And any client-side security logic for user-generated message content should be applied when displaying this HTML as though it were the body of a Zulip message.
- is_web_public: boolean
  
  Whether the channel has been configured to allow unauthenticated access to its message history from the web.
  
  Changes: New in Zulip 2.1.0.
- stream_post_policy: integer
  
  Policy for which users can post messages to the channel.
  - 1 = Any user can post.
  - 2 = Only administrators can post.
  - 3 = Only full members can post.
  - 4 = Only moderators can post.
  Changes: New in Zulip 3.0 (feature level 1), replacing the previous is_announcement_only boolean.
- message_retention_days: integer | null
  
  Number of days that messages sent to this channel will be stored before being automatically deleted by the message retention policy. There are two special values:
  - null, the default, means the channel will inherit the organization level setting.
  - -1 encodes retaining messages in this channel forever.
  Changes: New in Zulip 3.0 (feature level 17).
- history_public_to_subscribers: boolean
  
  Whether the history of the channel is public to its subscribers.
  
  Currently always true for public channels (i.e. "invite_only": false implies "history_public_to_subscribers": true), but clients should not make that assumption, as we may change that behavior in the future.
- first_message_id: integer | null
  
  The ID of the first message in the channel.
  
  Intended to help clients determine whether they need to display UI like the "show all topics" widget that would suggest the channel has older history that can be accessed.
  
  Is null for channels with no message history.
  
  Changes: New in Zulip 2.1.0.
- is_announcement_only: boolean
  
  Whether the given channel is announcement only or not.
  
  Changes: Deprecated in Zulip 3.0 (feature level 1). Clients should use stream_post_policy instead.
- can_remove_subscribers_group: integer
  
  ID of the user group whose members are allowed to unsubscribe others from the channel.
  
  Changes: Before Zulip 8.0 (feature level 197), the can_remove_subscribers_group setting was named can_remove_subscribers_group_id.
  
  New in Zulip 6.0 (feature level 142).
- stream_weekly_traffic: integer | null
  
  The average number of messages sent to the channel per week, as estimated based on recent weeks, rounded to the nearest integer.
  
  If null, no information is provided on the average traffic. This can be because the channel was recently created and there is insufficient data to make an estimate, or because the server wishes to omit this information for this client, this realm, or this endpoint or type of event.
  
  Changes: New in Zulip 8.0 (feature level 199). Previously, this statistic was available only in subscription objects.

Example

{
    "id": 0,
    "op": "delete",
    "streams": [
        {
            "can_remove_subscribers_group": 2,
            "creator_id": 11,
            "date_created": 1691057093,
            "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,
            "stream_weekly_traffic": null
        }
    ],
    "type": "stream"
}

stream op: update

Event sent to all users who can see that a channel exists when a property of that channel changes. See GET /streams response for details on the various properties of a channel.

Changes: Before Zulip 9.0 (feature level 256), this event was never sent when the first_message_id property of a channel was updated because the oldest message that had been sent to it changed.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
stream_id: integer

The ID of the channel whose details have changed.
name: string

The name of the channel whose details have changed.
property: string

The property of the channel which has changed. See GET /streams response for details on the various properties of a channel.

Clients should handle an "unknown" property received here without crashing, since that can happen when connecting to a server running a newer version of Zulip with new features.
value: 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 channel rendered as HTML, intended to be used when displaying the channel description in a UI.

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

Note: Only present if the changed property was invite_only.

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

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

Note: Only present if the changed property was invite_only.

Whether the channel's history is now readable by web-public spectators.

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

Example

{
    "history_public_to_subscribers": true,
    "id": 0,
    "is_web_public": false,
    "name": "test",
    "op": "update",
    "property": "invite_only",
    "stream_id": 11,
    "type": "stream",
    "value": true
}

reaction op: add

Event sent when a reaction is added to a message. Sent to all users who were recipients of the message.

emoji_name: string

Name of the emoji.
emoji_code: string

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

A string indicating the type of emoji. Each emoji reaction_type has an independent namespace for values of emoji_code.

Must be one of the following values:
- unicode_emoji : In this namespace, emoji_code will be a dash-separated hex encoding of the sequence of Unicode codepoints that define this emoji in the Unicode specification.
- realm_emoji : In this namespace, emoji_code will be the ID of the uploaded custom emoji.
- zulip_extra_emoji : These are special emoji included with Zulip. In this namespace, emoji_code will be the name of the emoji (e.g. "zulip").
user_id: integer

The ID of the user who added the reaction.

Changes: New in Zulip 3.0 (feature level 2). The user object is deprecated and will be removed in the future.
user: object

Dictionary with data on the user who added the reaction, including the user ID as the user_id field.

Changes: 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.
- user_id: integer
  
  ID of the user.
- email: string
  
  Zulip API email of the user.
- full_name: string
  
  Full name of the user.
- is_mirror_dummy: boolean
  
  Whether the user is a mirror dummy.
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
}

reaction op: remove

Event sent when a reaction is removed from a message. Sent to all users who were recipients of the message.

emoji_name: string

Name of the emoji.
emoji_code: string

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

A string indicating the type of emoji. Each emoji reaction_type has an independent namespace for values of emoji_code.

Must be one of the following values:
- unicode_emoji : In this namespace, emoji_code will be a dash-separated hex encoding of the sequence of Unicode codepoints that define this emoji in the Unicode specification.
- realm_emoji : In this namespace, emoji_code will be the ID of the uploaded custom emoji.
- zulip_extra_emoji : These are special emoji included with Zulip. In this namespace, emoji_code will be the name of the emoji (e.g. "zulip").
user_id: integer

The ID of the user who added the reaction.

Changes: New in Zulip 3.0 (feature level 2). The user object is deprecated and will be removed in the future.
user: object

Dictionary with data on the user who added the reaction, including the user ID as the user_id field.

Changes: 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.
- user_id: integer
  
  ID of the user.
- email: string
  
  Zulip API email of the user.
- full_name: string
  
  Full name of the user.
- is_mirror_dummy: boolean
  
  Whether the user is a mirror dummy.
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
}

attachment op: add

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
}

attachment op: update

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
}

attachment op: remove

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.
- id: integer
  
  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
}

submessage

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

user_status

Event sent to all users who can access the modified user when the status of a user changes.

Changes: Prior to Zulip 8.0 (feature level 228), this event was sent to all users in the organization.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
away: boolean

Whether the user has marked themself "away" with this status.

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

The text content of the status message.

This will be "" for users who set a status without selecting or writing a message.
emoji_name: string

The emoji name for the emoji the user selected for their new status.

This will be "" for users who set a status without selecting an emoji.

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

The emoji code for the emoji the user selected for their new status.

This will be "" for users who set a status without selecting an emoji.

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

The emoji type for the emoji the user selected for their new status.

This will be "" for users who set a status without selecting an emoji.

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

The ID of the user whose status changed.

Example

{
    "away": true,
    "emoji_code": "1f697",
    "emoji_name": "car",
    "id": 0,
    "reaction_type": "unicode_emoji",
    "status_text": "out to lunch",
    "type": "user_status",
    "user_id": 10
}

custom_profile_fields

Event sent to all users in a Zulip organization when new custom profile field types are configured for that Zulip organization.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
fields: (object)[]

An array of dictionaries where each dictionary contains details of a single new custom profile field for the Zulip organization.
- id: integer
  
  The ID of the custom profile field. This will be referenced in the custom profile fields section of user objects.
- type: integer
  
  An integer indicating the type of the custom profile field, which determines how it is configured and displayed to users.
  
  See the Custom profile fields article for details on what each type means.
  - 1: Short text
  - 2: Long text
  - 3: List of options
  - 4: Date picker
  - 5: Link
  - 6: Person picker
  - 7: External account
  - 8: Pronouns
  Changes: Field type 8 added in Zulip 6.0 (feature level 151).
- order: integer
  
  Custom profile fields are displayed in both settings UI and UI showing users' profiles in increasing order.
- name: string
  
  The name of the custom profile field.
- hint: string
  
  The help text to be displayed for the custom profile field in user-facing settings UI for configuring custom profile fields.
- field_data: string
  
  Field types 3 (List of options) and 7 (External account) support storing additional configuration for the field type in the field_data attribute.
  
  For field type 3 (List of options), this attribute is a JSON dictionary defining the choices and the order they will be displayed in the dropdown UI for individual users to select an option.
  
  The interface for field type 7 is not yet stabilized.
- display_in_profile_summary: boolean
  
  Whether the custom profile field, display or not on the user card.
  
  Currently it's value not allowed to be true of Long text and Person picker profile field types.
  
  This field is only included when its value is true.
  
  Changes: New in Zulip 6.0 (feature level 146).
- required: boolean
  
  Whether an organization administrator has configured this profile field as required.
  
  Because the required property is mutable, clients cannot assume that a required custom profile field has a value. The Zulip web application displays a prominent banner to any user who has not set a value for a required field.
  
  Changes: New in Zulip 9.0 (feature level 244).

Example

{
    "fields": [
        {
            "field_data": "",
            "hint": "",
            "id": 1,
            "name": "Phone number",
            "order": 1,
            "required": true,
            "type": 1
        },
        {
            "field_data": "",
            "hint": "What are you known for?",
            "id": 2,
            "name": "Biography",
            "order": 2,
            "required": true,
            "type": 2
        },
        {
            "field_data": "",
            "hint": "Or drink, if you'd prefer",
            "id": 3,
            "name": "Favorite food",
            "order": 3,
            "required": false,
            "type": 1
        },
        {
            "display_in_profile_summary": true,
            "field_data": "{\"0\":{\"text\":\"Vim\",\"order\":\"1\"},\"1\":{\"text\":\"Emacs\",\"order\":\"2\"}}",
            "hint": "",
            "id": 4,
            "name": "Favorite editor",
            "order": 4,
            "required": true,
            "type": 3
        },
        {
            "field_data": "",
            "hint": "",
            "id": 5,
            "name": "Birthday",
            "order": 5,
            "required": false,
            "type": 4
        },
        {
            "display_in_profile_summary": true,
            "field_data": "",
            "hint": "Or your personal blog's URL",
            "id": 6,
            "name": "Favorite website",
            "order": 6,
            "required": false,
            "type": 5
        },
        {
            "field_data": "",
            "hint": "",
            "id": 7,
            "name": "Mentor",
            "order": 7,
            "required": true,
            "type": 6
        },
        {
            "field_data": "{\"subtype\":\"github\"}",
            "hint": "Enter your GitHub username",
            "id": 8,
            "name": "GitHub",
            "order": 8,
            "required": true,
            "type": 7
        }
    ],
    "id": 0,
    "type": "custom_profile_fields"
}

default_stream_groups

Event sent to all users in a Zulip organization when an organization administrator changes the organization's configured default channel groups.

Default channel groups are an experimental feature that is not yet stabilized.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
default_stream_groups: (object)[]

An array of dictionaries where each dictionary contains details about a single default channel group.
- name: string
  
  Name of the default channel group.
- description: string
  
  Description of the default channel group.
- id: integer
  
  The ID of the default channel group.
- streams: (object)[]
  
  Array containing details about the channels in the default channel group.
  - stream_id: integer
    
    The unique ID of the channel.
  - name: string
    
    The name of the channel.
  - description: string
    
    The short description of the channel in text/markdown format, intended to be used to prepopulate UI for editing a channel's description.
  - date_created: integer
    
    The UNIX timestamp for when the channel was created, in UTC seconds.
    
    Changes: New in Zulip 4.0 (feature level 30).
  - creator_id: integer | null
    
    The ID of the user who created this channel.
    
    A null value means the channel has no recorded creator, which is often because the channel is very old, or because it was created via a data import tool or management command.
    
    Changes: New in Zulip 9.0 (feature level 254).
  - invite_only: boolean
    
    Specifies whether the channel is private or not. Only people who have been invited can access a private channel.
  - rendered_description: string
    
    The short description of the channel rendered as HTML, intended to be used when displaying the channel description in a UI.
    
    One should use the standard Zulip rendered_markdown CSS when displaying this content so that emoji, LaTeX, and other syntax work correctly. And any client-side security logic for user-generated message content should be applied when displaying this HTML as though it were the body of a Zulip message.
  - is_web_public: boolean
    
    Whether the channel has been configured to allow unauthenticated access to its message history from the web.
    
    Changes: New in Zulip 2.1.0.
  - stream_post_policy: integer
    
    Policy for which users can post messages to the channel.
    - 1 = Any user can post.
    - 2 = Only administrators can post.
    - 3 = Only full members can post.
    - 4 = Only moderators can post.
    Changes: New in Zulip 3.0 (feature level 1), replacing the previous is_announcement_only boolean.
  - message_retention_days: integer | null
    
    Number of days that messages sent to this channel will be stored before being automatically deleted by the message retention policy. There are two special values:
    - null, the default, means the channel will inherit the organization level setting.
    - -1 encodes retaining messages in this channel forever.
    Changes: New in Zulip 3.0 (feature level 17).
  - history_public_to_subscribers: boolean
    
    Whether the history of the channel is public to its subscribers.
    
    Currently always true for public channels (i.e. "invite_only": false implies "history_public_to_subscribers": true), but clients should not make that assumption, as we may change that behavior in the future.
  - first_message_id: integer | null
    
    The ID of the first message in the channel.
    
    Intended to help clients determine whether they need to display UI like the "show all topics" widget that would suggest the channel has older history that can be accessed.
    
    Is null for channels with no message history.
    
    Changes: New in Zulip 2.1.0.
  - is_announcement_only: boolean
    
    Whether the given channel is announcement only or not.
    
    Changes: Deprecated in Zulip 3.0 (feature level 1). Clients should use stream_post_policy instead.
  - can_remove_subscribers_group: integer
    
    ID of the user group whose members are allowed to unsubscribe others from the channel.
    
    Changes: Before Zulip 8.0 (feature level 197), the can_remove_subscribers_group setting was named can_remove_subscribers_group_id.
    
    New in Zulip 6.0 (feature level 142).

Example

{
    "default_stream_groups": [
        {
            "description": "New description",
            "id": 2,
            "name": "group1",
            "streams": [
                {
                    "can_remove_subscribers_group": 2,
                    "creator_id": 8,
                    "date_created": 1691057093,
                    "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": 2,
                    "creator_id": null,
                    "date_created": 1691057093,
                    "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": 2,
                    "creator_id": 9,
                    "date_created": 1691057093,
                    "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"
}

default_streams

Event sent to all users in a Zulip organization when the default channels in the organization are changed by an organization administrator.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
default_streams: (object)[]

An array of dictionaries where each dictionary contains details about a single default channel.
- stream_id: integer
  
  The unique ID of the channel.
- name: string
  
  The name of the channel.
- description: string
  
  The short description of the channel in text/markdown format, intended to be used to prepopulate UI for editing a channel's description.
- date_created: integer
  
  The UNIX timestamp for when the channel was created, in UTC seconds.
  
  Changes: New in Zulip 4.0 (feature level 30).
- creator_id: integer | null
  
  The ID of the user who created this channel.
  
  A null value means the channel has no recorded creator, which is often because the channel is very old, or because it was created via a data import tool or management command.
  
  Changes: New in Zulip 9.0 (feature level 254).
- invite_only: boolean
  
  Specifies whether the channel is private or not. Only people who have been invited can access a private channel.
- rendered_description: string
  
  The short description of the channel rendered as HTML, intended to be used when displaying the channel description in a UI.
  
  One should use the standard Zulip rendered_markdown CSS when displaying this content so that emoji, LaTeX, and other syntax work correctly. And any client-side security logic for user-generated message content should be applied when displaying this HTML as though it were the body of a Zulip message.
- is_web_public: boolean
  
  Whether the channel has been configured to allow unauthenticated access to its message history from the web.
  
  Changes: New in Zulip 2.1.0.
- stream_post_policy: integer
  
  Policy for which users can post messages to the channel.
  - 1 = Any user can post.
  - 2 = Only administrators can post.
  - 3 = Only full members can post.
  - 4 = Only moderators can post.
  Changes: New in Zulip 3.0 (feature level 1), replacing the previous is_announcement_only boolean.
- message_retention_days: integer | null
  
  Number of days that messages sent to this channel will be stored before being automatically deleted by the message retention policy. There are two special values:
  - null, the default, means the channel will inherit the organization level setting.
  - -1 encodes retaining messages in this channel forever.
  Changes: New in Zulip 3.0 (feature level 17).
- history_public_to_subscribers: boolean
  
  Whether the history of the channel is public to its subscribers.
  
  Currently always true for public channels (i.e. "invite_only": false implies "history_public_to_subscribers": true), but clients should not make that assumption, as we may change that behavior in the future.
- first_message_id: integer | null
  
  The ID of the first message in the channel.
  
  Intended to help clients determine whether they need to display UI like the "show all topics" widget that would suggest the channel has older history that can be accessed.
  
  Is null for channels with no message history.
  
  Changes: New in Zulip 2.1.0.
- is_announcement_only: boolean
  
  Whether the given channel is announcement only or not.
  
  Changes: Deprecated in Zulip 3.0 (feature level 1). Clients should use stream_post_policy instead.
- can_remove_subscribers_group: integer
  
  ID of the user group whose members are allowed to unsubscribe others from the channel.
  
  Changes: Before Zulip 8.0 (feature level 197), the can_remove_subscribers_group setting was named can_remove_subscribers_group_id.
  
  New in Zulip 6.0 (feature level 142).

Example

{
    "default_streams": [
        {
            "can_remove_subscribers_group": 2,
            "creator_id": 8,
            "date_created": 1691057093,
            "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"
}

delete_message

Event sent when a message has been deleted.

Sent to all users who currently are subscribed to the messages' recipient. May also be sent to additional users who had access to it, including, in particular, an administrator user deleting messages in a stream that they are not subscribed to.

This means that clients can assume that they will always receive an event of this type for deletions that the client itself initiated.

This event is also sent when the user loses access to a message, such as when it is moved to a channel that the user does not have permission to access.

Changes: Before Zulip 9.0 (feature level 274), this event was only sent to subscribers of the message's recipient.

Before Zulip 5.0 (feature level 77), events for direct messages contained additional sender_id and recipient_id fields.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
message_ids: (integer)[]

Only present for clients that support the bulk_message_deletion client capability.

A list containing the IDs of the newly deleted messages.
message_id: integer

Only present for clients that do not support the bulk_message_deletion client capability.

The ID of the newly deleted message.
message_type: string

The type of message. Either "stream" or "private".
stream_id: integer

Only present if message_type is "stream".

The ID of the channel to which the message was sent.
topic: string

Only present if message_type is "stream".

The topic to which the message was sent.

Example

{
    "id": 0,
    "message_id": 37,
    "message_type": "private",
    "type": "delete_message"
}

muted_topics

Event sent to a user's clients when that user's set of configured muted topics have changed.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
muted_topics: ((string | integer)[])[]

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

Changes: Deprecated in Zulip 6.0 (feature level 134). Starting with this version, clients that explicitly requested the replacement user_topic event type when registering their event queue will not receive this legacy event type.

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

Example

{
    "id": 0,
    "muted_topics": [
        [
            "Denmark",
            "topic",
            1594825442
        ]
    ],
    "type": "muted_topics"
}

user_topic

Event sent to a user's clients when the user mutes/unmutes a topic, or otherwise modifies their personal per-topic configuration.

Changes: New in Zulip 6.0 (feature level 134). Previously, clients were notified about changes in muted topic configuration via the muted_topics event type.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
stream_id: integer

The ID of the channel to which the topic belongs.
topic_name: string

The name of the topic.
last_updated: integer

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

An integer indicating the user's visibility preferences for the topic, such as whether the topic is muted.
- 0 = None. Used to indicate that the user no longer has a special visibility policy for this topic.
- 1 = Muted. Used to record muted topics.
- 2 = Unmuted. Used to record unmuted topics.
- 3 = Followed. Used to record followed topics.
Changes: In Zulip 7.0 (feature level 219), added followed as a visibility policy option.

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

Example

{
    "id": 1,
    "last_updated": 1594825442,
    "stream_id": 1,
    "topic_name": "topic",
    "type": "user_topic",
    "visibility_policy": 1
}

muted_users

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.
- id: integer
  
  The ID of the muted user.
- timestamp: integer
  
  An integer UNIX timestamp representing when the user was muted.

Example

{
    "id": 0,
    "muted_users": [
        {
            "id": 1,
            "timestamp": 1594825442
        },
        {
            "id": 22,
            "timestamp": 1654865392
        }
    ],
    "type": "muted_users"
}

heartbeat

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

onboarding_steps

Event sent when the set of onboarding steps to show for the current user has changed (e.g. because the user dismissed one).

Clients that feature a similar tutorial experience to the Zulip web app may want to handle these events.

Changes: Before Zulip 8.0 (feature level 233), this event was named hotspots. Prior to this feature level, one-time notice onboarding steps were not supported.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
onboarding_steps: (object)[]

An array of dictionaries where each dictionary contains details about a single onboarding step.

Changes: Before Zulip 8.0 (feature level 233), this array was named hotspots. Prior to this feature level, one-time notice onboarding steps were not supported, and the type field in these objects did not exist as all onboarding steps were implicitly hotspots.
- type: string
  
  The type of the onboarding step. Valid value is "one_time_notice".
  
  Changes: Removed type "hotspot" in Zulip 9.0 (feature level 259).
  
  New in Zulip 8.0 (feature level 233).
- name: string
  
  The name of the onboarding step.

Example

{
    "id": 0,
    "onboarding_steps": [
        {
            "name": "visibility_policy_banner",
            "type": "one_time_notice"
        }
    ],
    "type": "onboarding_steps"
}

update_message

Event sent when a message's content, topic and/or channel has been edited or when a message's content has a rendering update, such as for an inline URL preview. Sent to all users who had received the original message.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
user_id: integer | null

The ID of the user who sent the message.

Is null when event is for a rendering update of the original message, such as for an inline URL preview.

Changes: As of Zulip 5.0 (feature level 114), this field is present for all update_message events. Previously, this field was omitted for inline URL preview updates.
rendering_only: boolean

Whether the event only updates the rendered content of the message.

This field should be used by clients to determine if the event only provides a rendering update to the message content, such as for an inline URL preview. When true, the event does not reflect a user-generated edit and does not modify the message history.

Changes: New in Zulip 5.0 (feature level 114). Clients can correctly identify these rendering update event with earlier Zulip versions by checking whether the user_id field was omitted.
message_id: integer

The ID of the message which was edited or updated.

This field should be used to apply content edits to the client's cached message history, or to apply rendered content updates.

If the channel or topic was changed, the set of moved messages is encoded in the separate message_ids field, which is guaranteed to include message_id.
message_ids: (integer)[]

The list of IDs of messages to which any channel or topic changes encoded in this event should be applied.

This list always includes message_id, even when there are no channel or topic changes to apply.

These messages are guaranteed to have all been previously sent to channel stream_id with topic orig_subject, and have been moved to new_stream_id with topic subject (if those fields are present in the event).

Clients processing these events should update all cached message history associated with the moved messages (including adjusting unread_msgs data structures, where the client may not have the message itself in its history) to reflect the new channel and topic.

Content changes should be applied only to the single message indicated by message_id.
flags: (string)[]

The user's personal message flags for the message with ID message_id following the edit.

A client application should compare these to the original flags to identify cases where a mention or alert word was added by the edit.

Changes: In Zulip 8.0 (feature level 224), the wildcard_mentioned flag was deprecated in favor of the stream_wildcard_mentioned and topic_wildcard_mentioned flags. The wildcard_mentioned flag exists for backwards compatibility with older clients and equals stream_wildcard_mentioned || topic_wildcard_mentioned. Clients supporting older server versions should treat this field as a previous name for the stream_wildcard_mentioned flag as topic wildcard mentions were not available prior to this feature level.
edit_timestamp: integer

The time when this message edit operation was processed by the server.

Changes: As of Zulip 5.0 (feature level 114), this field is present for all update_message events. Previously, this field was omitted for inline URL preview updates.
stream_name: string

Only present if the message was edited and originally sent to a channel.

The name of the channel that the message was sent to. Clients are recommended to use the stream_id field instead.
stream_id: integer

Only present if the message was edited and originally sent to a channel.

The pre-edit channel for all of the messages with IDs in message_ids.

Changes: As of Zulip 5.0 (feature level 112), this field is present for all edits to a channel message. Previously, it was not present when only the content of the channel message was edited.
new_stream_id: integer

Only present if message(s) were moved to a different channel.

The post-edit channel for all of the messages with IDs in message_ids.
propagate_mode: string

Only present if this event moved messages to a different topic and/or channel.

The choice the editing user made about which messages should be affected by a channel/topic edit:
- "change_one": Just change the one indicated in message_id.
- "change_later": Change messages in the same topic that had been sent after this one.
- "change_all": Change all messages in that topic.
This parameter should be used to decide whether to change navigation and compose box state in response to the edit. For example, if the user was previously in topic narrow, and the topic was edited with "change_later" or "change_all", the Zulip web app will automatically navigate to the new topic narrow. Similarly, a message being composed to the old topic should have its recipient changed to the new topic.

This navigation makes it much more convenient to move content between topics without disruption or messages continuing to be sent to the pre-edit topic by accident.
orig_subject: string

Only present if this event moved messages to a different topic and/or channel.

The pre-edit topic for all of the messages with IDs in message_ids.
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.
- text: string
  
  The original link text present in the topic.
- url: string
  
  The expanded target url which the link points to.
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
}

typing op: start

Event sent when a user starts typing a message.

Sent to all clients for users who would receive the message being typed, with the additional rule that typing notifications for channel messages are only sent to clients that included stream_typing_notifications in their client capabilities when registering the event queue.

See POST /typing endpoint for more details.

Changes: Typing notifications for channel messages are new in Zulip 4.0 (feature level 58).

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
message_type: string

Type of message being composed. Must be "stream" or "direct".

Changes: In Zulip 8.0 (feature level 215), replaced the value "private" with "direct".

New in Zulip 4.0 (feature level 58). Previously, all typing notifications were implicitly direct messages.
sender: object

Object describing the user who is typing the message.
- user_id: integer
  
  The user's ID.
- email: string
  
  The Zulip API email address for the user.
recipients: (object)[]

Only present if message_type is "direct".

Array of dictionaries describing the set of users who would be recipients of the message being typed. Each dictionary contains details about one of the recipients. The sending user is guaranteed to appear among the recipients.
- user_id: integer
  
  The ID of the user.
- email: string
  
  The Zulip API email address for the user.
stream_id: integer

Only present if message_type is "stream".

The unique ID of the channel to which message is being typed.

Changes: New in Zulip 4.0 (feature level 58). Previously, typing notifications were only for direct messages.
topic: string

Only present if message_type is "stream".

Topic within the channel where the message is being typed.

Changes: New in Zulip 4.0 (feature level 58). Previously, typing notifications were only for direct messages.

Example

{
    "id": 0,
    "message_type": "direct",
    "op": "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"
}

typing op: stop

Event sent when a user stops typing a message.

Sent to all clients for users who would receive the message that was previously being typed, with the additional rule that typing notifications for channel messages are only sent to clients that included stream_typing_notifications in their client capabilities when registering the event queue.

See POST /typing endpoint for more details.

Changes: Typing notifications for channel messages are new in Zulip 4.0 (feature level 58).

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
message_type: string

Type of message being composed. Must be "stream" or "direct".

Changes: In Zulip 8.0 (feature level 215), replaced the value "private" with "direct".

New in Zulip 4.0 (feature level 58). Previously all typing notifications were implicitly direct messages.
sender: object

Object describing the user who was previously typing the message.
- user_id: integer
  
  The user's ID.
- email: string
  
  The Zulip API email address for the user.
recipients: (object)[]

Only present if message_type is "direct".

Array of dictionaries describing the set of users who would be recipients of the message that was previously being typed. Each dictionary contains details about one of the recipients. The sending user is guaranteed to appear among the recipients.
- user_id: integer
  
  The ID of the user.
- email: string
  
  The Zulip API email address for the user.
stream_id: integer

Only present if message_type is "stream".

The unique ID of the channel to which message is being typed.

Changes: New in Zulip 4.0 (feature level 58). Previously, typing notifications were only for direct messages.
topic: string

Only present if message_type is "stream".

Topic within the channel where the message is being typed.

Changes: New in Zulip 4.0 (feature level 58). Previously, typing notifications were only for direct messages.

Example

{
    "id": 0,
    "message_type": "direct",
    "op": "stop",
    "recipients": [
        {
            "email": "user8@zulip.testserver",
            "user_id": 8
        },
        {
            "email": "user10@zulip.testserver",
            "user_id": 10
        }
    ],
    "sender": {
        "email": "user10@zulip.testserver",
        "user_id": 10
    },
    "type": "typing"
}

update_message_flags op: add

Event sent to a user when message flags are added to messages.

This can reflect a direct user action, or can be the indirect consequence of another action. Whatever the cause, if there's a change in the set of message flags that the user has for a message, then an update_message_flags event will be sent with the change. Note that this applies when the user already had access to the message, and continues to have access to it. When a message newly appears or disappears, a message or delete_message event is sent instead.

Some examples of actions that trigger an update_message_flags event:

The "starred" flag is added when the user chooses to star a message.
The "read" flag is added when the user marks messages as read by scrolling through them, or uses Mark all messages as read on a conversation.
The "read" flag is added when the user mutes a message's sender.
The "read" flag is added after the user unsubscribes from a channel, or messages are moved to a not-subscribed channel, provided the user can still access the messages at all. Note a delete_message event is sent in the case where the user can no longer access the messages.

In some cases, a change in message flags that's caused by another change may happen a short while after the original change, rather than simultaneously. For example, when messages that were unread are moved to a channel where the user is not subscribed, the resulting change in message flags (and the corresponding update_message_flags event with flag "read") may happen later than the message move itself. The delay in that example is typically at most a few hundred milliseconds and can in rare cases be minutes or longer.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
operation: string

Old name for the op field in this event type.

Deprecated in Zulip 4.0 (feature level 32), and replaced by the op field.
flag: string

The flag that was added.
messages: (integer)[]

Array containing the IDs of all messages to which the flag was added.
all: boolean

Whether the specified flag was added to all messages. This field is only relevant for the "read" flag, and will be false for all other flags.

When true for the "read" flag, then the messages array will be empty.

Example

{
    "all": false,
    "flag": "starred",
    "id": 0,
    "messages": [
        63
    ],
    "op": "add",
    "operation": "add",
    "type": "update_message_flags"
}

update_message_flags op: remove

Event sent to a user when message flags are removed from messages.

See the description for the update_message_flags op: add event for more details about these events.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
operation: string

Old name for the op field in this event type.

Deprecated in Zulip 4.0 (feature level 32), and replaced by the op field.
flag: string

The flag to be removed.
messages: (integer)[]

Array containing the IDs of the messages from which the flag was removed.
all: boolean

Will be false for all specified flags.

Deprecated and will be removed in a future release.
message_details: object

Only present if the specified flag is "read".

A set of data structures describing the messages that are being marked as unread with additional details to allow clients to update the unread_msgs data structure for these messages (which may not be otherwise known to the client).

Changes: New in Zulip 5.0 (feature level 121). Previously, marking already read messages as unread was not supported by the Zulip API.
- {message_id}: object
  
  Object containing details about the message with the specified ID.
  - type: string
    
    The type of this message. Either "stream" or "private".
  - 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 direct 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 channel 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"
}

user_group op: add

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).
- can_mention_group: integer | object
  
  A group-setting value defining the set of users who have permission to mention this user group.
  
  Changes: Before Zulip 9.0 (feature level 258), this setting was always the integer form of a group-setting value.
  
  Before Zulip 8.0 (feature level 198), this setting was named can_mention_group_id.
  
  New in Zulip 8.0 (feature level 191). Previously, groups could be mentioned only if they were not system groups.
  
  Will be one of the following:
  - The ID of the user group with this permission.
  - An object with these fields:
    - direct_members: (integer)[]
      
      The list of IDs of individual users in the collection of users with this permission.
    - direct_subgroups: (integer)[]
      
      The list of IDs of the groups in the collection of users with this permission.

Example

{
    "group": {
        "can_mention_group": 11,
        "description": "Backend team",
        "id": 2,
        "is_system_group": false,
        "members": [
            12
        ],
        "name": "backend"
    },
    "id": 0,
    "op": "add",
    "type": "user_group"
}

user_group op: update

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.
- name: string
  
  The new name of the user group. Only present if the group's name changed.
- description: string
  
  The new description of the group. Only present if the description changed.
- can_mention_group: integer | object
  
  A group-setting value defining the set of users who have permission to mention this user group. Only present if this user group permission setting changed.
  
  Changes: Before Zulip 9.0 (feature level 258), this setting was always the integer form of a group-setting value.
  
  Before Zulip 8.0 (feature level 198), this setting was named can_mention_group_id.
  
  New in Zulip 8.0 (feature level 191). Previously, groups could be mentioned only if they were not system groups.
  
  Will be one of the following:
  - The ID of the user group with this permission.
  - An object with these fields:
    - direct_members: (integer)[]
      
      The list of IDs of individual users in the collection of users with this permission.
    - direct_subgroups: (integer)[]
      
      The list of IDs of the groups in the collection of users with this permission.

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

user_group op: remove

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

realm_linkifiers

Event sent to all users in a Zulip organization when the set of configured linkifiers for the organization has changed.

Processing this event is important for doing Markdown local echo correctly.

Clients will not receive this event unless the event queue is registered with the client capability {"linkifier_url_template": true}. See POST /register for how client capabilities can be specified.

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

New in Zulip 4.0 (feature level 54), replacing the deprecated realm_filters event type.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
realm_linkifiers: (object)[]

An ordered array of dictionaries where each dictionary contains details about a single linkifier.

Clients should always process linkifiers in the order given; this is important if the realm has linkifiers with overlapping patterns. The order can be modified using PATCH /realm/linkifiers.
- pattern: string
  
  The Python regular expression that represents the pattern that should be linkified by this linkifier.
- url_template: string
  
  The RFC 6570 compliant URL template to be used for linkifying matches.
  
  Changes: New in Zulip 7.0 (feature level 176). This replaced url_format, which contained a URL format string.
- id: integer
  
  The ID of the linkifier.

Example

{
    "id": 0,
    "realm_linkifiers": [
        {
            "id": 1,
            "pattern": "#(?P<id>[123])",
            "url_template": "https://realm.com/my_realm_filter/{id}"
        }
    ],
    "type": "realm_linkifiers"
}

realm_filters

Legacy event type that is no longer sent to clients. Previously, sent to all users in a Zulip organization when the set of configured linkifiers for the organization was changed.

Changes: Prior to Zulip 7.0 (feature level 176), this event type was sent to clients.

Deprecated in Zulip 4.0 (feature level 54), and replaced by the realm_linkifiers event type, which has a clearer name and format.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
realm_filters: ((integer | string)[])[]

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

Example

{
    "id": 0,
    "realm_filters": [],
    "type": "realm_filters"
}

realm_playgrounds

Event sent to all users in a Zulip organization when the set of configured code playgrounds for the organization has changed.

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

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
realm_playgrounds: (object)[]

An array of dictionaries where each dictionary contains data about a single playground entry.
- id: integer
  
  The unique ID for the realm playground.
- name: string
  
  The user-visible display name of the playground. Clients should display this in UI for picking which playground to open a code block in, to differentiate between multiple configured playground options for a given pygments language.
  
  Changes: New in Zulip 4.0 (feature level 49).
- pygments_language: string
  
  The name of the Pygments language lexer for that programming language.
- url_template: string
  
  The RFC 6570 compliant URL template for the playground. The template contains exactly one variable named code, which determines how the extracted code should be substituted in the playground URL.
  
  Changes: New in Zulip 8.0 (feature level 196). This replaced the url_prefix parameter, which was used to construct URLs by just concatenating url_prefix and code.

Example

{
    "id": 0,
    "realm_playgrounds": [
        {
            "id": 1,
            "name": "Python playground",
            "pygments_language": "Python",
            "url_template": "https://python.example.com"
        }
    ],
    "type": "realm_playgrounds"
}

realm_emoji op: update

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.
- {emoji_id}: object
  
  Object containing details about the emoji with the specified ID. It has the following properties:
  - id: string
    
    The ID for this emoji, same as the object's key.
  - name: string
    
    The user-friendly name for this emoji. Users in the organization can use this emoji by writing this name between colons (:name :).
  - source_url: string
    
    The path relative to the organization's URL where the emoji's image can be found.
  - still_url: string | null
    
    Only non-null when the emoji's image is animated.
    
    The path relative to the organization's URL where a still (not animated) version of the emoji can be found. (This is currently always the first frame of the animation).
    
    This is useful for clients to display the emoji in contexts where continuously animating it would be a bad user experience (E.g. because it would be distracting).
    
    Changes: New in Zulip 5.0 (added as optional field in feature level 97 and then made mandatory, but nullable, in feature level 113).
  - deactivated: boolean
    
    Whether the emoji has been deactivated or not.
  - author_id: integer | null
    
    The user ID of the user who uploaded the custom emoji. Will be null if the uploader is unknown.
    
    Changes: New in Zulip 3.0 (feature level 7). Previously was accessible via an author object with an id field.

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

realm_domains op: add

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.
- domain: string
  
  The new allowed domain.
- allow_subdomains: boolean
  
  Whether subdomains are allowed for this domain.

Example

{
    "id": 0,
    "op": "add",
    "realm_domain": {
        "allow_subdomains": false,
        "domain": "zulip.org"
    },
    "type": "realm_domains"
}

realm_domains op: change

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

realm_domains op: remove

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

realm_export

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. If null, it wasn't deleted.
- failed_timestamp: number | null
  
  The timestamp of when the export failed. If null, it didn't fail.
- 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"
}

realm_bot op: add

Event sent to users who can administer a newly created bot user. Clients will also receive a realm_user event that contains basic details (but not the API key).

The realm_user events are sufficient for clients that only need to interact with the bot; this realm_bot event type is relevant only for administering bots.

Only organization administrators and the user who owns the bot will receive this event.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
bot: object

Object containing details of a bot.
- user_id: integer
  
  The user ID of the bot.
- full_name: string
  
  The full name of the bot.
- api_key: string
  
  The API key of the bot which it uses to make API requests.
- default_sending_stream: string | null
  
  The default sending channel of the bot. If null, the bot doesn't have a default sending channel.
- default_events_register_stream: string | null
  
  The default channel for which the bot receives events/register data. If null, the bot doesn't have such a default channel.
- default_all_public_streams: boolean
  
  Whether the bot can send messages to all channels by default.
- avatar_url: string
  
  The URL of the bot's avatar.
- owner_id: integer | null
  
  The user ID of the bot's owner.
  
  If null, the bot has no owner.
- services: (object | object)[]
  
  An array containing extra configuration fields only relevant for outgoing webhook bots and embedded bots. This is always a single-element array.
  
  We consider this part of the Zulip API to be unstable; it is used only for UI elements for administering bots and is likely to change.
  - When the bot is an outgoing webhook.
    - base_url: string
      
      The URL the outgoing webhook is configured to post to.
    - token: string
      
      A unique token that the third-party service can use to confirm that the request is indeed coming from Zulip.
    - interface: integer
      
      An integer indicating what format requests are posted in:
      - 1 = Zulip's native outgoing webhook format.
      - 2 = Emulate the Slack outgoing webhook format.
  - When the bot is an embedded bot.
    - service_name: string
      
      The name of the bot.
    - config_data: object
      
      A dictionary of string key/value pairs, which describe the configuration for the bot. These are usually details like API keys, and are unique to the integration/bot. Can be an empty dictionary.
      - {config_key}: string
        
        Description/value of the configuration data key.
- email: string
  
  The email of the bot.
- bot_type: integer | null
  
  An integer describing the type of bot:
  - 1 for a Generic bot.
  - 2 for an Incoming webhook bot.
  - 3 for an Outgoing webhook bot.
  - 4 for an Embedded bot.
- is_active: boolean
  
  A boolean describing whether the user account has been deactivated.

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

realm_bot op: update

Event sent to users who can administer a bot user when the bot is configured. Clients may also receive a realm_user event that for changes in public data about the bot (name, etc.).

The realm_user events are sufficient for clients that only need to interact with the bot; this realm_bot event type is relevant only for administering bots.

Only organization administrators and the user who owns the bot will receive this event.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
bot: object

Object containing details about the changed bot. It contains two properties: the user ID of the bot and the property to be changed. The changed property is one of the remaining properties listed below.
- user_id: integer
  
  The user ID of the bot.
- full_name: string
  
  The full name of the bot.
- api_key: string
  
  The API key of the bot which it uses to make API requests.
- default_sending_stream: string | null
  
  The default sending channel of the bot. If null, the bot doesn't have a default sending channel.
- default_events_register_stream: string | null
  
  The default channel for which the bot receives events/register data. If null, the bot doesn't have such a default channel.
- default_all_public_streams: boolean
  
  Whether the bot can send messages to all channels by default.
- avatar_url: string
  
  The URL of the bot's avatar.
- owner_id: integer | null
  
  The user ID of the bot's owner.
  
  If null, the bot has no owner.
- services: (object | object)[]
  
  An array containing extra configuration fields only relevant for outgoing webhook bots and embedded bots. This is always a single-element array.
  
  We consider this part of the Zulip API to be unstable; it is used only for UI elements for administering bots and is likely to change.
  - When the bot is an outgoing webhook.
    - base_url: string
      
      The URL the outgoing webhook is configured to post to.
    - token: string
      
      A unique token that the third-party service can use to confirm that the request is indeed coming from Zulip.
    - interface: integer
      
      An integer indicating what format requests are posted in:
      - 1 = Zulip's native outgoing webhook format.
      - 2 = Emulate the Slack outgoing webhook format.
  - When the bot is an embedded bot.
    - service_name: string
      
      The name of the bot.
    - config_data: object
      
      A dictionary of string key/value pairs, which describe the configuration for the bot. These are usually details like API keys, and are unique to the integration/bot. Can be an empty dictionary.
      - {config_key}: string
        
        Description/value of the configuration data key.
- is_active: boolean
  
  A boolean describing whether the user account has been deactivated.
  
  Changes: New in Zulip 8.0 (feature level 222). Previously we sent realm_user event with op field set to remove when deactivating a bot and realm_user event with op field set to add when reactivating a bot.

Example

{
    "bot": {
        "services": [
            {
                "base_url": "http://hostname.domain2.com",
                "interface": 2,
                "token": "grr8I2APXRmVL0FRTMRYAE4DRPQ5Wlaw"
            }
        ],
        "user_id": 37
    },
    "id": 0,
    "op": "update",
    "type": "realm_bot"
}

realm_bot op: remove

Event sent to all users when a bot has been deactivated.

Changes: Deprecated and no longer sent since Zulip 8.0 (feature level 222).

Previously, this event was sent to all users in a Zulip organization when a bot was deactivated.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
bot: object

Object containing details about the deactivated bot.
- user_id: integer
  
  The user ID of the deactivated bot.
- full_name: string
  
  The full name of the deactivated bot.

Example

{
    "bot": {
        "full_name": "Foo Bot",
        "user_id": 35
    },
    "id": 1,
    "op": "remove",
    "type": "realm_bot"
}

realm_bot op: delete

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.
- user_id: integer
  
  The user ID of the deactivated bot.

Example

{
    "bot": {
        "user_id": 35
    },
    "id": 1,
    "op": "delete",
    "type": "realm_bot"
}

realm op: update

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.
- upload_quota: integer
  
  Note: Only present if changed property is plan_type.
  
  The new upload quota for the Zulip organization.

Example

{
    "id": 0,
    "op": "update",
    "property": "disallow_disposable_email_addresses",
    "type": "realm",
    "value": false
}

realm op: deactivated

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

restart

Event sent to all the users whenever the Zulip server restarts.

Specifically, this event is sent whenever the Tornado process for the user is restarted; in particular, this will always happen when the Zulip server is upgraded.

Clients should use this event to update their tracking of the server's capabilities, and to decide if they wish to get a new event queue after a server upgrade. Clients doing so must implement a random delay strategy to spread such restarts over 5 minutes or more to avoid creating a synchronized thundering herd effect.

Changes: Removed the immediate flag, which was only used by web clients in development, in Zulip 9.0 (feature level 240).

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
zulip_version: string

The Zulip version number, in the format where this appears in the server_settings and register responses.

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

The Zulip merge base number, in the format where this appears in the server_settings and register responses.

Changes: New in Zulip 5.0 (feature level 88).
zulip_feature_level: integer

The Zulip feature level of the server after the restart.

Clients should use this to update their tracking of the server's capabilities, and may choose to refetch their state and create a new event queue when the API feature level has changed in a way that the client finds significant. Clients choosing to do so must implement a random delay strategy to spread such restarts over 5 or more minutes to avoid creating a synchronized thundering herd effect.

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

The timestamp at which the server started.

Example

{
    "id": 0,
    "server_generation": 1619334181,
    "type": "restart",
    "zulip_feature_level": 57,
    "zulip_merge_base": "5.0-dev-1646-gea6b21cd8c",
    "zulip_version": "5.0-dev-1650-gc3fd37755f"
}

web_reload_client

An event which signals the official Zulip web/desktop app to update, by reloading the page and fetching a new queue; this will generally follow a restart event. Clients which do not obtain their code from the server (e.g. mobile and terminal clients, which store their code locally) should ignore this event.

Clients choosing to reload the application must implement a random delay strategy to spread such restarts over 5 or more minutes to avoid creating a synchronized thundering herd effect.

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

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
immediate: boolean

Whether the client should fetch a new event queue immediately, rather than using a backoff strategy to avoid thundering herds. A Zulip development server uses this parameter to reload clients immediately.

Example

{
    "id": 0,
    "immediate": true,
    "type": "web_reload_client"
}

realm op: update_dict

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.

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

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
property: string

Always "default". Present for backwards-compatibility with older clients that predate the update_dict event style.

Deprecated and will be removed in a future release.
data: object

An object containing the properties that have changed.

Changes: In Zulip 7.0 (feature level 183), the community_topic_editing_limit_seconds property was removed. It was documented as potentially returned as a changed property in this event, but in fact it was only ever returned in the POST /register response.

Before Zulip 6.0 (feature level 150), on changing any of allow_message_editing, message_content_edit_limit_seconds, or edit_topic_policy settings, this object included all the three settings irrespective of which of these settings were changed. Now, a separate event is sent for each changed setting.
- 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 keys mapped to dictionaries that describe the properties of the named authentication method for the organization - its enabled status and availability for use by the organization.
  
  Clients should use this to implement server-settings UI to change which methods are enabled for the organization. For authentication UI itself, clients should use the pre-authentication metadata returned by GET /server_settings.
  
  Changes: In Zulip 9.0 (feature level 243), the values in this dictionary were changed. Previously, the values were a simple boolean indicating whether the backend is enabled or not.
  - Dictionary describing the properties of an authentication method for the organization - its enabled status and availability for use by the organization.
    - enabled: boolean
      
      Boolean describing whether the authentication method (i.e. its key) is enabled in this organization.
    - available: boolean
      
      Boolean describing whether the authentication method is available for use. If false, the organization is not eligible to enable the authentication method.
    - unavailable_reason: string
      
      Reason why the authentication method is unavailable. This field is optional and is only present when 'available' is false.
- bot_creation_policy: integer
  
  The policy for which users can create bot users in this organization.
- create_multiuse_invite_group: integer
  
  The ID of the user group whose members are allowed to create reusable invitation links to the organization.
  
  This setting can currently only be set to user groups that are system groups, except for the system groups named "role:internet" and "role:owners".
  
  Changes: New in Zulip 8.0 (feature level 209).
- can_create_public_channel_group: integer | object
  
  A group-setting value defining the set of users who have permission to create public channels in this organization.
  
  This setting cannot be set to "role:internet", "role:everyone", "role:owners" and "role:nobody" system groups.
  
  Changes: New in Zulip 9.0 (feature level 264). Previously realm_create_public_stream_policy field used to control the permission to create public channels.
  - The ID of the user group with this permission.
  - An object with these fields:
    - direct_members: (integer)[]
      
      The list of IDs of individual users in the collection of users with this permission.
    - direct_subgroups: (integer)[]
      
      The list of IDs of the groups in the collection of users with this permission.
- can_create_private_channel_group: integer | object
  
  A group-setting value defining the set of users who have permission to create private channels in this organization.
  
  This setting cannot be set to "role:internet", "role:everyone", "role:owners" and "role:nobody" system groups.
  
  Changes: New in Zulip 9.0 (feature level 266). Previously realm_create_private_stream_policy field used to control the permission to create private channels.
  - The ID of the user group with this permission.
  - An object with these fields:
    - direct_members: (integer)[]
      
      The list of IDs of individual users in the collection of users with this permission.
    - direct_subgroups: (integer)[]
      
      The list of IDs of the groups in the collection of users with this permission.
- create_web_public_stream_policy: integer
  
  The policy for which users can create web public channels in this organization.
  
  Changes: New in Zulip 5.0 (feature level 103).
- default_code_block_language: string
  
  The default pygments language code to be used for code blocks in this organization. If an empty string, no default has been set.
  
  Changes: Prior to Zulip 8.0 (feature level 195), a server bug meant that both null and an empty string could represent that no default was set for this realm setting in the POST /register response. The documentation for both that endpoint and this event incorrectly stated that the only representation for no default language was null. This event in fact uses the empty string to indicate that no default has been set in all server versions.
- default_language: string
  
  The default language for the organization.
- description: string
  
  The description of the organization, used on login and registration pages.
- digest_emails_enabled: boolean
  
  Whether the organization has enabled weekly digest emails.
- digest_weekday: integer
  
  The day of the week when the organization will send its weekly digest email to inactive users.
- direct_message_initiator_group: integer | object
  
  A group-setting value defining the set of users who have permission to start a new direct message conversation involving other non-bot users. Users who are outside this group and attempt to send the first direct message to a given collection of recipient users will receive an error, unless all other recipients are bots or the sender.
  
  Changes: New in Zulip 9.0 (feature level 270).
  
  Previously, access to send direct messages was controlled by the private_message_policy realm setting, which supported values of 1 (enabled) and 2 (disabled).
  - The ID of the user group with this permission.
  - An object with these fields:
    - direct_members: (integer)[]
      
      The list of IDs of individual users in the collection of users with this permission.
    - direct_subgroups: (integer)[]
      
      The list of IDs of the groups in the collection of users with this permission.
- direct_message_permission_group: integer | object
  
  A group-setting value defining the set of users who have permission to fully use direct messages. Users outside this group can only send direct messages to conversations where all the recipients are in this group, are bots, or are the sender, ensuring that every direct message conversation will be visible to at least one user in this group.
  
  Changes: New in Zulip 9.0 (feature level 270).
  
  Previously, access to send direct messages was controlled by the private_message_policy realm setting, which supported values of 1 (enabled) and 2 (disabled).
  - The ID of the user group with this permission.
  - An object with these fields:
    - direct_members: (integer)[]
      
      The list of IDs of individual users in the collection of users with this permission.
    - direct_subgroups: (integer)[]
      
      The list of IDs of the groups in the collection of users with this permission.
- 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
  - 6 = Nobody
  Changes: Nobody added as an option in Zulip 7.0 (feature level 159).
  
  New in Zulip 5.0 (feature level 75), replacing the previous allow_community_topic_editing boolean.
- 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 channels are enabled in this organization.
  
  Can only be enabled if the WEB_PUBLIC_STREAMS_ENABLED server setting is enabled on the Zulip server. See also the 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 channels 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_within_stream_limit_seconds: integer | null
  
  Messages sent more than this many seconds ago cannot be moved within a channel to another topic by users who have permission to do so based on this organization's topic edit policy. This setting does not affect moderators and administrators.
  
  Will not be 0. A null value means no limit, so message topics can be edited regardless of how long ago they were sent.
  
  Changes: New in Zulip 7.0 (feature level 162). Previously, this time limit was always 72 hours for users who were not administrators or moderators.
- move_messages_between_streams_limit_seconds: integer | null
  
  Messages sent more than this many seconds ago cannot be moved between channels by users who have permission to do so based on this organization's message move policy. This setting does not affect moderators and administrators.
  
  Will not be 0. A null value means no limit, so messages can be moved regardless of how long ago they were sent.
  
  Changes: New in Zulip 7.0 (feature level 162). Previously, there was no time limit for moving messages between channels for users with permission to do so.
- move_messages_between_streams_policy: integer
  
  The policy for which users can move messages from one channel to another.
  - 1 = Members only
  - 2 = Administrators only
  - 3 = Full members only
  - 4 = Moderators only
  - 6 = Nobody
  Changes: Nobody added as an option in Zulip 7.0 (feature level 159).
  
  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.
- new_stream_announcements_stream_id: integer
  
  The ID of the channel to which automated messages announcing the creation of new channels are sent.
  
  Will be -1 if such automated messages are disabled.
  
  Since these automated messages are sent by the server, this field is primarily relevant to clients containing UI for changing it.
  
  Changes: In Zulip 9.0 (feature level 241), renamed notifications_stream_id to new_stream_announcements_stream_id.
- org_type: integer
  
  The organization type for the realm.
  - 0 = Unspecified
  - 10 = Business
  - 20 = Open-source project
  - 30 = Education (non-profit)
  - 35 = Education (for-profit)
  - 40 = Research
  - 50 = Event or conference
  - 60 = Non-profit (registered)
  - 70 = Government
  - 80 = Political group
  - 90 = Community
  - 100 = Personal
  - 1000 = Other
  Changes: New in Zulip 6.0 (feature level 128).
- plan_type: integer
  
  The plan type of the organization.
  - 1 = Self-hosted organization (SELF_HOSTED)
  - 2 = Zulip Cloud free plan (LIMITED)
  - 3 = Zulip Cloud Standard plan (STANDARD)
  - 4 = Zulip Cloud Standard plan, sponsored for free (STANDARD_FREE)
- presence_disabled: boolean
  
  Whether online presence of other users is shown in this organization.
- require_unique_names: boolean
  
  Indicates whether the organization is configured to require users to have unique full names. If true, the server will reject attempts to create a new user, or change the name of an existing user, where doing so would lead to two users whose names are identical modulo case and unicode normalization.
  
  Changes: New in Zulip 9.0 (feature level 246). Previously, the Zulip server could not be configured to enforce unique names.
- send_welcome_emails: boolean
  
  Whether or not this organization is configured to send the standard Zulip welcome emails to new users joining the organization.
- signup_announcements_stream_id: integer
  
  The ID of the channel to which automated messages announcing that new users have joined the organization are sent.
  
  Will be -1 if such automated messages are disabled.
  
  Since these automated messages are sent by the server, this field is primarily relevant to clients containing UI for changing it.
  
  Changes: In Zulip 9.0 (feature level 241), renamed signup_notifications_stream_id to signup_announcements_stream_id.
- zulip_update_announcements_stream_id: integer
  
  The ID of the channel to which automated messages announcing new features or other end-user updates about the Zulip software are sent.
  
  Will be -1 if such automated messages are disabled.
  
  Since these automated messages are sent by the server, this field is primarily relevant to clients containing UI for changing it.
  
  Changes: New in Zulip 9.0 (feature level 242).
- 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.
- jitsi_server_url: string | null
  
  The URL of the custom Jitsi Meet server configured in this organization's settings.
  
  null, the default, means that the organization is using the should use the server-level configuration, server_jitsi_server_url.
  
  Changes: New in Zulip 8.0 (feature level 212). Previously, this was only available as a server-level configuration, and required a server restart to change.
- 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 channels.
  - 1 = Any user can use wildcard mentions in large channels.
  - 2 = Only members can use wildcard mentions in large channels.
  - 3 = Only full members can use wildcard mentions in large channels.
  - 5 = Only organization administrators can use wildcard mentions in large channels.
  - 6 = Nobody can use wildcard mentions in large channels.
  - 7 = Only organization administrators and moderators can use wildcard mentions in large channels.
  All users will receive a warning/reminder when using mentions in large channels, even when permitted to do so.
  
  Changes: New in Zulip 4.0 (feature level 33). Moderators option added in Zulip 4.0 (feature level 62). Channel 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).
- enable_guest_user_indicator: boolean
  
  Whether clients should display "(guest)" after the names of guest users to prominently highlight their status.
  
  Changes: New in Zulip 8.0 (feature level 216).
- can_access_all_users_group: integer
  
  The ID of the user group whose members are allowed to access all users in the organization.
  
  This setting can currently only be set to "role:everyone" system group.
  
  Changes: New in Zulip 8.0 (feature level 225).
- push_notifications_enabled: boolean
  
  Whether push notifications are enabled for this organization. Typically true for Zulip Cloud and self-hosted realms that have a valid registration for the Mobile push notifications service, and false for self-hosted servers that do not.
  
  Changes: New in Zulip 8.0 (feature level 231). Previously, this value was never updated via events.
- push_notifications_enabled_end_timestamp: integer | null
  
  If the server expects the realm's push notifications access to end at a definite time in the future, the time at which this is expected to happen. Mobile clients should use this field to display warnings to users when the indicated timestamp is near.
  
  Changes: New in Zulip 8.0 (feature level 231).

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
}

drafts op: add

Event containing details of newly created drafts.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
drafts: (object)[]

An array containing objects for the newly created drafts.
- id: integer
  
  The unique ID of the draft. It will only used whenever the drafts are fetched. This field should not be specified when the draft is being created or edited.
- type: string
  
  The type of the draft. Either unaddressed (empty string), "stream", or "private" (for one-on-one and group direct messages).
- to: (integer)[]
  
  An array of the tentative target audience IDs. For channel messages, this should contain exactly 1 ID, the ID of the target channel. For direct messages, this should be an array of target user IDs. For unaddressed drafts, this is ignored, and clients should send an empty array.
- topic: string
  
  For channel message drafts, the tentative topic name. For direct or unaddressed messages, this will be ignored and should ideally be the empty string. Should not contain null bytes.
- content: string
  
  The body of the draft. Should not contain null bytes.
- timestamp: integer
  
  A Unix timestamp (seconds only) representing when the draft was last edited. When creating a draft, this key need not be present and it will be filled in automatically by the server.

Example

{
    "drafts": [
        {
            "content": "Hello there!",
            "id": 17,
            "timestamp": 15954790200,
            "to": [
                6
            ],
            "topic": "",
            "type": "private"
        }
    ],
    "op": "add",
    "type": "drafts"
}

drafts op: update

Event containing details for an edited draft.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
draft: object

A dictionary for representing a message draft.
- id: integer
  
  The unique ID of the draft. It will only used whenever the drafts are fetched. This field should not be specified when the draft is being created or edited.
- type: string
  
  The type of the draft. Either unaddressed (empty string), "stream", or "private" (for one-on-one and group direct messages).
- to: (integer)[]
  
  An array of the tentative target audience IDs. For channel messages, this should contain exactly 1 ID, the ID of the target channel. For direct messages, this should be an array of target user IDs. For unaddressed drafts, this is ignored, and clients should send an empty array.
- topic: string
  
  For channel message drafts, the tentative topic name. For direct or unaddressed messages, this will be ignored and should ideally be the empty string. Should not contain null bytes.
- content: string
  
  The body of the draft. Should not contain null bytes.
- timestamp: integer
  
  A Unix timestamp (seconds only) representing when the draft was last edited. When creating a draft, this key need not be present and it will be filled in automatically by the server.

Example

{
    "draft": {
        "content": "Hello everyone!",
        "id": 17,
        "timestamp": 15954790200,
        "to": [
            6,
            7,
            8,
            9,
            10
        ],
        "topic": "",
        "type": "private"
    },
    "op": "update",
    "type": "drafts"
}

drafts op: remove

Event containing the ID of a deleted draft.

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
draft_id: integer

The ID of the draft that was just deleted.

Example

{
    "draft_id": 17,
    "op": "remove",
    "type": "drafts"
}

scheduled_messages op: add

Event sent to a user's clients when scheduled messages are created.

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

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
scheduled_messages: (object)[]

An array of objects containing details of the newly created scheduled messages.
- scheduled_message_id: integer
  
  The unique ID of the scheduled message, which can be used to modify or delete the scheduled message.
  
  This is different from the unique ID that the message will have after it is sent.
- type: string
  
  The type of the scheduled message. Either "stream" or "private".
- to: integer | (integer)[]
  
  The scheduled message's tentative target audience.
  
  For channel messages, it will be the unique ID of the target channel. For direct messages, it will be an array with the target users' IDs.
- topic: string
  
  Only present if type is "stream".
  
  The topic for the channel message.
- content: string
  
  The content/body of the scheduled message, in text/markdown format.
- rendered_content: string
  
  The content/body of the scheduled message rendered in HTML.
- scheduled_delivery_timestamp: integer
  
  The UNIX timestamp for when the message will be sent by the server, in UTC seconds.
- failed: boolean
  
  Whether the server has tried to send the scheduled message and it failed to successfully send.
  
  Clients that support unscheduling and editing scheduled messages should display scheduled messages with "failed": true with an indicator that the server failed to send the message at the scheduled time, so that the user is aware of the failure and can get the content of the scheduled message.
  
  Changes: New in Zulip 7.0 (feature level 181).

Example

{
    "op": "add",
    "scheduled_messages": [
        {
            "content": "Hello there!",
            "failed": false,
            "rendered_content": "<p>Hello there!</p>",
            "scheduled_delivery_timestamp": 1681662420,
            "scheduled_message_id": 17,
            "to": [
                6
            ],
            "type": "private"
        }
    ],
    "type": "scheduled_messages"
}

scheduled_messages op: update

Event sent to a user's clients when a scheduled message is edited.

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

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
scheduled_message: object

Object containing details of the scheduled message.
- scheduled_message_id: integer
  
  The unique ID of the scheduled message, which can be used to modify or delete the scheduled message.
  
  This is different from the unique ID that the message will have after it is sent.
- type: string
  
  The type of the scheduled message. Either "stream" or "private".
- to: integer | (integer)[]
  
  The scheduled message's tentative target audience.
  
  For channel messages, it will be the unique ID of the target channel. For direct messages, it will be an array with the target users' IDs.
- topic: string
  
  Only present if type is "stream".
  
  The topic for the channel message.
- content: string
  
  The content/body of the scheduled message, in text/markdown format.
- rendered_content: string
  
  The content/body of the scheduled message rendered in HTML.
- scheduled_delivery_timestamp: integer
  
  The UNIX timestamp for when the message will be sent by the server, in UTC seconds.
- failed: boolean
  
  Whether the server has tried to send the scheduled message and it failed to successfully send.
  
  Clients that support unscheduling and editing scheduled messages should display scheduled messages with "failed": true with an indicator that the server failed to send the message at the scheduled time, so that the user is aware of the failure and can get the content of the scheduled message.
  
  Changes: New in Zulip 7.0 (feature level 181).

Example

{
    "op": "update",
    "scheduled_message": {
        "content": "Hello there!",
        "failed": false,
        "rendered_content": "<p>Hello there!</p>",
        "scheduled_delivery_timestamp": 1681662420,
        "scheduled_message_id": 17,
        "to": [
            6
        ],
        "type": "private"
    },
    "type": "scheduled_messages"
}

scheduled_messages op: remove

Event sent to a user's clients when a scheduled message is deleted.

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

id: integer

The ID of the event. Events appear in increasing order but may not be consecutive.
type: string

The event's type, relevant both for client-side dispatch and server-side filtering by event type in POST /register.
scheduled_message_id: integer

The ID of the scheduled message that was deleted.

Example

{
    "op": "remove",
    "scheduled_message_id": 17,
    "type": "scheduled_messages"
}

Example response(s)

Changes: As of Zulip 7.0 (feature level 167), if any parameters sent in the request are not supported by this endpoint, a successful JSON response will include an ignored_parameters_unsupported array.

A typical successful JSON response may look like:

{
    "events": [
        {
            "id": 0,
            "message": {
                "avatar_url": "https://url/for/othello-bots/avatar",
                "client": "website",
                "content": "I come not, friends, to steal away your hearts.",
                "content_type": "text/x-markdown",
                "display_recipient": "Denmark",
                "id": 12345678,
                "recipient_id": 12314,
                "sender_email": "othello-bot@example.com",
                "sender_full_name": "Othello Bot",
                "sender_id": 13215,
                "sender_realm_str": "example",
                "timestamp": 1375978403,
                "topic_links": [],
                "type": "stream"
            },
            "type": "message"
        },
        {
            "id": 1,
            "message": {
                "avatar_url": "https://url/for/othello-bots/avatar",
                "client": "website",
                "content": "With mirth and laughter let old wrinkles come.",
                "content_type": "text/x-markdown",
                "display_recipient": [
                    {
                        "email": "hamlet@example.com",
                        "full_name": "Hamlet of Denmark",
                        "id": 31572
                    }
                ],
                "id": 12345679,
                "recipient_id": 18391,
                "sender_email": "othello-bot@example.com",
                "sender_full_name": "Othello Bot",
                "sender_id": 13215,
                "sender_realm_str": "example",
                "subject": "",
                "timestamp": 1375978404,
                "topic_links": [],
                "type": "private"
            },
            "type": "message"
        }
    ],
    "msg": "",
    "queue_id": "fb67bf8a-c031-47cc-84cf-ed80accacda8",
    "result": "success"
}

BAD_EVENT_QUEUE_ID errors

This error occurs if the target event queue has been garbage collected. A compliant client will handle this error by re-initializing itself (e.g. a Zulip web app browser window will reload in this case).

See the /register endpoint docs for details on how to handle these correctly.

The following is the error response in such case:

{
    "code": "BAD_EVENT_QUEUE_ID",
    "msg": "Bad event queue ID: fb67bf8a-c031-47cc-84cf-ed80accacda8",
    "queue_id": "fb67bf8a-c031-47cc-84cf-ed80accacda8",
    "result": "error"
}

Zulip homepage

API documentation home

Integrations

Interactive bots (beta)

REST API

Messages

Scheduled messages

Drafts

Channels

Users

Invitations

Server & organizations

Real-time events

Specialty endpoints

Back to Zulip

Get events from an event queue

Usage examples

Parameters

Response

Return values

Events by type

alert_words

update_display_settings

update_global_notifications

user_settings op: update

realm_user op: update

subscription op: add

subscription op: remove

subscription op: update

subscription op: peer_add

subscription op: peer_remove

message

has_zoom_token

invites_changed

realm_user op: add

realm_user op: remove

presence

stream op: create

stream op: delete

stream op: update

reaction op: add

reaction op: remove

attachment op: add

attachment op: update

attachment op: remove

submessage

user_status

custom_profile_fields

default_stream_groups

default_streams

delete_message

muted_topics

user_topic

muted_users

heartbeat

onboarding_steps

update_message

typing op: start

typing op: stop

update_message_flags op: add

update_message_flags op: remove

user_group op: add

user_group op: update

user_group op: add_members

user_group op: remove_members

user_group op: add_subgroups

user_group op: remove_subgroups

user_group op: remove

realm_linkifiers

realm_filters

realm_playgrounds

realm_emoji op: update

realm_domains op: add

realm_domains op: change

realm_domains op: remove

realm_export

realm_bot op: add

realm_bot op: update

realm_bot op: remove

realm_bot op: delete

Events by `type`