# Get new events from an events queue `GET {{ api_url }}/v1/events` This endpoint allows you to receive new events from an event queue that can be created by [requesting the `{{ api_url}}/v1/register` endpoint](/api/register-queue). ## Arguments {generate_api_arguments_table|arguments.json|get-events-from-queue.md} **Note**: The arguments documented above are optional in the sense that even if you haven't registered a queue by explicitly requesting the `{{ api_url}}/v1/register` endpoint, you could pass the arguments for [the `{{ api_url}}/v1/register` endpoint](/api/register-queue) 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`: {generate_api_arguments_table|arguments.json|call_on_each_event} ## Usage examples
``` curl -G {{ api_url }}/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](https://github.com/zulip/zulip-js). ```js const zulip = require('zulip-js'); const config = { username: 'othello-bot@example.com', apiKey: 'a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5', realm: '{{ api_url }}' }; const client = zulip(config); // Register queue to receive messages for user client.queues.register({ event_types: ['message'] }).then((res) => { // Retrieve events from a queue // Blocking until there is an event (or the request times out) client.events.retrieve({ queue_id: res.queue_id, last_event_id: -1, dont_block: false }).then(console.log); }); ```
## 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: ``` { 'result':'success', 'msg':'', 'events':[ { 'type':'message', 'id':0, 'message':{ 'content_type':'text/x-markdown', 'avatar_url':'https://url/for/othello-bots/avatar', 'timestamp':1375978403, 'display_recipient':'Denmark', 'sender_id':13215, 'sender_full_name':'Othello Bot', 'sender_email':'othello-bot@example.com', 'sender_short_name':'othello-bot', 'sender_realm_str':'example', 'content':'Something is rotten in the state of Denmark.', 'recipient_id':12314, 'client':'website', 'subject_links':[ ], 'subject':'Castle', 'type':'stream', 'id':12345678, } }, { 'type':'message', 'id':1, 'message':{ 'content_type':'text/x-markdown', 'avatar_url':'https://url/for/othello-bots/avatar', 'timestamp':1375978404, 'display_recipient':[ { 'full_name':'Hamlet of Denmark', 'email':'hamlet@example.com', 'short_name':'hamlet', 'id':31572 } ], 'sender_id':13215, 'sender_full_name':'Othello Bot', 'sender_email':'othello-bot@example.com', 'sender_short_name':'othello-bot', 'sender_realm_str':'example', 'content':'I come not, friends, to steal away your hearts.', 'recipient_id':18391, 'client':'website', 'subject_links':[ ], 'subject':'', 'type':'private', 'id':12345679, } } ] } ``` {!invalid-api-key-json-response.md!}