Get events from an event queue

GET https://z.labs.greyorange.com/api/v1/events

This endpoint allows you to receive new events from a registered event queue.

Long-lived clients should use the event_queue_longpoll_timeout_seconds property returned by POST /register as the client-side HTTP request timeout for calls to this endpoint. It is guaranteed to be higher than heartbeat frequency and should be respected by clients to avoid breaking when heartbeat frequency increases.

Usage examples

#!/usr/bin/env python3

import sys
import zulip

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

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

More examples and documentation can be found here.

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

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

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

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

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

curl -sSX GET -G https://z.labs.greyorange.com/api/v1/events \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode queue_id=1375801870:2942 \
    --data-urlencode last_event_id=-1

Parameters

queue_id string required

Example: "1375801870:2942"

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 https://z.labs.greyorange.com/api/v1/register endpoint, you could pass the parameters for the https://z.labs.greyorange.com/api/v1/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

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)[]

    Array of strings, each a configured alert word.

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.

  • setting_name: string

    Name of the changed display setting.

  • setting: boolean | integer | string

    New value of the changed setting.

  • language_name: string

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

Example

{
    "id": 0,
    "setting": false,
    "setting_name": "high_contrast_mode",
    "type": "update_display_settings"
}

update_global_notifications

Event sent to a user's clients when that user's notification settings have changed with an additional rule that it is only sent to clients that did not include user_settings_object in their client_capabilities when registering the event queue.

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

  • id: integer

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

  • type: string

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

  • notification_name: string

    Name of the changed notification setting.

  • setting: boolean | integer | string

    New value of the changed setting.

Example

{
    "id": 0,
    "notification_name": "enable_sounds",
    "setting": true,
    "type": "update_global_notifications"
}

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 in an organization for changes in the set of users or those users metadata.

  • id: integer

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

  • type: string

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

  • person: object | object | object | object | object | object | object | object | object

    Object containing the changed details of the user. It has multiple forms depending on the value changed.

    • When a user changes their full name.

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

    • When billing role of a user changes.

      • user_id: integer

        The ID of the user affected by this change.

      • is_billing_admin: boolean

        A boolean specifying whether the user is now a billing administrator.

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

    • When the delivery email of a user changes.

      Note: This event is only visible to admins.

      • user_id: integer

        The ID of the user affected by this change.

      • delivery_email: string

        The new delivery email of the user.

    • 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

          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.

    • When the Zulip display email address of a user changes, either due to the user's email address changing, or due to changes in the organization's email address visibility.

      • user_id: integer

        The ID of the user affected by this change.

      • new_email: string

        The new email of the user.

Example

{
    "id": 0,
    "op": "update",
    "person": {
        "avatar_source": "G",
        "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=3",
        "avatar_url_medium": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&s=500&version=3",
        "avatar_version": 3,
        "user_id": 10
    },
    "type": "realm_user"
}

subscription op: add

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

  • id: integer

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

  • type: string

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

  • subscriptions: (object)[]

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

    • stream_id: integer

      The unique ID of a stream.

    • name: string

      The name of a stream.

    • description: string

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

      See also rendered_description.

    • rendered_description: string

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

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

      See also description.

    • date_created: integer

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

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

    • invite_only: boolean

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

    • subscribers: (integer)[]

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

    • desktop_notifications: boolean | null

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

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

    • email_notifications: boolean | null

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

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

    • wildcard_mentions_notify: boolean | null

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

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

    • push_notifications: boolean | null

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

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

    • audible_notifications: boolean | null

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

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

    • pin_to_top: boolean

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

    • email_address: string

      Email address of the given stream, used for sending emails to the stream.

    • is_muted: boolean

      Whether the user has muted the stream. Muted streams do not count towards your total unread count and do not show up in All messages view (previously known as Home view).

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

    • in_home_view: boolean

      Legacy property for if the given stream is muted, with inverted meeting.

      Deprecated; clients should use is_muted where available.

    • is_announcement_only: boolean

      Whether only organization administrators can post to the stream.

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

    • is_web_public: boolean

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

    • role: integer

      The user's role within the stream (distinct from the user's organization-level role). Valid values are:

      • 20 => Stream administrator.
      • 50 => Subscriber.

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

    • color: string

      The user's personal color for the stream.

    • stream_post_policy: integer

      Policy for which users can post messages to the stream.

      • 1 => Any user can post.
      • 2 => Only administrators can post.
      • 3 => Only full members can post.
      • 4 => Only moderators can post.

      Changes: New in Zulip 3.0, replacing the previous is_announcement_only boolean.

    • message_retention_days: integer | null

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

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

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

    • history_public_to_subscribers: boolean

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

      Currently always true for public streams (i.e. invite_only=False implies history_public_to_subscribers=True), but clients should not make that assumption, as we may change that behavior in the future.

    • first_message_id: integer | null

      The id of the first message in the stream.

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

      Null is used for streams with no message history.

    • stream_weekly_traffic: integer | null

      The average number of messages sent to the stream in recent weeks, rounded to the nearest integer.

      Null means the stream was recently created and there is insufficient data to estimate the average traffic.

Example

{
    "id": 0,
    "op": "add",
    "subscriptions": [
        {
            "audible_notifications": null,
            "color": "#76ce90",
            "description": "",
            "desktop_notifications": null,
            "email_address": "test_stream.af64447e9e39374841063747ade8e6b0.show-sender@testserver",
            "email_notifications": null,
            "first_message_id": null,
            "history_public_to_subscribers": true,
            "in_home_view": true,
            "invite_only": false,
            "is_announcement_only": false,
            "is_muted": false,
            "is_web_public": false,
            "message_retention_days": null,
            "name": "test_stream",
            "pin_to_top": false,
            "push_notifications": null,
            "rendered_description": "",
            "stream_id": 9,
            "stream_post_policy": 1,
            "stream_weekly_traffic": null,
            "subscribers": [
                10
            ],
            "wildcard_mentions_notify": null
        }
    ],
    "type": "subscription"
}

subscription op: remove

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

  • id: integer

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

  • type: string

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

  • subscriptions: (object)[]

    A list of dictionaries, where each dictionary contains information about one of the newly unsubscribed streams.

    • stream_id: integer

      The ID of the stream.

    • name: string

      The name of the stream.

Example

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

subscription op: update

Event sent to a user's clients when a property of the user's subscription to a stream has been updated. This event is used only for personal properties like is_muted; see the stream event for global properties of a stream.

  • id: integer

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

  • type: string

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

  • stream_id: integer

    The ID of the stream whose subscription details have changed.

  • property: string

    The property of the subscription which has changed. See /users/me/subscriptions/properties GET for details on the various properties of a stream.

    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.

  • value: integer | boolean | string

    The new value of the changed property.

Example

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

subscription op: peer_add

Event sent to other users when users have been subscribed to streams. Sent to all users if the stream is public or to only the existing subscribers if the stream is private.

  • id: integer

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

  • type: string

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

  • stream_ids: (integer)[]

    The IDs of the streams to which the user has subscribed.

  • user_ids: (integer)[]

    The IDs of the users who subscribed.

Example

{
    "id": 0,
    "op": "peer_add",
    "stream_id": 9,
    "type": "subscription",
    "user_id": 12
}

subscription op: peer_remove

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

  • id: integer

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

  • type: string

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

  • stream_ids: (integer)[]

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

  • user_ids: (integer)[]

    The IDs of the users who have been unsubscribed.

Example

{
    "id": 0,
    "op": "peer_remove",
    "stream_id": 9,
    "type": "subscription",
    "user_id": 12
}

message

Event type for messages.

  • id: integer

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

  • type: string

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

  • message: object

    Object containing details of the message.

    • avatar_url: string | null

      The URL of the user's avatar. Can be null only if client_gravatar was passed, which means that the user has not uploaded an avatar in Zulip, and the client should compute the gravatar URL by hashing the user's email address itself for this user.

    • client: string

      A Zulip "client" string, describing what Zulip client sent the message.

    • content: string

      The content/body of the message.

    • content_type: string

      The HTTP content_type for the message content. This will be text/html or text/x-markdown, depending on whether apply_markdown was set.

    • display_recipient: string | (object)[]

      Data on the recipient of the message; either the name of a stream or a dictionary containing basic data on the users who received the message.

    • edit_history: (object)[]

      An array of objects, with each object documenting the changes in a previous edit made to the the message, ordered chronologically from most recent to least recent edit.

      Not present if the message has never been edited or if the realm has disabled viewing of message edit history.

      Every object will contain user_id and timestamp.

      The other fields are optional, and will be present or not depending on whether the stream, topic, and/or message content were modified in the edit event. For example, if only the topic was edited, only prev_topic and topic will be present in addition to user_id and timestamp.

      • prev_content: string

        Only present if message's content was edited.

        The content of the message immediately prior to this edit event.

      • prev_rendered_content: string

        Only present if message's content was edited.

        The rendered HTML representation of prev_content.

      • prev_rendered_content_version: integer

        Only present if message's content was edited.

        The Markdown processor version number for the message immediately prior to this edit event.

      • prev_stream: integer

        Only present if message's stream was edited.

        The stream ID of the message immediately prior to this edit event.

      • prev_topic: string

        Only present if message's topic was edited.

        The topic of the message immediately prior to this edit event.

        Changes: New in Zulip 5.0 (feature level 118). Previously, this field was called prev_subject; clients are recommended to rename prev_subject to prev_topic if present for compatibility with older Zulip servers.

      • stream: integer

        Only present if message's stream was edited.

        The ID of the stream containing the message immediately after this edit event.

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

      • timestamp: integer

        The UNIX timestamp for the edit.

      • topic: string

        Only present if message's topic was edited.

        The topic of the message immediately after this edit event.

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

      • user_id: integer | null

        The ID of the user that made the edit.

        Will be null only for edit history events predating March 2017.

        Clients can display edit history events where this is null as modified by either the sender (for content edits) or an unknown user (for topic edits).

    • id: integer

      The unique message ID. Messages should always be displayed sorted by ID.

    • is_me_message: boolean

      Whether the message is a /me status message

    • last_edit_timestamp: integer

      The UNIX timestamp for when the message was last edited, in UTC seconds.

      Not present if the message has never been edited.

    • reactions: (object)[]

      Data on any reactions to the message.

      • emoji_code: string

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

        For example, for unicode_emoji, this will be an encoding of the Unicode codepoint; for realm_emoji, it'll be the ID of the realm emoji.

      • emoji_name: string

        Name of the emoji.

      • reaction_type: string

        One of the following values:

        • unicode_emoji: Unicode emoji (emoji_code will be its Unicode codepoint).
        • realm_emoji: Custom emoji. (emoji_code will be its ID).
        • zulip_extra_emoji: Special emoji included with Zulip. Exists to namespace the zulip emoji.
      • 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

        Deprecated and to be removed in a future release once core clients have migrated to use the adjacent user_id field introduced in Zulip 3.0 (feature level 2). Clients supporting older Zulip server versions should just use the user ID below as they would the user_id field.

        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.

        • id: integer

          ID of the user.

        • email: string

          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 stream or group of users). Useful primarily for hashing.

    • sender_email: string

      The Zulip display email address of the message's sender.

    • sender_full_name: string

      The full name of the message's sender.

    • sender_id: integer

      The user ID of the message's sender.

    • sender_realm_str: string

      A string identifier for the realm the sender is in. Unique only within the context of a given Zulip server.

      E.g. on example.zulip.com, this will be example.

    • stream_id: integer

      Only present for stream messages; the ID of the stream.

    • subject: string

      The topic of the message. Currently always "" for private messages, though this could change if Zulip adds support for topics in private message conversations.

      The field name is a legacy holdover from when topics were called "subjects" and will eventually change.

    • submessages: (string)[]

      Data used for certain experimental Zulip integrations.

    • timestamp: integer

      The UNIX timestamp for when the message was sent, in UTC seconds.

    • topic_links: (object)[]

      Data on any links to be included in the topic line (these are generated by custom linkification filters that match content in the message's topic.)

      Changes: This field contained a list of urls before Zulip 4.0 (feature level 46).

      New in Zulip 3.0 (feature level 1): Previously, this field was called subject_links; clients are recommended to rename subject_links to topic_links if present for compatibility with older Zulip servers.

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

Example

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

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 to organization administrators when the set of invitations changes; this tells clients they need to refetch data from GET /invites if they are displaying UI containing active invitations.

  • id: integer

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

  • type: string

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

Example

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

realm_user op: add

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

  • id: integer

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

  • type: string

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

  • person: object

    A dictionary containing basic data on a given Zulip user.

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

    • is_bot: boolean

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

    • avatar_url: string | null

      URL for the user's avatar. Will be null if the client_gravatar query parameter was set to True and the user's avatar is hosted by the Gravatar provider (i.e. the user has never uploaded an avatar).

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

    • avatar_version: integer

      Version for the user's avatar. Used for cache-busting requests for the user's avatar. Clients generally shouldn't need to use this; most avatar URLs sent by Zulip will already end with ?v={avatar_version}.

    • full_name: string

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

    • is_admin: boolean

      A boolean specifying whether the user is an organization administrator.

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

      A boolean specifying whether the user is a billing administrator.

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

    • role: integer

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

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

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

    • 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.
    • user_id: integer

      The unique ID of the user.

    • bot_owner_id: integer | null

      If the user is a bot (i.e. is_bot is True), bot_owner 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.

    • is_active: boolean

      A boolean specifying whether the user account has been deactivated.

    • is_guest: boolean

      A boolean specifying whether the user is a guest user.

    • timezone: string

      The time zone of the user.

    • date_joined: string

      The time the user account was created.

    • delivery_email: string

      The user's real email address. This field is present only if email address visibility is limited and you are an administrator with access to real email addresses under the configured policy.

    • profile_data: object

      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 user filled in the custom profile field with id 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",
        "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 all users in a Zulip organization when a user is deactivated.

  • id: integer

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

  • type: string

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

  • person: object

    Object containing details of the deactivated user.

    • user_id: integer

      The ID of the deactivated user.

    • full_name: string

      The full name of the user.

      Deprecated: We expect to remove this field in the future.

Example

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

presence

Event sent to all users in an organization when a user comes back online after being long offline. While most presence updates happen done via polling the main presence endpoint, this event is important to avoid confusing users when someone comes online and then immediately sends a message (one wouldn't want them to still appear offline at that point!).

  • id: integer

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

  • type: string

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

  • user_id: integer

    The ID of modified user.

  • email: string

    The email of the user.

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

  • server_timestamp: number

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

  • presence: object

    An object contatining a set of objects which describe the the user's presence on various platforms.

    • {client_name}: object

      Object containing the details of the user's presence on a particular platform with the client's platform name being the object key.

      • client: string

        The client's platform name.

      • status: string

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

Example

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

stream op: create

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

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

  • id: integer

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

  • type: string

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

  • streams: (object)[]

    Array of stream objects, each containing details about the newly added stream(s).

    • stream_id: integer

      The unique ID of the stream.

    • name: string

      The name of the stream.

    • description: string

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

    • date_created: integer

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

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

    • invite_only: boolean

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

    • rendered_description: string

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

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

    • is_web_public: boolean

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

    • stream_post_policy: integer

      Policy for which users can post messages to the stream.

      • 1 => Any user can post.
      • 2 => Only administrators can post.
      • 3 => Only full members can post.
      • 4 => Only moderators can post.

      Changes: New in Zulip 3.0, replacing the previous is_announcement_only boolean.

    • message_retention_days: integer | null

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

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

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

    • history_public_to_subscribers: boolean

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

      Currently always true for public streams (i.e. invite_only=False implies history_public_to_subscribers=True), but clients should not make that assumption, as we may change that behavior in the future.

    • first_message_id: integer | null

      The id of the first message in the stream.

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

      Null is used for streams with no message history.

    • is_announcement_only: boolean

      Whether the given stream is announcement only or not.

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

Example

{
    "id": 0,
    "op": "create",
    "streams": [
        {
            "description": "",
            "first_message_id": null,
            "history_public_to_subscribers": false,
            "invite_only": true,
            "is_announcement_only": false,
            "is_web_public": false,
            "message_retention_days": null,
            "name": "private",
            "rendered_description": "",
            "stream_id": 12,
            "stream_post_policy": 1
        }
    ],
    "type": "stream"
}

stream op: delete

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

  • id: integer

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

  • type: string

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

  • streams: (object)[]

    Array of stream objects, each contatining details about a stream that was deleted.

    • stream_id: integer

      The unique ID of the stream.

    • name: string

      The name of the stream.

    • description: string

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

    • date_created: integer

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

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

    • invite_only: boolean

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

    • rendered_description: string

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

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

    • is_web_public: boolean

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

    • stream_post_policy: integer

      Policy for which users can post messages to the stream.

      • 1 => Any user can post.
      • 2 => Only administrators can post.
      • 3 => Only full members can post.
      • 4 => Only moderators can post.

      Changes: New in Zulip 3.0, replacing the previous is_announcement_only boolean.

    • message_retention_days: integer | null

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

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

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

    • history_public_to_subscribers: boolean

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

      Currently always true for public streams (i.e. invite_only=False implies history_public_to_subscribers=True), but clients should not make that assumption, as we may change that behavior in the future.

    • first_message_id: integer | null

      The id of the first message in the stream.

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

      Null is used for streams with no message history.

    • is_announcement_only: boolean

      Whether the given stream is announcement only or not.

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

Example

{
    "id": 0,
    "op": "delete",
    "streams": [
        {
            "description": "",
            "first_message_id": null,
            "history_public_to_subscribers": false,
            "invite_only": true,
            "is_announcement_only": false,
            "is_web_public": false,
            "message_retention_days": null,
            "name": "private",
            "rendered_description": "",
            "stream_id": 12,
            "stream_post_policy": 1
        }
    ],
    "type": "stream"
}

stream op: update

Event sent to all users who can see that a stream exists when a property of that stream changes.

  • id: integer

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

  • type: string

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

  • stream_id: integer

    The ID of the stream whose details have changed.

  • name: string

    The name of the stream whose details have changed.

  • property: string

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

    Clients should handle an "unknown" property received here without crashing, since that can happen when connecting to a server running a newer version of Zulip with new features.

  • value: integer | boolean | string

    The new value of the changed property.

  • rendered_description: string

    Note: Only present if the changed property was description.

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

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

  • history_public_to_subscribers: boolean

    Note: Only present if the changed property was invite_only.

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

    Currently always true for public streams (i.e. invite_only=False implies history_public_to_subscribers=True), but clients should not make that assumption, as we may change that behavior in the future.

  • is_web_public: boolean

    Note: Only present if the changed property was invite_only.

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

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

Example

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

reaction op: add

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

  • emoji_code: string

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

    For example, for unicode_emoji, this will be an encoding of the Unicode codepoint; for realm_emoji, it'll be the ID of the realm emoji.

  • emoji_name: string

    Name of the emoji.

  • reaction_type: string

    One of the following values:

    • unicode_emoji: Unicode emoji (emoji_code will be its Unicode codepoint).
    • realm_emoji: Custom emoji. (emoji_code will be its ID).
    • zulip_extra_emoji: Special emoji included with Zulip. Exists to namespace the zulip emoji.
  • 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

    Deprecated and to be removed in a future release once core clients have migrated to use the adjacent user_id field introduced in Zulip 3.0 (feature level 2). Clients supporting older Zulip server versions should just use the user ID below as they would the user_id field.

    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.

    • id: integer

      ID of the user.

    • email: string

      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_code: string

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

    For example, for unicode_emoji, this will be an encoding of the Unicode codepoint; for realm_emoji, it'll be the ID of the realm emoji.

  • emoji_name: string

    Name of the emoji.

  • reaction_type: string

    One of the following values:

    • unicode_emoji: Unicode emoji (emoji_code will be its Unicode codepoint).
    • realm_emoji: Custom emoji. (emoji_code will be its ID).
    • zulip_extra_emoji: Special emoji included with Zulip. Exists to namespace the zulip emoji.
  • 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

    Deprecated and to be removed in a future release once core clients have migrated to use the adjacent user_id field introduced in Zulip 3.0 (feature level 2). Clients supporting older Zulip server versions should just use the user ID below as they would the user_id field.

    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.

    • id: integer

      ID of the user.

    • email: string

      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 2.2 (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 2.2 (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 2.2 (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 2.2 (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 in a Zulip organization when the status of a user changes.

  • id: integer

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

  • type: string

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

  • away: boolean

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

  • status_text: string

    The text content of the status 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 custom the 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 Add 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
    • 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.

Example

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

default_stream_groups

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

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

  • id: integer

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

  • type: string

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

  • default_stream_groups: (object)[]

    An array of dictionaries where each dictionary contains details about a single default stream group.

    • name: string

      Name of the default stream group.

    • description: string

      Description of the default stream group.

    • id: integer

      id of the default stream group.

    • streams: (object)[]

      Array containing details about the streams in the default stream group.

      • stream_id: integer

        The unique ID of the stream.

      • name: string

        The name of the stream.

      • description: string

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

      • date_created: integer

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

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

      • invite_only: boolean

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

      • rendered_description: string

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

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

      • is_web_public: boolean

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

      • stream_post_policy: integer

        Policy for which users can post messages to the stream.

        • 1 => Any user can post.
        • 2 => Only administrators can post.
        • 3 => Only full members can post.
        • 4 => Only moderators can post.

        Changes: New in Zulip 3.0, replacing the previous is_announcement_only boolean.

      • message_retention_days: integer | null

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

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

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

      • history_public_to_subscribers: boolean

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

        Currently always true for public streams (i.e. invite_only=False implies history_public_to_subscribers=True), but clients should not make that assumption, as we may change that behavior in the future.

      • first_message_id: integer | null

        The id of the first message in the stream.

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

        Null is used for streams with no message history.

      • is_announcement_only: boolean

        Whether the given stream is announcement only or not.

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

Example

{
    "default_stream_groups": [
        {
            "description": "New description",
            "id": 2,
            "name": "group1",
            "streams": [
                {
                    "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
                },
                {
                    "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
                },
                {
                    "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 streams in the organization are changed by an organization administrator.

  • id: integer

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

  • type: string

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

  • default_streams: (object)[]

    An array of dictionaries where each dictionary contains details about a single default stream.

    • stream_id: integer

      The unique ID of the stream.

    • name: string

      The name of the stream.

    • description: string

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

    • date_created: integer

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

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

    • invite_only: boolean

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

    • rendered_description: string

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

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

    • is_web_public: boolean

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

    • stream_post_policy: integer

      Policy for which users can post messages to the stream.

      • 1 => Any user can post.
      • 2 => Only administrators can post.
      • 3 => Only full members can post.
      • 4 => Only moderators can post.

      Changes: New in Zulip 3.0, replacing the previous is_announcement_only boolean.

    • message_retention_days: integer | null

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

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

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

    • history_public_to_subscribers: boolean

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

      Currently always true for public streams (i.e. invite_only=False implies history_public_to_subscribers=True), but clients should not make that assumption, as we may change that behavior in the future.

    • first_message_id: integer | null

      The id of the first message in the stream.

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

      Null is used for streams with no message history.

    • is_announcement_only: boolean

      Whether the given stream is announcement only or not.

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

Example

{
    "default_streams": [
        {
            "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 received the message.

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

  • id: integer

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

  • type: string

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

  • message_ids: (integer)[]

    The message_ids property will be present for clients that support the bulk_message_deletion client capability.

    An containing the IDs of the newly deleted messages.

  • message_id: integer

    The message_id property will be present for clients that do not support the bulk_message_deletion client capability.

    The ID of the newly deleted message.

  • message_type: string

    The type of message. Either 'stream' or 'private'. The other keys present in the event, necessary to update various frontend data structures that might be tracking the message, depend on the message type.

  • stream_id: integer

    Only present for stream messages.

    The ID of the stream to which the message was sent.

  • topic: string

    Only present for stream messages.

    The topic to which the message was sent.

Example

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

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

Example

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

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

hotspots

Event sent when the set of onboarding "hotspots" to show for the current user have changed (E.g. because the user dismissed one).

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

  • id: integer

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

  • type: string

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

  • hotspots: (object)[]

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

    • delay: number

      The delay after which the user should be shown the hotspot.

    • name: string

      The name of the hotspot.

    • title: string

      The title of the hotspot, as will be displayed to the user.

    • description: string

      The description of the hotspot, as will be displayed to the user.

Example

{
    "hotspots": [
        {
            "delay": 0.5,
            "description": "Messages sent to a stream are seen by everyone subscribed to that stream. Try clicking on one of the stream links below.",
            "name": "intro_streams",
            "title": "Catch up on a stream"
        }
    ],
    "id": 0,
    "type": "hotspots"
}

update_message

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

  • id: integer

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

  • type: string

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

  • user_id: integer | null

    The ID of the user who sent the message.

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

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

  • rendering_only: boolean

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

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

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

  • message_id: integer

    The ID of the message which was edited or updated.

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

    If the stream or topic was changed, the set of moved messages is encoded in the separate message_ids field, which is guaranteed to include message_id.

  • message_ids: (integer)[]

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

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

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

    Content changes should be applied only to the single message indicated by message_id.

  • flags: (string)[]

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

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

  • edit_timestamp: integer

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

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

  • stream_name: string

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

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

  • stream_id: integer

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

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

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

  • new_stream_id: integer

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

    The post-edit stream for all of the messages with IDs in message_ids.

  • propagate_mode: string

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

    The choice the editing user made about which messages should be affected by a stream/topic edit:

    • change_one => Just change the one indicated in message_id.
    • change_later => Change messages in the same topic that had been sent after this one.
    • change_all=> Change all messages in that topic.

    This parameter should be used to decide whether to change navigation and compose box state in response to the edit. For example, if the user was previously in topic narrow, and the topic was edited with change_later or change_all, the Zulip web app will automatically navigate to the new topic narrow. Similarly, a message being composed to the old topic should have its recipient changed to the new topic.

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

  • orig_subject: string

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

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

  • subject: string

    Only present if this event moved messages to a different topic.

    The post-edit topic for all of the messages with IDs in message_ids.

  • topic_links: (object)[]

    Only present if this event moved messages to a different topic.

    Data on any links to be included in the topic line (these are generated by custom linkification filter that match content in the message's topic.), corresponding to the post-edit topic.

    Changes: This field contained a list of urls before Zulip 4.0 (feature level 46).

    New in Zulip 3.0 (feature level 1). Previously, this field was called subject_links; clients are recommended to rename subject_links to topic_links if present for compatibility with older Zulip servers.

    • 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 stream messages are only sent to clients that included stream_typing_notifications in their client_capabilities when registering the event queue.

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

See the typing endpoint docs for more details.

  • id: integer

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

  • type: string

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

  • message_type: string

    Type of message being composed. Must be "stream" or "private", as with sending a message.

    Changes: New in Zulip 4.0 (feature level 58). Previously, all typing notifications were implicitly private private.

  • sender: object

    Object describing the "sender" (i.e. the user who is typing a message).

    • user_id: integer

      The user's ID.

    • email: string

      The Zulip display email address for the user.

  • recipients: (object)[]

    Only present if message_type is private.

    Array of dictionaries describing the set of users who would be recipients of the message being typed. Each dictionary contains details on one one of the recipients users; the sending user is guaranteed to appear among the recipients.

    • user_id: integer

      The ID of the user.

    • email: string

      The Zulip display email address for the user.

  • stream_id: integer

    Only present if message_type is stream.

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

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

  • topic: string

    Only present if message_type is stream.

    Topic within the stream where the message is being typed.

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

Example

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

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 stream messages are only sent to clients that included stream_typing_notifications in their client_capabilities when registering the event queue.

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

See the typing endpoint docs for more details.

  • id: integer

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

  • type: string

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

  • message_type: string

    Type of message being composed. Must be "stream" or "private", as with sending a message.

    Changes: New in Zulip 4.0 (feature level 58). Previously, all typing notifications were implicitly private private.

  • sender: object

    Object describing the "sender" (i.e. the user who was previously typing a message).

    • user_id: integer

      The user's ID.

    • email: string

      The Zulip display email address for the user.

  • recipients: (object)[]

    Only present for typing notifications for (group) private messages.

    Array of dictionaries describing the set of users who would be recipients of the message that stopped being typed. Each dictionary contains details on one one of the recipients users; the sending user is guaranteed to appear among the recipients.

    • user_id: integer

      The ID of the user.

    • email: string

      The Zulip display email address for the user.

  • stream_id: integer

    Only present if message_type is stream.

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

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

  • topic: string

    Only present if message_type is stream.

    Topic within the stream where the message is being typed.

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

Example

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

update_message_flags op: add

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

  • id: integer

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

  • type: string

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

  • operation: string

    Old name for op for this event type.

    Deprecated: This is deprecated; please use op instead starting with Zulip 4.0 (feature level 32).

  • flag: string

    The flag that was added.

  • messages: (integer)[]

    Array containing the ids of all messages to which the flag was added.

  • all: boolean

    Whether the flag was added to all messages (E.g. all messages were marked as read). If this is true, then the messages array will be empty.

Example

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

update_message_flags op: remove

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

  • id: integer

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

  • type: string

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

  • operation: string

    Old name for op for this event type.

    Deprecated: This is deprecated; please use op instead starting with Zulip 4.0 (feature level 32).

  • flag: string

    The flag to be removed.

  • messages: (integer)[]

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

  • all: boolean

    Whether the flag was removed from all messages. If this is true then the messages array will be empty.

  • message_details: object

    Present if message and update_message_flags are both present in event_types and the flag is read and the op is remove.

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

    Changes: New in Zulip 5.0 (feature level 121). Previously, marking already read messages as unread was not supported by the Zulip API.

    • Additional properties.

      • type: string

        The type of this message.

      • mentioned: boolean

        A flag which indicates whether the message contains a mention of the user.

        Present only if the message mentions the current user.

      • user_ids: (integer)[]

        Present only if type is private.

        The user IDs of every recipient of this private message, excluding yourself. Will be the empty list for a message you had sent to only yourself.

      • stream_id: integer

        Present only if type is stream.

        The ID of the stream where the message was sent.

      • topic: string

        Present only if type is stream.

        Name of the topic where the message was sent.

      • unmuted_stream_msg: boolean

        Deprecated Internal implementation detail. Clients should ignore this field as it will be removed in the future.

Example

{
    "all": false,
    "flag": "starred",
    "id": 0,
    "message_details": {
        "63": {
            "stream_id": 22,
            "topic": "lunch",
            "type": "stream"
        }
    },
    "messages": [
        63
    ],
    "op": "remove",
    "operation": "remove",
    "type": "update_message_flags"
}

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.

    • id: integer

      The ID of the user group.

    • is_system_group: boolean

      Whether the user group is a system group which cannot be directly modified by users.

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

Example

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

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.

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: 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 to doing Markdown local echo correctly.

Changes: New in Zulip 4.0 (feature level 54), replacing the previous realm_filters event type, which is still sent for backwards compatibility reasons.

Clients should migrate to requesting and processing the realm_linkifiers event type when possible, since we plan to remove the legacy realm_filters logic entirely in a future release.

  • id: integer

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

  • type: string

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

  • realm_linkifiers: (object)[]

    Array of dictionaries where each dictionary contains details about a single realm linkifier.

    • pattern: string

      The string regex pattern which represents the pattern that should be linkified by this linkifier.

    • url_format: string

      The URL format string to be used for linkifying matches.

    • id: integer

      The ID of the linkifier.

Example

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

realm_filters

Legacy event type. Sent to all users in a Zulip organization when the set of configured linkifiers for the organization has changed.

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

  • id: integer

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

  • type: string

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

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

    An array of tuples, where each tuple describes a linkifier. The first element of the tuple is a string regex pattern which represents the pattern that should be linkified on matching. The second element is the URL with which the pattern matching string should be linkified with and the third element is the ID of the realm filter.

Example

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

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_prefix: string

      The url prefix for the playground.

Example

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

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 and 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. Null if it wasn't.

    • failed_timestamp: number | null

      The timestamp of when the export failed. Null if it didn't.

    • export_url: string | null

      The URL of the export. null if there's no URL.

    • pending: boolean

      Whether the export is pending or not.

Example

{
    "exports": [
        {
            "acting_user_id": 10,
            "deleted_timestamp": null,
            "export_time": 1594825443.656797,
            "export_url": null,
            "failed_timestamp": 1594825444.436336,
            "id": 107,
            "pending": false
        }
    ],
    "id": 1,
    "type": "realm_export"
}

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 stream of the bot. Null if the bot doesn't have a default sending stream.

    • default_events_register_stream: string | null

      The default stream for which the bot receives events/register data. Null if the bot doesn't have such a default stream.

    • default_all_public_streams: boolean

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

    • avatar_url: string

      The URL of the bot's avatar.

    • owner_id: integer | null

      The user id of the bot's owner.

      Null if the bot has no owner.

    • services: (object | object)[]

      The "Services" array contains extra configuration fields only relevant for Outgoing webhook bots and Embedded bots. It is always a single-element array.

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

    • email: string

      The email of the bot.

    • bot_type: integer | null

      An integer describing the type of bot:

      • 1 for a Generic bot.
      • 2 for an Incoming webhook bot.
      • 3 for an Outgoing webhook bot.
      • 4 for an Embedded bot.
    • is_active: boolean

      A boolean describing whether the user account has been deactivated.

Example

{
    "bot": {
        "api_key": "6hc6MC9mpNFvoo0gSOWnZEq4aJEn8UNK",
        "avatar_url": "https://secure.gravatar.com/avatar/af8abc2537d283b212a6bd4d1289956d?d=identicon&version=1",
        "bot_type": 1,
        "default_all_public_streams": false,
        "default_events_register_stream": null,
        "default_sending_stream": null,
        "email": "test-bot@zulip.testserver",
        "full_name": "Foo Bot",
        "is_active": true,
        "owner_id": 10,
        "services": [],
        "user_id": 36
    },
    "id": 1,
    "op": "add",
    "type": "realm_bot"
}

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 stream of the bot. Null if the bot doesn't have a default sending stream.

    • default_events_register_stream: string | null

      The default stream for which the bot receives events/register data. Null if the bot doesn't have such a default stream.

    • default_all_public_streams: boolean

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

    • avatar_url: string

      The URL of the bot's avatar.

    • owner_id: integer | null

      The user id of the bot's owner.

      Null if the bot has no owner.

    • services: (object | object)[]

      The "Services" array contains extra configuration fields only relevant for Outgoing webhook bots and Embedded bots. It is always a single-element array.

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

Example

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

realm_bot op: remove

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

  • id: integer

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

  • type: string

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

  • bot: object

    Object containing details about the deactivated bot.

    • 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": {
        "full_name": "Foo 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 can use this event to know when they should get a new event queue after a server upgrade. Clients doing so must implement a random delay strategy to spread such restarts over 10 minutes or more to avoid creating a synchronized thundering herd effect.

  • id: integer

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

  • type: string

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

  • zulip_version: string

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

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

  • zulip_merge_base: string

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

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

  • zulip_feature_level: integer

    The Zulip feature level of the server after the restart.

    Clients can safely avoid refetching their state and creating a new event queue when the API feature level has not changed, or when they know the specific feature level change is not relevant to the client (E.g. it just adds a new endpoint that the client doesn't use).

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

  • immediate: boolean

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

  • server_generation: integer

    The timestamp at which the server started.

Example

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

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.

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

    • add_custom_emoji_policy: integer

      The policy for which users can add custom emoji in this organization.

    • allow_edit_history: boolean

      Whether this organization is configured to allow users to access message edit history.

    • allow_message_editing: boolean

      Whether this organizations message edit policy allows editing the content of messages.

    • authentication_methods: object

      Dictionary of 'authentication_method_name': 'boolean' with each entry describing whether the authentication name can be used for authenticating into the organization.

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

      The policy for which users can create bot users in this organization.

    • community_topic_editing_limit_seconds: integer

      Messages sent more than this many seconds ago cannot have their topics edited by other users with this organization's message edit policy.

      Changes: New in Zulip 3.0 (feature level 11). Previously this value was hardcoded to 86400 seconds (1 day).

    • create_public_stream_policy: integer

      The policy for which users can create public streams in this organization.

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

    • create_private_stream_policy: integer

      The policy for which users can create private streams in this organization.

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

    • default_code_block_language: string | null

      The default pygments language code to be used for a code blocks in this organization. Null if no default has been set.

    • default_language: string

      The default language for the organization.

    • description: string

      The description of the organization, used on login and registration pages.

    • digest_emails_enabled: boolean

      Whether the organization has enabled weekly digest emails.

    • digest_weekday: integer

      The day of the week when the organization will send its weekly digest email to inactive users.

    • disallow_disposable_email_addresses: boolean

      Whether the organization disallows disposable email addresses.

    • edit_topic_policy: integer

      The policy for which users can edit topics of any message.

      • 1 = members only
      • 2 = admins only
      • 3 = full members only
      • 4 = moderators only
      • 5 = everyone

      Changes: New in Zulip 5.0 (feature level 75), replacing the previous allow_community_topic_editing boolean.

    • email_address_visibility: integer

      The policy for which users in this organization can see the real email addresses of other users.

      • 1 = everyone
      • 2 = members only
      • 3 = administrators only
      • 4 = nobody (though note that administrators can change this setting).
      • 5 = moderators only
    • email_changes_disabled: boolean

      Whether users are allowed to change their own email address in this organization. This is typically disabled for organizations that synchronize accounts from LDAP or a similar corporate database.

    • emails_restricted_to_domains: boolean

      Whether new users joining this organization are required to have an email address in one of the realm_domains configured for the organization.

    • enable_spectator_access: boolean

      Whether web-public streams are enabled in this organization.

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

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

    • giphy_rating: integer

      Maximum rating of the GIFs that will be retrieved from GIPHY.

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

    • icon_source: string

      String indicating whether the organization's profile icon was uploaded by a user or is the default. Useful for UI allowing editing the organization's icon.

      • "G" means generated by Gravatar (the default).
      • "U" means uploaded by an organization administrator.
    • icon_url: string

      The URL of the organization's profile icon.

    • inline_image_preview: boolean

      Whether this organization has been configured to enable previews of linked images.

    • inline_url_embed_preview: boolean

      Whether this organization has been configured to enable previews of linked websites.

    • invite_required: boolean

      Whether an invitation is required to join this organization.

    • invite_to_realm_policy: integer

      The policy for which users can invite other users to join the organization.

      Changes: New in Zulip 4.0 (feature level 50) replacing the previous invite_by_admins_only boolean.

    • invite_to_stream_policy: integer

      The policy for which users can add other users to streams in this organization.

    • logo_source: string

      String indicating whether the organization's profile wide logo was uploaded by a user or is the default. Useful for UI allowing editing the organization's wide logo.

      • "D" means the logo is the default Zulip logo.
      • "U" means uploaded by an organization administrator.
    • logo_url: string

      The URL of the organization's wide logo configured in the organization profile.

    • mandatory_topics: boolean

      Whether topics are required for messages in this organization.

    • message_content_allowed_in_email_notifications: boolean

      Whether notification emails in this organization are allowed to contain Zulip the message content, or simply indicate that a new message was sent.

    • message_content_delete_limit_seconds: integer | null

      Messages sent more than this many seconds ago cannot be deleted with this organization's message deletion policy.

      Will not be 0. A 'null' value means no limit: messages can be deleted regardless of how long ago they were sent.

      Changes: No limit was represented using the special value 0 before Zulip 5.0 (feature level 100).

    • message_content_edit_limit_seconds: integer

      Messages sent more than this many seconds ago cannot be edited with this organization's message edit policy.

    • move_messages_between_streams_policy: integer

      The policy for which users can move messages from one stream to another.

      • 1 = Members only
      • 2 = Administrators only
      • 3 = Full members only
      • 4 = Moderators only

      Changes: New in Zulip 4.0 (feature level 56)

    • name: string

      The name of the organization, used in login pages etc.

    • name_changes_disabled: boolean

      Indicates whether users are allowed to change their name via the Zulip UI in this organization. Typically disabled in organizations syncing this type of account information from an external user database like LDAP.

    • night_logo_source: string

      String indicating whether the organization's dark theme profile wide logo was uploaded by a user or is the default. Useful for UI allowing editing the organization's wide logo.

      • "D" means the logo is the default Zulip logo.
      • "U" means uploaded by an organization administrator.
    • night_logo_url: string

      The URL of the organization's dark theme wide-format logo configured in the organization profile.

    • notifications_stream_id: integer

      The ID of the stream to which notifications announcing the creation of new streams are sent. -1 if such notifications are disabled.

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

    • plan_type: integer

      The plan type of the organization.

      • 1 = Self-hosted organization (SELF_HOSTED)
      • 2 = Zulip Cloud free plan (LIMITED)
      • 3 = Zulip Cloud Standard plan (STANDARD)
      • 4 = Zulip Cloud Standard plan, sponsored for free (STANDARD_FREE)
    • presence_disabled: boolean

      Whether online presence of other users is shown in this organization.

    • private_message_policy: integer

      Policy for who can send private messages in this organization.

      • 1 = Everyone
      • 2 = Nobody
    • send_welcome_emails: boolean

      Whether or not this organization is configured to send the standard Zulip welcome emails to new users joining the organization.

    • signup_notifications_stream_id: integer

      The ID of the stream to which notifications announcing that new users have joined the organization are sent. -1 if such notifications are disabled.

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

    • user_group_edit_policy: integer

      The organization's policy for who can manage user groups .

      • 1 = All members can create and edit user groups
      • 2 = Only organization administrators can create and edit user groups
      • 3 = Only full members can create and edit user groups
      • 4 = Only organization administrators and moderators can create and edit user groups
    • video_chat_provider: integer

      The configured video call provider for the organization.

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

    • wildcard_mention_policy: integer

      The policy for who can use wildcard mentions in large streams.

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

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

      Changes: New in Zulip 4.0 (feature level 33). Moderators option added in Zulip 4.0 (feature level 62).

Example

{
    "data": {
        "allow_message_editing": false,
        "edit_topic_policy": 2,
        "message_content_edit_limit_seconds": 0
    },
    "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 PMs and private group messages).

    • to: (integer)[]

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

    • topic: string

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

    • content: string

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

    • timestamp: number

      A Unix timestamp (seconds only) representing when the draft was last edited. When creating a draft, this key need not be present and it will be filled in automatically by the server.

Example

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

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 PMs and private group messages).

    • to: (integer)[]

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

    • topic: string

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

    • content: string

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

    • timestamp: number

      A Unix timestamp (seconds only) representing when the draft was last edited. When creating a draft, this key need not be present and it will be filled in automatically by the server.

Example

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

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": "update",
    "type": "drafts"
}

Example response

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": "1375801870:2942",
    "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: 1518820930:1",
    "queue_id": "1518820930:1",
    "result": "error"
}