Get events from an event queue
GET https://chat.fhir.org/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://chat.fhir.org/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
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://chat.fhir.org/api/v1/register endpoint, you could pass the parameters for
the https://chat.fhir.org/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
}
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.
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.
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 redunant 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 platfroms.
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 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.
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
}
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.
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
}
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
}
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.