Real-time events API

WyzePal's real-time events API lets you write software that reacts immediately to events happening in WyzePal. This API is what powers the real-time updates in the WyzePal web and mobile apps. As a result, the events available via this API cover all changes to data displayed in the WyzePal 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 WyzePal'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 WyzePal.

call_on_each_event takes care of all the potentially tricky details of long-polling, error handling, exponential backoff in retries, etc. It's cousin, call_on_each_message, provides an even simpler interface for processing WyzePal messages.

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

Usage examples

#!/usr/bin/env python

import sys
import wyzepal

# Pass the path to your wyzepalrc file here.
client = wyzepal.Client(config_file="~/wyzepalrc")

# Print every message the current user would receive
# This is a blocking call that will run forever
client.call_on_each_message(lambda msg: sys.stdout.write(str(msg) + "\n"))

# Print every event relevant to the user
# This is a blocking call that will run forever
client.call_on_each_event(lambda event: sys.stdout.write(str(event) + "\n"))


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 [].

event_types "event_types=['message']" No

A JSON-encoded array indicating which types of events you're interested in. Values that you might find useful include:

* message (messages),
* subscription (changes in your subscriptions),
* realm_user (changes in the list of users in your realm)

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']