Get new events from an events queue

GET https://omegaletter.chat/api/v1/events

This endpoint allows you to receive new events from an event queue that can be created by requesting the https://omegaletter.chat/api/v1/register endpoint.

Usage examples

Python
JavaScript
curl

curl -G https://omegaletter.chat/api/v1/events \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY
    -d "queue_id=1375801870:2942" \
    -d "last_event_id=-1"

#!/usr/bin/env python

import sys
import zulip

# Download ~/zuliprc-dev from your dev server
client = zulip.Client(config_file="~/zuliprc-dev")

# 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
# arguments, like so:
print(client.get_events(
    queue_id="1515010080:4",
    last_event_id=-1
))

# Print each message the user receives
# 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
# This will never be reached unless you comment out the previous line
client.call_on_each_event(lambda msg: sys.stdout.write(str(msg) + "\n"))

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');

// Download zuliprc-dev from your dev server
const config = {
    zuliprc: 'zuliprc-dev',
};

zulip(config).then((client) => {
    // Register queue to receive messages for user
    const queueParams = {
        event_types: ['message']
    };
    client.queues.register(queueParams).then((res) => {
        // Retrieve events from a queue
        // Blocking until there is an event (or the request times out)
        const eventParams = {
            queue_id: res.queue_id,
            last_event_id: -1,
            dont_block: false,
        };
        client.events.retrieve(eventParams).then(console.log);
    });
});

Arguments

Argument	Example	Required	Description
`queue_id`	`1375801870:2942`	Optional	The ID of a queue that you registered via `POST /api/v1/register`(see Register a queue).
`last_event_id`	`-1`	Optional	The highest event ID in this queue that you've received and wish to acknowledge. See the code for `call_on_each_event` in the zulip Python module for an example implementation of correctly processing each event exactly once.
`dont_block`	`True` or `False`	Optional	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. Default is `False`.

Note: The arguments documented above are optional in the sense that even if you haven't registered a queue by explicitly requesting the https://omegaletter.chat/api/v1/register endpoint, you could pass the arguments for the https://omegaletter.chat/api/v1/register endpoint to this endpoint and a queue would be registered in the absence of a queue_id.

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

Argument	Example	Required	Description
`narrow`	`narrow=['stream', 'Denmark']`	Optional	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']`	Optional	A JSON-encoded array indicating which types of events you're interested in. Values that you might find useful include: * messages (messages), * subscriptions (changes in your subscriptions), * realm_user (changes in the list of users in your realm), and * pointer (changes in your pointer). 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']`

Response

Return values

events: An array (possibly zero-length if dont_block is set) of events with IDs newer than last_event_id. Event IDs are guaranted to be increasing, but they are not guaranteed to be consecutive.

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": "Something is rotten in the state of Denmark.",
                "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",
                "sender_short_name": "othello-bot",
                "subject": "Castle",
                "subject_links": [],
                "timestamp": 1375978403,
                "type": "stream"
            },
            "type": "message"
        },
        {
            "id": 1,
            "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": [
                    {
                        "email": "hamlet@example.com",
                        "full_name": "Hamlet of Denmark",
                        "id": 31572,
                        "short_name": "hamlet"
                    }
                ],
                "id": 12345679,
                "recipient_id": 18391,
                "sender_email": "othello-bot@example.com",
                "sender_full_name": "Othello Bot",
                "sender_id": 13215,
                "sender_realm_str": "example",
                "sender_short_name": "othello-bot",
                "subject": "",
                "subject_links": [],
                "timestamp": 1375978404,
                "type": "private"
            },
            "type": "message"
        }
    ],
    "msg": "",
    "result": "success"
}

Home

Integrations

Writing webhook integrations

Interactive bots (beta)

REST API

Messages

Streams

Users