Get events from an event queue

GET https://hyperfoil.zulipchat.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
))

call_on_each_message and call_on_each_event will automatically register a queue for you.

More examples and documentation can be found here.

const Zulip = require('zulip-js');

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

Zulip(config).then(async (client) => {
    // Retrieve events from a queue with given "queue_id"
    const eventParams = {
        queue_id,
        last_event_id: -1,
    };

    return await client.events.retrieve(eventParams);
}).then(console.log).catch(console.err);

curl -sSX GET -G https://hyperfoil.zulipchat.com/api/v1/events \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    -d 'queue_id=1375801870:2942' \
    -d 'last_event_id=-1'

Parameters

queue_id required

Example: 1375801870:2942

The ID of an event queue that was previously registered via POST /api/v1/register (see Register a queue).


last_event_id optional

Example: -1

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


dont_block optional

Example: True

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

Defaults to false.


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

  • handler_id: An internal field that should not be present in these API responses.

    Deprecated: This will be removed in a future release.

Events

alert_words

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

  • alert_words: Array of strings, each a configured alert word.

Example

{
    "type": "alert_words",
    "alert_words": [
        "alert_word"
    ],
    "id": 0
}

update_display_settings

Event sent to a user's clients when that user's display settings have changed.

  • setting_name: Name of the changed display setting.

  • setting: New value of the changed setting.

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

Example

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

update_global_notifications

Event sent to a user's clients when that user's notification settings have changed.

  • notification_name: Name of the changed notification setting.

  • setting: New value of the changed setting.

Example

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

realm_user op: update

Event sent generally to all users in an organization for changes in the set of users or those users metadata.

  • person: 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: The ID of modified user.

      • full_name: The new full name for the user.

    • When a user changes their avatar.

      • user_id: The ID of the user who is affected by this change.

      • avatar_url: The url of the new avatar URL for the user.

      • avatar_source: The new avatar data source type for the user.

        Value values are G (gravatar) and U (uploaded by user).

      • avatar_url_medium: The new medium-size avatar URL for user.

      • avatar_version: The version number for the user's avatar. This is useful for cache-busting.

    • When a user changes their timezone setting.

      • user_id: The ID of modified user.

      • email: The email of the user.

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

      • timezone: The new timezone of the user.

    • When the owner of a bot changes.

      • user_id: The ID of the user/bot whose owner has changed.

      • bot_owner_id: The user id of the new bot owner.

    • When the role of a user changes.

      • user_id: The ID of the user affected by this change.

      • role: 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: The ID of the user affected by this change.

      • delivery_email: The new delivery email of the user.

    • When the user updates one of their custom profile fields.

      • user_id: The ID of the user affected by this change.

      • custom_profile_field: Object containing details about the custom profile data change.

        • id: The ID of the custom profile field which user updated.

        • value: User's personal value for this custom profile field.

        • rendered_value: 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

{
    "type": "realm_user",
    "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
    },
    "id": 0
}

subscription op: add

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

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

    • stream_id: The unique ID of a stream.

    • name: The name of a stream.

    • description: 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: 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: The UNIX timestamp for when the stream was created, in UTC seconds.

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

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

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

    • desktop_notifications: 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: 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: 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: 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: 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: A boolean specifying whether the given stream has been pinned to the top.

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

    • is_muted: 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: Legacy property for if the given stream is muted, with inverted meeting.

      Deprecated; clients should use is_muted where available.

    • is_announcement_only: 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: Whether the stream has been configured to allow unauthenticated access to its message history from the web.

    • role: 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: The user's personal color for the stream.

    • stream_post_policy: Policy for which users can post messages to the stream.

      • 1 => Any user can post.
      • 2 => Only administrators can post.
      • 3 => Only new members can post.

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

    • message_retention_days: 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: 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: 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: 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

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

subscription op: remove

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

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

    • stream_id: The ID of the stream.

    • name: The name of the stream.

Example

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

subscription op: update

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

  • stream_id: The ID of the stream whose subscription details have changed.

  • name: The name of the stream whose subscription details have changed.

  • property: 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: The new value of the changed property.

  • email: The display email for the current user.

    Deprecated and to be removed as it serves no purpose to include this field here.

Example

{
    "op": "update",
    "type": "subscription",
    "property": "pin_to_top",
    "value": true,
    "email": "user10@zulip.testserver",
    "stream_id": 11,
    "name": "test_stream",
    "id": 0
}

subscription op: peer_add

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

  • stream_id: The ID of the stream to which the user has subscribed.

  • user_id: The ID of the user who subscribed.

Example

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

subscription op: peer_remove

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

  • stream_id: The ID of the stream from which the user has been unsubscribed from.

  • user_id: The ID of the user who has been unsubscribed.

Example

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

message

Event type for messages.

  • message: Object containing details of the message.

    • avatar_url: 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: A Zulip "client" string, describing what Zulip client sent the message.

    • content: The content/body of the message.

    • content_type: 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: 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: The unique message ID. Messages should always be displayed sorted by ID.

    • is_me_message: Whether the message is a [/me status message][status-messages]

    • reactions: Data on any reactions to the message.

      • emoji_code: 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: Name of the emoji.

      • reaction_type: 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: 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: 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: ID of the user.

        • email: Email of the user.

        • full_name: Full name of the user.

        • is_mirror_dummy: Whether the user is a mirror dummy.

    • recipient_id: A unique ID for the set of users receiving the message (either a stream or group of users). Useful primarily for hashing.

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

    • sender_full_name: The full name of the message's sender.

    • sender_id: The user ID of the message's sender.

    • sender_realm_str: 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: Only present for stream messages; the ID of the stream.

    • subject: The topic of the message (only present for stream messages). The field name is a legacy holdover from when topics were called "subjects" and will eventually change.

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

      Changes: 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.

    • submessages: Data used for certain experimental Zulip integrations.

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

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

  • flags: The user's [message flags][message-flags] for the message.

  • email_notified: Whether the user receiving the event has already been notified via email.

    Deprecated: This field is present only due to a bug and will be removed from the API.

  • push_notified: Whether the user receiving the event has already been notified via mobile notification.

    Deprecated: This field is present only due to a bug and will be removed from the API.

  • stream_push_notify: Whether the user receiving the event has to be notified via mobile notification for stream message.

    Deprecated: This field is present only due to a bug and will be removed from the API.

  • stream_email_notify: Whether the user receiving the event has to be notified via email for stream message.

    Deprecated: This field is present only due to a bug and will be removed from the API.

  • wildcard_mention_notify: Whether the user has to be notified due to wildcard mention.

    Deprecated: This field is present only due to a bug and will be removed from the API.

Example

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

has_zoom_token

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

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

Example

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

invites_changed

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

Example

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

realm_user op: add

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

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

    • email: 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: A boolean specifying whether the user is a bot or full account.

    • avatar_url: URL for the 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).

    • avatar_version: Version for the 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: Full name of the user or bot, used for all display purposes.

    • is_admin: A boolean specifying whether the user is an organization administrator.

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

    • bot_type: 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: The unique ID of the user.

    • bot_owner_id: 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: A boolean specifying whether the user account has been deactivated.

    • is_guest: A boolean specifying whether the user is a guest user.

    • timezone: The time zone of the user.

    • date_joined: The time the user account was created.

    • delivery_email: 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: 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 with data about what value user filled in the custom profile field with id id.

        • value: User's personal value for this custom profile field.

        • rendered_value: 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

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

realm_user op: remove

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

  • person: Object containing details of the deactivated user.

    • user_id: The ID of the deactivated user.

    • full_name: The full name of the user.

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

Example

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

presence

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

  • user_id: The ID of modified user.

  • email: 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: The timestamp of when the Zulip server received the user's presence as a UNIX timestamp.

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

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

      • client: The client's platform name.

      • status: The status of the user on this client. It is either idle or active.

      • timestamp: The UNIX timestamp of when this client sent the user's presence to the server with the precision of a second.

      • pushable: Whether the client is capable of showing mobile/push notifications to the user.

Example

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

stream op: add

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.

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

    • stream_id: The unique ID of the stream.

    • name: The name of the stream.

    • description: 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: The UNIX timestamp for when the stream was created, in UTC seconds.

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

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

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

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

    • stream_post_policy: Policy for which users can post messages to the stream.

      • 1 => Any user can post.
      • 2 => Only administrators can post.
      • 3 => Only new members can post.

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

    • message_retention_days: 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: 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: 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: Whether the given stream is announcement only or not.

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

Example

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

stream op: occupy

Event sent to all users who can see a stream exists when a stream that previously had no subscribers gains its first subscriber (typically when a deactivated stream is reactivated). It works very similarly to create events.

We expect to change how stream deactivation/reactivation is represented in the future.

  • streams: Array of stream objects, each contatining details about the newly occupied streams.

    • stream_id: The unique ID of the stream.

    • name: The name of the stream.

    • description: 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: The UNIX timestamp for when the stream was created, in UTC seconds.

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

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

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

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

    • stream_post_policy: Policy for which users can post messages to the stream.

      • 1 => Any user can post.
      • 2 => Only administrators can post.
      • 3 => Only new members can post.

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

    • message_retention_days: 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: 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: 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: Whether the given stream is announcement only or not.

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

Example

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

stream op: vacate

Event sent to all users who can see a stream exists when a stream no longer has any users (which deactivates the stream).

We expect to change how stream deactivation/reactivation is represented in the future.

  • streams: Array of stream objects, each containing details about a now-empty stream.

    • stream_id: The unique ID of the stream.

    • name: The name of the stream.

    • description: 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: The UNIX timestamp for when the stream was created, in UTC seconds.

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

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

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

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

    • stream_post_policy: Policy for which users can post messages to the stream.

      • 1 => Any user can post.
      • 2 => Only administrators can post.
      • 3 => Only new members can post.

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

    • message_retention_days: 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: 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: 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: Whether the given stream is announcement only or not.

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

Example

{
    "type": "stream",
    "op": "vacate",
    "streams": [
        {
            "name": "test_stream",
            "stream_id": 11,
            "description": "",
            "rendered_description": "",
            "invite_only": false,
            "is_web_public": false,
            "stream_post_policy": 1,
            "history_public_to_subscribers": true,
            "first_message_id": null,
            "message_retention_days": null,
            "is_announcement_only": false
        }
    ],
    "id": 2
}

stream op: delete

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

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

    • stream_id: The unique ID of the stream.

    • name: The name of the stream.

    • description: 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: The UNIX timestamp for when the stream was created, in UTC seconds.

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

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

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

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

    • stream_post_policy: Policy for which users can post messages to the stream.

      • 1 => Any user can post.
      • 2 => Only administrators can post.
      • 3 => Only new members can post.

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

    • message_retention_days: 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: 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: 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: Whether the given stream is announcement only or not.

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

Example

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

stream op: update

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

  • stream_id: The ID of the stream whose details have changed.

  • name: The name of the stream whose details have changed.

  • property: 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: The new value of the changed property.

  • rendered_description: 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: 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

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

reaction op: add

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

  • emoji_code: 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: Name of the emoji.

  • reaction_type: 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: 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: 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: ID of the user.

    • email: Email of the user.

    • full_name: Full name of the user.

    • is_mirror_dummy: Whether the user is a mirror dummy.

  • message_id: The ID of the message to which a reaction was added.

Example

{
    "type": "reaction",
    "op": "add",
    "user_id": 10,
    "user": {
        "user_id": 10,
        "email": "user10@zulip.testserver",
        "full_name": "King Hamlet"
    },
    "message_id": 32,
    "emoji_name": "tada",
    "emoji_code": "1f389",
    "reaction_type": "unicode_emoji",
    "id": 0
}

reaction op: remove

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

  • emoji_code: 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: Name of the emoji.

  • reaction_type: 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: 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: 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: ID of the user.

    • email: Email of the user.

    • full_name: Full name of the user.

    • is_mirror_dummy: Whether the user is a mirror dummy.

  • message_id: The ID of the message from which the reaction was removed.

Example

{
    "type": "reaction",
    "op": "remove",
    "user_id": 10,
    "user": {
        "user_id": 10,
        "email": "user10@zulip.testserver",
        "full_name": "King Hamlet"
    },
    "message_id": 52,
    "emoji_name": "tada",
    "emoji_code": "1f389",
    "reaction_type": "unicode_emoji",
    "id": 0
}

attachment op: add

Event sent to a user's clients when the user uploads a new file in a Zulip message. Useful to implement live update in UI showing all files the current user has uploaded.

  • attachment: Dictionary containing details of a file uploaded by a user.

    • id: The unique ID for the attachment.

    • name: Name of the uploaded file.

    • path_id: 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: Size of the file in bytes.

    • create_time: 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: 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: 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: The unique message ID. Messages should always be displayed sorted by ID.

  • upload_space_used: The total size of all files uploaded by in the organization, in bytes.

Example

{
    "type": "attachment",
    "op": "add",
    "attachment": {
        "id": 1,
        "name": "zulip.txt",
        "path_id": "2/ce/2Xpnnwgh8JWKxBXtTfD6BHKV/zulip.txt",
        "size": 6,
        "create_time": 1594825414000,
        "messages": []
    },
    "upload_space_used": 6,
    "id": 0
}

attachment op: update

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.

  • attachment: Dictionary containing details of a file uploaded by a user.

    • id: The unique ID for the attachment.

    • name: Name of the uploaded file.

    • path_id: 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: Size of the file in bytes.

    • create_time: 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: 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: 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: The unique message ID. Messages should always be displayed sorted by ID.

  • upload_space_used: The total size of all files uploaded by in the organization, in bytes.

Example

{
    "type": "attachment",
    "op": "update",
    "attachment": {
        "id": 1,
        "name": "zulip.txt",
        "path_id": "2/ce/2Xpnnwgh8JWKxBXtTfD6BHKV/zulip.txt",
        "size": 6,
        "create_time": 1594825414000,
        "messages": []
    },
    "upload_space_used": 6,
    "id": 0
}

attachment op: remove

Event sent to a user's clients when the user deletes a file they had uploaded. Useful primarily for UI showing all the files the current user has uploaded.

  • attachment: Dictionary containing the id of the deleted attachment.

    • id: The ID of the deleted attachment.
  • upload_space_used: The total size of all files uploaded by in the organization, in bytes.

Example

{
    "type": "attachment",
    "op": "remove",
    "attachment": {
        "id": 1
    },
    "upload_space_used": 0,
    "id": 0
}

submessage

Event sent when a submessage is added to a message.

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

  • msg_type: The type of the message.

  • content: The new content of the submessage.

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

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

  • submessage_id: The ID of the submessage.

Example

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

user_status

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

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

  • status_text: The text content of the status message.

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

Example

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

custom_profile_fields op: add

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

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

    • id: The ID of the custom profile field. This will be referenced in custom the profile fields section of user objects.

    • type: 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: Custom profile fields are displayed in both settings UI and UI showing users' profiles in increasing order.

    • name: The name of the custom profile field.

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

    • field_data: 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

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

default_stream_groups

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

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

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

    • name: Name of the default stream group.

    • description: Description of the default stream group.

    • id: id of the default stream group.

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

      • stream_id: The unique ID of the stream.

      • name: The name of the stream.

      • description: 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: The UNIX timestamp for when the stream was created, in UTC seconds.

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

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

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

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

      • stream_post_policy: Policy for which users can post messages to the stream.

        • 1 => Any user can post.
        • 2 => Only administrators can post.
        • 3 => Only new members can post.

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

      • message_retention_days: 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: 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: 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: Whether the given stream is announcement only or not.

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

Example

{
    "type": "default_stream_groups",
    "default_stream_groups": [
        {
            "name": "group1",
            "id": 2,
            "description": "New description",
            "streams": [
                {
                    "name": "Scotland",
                    "stream_id": 3,
                    "description": "Located in the United Kingdom",
                    "rendered_description": "<p>Located in the United Kingdom</p>",
                    "invite_only": false,
                    "is_web_public": false,
                    "stream_post_policy": 1,
                    "history_public_to_subscribers": true,
                    "first_message_id": 1,
                    "message_retention_days": null,
                    "is_announcement_only": false
                },
                {
                    "name": "Denmark",
                    "stream_id": 1,
                    "description": "A Scandinavian country",
                    "rendered_description": "<p>A Scandinavian country</p>",
                    "invite_only": false,
                    "is_web_public": false,
                    "stream_post_policy": 1,
                    "history_public_to_subscribers": true,
                    "first_message_id": 4,
                    "message_retention_days": null,
                    "is_announcement_only": false
                },
                {
                    "name": "Verona",
                    "stream_id": 5,
                    "description": "A city in Italy",
                    "rendered_description": "<p>A city in Italy</p>",
                    "invite_only": false,
                    "is_web_public": false,
                    "stream_post_policy": 1,
                    "history_public_to_subscribers": true,
                    "first_message_id": 6,
                    "message_retention_days": null,
                    "is_announcement_only": false
                }
            ]
        }
    ],
    "id": 0
}

default_streams

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

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

    • stream_id: The unique ID of the stream.

    • name: The name of the stream.

    • description: 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: The UNIX timestamp for when the stream was created, in UTC seconds.

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

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

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

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

    • stream_post_policy: Policy for which users can post messages to the stream.

      • 1 => Any user can post.
      • 2 => Only administrators can post.
      • 3 => Only new members can post.

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

    • message_retention_days: 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: 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: 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: Whether the given stream is announcement only or not.

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

Example

{
    "type": "default_streams",
    "default_streams": [
        {
            "name": "Scotland",
            "stream_id": 3,
            "description": "Located in the United Kingdom",
            "rendered_description": "<p>Located in the United Kingdom</p>",
            "invite_only": false,
            "is_web_public": false,
            "stream_post_policy": 1,
            "history_public_to_subscribers": true,
            "first_message_id": 1,
            "message_retention_days": null,
            "is_announcement_only": false
        }
    ],
    "id": 0
}

delete_message

Event sent when a message has been deleted. Sent to all users who received the message.

  • message_ids: 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: 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: 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: Only present for private messages.

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

  • sender_id: Only present for private messages.

    The ID of the user who sent the private message.

  • stream_id: Only present for stream messages.

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

  • topic: Only present for stream messages.

    The topic to which the message was sent.

Example

{
    "type": "delete_message",
    "recipient_id": 10,
    "sender_id": 8,
    "message_type": "private",
    "message_id": 37,
    "id": 0
}

muted_topics

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

  • muted_topics: 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

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

hotspots

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

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

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

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

    • name: The name of the hotspot.

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

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

Example

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

update_message

Event sent when a message has been edited. Sent to all users who had received the original message.

  • user_id: The ID of the user who sent the message.

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

  • edit_timestamp: The timestamp when the message was edited.

  • stream_name: Only present if the message was originally sent to a stream.

    The name of the stream that the message was sent to.

  • stream_id: Only present if the message was originally sent to a stream.

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

  • new_stream_id: Note: Only present if message(s) were moved to a different stream.

    The ID of the stream that the message was moved to.

  • orig_content: The original Markdown content of the message, before this edit.

  • orig_rendered_content: The original content of the message, before this edit, rendered as HTML.

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

  • content: The new content of the message, in the original markdown.

  • rendered_content: The new content of the message, rendered in HTML.

  • is_me_message: Whether the message is now a [/me status message][status-messages].

  • propagate_mode: Which message(s) should be edited: just the one indicated in message_id, messages in the same topic that had been sent after this one, or all of them.

  • orig_subject: The original topic of the message. Only present if the topic of the message was changed.

  • subject: The current topic of the message following the edit.

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

    Changes: 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.

  • message_ids: For edits changing the stream or topic of multiple messages, the list of IDs of other messages to be moved as well.

    The messages are guaranteed to have all been previously in the sam stream and topic.

  • flags: The user's personal [message flags][message-flags] for the message following the edit. The client should compare these to the original flags to identify cases where a mention was added by the edit.

Example

{
    "type": "update_message",
    "user_id": 10,
    "edit_timestamp": 1594825451,
    "message_id": 58,
    "stream_name": "Verona",
    "orig_content": "hello",
    "orig_rendered_content": "<p>hello</p>",
    "content": "new content",
    "rendered_content": "<p>new content</p>",
    "prev_rendered_content_version": 1,
    "is_me_message": false,
    "propagate_mode": "change_all",
    "stream_id": 5,
    "orig_subject": "test",
    "subject": "new_topic",
    "topic_links": [],
    "message_ids": [
        58,
        57
    ],
    "flags": [],
    "id": 0
}

typing op: start

Event sent when a user starts typing a private or group private message. Sent to all clients for users who would receive the message being typed.

See the typing endpoint docs for more details.

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

    • user_id: The user's ID.

    • email: The Zulip display email address for the user.

  • recipients: 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: The ID of the user.

    • email: The Zulip display email address for the user.

Example

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

typing op: stop

Event sent when a user stops typing a private or group private message. Sent to all clients for users who would receive the message that was previously being typed.

See the typing endpoint docs for more details.

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

    • user_id: The user's ID.

    • email: The Zulip display email address for the user.

  • recipients: 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: The ID of the user.

    • email: The Zulip display email address for the user.

Example

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

update_message_flags op: add

Event sent to a user when [message flags][message-flags] are added to a message.

  • operation: 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: The flag that was added.

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

  • all: 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

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

update_message_flags op: remove

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

  • operation: 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: The flag to be removed.

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

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

Example

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

user_group op: add

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

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

    • name: The name of the user group.

    • description: The description of the user group.

    • members: Array containing the id of the users who are members of this user group.

    • id: The ID of the user group.

Example

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

user_group op: update

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

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

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

    • name: The new name of the user group. Only present if the group's name changed.

    • description: The new description of the group. Only present if the description changed.

Example

{
    "type": "user_group",
    "op": "update",
    "group_id": 2,
    "data": {
        "description": "Mention this group to get the security team's attention."
    },
    "id": 0
}

user_group op: add_members

Event sent to all users when users have been added to a user group.

  • group_id: The ID of the user group with new members.

  • user_ids: Array containing the IDs of the users who have been added to the user group.

Example

{
    "type": "user_group",
    "op": "add_members",
    "group_id": 2,
    "user_ids": [
        10
    ],
    "id": 0
}

user_group op: remove_members

Event sent to all users when users have been removed from a user group.

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

  • user_ids: Array containing the IDs of the users who have been removed from the user group.

Example

{
    "type": "user_group",
    "op": "remove_members",
    "group_id": 2,
    "user_ids": [
        10
    ],
    "id": 0
}

user_group op: remove

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

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

Example

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

realm_filters

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.

  • realm_filters: 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

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

realm_emoji op: update

Event sent to all users in a Zulip organization when a custom emoji has been updated, typically when it has been deactivated.

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

    • {emoji_id}: Object containing details about the emoji with the specified ID. It has the following properties:

      • id: The ID for this emoji, same as the object's key.

      • name: The user-friendly name for this emoji. Users in the organization can use this emoji by writing this name between colons (:name :).

      • source_url: The path relative to the organization's URL where the emoji's image can be found.

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

      • author_id: 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

{
    "type": "realm_emoji",
    "op": "update",
    "realm_emoji": {
        "2": {
            "id": "2",
            "name": "my_emoji",
            "source_url": "/user_avatars/2/emoji/images/2.png",
            "deactivated": true,
            "author_id": 11
        },
        "1": {
            "id": "1",
            "name": "green_tick",
            "source_url": "/user_avatars/2/emoji/images/1.png",
            "deactivated": false,
            "author_id": 11
        }
    },
    "id": 0
}

realm_domains op: add

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

  • realm_domain: Object containing details of the newly added domain.

    • domain: The new allowed domain.

    • allow_subdomains: Whether subdomains are allowed for this domain.

Example

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

realm_domains op: change

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

  • realm_domain: Object containing details of the edited domain.

    • domain: The domain whose settings have changed.

    • allow_subdomains: Whether subdomains are allowed for this domain.

Example

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

realm_domains op: remove

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

  • domain: The domain to be removed.

Example

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

realm_export

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

  • exports: An array of dictionaries where each dictionary contains data about a single organization export request.

    • id: The id of the export.

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

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

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

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

    • export_url: The url of the export. Null if there's no url.

    • pending: Whether the export is pending or not.

Example

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

realm_bot op: add

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

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

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

  • bot: Object containing details of a bot.

    • user_id: The user id of the bot.

    • full_name: The full name of the bot.

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

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

    • default_events_register_stream: 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: Whether the bot can send messages to all streams by default.

    • avatar_url: The URL of the bot's avatar.

    • owner_id: The user id of the bot's owner.

      Null if the bot has no owner.

    • services: 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: The email of the bot.

    • bot_type: 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: A boolean describing whether the user account has been deactivated.

Example

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

realm_bot op: update

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

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

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

  • bot: 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: The user id of the bot.

    • full_name: The full name of the bot.

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

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

    • default_events_register_stream: 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: Whether the bot can send messages to all streams by default.

    • avatar_url: The URL of the bot's avatar.

    • owner_id: The user id of the bot's owner.

      Null if the bot has no owner.

    • services: 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

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

realm_bot op: remove

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

  • bot: Object containing details about the deactivated bot.

    • user_id: The user ID of the deactivated bot.

    • full_name: The full name of the deactivated bot.

Example

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

realm_bot op: delete

Event sent to all users when a bot has been deactivated. Note that this is very similar to the bot_remove event and one of them will be removed soon.

  • bot: Object containing details about the deactivated bot.

    • user_id: The user ID of the deactivated bot.

Example

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

realm op: update

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

  • property: The name of the property that was changed.

  • value: The new value of the property.

  • extra_data: Object containing extra data related to the changed property.

    • upload_quota: Note: Only present if changed property is plan_type.

      The new upload quota for the Zulip organization.

Example

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

realm op: update_dict

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.

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

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

Example

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

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": "Castle",
                "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.