Users

Real-time events

Real-time events API

Zulip's real-time events API lets you write software that reacts
immediately to events happening in Zulip. This API is what powers the
real-time updates in the Zulip web and mobile apps. As a result, the
events available via this API cover all changes to data displayed in
the Zulip product, from new messages to stream descriptions to
emoji reactions to changes in user or organization-level settings.

Using the events API

The simplest way to use Zulip's real-time events API is by using
call_on_each_event from our Python bindings. You just need to write
a Python function (in the examples below, the lambdas) and pass it
into call_on_each_event; your function will be called whenever a new
event matching the specific event_type and/or narrow arguments
occurs in Zulip.

More complex applications (like a Zulip terminal client) may need to
instead use the raw register and
events endpoints.

Usage examples

Python

#!/usr/bin/env pythonimportsysimportzulip# Download ~/zuliprc-dev from your dev serverclient=zulip.Client(config_file="~/zuliprc-dev")# Print every message the current user would receive# This is a blocking call that will run foreverclient.call_on_each_message(lambdamsg:sys.stdout.write(str(msg)+"\n"))# Print every event relevant to the user# This is a blocking call that will run foreverclient.call_on_each_event(lambdaevent:sys.stdout.write(str(event)+"\n"))

Arguments

You may also pass in the following keyword arguments to call_on_each_event:

Argument

Example

Required

Description

narrow

"narrow=['stream', 'Denmark']"

No

A JSON-encoded array of length 2 indicating the narrow for which you'd like to receive events for. For instance, to receive events for the stream Denmark, you would specify narrow=['stream', 'Denmark']. Another example is narrow=['is', 'private'] for private messages. Default is [].

If you do not specify this argument, you will receive all events, and have to filter out the events not relevant to your client in your client code. For most applications, one is only interested in messages, so one specifies: event_types=['message']