Get events from an event queue

GET https://team.webramz.com/api/v1/events

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

Usage examples

#!/usr/bin/env python

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:
print(client.get_events(
    queue_id="1515010080:4",
    last_event_id=-1
))

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://team.webramz.com/api/v1/events \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode queue_id=1375801870:2942 \
    --data-urlencode last_event_id=-1

Parameters

Note: The parameters documented above are optional in the sense that even if you haven't registered a queue by explicitly requesting the https://team.webramz.com/api/v1/register endpoint, you could pass the parameters for the https://team.webramz.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

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

Event sent to a user's clients when that user's display settings 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.

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

Event sent to a user's clients when that user's notification settings 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.

• notification_name: string Name of the changed notification setting.

• setting: boolean | integer | string New value of the changed setting.

Example

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

Event sent 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 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 timezone 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 timezone 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 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.

Example

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

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

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

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

• subscriptions: (object)[] A list of dictionaries where each dictionary contains information about one of the subscribed streams.

  • stream_id: integer The unique ID of a stream.

  • name: string The name of a stream.

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

  • rendered_description: string A short description of a 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.

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

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

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

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

• subscriptions: (object)[] A list of dictionaries, where each dictionary contains information about one of the newly unsubscribed streams.

  • stream_id: integer The ID of the stream.

  • name: string The name of the stream.

Example

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

Event sent to a user's clients when a property of the user's subscription to a stream has been updated. This event is used only for personal properties like is_muted; 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
}

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
}

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

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

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

• stream_ids: (integer)[] The IDs of the streams from which the users have been unsubscribed from.

• user_ids: (integer)[] The IDs of the users who have been unsubscribed.

Example

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

Event type for messages.

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

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

• message: object Object containing details of the message.

  • avatar_url: string 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.

  • 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

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

    • 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 Dictionary with data on the user who added the reaction, including the user ID as the id field. Note: In the events API, this user dictionary confusing had the user ID in a field called user_id instead. We recommend ignoring fields other than the user ID. Deprecated and to be removed in a future release once core clients have migrated to use the user_id field.

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

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

  • submessages: (string)[] Data used for certain experimental Zulip integrations.

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

  • type: string The type of the message: stream or private.

• flags: (string)[] The user's message flags for the message.

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

Example

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

Event sent to a user's clients when the user completes the OAuth flow for the Zoom integration. Clients need to know whether initiating Zoom OAuth is required before creating a Zoom call.

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

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

• value: boolean A boolean specifying whether the user has zoom token or not.

Example

{
    "id": 0,
    "type": "has_zoom_token",
    "value": true
}

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

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

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

Example

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

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

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

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

• person: object A dictionary containing basic data on a given Zulip user.

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

  • role: integer Organization-level role) of the user. Poosible 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 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 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_bot": false,
        "is_guest": false,
        "is_owner": false,
        "profile_data": {},
        "role": 400,
        "timezone": "",
        "user_id": 38
    },
    "type": "realm_user"
}

Event sent to all users in a Zulip organization when a user is deactivated.

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

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

• person: object Object containing details of the deactivated user.

  • user_id: integer The ID of the deactivated user.

  • full_name: string The full name of the user.

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

Example

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

Event sent to all users in an organization when a user comes back online after being 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
}

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

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

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.

Example

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

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

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

• 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 Dictionary with data on the user who added the reaction, including the user ID as the id field. Note: In the events API, this user dictionary confusing had the user ID in a field called user_id instead. We recommend ignoring fields other than the user ID. Deprecated and to be removed in a future release once core clients have migrated to use the user_id field.

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

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.

• 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 Dictionary with data on the user who added the reaction, including the user ID as the id field. Note: In the events API, this user dictionary confusing had the user ID in a field called user_id instead. We recommend ignoring fields other than the user ID. Deprecated and to be removed in a future release once core clients have migrated to use the user_id field.

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

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
}

Event sent 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
}

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
}

Event sent when a submessage is added to a message.

Submessages are an experimental API used for widgets such as the /poll widget in Zulip.

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

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

• msg_type: string The type of the message.

• content: string The new content of the submessage.

• message_id: integer The ID of the message to which the submessage has been added.

• sender_id: integer The ID of the user who sent the message.

• submessage_id: integer The ID of the submessage.

Example

{
    "content": "{\"type\":\"vote\",\"key\":\"58,1\",\"vote\":1}",
    "id": 28,
    "message_id": 970461,
    "msg_type": "widget",
    "sender_id": 58,
    "submessage_id": 4737,
    "type": "submessage"
}

Event sent to all users in a Zulip organization when the status of a user changes.

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

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

• away: boolean Whether the user has marked themself "away".

• status_text: string The text content of the status message.

• user_id: integer The ID of the user whose status changed.

Example

{
    "away": true,
    "id": 0,
    "status_text": "out to lunch",
    "type": "user_status",
    "user_id": 10
}

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

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

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

• fields: (object)[] An array of dictionaries where each dictionary contains details of a single new custom profile field for the Zulip organization.

  • id: integer The ID of the custom profile field. This will be referenced in 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"
}

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

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

Event sent when a message has been deleted. Sent to all users who received the 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.

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

• recipient_id: integer Only present for private messages.

  The ID of the user (or group of users) who received the private message.

• sender_id: integer Only present for private messages.

  The ID of the user who sent the private message.

• 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",
    "recipient_id": 10,
    "sender_id": 8,
    "type": "delete_message"
}

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

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

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

• muted_topics: ((string | integer)[])[] Array of tuples, where each tuple describes a muted topic. The first element of 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"
}

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

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 webapp may want to handle these events.

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

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

• hotspots: (object)[] An array of dictionaries where each dictionary contains details about a single hotspot.

  • delay: number The delay after which the user should be shown the hotspot.

  • name: string The name of the hotspot.

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

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

Example

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

Event sent when a message has been edited. 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 The ID of the user who sent the message.

• message_id: integer The ID of the message which was edited.

  This field should be used to apply content edits to the client's cached message history. 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.

• edit_timestamp: integer The time when this message edit operation was processed by the server.

• stream_name: string Only present if the message was 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 originally sent to a stream.

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

• new_stream_id: integer Note: 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 The choice the editing user made about which messages should be affected by a stream/topic edit: just the one indicated in message_id, messages in the same topic that had been sent after this one, or 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 webapp 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 The pre-edit topic for all of the messages with IDs in message_ids.

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

• subject: string The post-edit topic for all of the messages with IDs in message_ids.

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

• topic_links: (object)[] 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.

  Only present if this event moved messages to a different 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 The original content of the message with ID message_id immediately prior to this edit, in the original markdown.

• orig_rendered_content: string The original content of the message with ID message_id immediately prior to this edit, rendered as HTML.

• prev_rendered_content_version: integer The Markdown processor version number for the pre-edit message.

  Clients should ignore this field.

• content: string The new content of the message with ID message_id, in the original Markdown.

• rendered_content: string The new content of the message with ID message_id, rendered in HTML.

• is_me_message: boolean Whether the message with ID message_id is now a /me status message.

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

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>",
    "stream_id": 5,
    "stream_name": "Verona",
    "subject": "new_topic",
    "topic_links": [],
    "type": "update_message",
    "user_id": 10
}

Event sent when a user starts typing a message.

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

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

See the typing endpoint docs for more details.

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

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

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

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

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

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

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

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

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.

Example

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

Event sent to users in an organization when a user group is created.

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

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

• group: object Object containing the user group's attributes.

  • name: string The name of the user group.

  • description: string The description of the user group.

  • members: (integer)[] Array containing the id of the users who are members of this user group.

  • id: integer The ID of the user group.

Example

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

Event sent to all users in a Zulip organization when a property of a user group is changed.

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

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

• group_id: integer The ID of the user group whose details have changed.

• data: object Dictionary containing the changed details of the user group.

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

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

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

Event sent to all users when a user group has been deleted.

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

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

• group_id: integer The ID of the group which has been deleted.

Example

{
    "group_id": 2,
    "id": 0,
    "op": "remove",
    "type": "user_group"
}

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

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

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

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

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

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

• realm_linkifiers: (object)[] Array of dictionaries where each dictionary contains details about a single realm linkifier.

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

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

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

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

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

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

Example

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

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

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

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

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

• realm_playgrounds: (object)[] An array of dictionaries where each dictionary contains data about a single playground entry.

  • id: integer The unique ID for the realm playground.

  • name: string The user-visible display name of the playground. Clients should display this in UI for picking which playground to open a code block in, to differentiate between multiple configured playground options for a given pygments language.

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

  • pygments_language: string The name of the Pygments language lexer for that programming language.

  • url_prefix: string The url prefix for the playground.

Example

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

Event sent to all users in a Zulip organization when a custom emoji has been updated, typically when a new emoji has been added or an old one has been deactivated. The event contains all custom emoji configured for the organization, not just the updated custom emoji.

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

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

• realm_emoji: object An object in which each key describes a realm emoji.

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

    • deactivated: boolean Whether the emoji has been deactivated or not.

    • author_id: integer 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"
}

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

Event sent to all users in a Zulip organization when the set of allowed domains for new users has changed.

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

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

• realm_domain: object Object containing details of the edited domain.

  • domain: string The domain whose settings have changed.

  • allow_subdomains: boolean Whether subdomains are allowed for this domain.

Example

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

Event sent to all users in a Zulip organization when the set of allowed domains for new users has changed.

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

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

• domain: string The domain to be removed.

Example

{
    "domain": "zulip.org",
    "id": 0,
    "op": "remove",
    "type": "realm_domains"
}

Event sent to the user who requested a data export when the status of the export changes.

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

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

• exports: (object)[] An array of dictionaries where each dictionary contains data about a single organization export request.

  • id: integer The id of the export.

  • acting_user_id: integer The id of the user who did the export.

  • export_time: number The UNIX timestamp of when the export was made.

  • deleted_timestamp: number The timestamp of when the export was deleted. Null if it wasn't.

  • failed_timestamp: number The timestamp of when the export failed. Null if it didn't.

  • export_url: string The URL of the export. null if there's no URL.

  • pending: boolean Whether the export is pending or not.

Example

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

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

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

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

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

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

• bot: object Object containing details of a bot.

  • user_id: integer The user id of the bot.

  • full_name: string The full name of the bot.

  • api_key: string The API key of the bot which it uses to make API requests.

  • default_sending_stream: string The default sending stream of the bot. Null if the bot doesn't have a default sending stream.

  • default_events_register_stream: string 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 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 An integer describing the type of bot:

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

  • is_active: boolean A boolean describing whether the user account has been deactivated.

Example

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

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

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

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

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

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

• bot: object Object containing details about the changed bot. It contains two properties: the user id of the bot and the property to be changed. The changed property is one of the remaining properties listed below.

  • user_id: integer The user id of the bot.

  • full_name: string The full name of the bot.

  • api_key: string The API key of the bot which it uses to make API requests.

  • default_sending_stream: string The default sending stream of the bot. Null if the bot doesn't have a default sending stream.

  • default_events_register_stream: string 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 The user id of the bot's owner.

    Null if the bot has no owner.

  • services: (object | object)[] The "Services" array contains extra configuration fields only relevant for Outgoing webhook bots and Embedded bots. It is always a single-element array.

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

Example

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

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

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

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

• bot: object Object containing details about the deactivated bot.

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

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

Event sent to all users in a Zulip organization when the configuration of the organization (realm) 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.

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

Event sent to all users in a Zulip organization when the organization (realm) is deactivated. Its main purpose is to flush active longpolling connections so clients can immediately show the organization as deactivated.

Clients cannot rely on receiving this event, because they will no longer be able to authenticate to the Zulip API due to the deactivation, and thus can miss it if they did not have an active longpolling connection at the moment of deactivation.

Correct handling of realm deactivations requires that clients parse authentication errors from GET /events; if that is done correctly, the client can ignore this event type and rely on its handling of the GET /events request it will do immediately after processing this batch of events.

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

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

• realm_id: integer The ID of the deactivated realm.

Example

{
    "id": 0,
    "op": "deactivated",
    "realm_id": 2,
    "type": "realm"
}

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

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

Clients can use this event to know when they should get a new event queue after a server upgrade. Clients doing so must implement a random delay strategy to spread such restarts over 10 minutes or more to avoid creating a synchronized thundering herd effect.

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

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

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

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

• zulip_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_version": "4.0-dev+git"
}

Event sent to all users in a Zulip organization when the configuration of the organization (realm) has changed.

Unlike realm / update, 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.

• data: object An object containing the properties that have changed.

  • add_emoji_by_admins_only: boolean Whether the organization is configured to only allow administrators to upload new custom emoji.

  • allow_edit_history: boolean Whether this organization is configured to allow users to access message edit history.

  • allow_message_deleting: boolean Whether messages can be deleted in this Zulip organization.

  • bot_creation_policy: integer The policy for which users can create bot users in this organization.

  • create_stream_policy: integer The policy for which users can create streams in this organization.

  • invite_to_stream_policy: integer The policy for which users can add other users to streams in this organization.

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

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

  • default_language: string The default UI language for new users joining this organization.

  • default_twenty_four_hour_time: boolean Whether new members of this organization will see times displayed in 24-hour time (true) or 12-hour time (false).

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

  • realm_giphy_rating: integer Maximum rating of the GIFs that will be retrieved from GIPHY.

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

  • digest_emails_enabled: boolean Whether the organization has enabled weekly digest emails.

  • disallow_disposable_email_addresses: boolean Whether the organization disallows disposable email addresses.

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

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

  • invite_required: boolean Whether an invitation is required to join this organization.

  • invite_to_realm_policy: integer Policy for who can invite new users to join the organization:

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

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

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

  • mandatory_topics: boolean Whether topics are required for messages in this organization.

  • message_retention_days: integer The default message retention policy for this organization. Pass "forever" to request that messages by retained forever (the default).

  • realm_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 this type of account information an external user database like LDAP.

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

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

  • send_welcome_emails: boolean Whether or not this organization is configured to send the standard Zulip welcome emails to new users joining the 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.

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

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

  • private_message_policy: integer Policy for who can send private messages in this organization.

    • 1 = Everyone
    • 2 = Nobody

  • 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

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

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

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

  • allow_message_editing: boolean Whether this organizations message edit policy allows editing the content of messages.

  • allow_community_topic_editing: boolean Whether community topic editing is enabled in this organization.

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

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

  • icon_url: string The URL of the organization's profile icon.

  • 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_file_size: integer The maximum file size allowed for the organization's icon. Useful for UI allowing editing the organization's icon.

  • logo_url: string The URL of the organization's wide logo configured in the organization profile.

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

  • night_logo_url: string The URL of the organization's night theme wide-format logo configured in the organization profile.

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

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

  • max_logo_file_size: integer The maximum file size allowed for the uploaded organization logos.

  • bot_domain: string The fake email domain that will be used for new bots created this organization. Useful for UI for creating bots.

  • realm_uri: string The URL for the organization.

  • available_video_chat_providers: object Dictionary where each entry describes a supported video call provider that is configured on this server and could be selected by an organization administrator.

    Useful for administrative settings UI that allows changing the video call provider.

    • {provider_name}: object Dictionary containing the details of the video call provider with the name of the chat provider as the key.

      • name: string The name of the video call provider.

      • id: integer The ID of the video call provider.

  • presence_disabled: boolean Whether online presence of other users is shown in this organization.

  • settings_send_digest_emails: boolean Whether this Zulip server is configured to allow organizations to enable digest emails.

    Relevant for administrative settings UI that can change the digest email settings.

  • is_zephyr_mirror_realm: boolean Whether the organization is a Zephyr mirror realm.

  • email_auth_enabled: boolean Whether the organization has enabled Zulip's default email and password authentication feature. Determines whether Zulip stores a password for the user and clients should offer any UI for changing the user's Zulip password.

  • password_auth_enabled: boolean Whether the organization allows any sort of password-based authentication (whether via EmailAuthBackend or LDAP passwords).

    Determines whether a client might ever need to display a password prompt (clients will primarily look at this attribute in server_settings before presenting a login page).

  • push_notifications_enabled: boolean Whether push notifications are enabled for this organization. Typically false for self-hosted servers that have not configured the Mobile push notifications service.

  • upload_quota: integer The total quota for uploaded files in this organization.

    Clients are not responsible for checking this quota; it is included in the API only for display purposes.

    Null if there is no limit.

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

  • zulip_plan_is_not_limited: boolean Whether the organization is using a limited (Zulip Cloud Free) plan.

  • upgrade_text_for_wide_organization_logo: string Text to use when displaying UI for wide organization logos, a feature that is currently not available on the Zulip Cloud Free plan.

    Useful only for clients supporting administrative UI for uploading a new wide organization logo to brand the organization.

  • default_external_accounts: object Dictionary where each entry describes a default external account type that can be configured with Zulip's custom profile fields feature.

    • {site_name}: object Dictionary containing the details of the default external account provider with the name of the website as the key.

      • name: string The name of the external account provider

      • text: string The text describing the external account.

      • hint: string The help text to be displayed for the custom profile field in user-facing settings UI for configuring custom profile fields for this account.

      • url_pattern: string The regex pattern of the URL of a profile page on the external site.

  • jitsi_server_url: string The base URL the organization uses to create Jitsi video calls.

  • development_environment: boolean Whether this Zulip server is a development environment. Used to control certain features or UI (such as error popups) that should only apply when connected to a Zulip development environment.

  • server_generation: integer A timestamp indicating when the process hosting this event queue was started. Clients will likely only find this value useful for inclusion in detailed error reports.

  • password_min_length: integer This Zulip server's configured minimum required length for passwords. Necessary for password change UI to show whether the password will be accepted.

  • password_min_guesses: integer This Zulip server's configured minimum zxcvbn minimum guesses. Necessary for password change UI to show whether the password will be accepted.

  • max_file_upload_size_mib: integer The maximum file size that can be uploaded to this Zulip server.

  • max_avatar_file_size_mib: integer The maximum avatar size that can be uploaded to this Zulip server.

  • server_inline_image_preview: boolean Whether the server is configured with support for inline image previews. Clients containing administrative UI for changing realm_inline_image_preview should consult this field before offering that feature.

  • server_inline_url_embed_preview: boolean Whether the server is configured with support for inline URL previews. Clients containing administrative UI for changing realm_inline_url_embed_preview should consult this field before offering that feature.

  • server_avatar_changes_disabled: boolean Whether the server allows avatar changes. Similar to realm_avatar_changes_disabled but based on the AVATAR_CHANGES_DISABLED Zulip server level setting.

  • server_name_changes_disabled: boolean Whether the server allows name changes. Similar to realm_name_changes_disabled but based on the NAME_CHANGES_DISABLED Zulip server level setting.

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

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

Example

{
    "data": {
        "allow_community_topic_editing": false,
        "allow_message_editing": false,
        "message_content_edit_limit_seconds": 0
    },
    "id": 0,
    "op": "update_dict",
    "property": "default",
    "type": "realm"
}

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

If the target event queue has been garbage collected, you'll get the following error response:

{
    "code": "BAD_EVENT_QUEUE_ID",
    "msg": "Bad event queue id: 1518820930:1",
    "queue_id": "1518820930:1",
    "result": "error"
}

A compliant client will handle this error by re-initializing itself (e.g. a Zulip webapp browser window will reload in this case).

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