Zulip real_time_events API
The real_time_events API from Zulip — 4 operation(s) for real_time_events.
OpenAPI Specification
openapi: 3.0.1
info:
version: 1.0.0
title: Zulip REST authentication real_time_events API
description: 'Powerful open source group chat
'
contact:
url: https://zulip.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://{subdomain}.zulipchat.com/api/v1
variables:
subdomain:
default: example
- url: '{server}/api/v1'
variables:
server:
default: https://
- url: https://chat.zulip.org/api/v1
- url: http://localhost:9991/api/v1
- url: http://{subdomain}.testserver/json
security:
- basicAuth: []
tags:
- name: real_time_events
paths:
/events:
get:
operationId: get-events
summary: Get events from an event queue
tags:
- real_time_events
description: 'This endpoint allows you to receive new events from
[a registered event queue](/api/register-queue).
Long-lived clients should use the
`event_queue_longpoll_timeout_seconds` property returned by
`POST /register` as the client-side HTTP request timeout for
calls to this endpoint. It is guaranteed to be higher than
heartbeat timeout and should be respected by clients to
avoid breaking when heartbeat timeout increases.
'
x-curl-examples-parameters:
oneOf:
- type: include
parameters:
enum:
- queue_id
- last_event_id
x-parameter-description: "!!! warn \"\"\n\n **Note**: The parameters documented above are optional in the sense that\n even if you haven't registered a queue by explicitly requesting the\n `POST /register` endpoint, you could pass the parameters for\n [the `POST /register` endpoint](/api/register-queue) to this\n endpoint and a queue would be registered in the absence of a `queue_id`.\n"
x-python-examples-extra-imports:
- sys
parameters:
- $ref: '#/components/parameters/QueueId'
- name: last_event_id
in: query
description: 'The highest event ID in this queue that you''ve received and
wish to acknowledge. See the [code for
`call_on_each_event`](https://github.com/zulip/python-zulip-api/blob/main/zulip/zulip/__init__.py)
in the [zulip Python
module](https://github.com/zulip/python-zulip-api) for an
example implementation of correctly processing each event
exactly once.
'
schema:
type: integer
example: -1
- name: dont_block
in: query
description: '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.
'
schema:
type: boolean
default: false
example: true
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccessBase'
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
events:
type: array
description: '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.
'
items:
oneOf:
- type: object
description: 'Event sent to a user''s clients when that user''s set of configured
[alert words](/help/dm-mention-alert-notifications#alert-words) have changed.
'
properties:
id:
$ref: '#/components/schemas/EventIdSchema'
type:
allOf:
- $ref: '#/components/schemas/EventTypeSchema'
- enum:
- alert_words
alert_words:
type: array
description: 'An array of strings, where each string is an alert word (or phrase)
configured by the user.
'
items:
type: string
additionalProperties: false
example:
type: alert_words
alert_words:
- alert_word
id: 0
- type: object
description: 'Event sent to a user''s clients when that user''s settings have changed.
**Changes**: In Zulip 12.0 (feature level 439), the deprecated, legacy
`update_display_settings` and `update_global_notifications` event types
were removed entirely. All clients should be using this event type for
updates to a user''s settings.
New in Zulip 5.0 (feature level 89), replaced and deprecated the
`update_display_settings` and `update_global_notifications` event types.
'
properties:
id:
$ref: '#/components/schemas/EventIdSchema'
type:
allOf:
- $ref: '#/components/schemas/EventTypeSchema'
- enum:
- user_settings
op:
type: string
enum:
- update
property:
type: string
description: 'Name of the changed setting.
'
value:
description: 'New value of the changed setting.
'
oneOf:
- type: boolean
- type: integer
- type: string
language_name:
description: 'Present only if the setting to be changed is
`default_language`. Contains the name of the
new default language in English.
'
type: string
additionalProperties: false
example:
type: user_settings
op: update
property: high_contrast_mode
value: false
id: 0
- type: object
description: 'Event sent generally to all users who can access the modified
user for changes in the set of users or those users metadata.
**Changes**: Prior to Zulip 8.0 (feature level 228), this event
was sent to all users in the organization.
'
properties:
id:
$ref: '#/components/schemas/EventIdSchema'
type:
allOf:
- $ref: '#/components/schemas/EventTypeSchema'
- enum:
- realm_user
op:
type: string
enum:
- update
person:
description: 'Object containing the changed details of the user.
It has multiple forms depending on the value changed.
**Changes**: Removed `is_billing_admin` field in Zulip 10.0
(feature level 363), as it was replaced by the
`can_manage_billing_group` realm setting.
'
oneOf:
- type: object
description: 'When a user changes their full name.
'
properties:
user_id:
type: integer
description: 'The ID of modified user.
'
full_name:
type: string
description: 'The new full name for the user.
'
additionalProperties: false
- type: object
description: 'When a user changes their avatar.
'
properties:
user_id:
type: integer
description: 'The ID of the user who is affected by this change.
'
avatar_url:
type: string
description: 'The URL of the new avatar for the user.
'
avatar_source:
type: string
description: 'The new avatar data source type for the user. Valid values are:
- "G" = Hosted by Gravatar
- "J" = Generated using Jdenticon
- "U" = Uploaded by user
**Changes**: The "J" value is new in Zulip 12.0 (feature level 466).
'
avatar_url_medium:
type: string
description: 'The new medium-size avatar URL for user.
'
avatar_version:
type: integer
description: 'The version number for the user''s avatar. This is useful
for cache-busting.
'
additionalProperties: false
- type: object
additionalProperties: false
description: 'When a user changes their [profile time zone](/help/change-your-timezone).
'
properties:
user_id:
type: integer
description: 'The ID of modified user.
'
email:
type: string
description: 'The Zulip API email of the user.
**Deprecated**: This field will be removed in a future
release as it is redundant with the `user_id`.
'
deprecated: true
timezone:
type: string
description: 'The IANA identifier of the new profile time zone for the user.
'
- type: object
additionalProperties: false
description: 'When the owner of a bot changes.
'
properties:
user_id:
type: integer
description: 'The ID of the user/bot whose owner has changed.
'
bot_owner_id:
type: integer
description: 'The user ID of the new bot owner.
'
- type: object
additionalProperties: false
description: 'When the [role](/help/user-roles) of a user changes.
'
properties:
user_id:
type: integer
description: 'The ID of the user affected by this change.
'
role:
type: integer
description: 'The new [role](/api/roles-and-permissions) of the user.
'
enum:
- 100
- 200
- 300
- 400
- 600
- type: object
additionalProperties: false
description: 'When the value of a user''s delivery email as visible to you changes,
either due to the email address changing or your access to the user''s
email changing via an update to their `email_address_visibility`
setting.
**Changes**: Prior to Zulip 7.0 (feature level 163), this event was
sent only to the affected user, and this event would only be triggered
by changing the affected user''s delivery email.
'
properties:
user_id:
type: integer
description: 'The ID of the user affected by this change.
'
delivery_email:
type: string
nullable: true
description: 'The new delivery email of the user.
This value can be `null` if the affected user
changed their `email_address_visibility` setting
such that you cannot access their real email.
**Changes**: Before Zulip 7.0 (feature level 163),
`null` was not a possible value for this event as
it was only sent to the affected user when their
email address was changed.
'
- type: object
additionalProperties: false
description: 'When the user updates one of their custom profile
fields.
'
properties:
user_id:
type: integer
description: 'The ID of the user affected by this change.
'
custom_profile_field:
type: object
additionalProperties: false
description: 'Object containing details about the custom
profile data change.
'
properties:
id:
type: integer
description: 'The ID of the custom profile field which user updated.
'
value:
type: string
nullable: true
description: 'User''s personal value for this custom profile field,
or `null` if unset.
'
rendered_value:
type: string
description: '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.
See [Markdown message formatting](/api/message-formatting) for details on Zulip''s HTML format.
'
- type: object
additionalProperties: false
description: 'When the Zulip API email address of a user changes,
either due to the user''s email address changing, or
due to changes in the user''s
[email address visibility][help-email-visibility].
[help-email-visibility]: /help/configure-email-visibility
'
properties:
user_id:
type: integer
description: 'The ID of the user affected by this change.
'
new_email:
type: string
description: 'The new value of `email` for the user. The client
should update any data structures associated
with this user to use this new value as the
user''s Zulip API email address.
'
- type: object
additionalProperties: false
description: 'When a user is deactivated or reactivated. Only
users who can access the modified user under the
organization''s `can_access_all_users_group` policy
will receive this event.
Clients receiving a deactivation event should
remove the user from all user groups in their data
structures, because deactivated users cannot be
members of groups.
**Changes**: Prior to Zulip 10.0 (feature level
303), reactivation events were sent to users who
could not access the reactivated user due to a
`can_access_all_users_group` policy. Also,
previously, Clients were not required to update
group membership records during user deactivation.
New in Zulip 8.0 (feature level 222). Previously the server
sent a `realm_user` event with `op` field set to `remove`
when deactivating a user and a `realm_user` event with `op`
field set to `add` when reactivating a user.
'
properties:
user_id:
type: integer
description: 'The ID of the user affected by this change.
'
is_active:
type: boolean
description: 'A boolean describing whether the user account has been deactivated.
'
- type: object
additionalProperties: false
description: 'When an imported user logs into the organization for
the first time.
**Changes**: New in Zulip 12.0 (feature level 433).
'
properties:
user_id:
type: integer
description: 'The ID of the user affected by this change.
'
is_imported_stub:
type: boolean
description: This value is always `false`.
- type: object
additionalProperties: false
description: 'Sent when the `date_joined` value is updated after an
imported stub user or a user created via the API logs
in for the first time.
**Changes**: New in Zulip 12.0 (feature level 475).
'
properties:
user_id:
type: integer
description: 'The ID of the user affected by this change.
'
date_joined:
type: string
description: 'The time when the user logged in to their account
for the first time.
'
additionalProperties: false
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
- type: object
description: 'Event sent to a user''s clients when that user''s channel subscriptions
have changed (either the set of subscriptions or their properties).
'
properties:
id:
$ref: '#/components/schemas/EventIdSchema'
type:
allOf:
- $ref: '#/components/schemas/EventTypeSchema'
- enum:
- subscription
op:
type: string
enum:
- add
subscriptions:
type: array
description: 'A list of dictionaries where each dictionary contains
information about one of the subscribed channels.
**Changes**: Removed `email_address` field from the dictionary
in Zulip 8.0 (feature level 226).
Removed `role` field from the dictionary
in Zulip 6.0 (feature level 133).
'
items:
$ref: '#/components/schemas/Subscription'
additionalProperties: false
example:
type: subscription
op: add
subscriptions:
- name: test
stream_id: 9
is_archived: false
creator_id: null
description: ''
rendered_description: ''
invite_only: false
is_web_public: false
stream_post_policy: 1
history_public_to_subscribers: true
first_message_id: null
folder_id: 1
is_recently_active: true
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
stream_weekly_traffic: null
can_add_subscribers_group: 2
can_remove_subscribers_group: 2
can_subscribe_group: 2
subscribers:
- 10
id: 0
- type: object
description: 'Event sent to a user''s clients when that user has been unsubscribed
from one or more channels.
'
properties:
id:
$ref: '#/components/schemas/EventIdSchema'
type:
allOf:
- $ref: '#/components/schemas/EventTypeSchema'
- enum:
- subscription
op:
type: string
enum:
- remove
subscriptions:
type: array
description: 'A list of dictionaries, where each dictionary contains
information about one of the newly unsubscribed channels.
'
items:
type: object
additionalProperties: false
description: 'Dictionary containing details about the unsubscribed channel.
'
properties:
stream_id:
type: integer
description: 'The ID of the channel.
'
name:
type: string
description: 'The name of the channel.
'
additionalProperties: false
example:
type: subscription
op: remove
subscriptions:
- name: test
stream_id: 9
id: 0
- type: object
description: 'Event sent to a user''s clients when a property of the user''s
subscription to a channel has been updated. This event is used
only for personal properties like `is_muted` or `pin_to_top`.
See the [`stream op: update` event](/api/get-events#stream-update)
for updates to global properties of a channel.
'
properties:
id:
$ref: '#/components/schemas/EventIdSchema'
type:
allOf:
- $ref: '#/components/schemas/EventTypeSchema'
- enum:
- subscription
op:
type: string
enum:
- update
stream_id:
type: integer
description: 'The ID of the channel whose subscription details have changed.
'
property:
type: string
description: 'The property of the subscription which has changed. For details on the
various subscription properties that a user can change, see
[POST /users/me/subscriptions/properties](/api/update-subscription-settings).
Clients should generally handle an unknown property received here without
crashing, since that will naturally happen when connecting to a Zulip
server running a new version that adds a new subscription property.
**Changes**: As of Zulip 6.0 (feature level 139), updates to the `is_muted`
property or the deprecated `in_home_view` property will send two `subscription`
update events, one for each property, to support clients fully migrating to
use the `is_muted` property. Prior to this feature level, updates to either
# --- truncated at 32 KB (720 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zulip/refs/heads/main/openapi/zulip-real-time-events-api-openapi.yml