Get events from an event queue
GET https://chat.convergenceservices.in/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
# arguments, 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((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);
});
});
curl -G https://chat.convergenceservices.in/api/v1/events \
-u BOT_EMAIL_ADDRESS:BOT_API_KEY
-d "queue_id=1375801870:2942" \
-d "last_event_id=-1"
Arguments
Argument |
Example |
Required |
Description |
queue_id |
"1375801870:2942" |
No |
The ID of a queue that you registered via POST /api/v1/register (see Register a queue). |
last_event_id |
-1 |
No |
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 |
No |
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 arguments documented above are optional in the sense that
even if you haven't registered a queue by explicitly requesting the
https://chat.convergenceservices.in/api/v1/register
endpoint, you could pass the arguments for
the https://chat.convergenceservices.in/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 (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": "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",
"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": "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,
"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"
}
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 uKnowva Messenger webapp browser window will reload in this case).
See the /register endpoint docs for details on how to
handle these correctly.