Home

Integrations

Interactive bots (beta)

REST API

Messages

Streams

Users

Server & organizations

Real-time events

Specialty endpoints

Back to Zulip

Register an event queue

POST https://zulip.dioco.io/api/v1/register

This powerful endpoint can be used to register a Zulip "event queue" (subscribed to certain types of "events", or updates to the messages and other Zulip data the current user has access to), as well as to fetch the current state of that data.

(register also powers the call_on_each_event Python API, and is intended primarily for complex applications for which the more convenient call_on_each_event API is insufficient).

This endpoint returns a queue_id and a last_event_id; these can be used in subsequent calls to the "events" endpoint to request events from the Zulip server using long-polling.

The server will queue events for up to 10 minutes of inactivity. After 10 minutes, your event queue will be garbage-collected. The server will send heartbeat events every minute, which makes it easy to implement a robust client that does not miss events unless the client loses network connectivity with the Zulip server for 10 minutes or longer.

Once the server garbage-collects your event queue, the server will return an error with a code of BAD_EVENT_QUEUE_ID if you try to fetch events from the event queue. Your software will need to handle that error condition by re-initializing itself (e.g. this is what triggers your browser reloading the Zulip webapp when your laptop comes back online after being offline for more than 10 minutes).

When prototyping with this API, we recommend first calling register with no event_types parameter to see all the available data from all supported event types. Before using your client in production, you should set appropriate event_types and fetch_event_types filters so that your client only requests the data it needs. A few minutes doing this often saves 90% of the total bandwidth and other resources consumed by a client using this API.

See the events system developer documentation if you need deeper details about how the Zulip event queue system works, avoids clients needing to worry about large classes of potentially messy races, etc.

Usage examples

  • Python
  • JavaScript
  • curl

#!/usr/bin/env python3

import zulip

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

# Register the queue
result = client.register(
    event_types=['message', 'realm_emoji'],
)
print(result)

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) => {
    // Register a queue
    const params = {
        event_types: ["message"],
    };

    return await client.queues.register(params);
}).then(console.log).catch(console.err);


curl -sSX POST https://zulip.dioco.io/api/v1/register \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode event_types='["message"]'

Parameters

apply_markdown optional

Example: True

Set to true if you would like the content to be rendered in HTML format (otherwise the API will return the raw text that the user entered)

Defaults to false.

client_gravatar optional

Example: True

Whether the client supports computing gravatars URLs. If enabled, avatar_url will be included in the response only if there is a Zulip avatar, and will be null for users who are using gravatar as their avatar. This option significantly reduces the compressed size of user data, since gravatar URLs are long, random strings and thus do not compress well. The client_gravatar field is set to true if clients can compute their own gravatars.

Defaults to false.

slim_presence optional

Example: True

Setting this to true will make presence dictionaries be keyed by user_id instead of email.

Changes: New in Zulip 3.0 (Unstable with no feature level yet).

Defaults to false.

event_types optional

Example: ["message"]

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 to users in the organization and their properties, such as their name).

If you do not specify this parameter, 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']

all_public_streams optional

Example: True

Set to True if you would like to receive events that occur within all public streams.

Defaults to false.

include_subscribers optional

Example: True

Whether each returned stream object should include a subscribers field containing a list of the user IDs of its subscribers.

(This may be significantly slower in organizations with thousands of users subscribed to many streams.)

Changes: New in Zulip 2.1.0.

Defaults to false.

client_capabilities optional

Example: {"notification_settings_null": true}

Dictionary containing details on features the client supports that are relevant to the format of responses sent by the server.

  • notification_settings_null: Boolean for whether the client can handle the current API with null values for stream-level notification settings (which means the stream is not customized and should inherit the user's global notification settings for stream messages). New in Zulip 2.1.0; in earlier Zulip releases, stream-level notification settings were simple booleans.

  • bulk_message_deletion: Boolean for whether the client's handler for the delete_message event type has been updated to process the new bulk format (with a message_ids, rather than a singleton message_id). Otherwise, the server will send delete_message events in a loop. New in Zulip 3.0 (feature level 13). This capability is for backwards-compatibility; it will be required in a future server release.

  • user_avatar_url_field_optional: Boolean for whether the client required avatar URLs for all users, or supports using GET /avatar/{user_id} to access user avatars. If the client has this capability, the server may skip sending a avatar_url field in the realm_user at its sole discretion to optimize network performance. This is an important optimization in organizations with 10,000s of users. New in Zulip 3.0 (feature level 18).

fetch_event_types optional

Example: ["message"]

Same as the event_types parameter except that the values in fetch_event_types are used to fetch initial data. If fetch_event_types is not provided, event_types is used and if event_types is not provided, this parameter defaults to None.

narrow optional

Example: [["stream", "Denmark"]]

A JSON-encoded array of arrays 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 [].

Response

Return values

  • queue_id: The ID of the queue that has been allocated for your client.

  • last_event_id: The initial value of last_event_id to pass to GET /api/v1/events.

  • zulip_feature_level: The server's current Zulip feature level.

  • zulip_version: The server's version.

Example response

A typical successful JSON response may look like:

{
    "last_event_id": -1,
    "msg": "",
    "queue_id": "1517975029:0",
    "realm_emoji": {
        "1": {
            "author_id": 5,
            "deactivated": false,
            "id": "1",
            "name": "green_tick",
            "source_url": "/user_avatars/1/emoji/images/1.png"
        }
    },
    "result": "success",
    "zulip_feature_level": 2,
    "zulip_version": "2.1.0"
}