Get events from an event queue
GET https://oscafrica.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://oscafrica.zulipchat.com/api/v1/events \
-u BOT_EMAIL_ADDRESS:BOT_API_KEY \
--data-urlencode queue_id=1375801870:2942 \
--data-urlencode last_event_id=-1
Parameters
queue_id 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
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://oscafrica.zulipchat.com/api/v1/register endpoint, you could pass the parameters for
the https://oscafrica.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
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
}
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.
Example
{
"type": "update_global_notifications",
"notification_name": "enable_sounds",
"setting": true
}
Event sent generally to all users in an organization for changes
in the set of users or those users metadata.
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
}
Event sent to a user's clients when that user's stream subscriptions
have changed (either the set of subscriptions or their properties).
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
}
Event sent to a user's clients when that user has been unsubscribed
from one or more streams.
Example
{
"type": "subscription",
"op": "remove",
"subscriptions": [
{
"name": "test_stream",
"stream_id": 9
}
],
"id": 0
}
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 users have been subscribed to
streams. Sent to all users if the stream is public or to only
the existing subscribers if the stream is private.
Example
{
"type": "subscription",
"op": "peer_add",
"stream_id": 9,
"user_id": 12,
"id": 0
}
subscription op: peer_remove
Event sent to other users when users have been unsubscribed
from streams. Sent to all users if the stream is public or to only
the existing subscribers if the stream is private.
Example
{
"type": "subscription",
"op": "peer_remove",
"stream_id": 9,
"user_id": 12,
"id": 0
}
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
}
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
}
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
}
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.
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
}
Event sent to all users in a Zulip organization when
a user is deactivated.
Example
{
"type": "realm_user",
"op": "remove",
"person": {
"user_id": 35,
"full_name": "Foo Bot"
},
"id": 0
}
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.
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
}
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.
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
}
Event sent to all users who can see a stream when it is deactivated.
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
}
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
}
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
}
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
}
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
}
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
}
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
}
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
}
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.
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
}
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.
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
}
Event sent to all users in a Zulip organization when the
default streams in the organization are changed by an
organization administrator.
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
}
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
}
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
}
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.
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
}
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
}
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).
-
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.
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
}
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).
-
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.
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
}
Event sent to users in an organization when a user group is created.
Example
{
"type": "user_group",
"op": "add",
"group": {
"name": "backend",
"members": [
12
],
"description": "Backend team",
"id": 2
},
"id": 0
}
Event sent to all users in a Zulip organization
when a property of a user group is 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.
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.
Example
{
"type": "user_group",
"op": "remove_members",
"group_id": 2,
"user_ids": [
10
],
"id": 0
}
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
}
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
}
Event sent to all users in a Zulip organization when
a custom emoji has been updated,
typically when it has been deactivated.
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
}
Event sent to all users in a Zulip organization when the set of
allowed domains for new users
has changed.
Example
{
"type": "realm_domains",
"op": "add",
"realm_domain": {
"domain": "zulip.org",
"allow_subdomains": false
},
"id": 0
}
Event sent to all users in a Zulip organization when the set of
allowed domains for new users
has changed.
Example
{
"type": "realm_domains",
"op": "change",
"realm_domain": {
"domain": "zulip.org",
"allow_subdomains": true
},
"id": 0
}
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
}
Event sent to the user who requested a data export
when the status of the export changes.
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
}
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.
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
}
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.
Example
{
"type": "realm_bot",
"op": "update",
"bot": {
"user_id": 37,
"services": [
{
"base_url": "http://hostname.domain2.com",
"interface": 2,
"token": "grr8I2APXRmVL0FRTMRYAE4DRPQ5Wlaw"
}
]
},
"id": 0
}
Event sent to all users when a bot has been deactivated.
Example
{
"type": "realm_bot",
"op": "remove",
"bot": {
"user_id": 35,
"full_name": "Foo Bot"
},
"id": 1
}
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.
Example
{
"type": "realm_bot",
"op": "delete",
"bot": {
"user_id": 35,
"full_name": "Foo Bot"
},
"id": 1
}
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.
Example
{
"type": "realm",
"op": "update",
"property": "disallow_disposable_email_addresses",
"value": false,
"id": 0
}
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.
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.