{% extends "zerver/portico.html" %} {# API information page #} {% block portico_content %}

We hear you like APIs...

We have a well-documented API that allows you to build custom integrations, in addition to our existing integrations. For ease-of-use, we've created a Python module that you can drop in to a project to start interacting with our API. There is also a JavaScript library that can be used either in the browser or in Node.js.

Don't want to make it yourself? Zulip already integrates with lots of services.


Download Python bindings and examplesVersion 0.2.5

 

Installation instructions

Python

This package uses distutils, so you can just run python setup.py install after downloading.

If you have setuptools installed on your system then the application's dependencies will be downloaded and installed automatically from PyPI. Otherwise, you'll need to make sure you have these Python libraries installed:

 

JavaScript

Install it with npm:

npm install zulip-js

Usage examples

No download required!

{# These code snippets are generated using our very own Zulip tool, by sending them to myself in a code block, and then using the inspector to pull out the resulting HTML :) #}

Stream message

curl {{ external_api_uri_subdomain }}/v1/messages \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    -d "type=stream" \
    -d "to=Denmark" \
    -d "subject=Castle" \
    -d "content=Something is rotten in the state of Denmark."

Private message

curl {{ external_api_uri_subdomain }}/v1/messages \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    -d "type=private" \
    -d "to=hamlet@example.com" \
    -d "content=I come not, friends, to steal away your hearts."
#!/usr/bin/env python

import zulip
import sys

# Keyword arguments 'email' and 'api_key' are not required if you are using ~/.zuliprc
client = zulip.Client(email="othello-bot@example.com",
                      api_key="a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5",
                      site="{{ external_api_uri_subdomain }}")
# Send a stream message
client.send_message({
    "type": "stream",
    "to": "Denmark",
    "subject": "Castle",
    "content": "Something is rotten in the state of Denmark."
})
# Send a private message
client.send_message({
    "type": "private",
    "to": "hamlet@example.com",
    "content": "I come not, friends, to steal away your hearts."
})

# 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"))

You can use zulip-send (found in bin/ in the tarball) to easily send Zulips from the command-line, providing the message to be sent on STDIN.

Stream message

zulip-send --stream Denmark --subject Castle \
--user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5{% if api_site_required %} \
--site={{ external_api_uri_subdomain }}{% endif %}

Private message

zulip-send hamlet@example.com \
--user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5{% if api_site_required %} \
--site={{ external_api_uri_subdomain }}{% endif %}

Passing in the message on the command-line

If you'd like, you can also provide the message on the command-line with the -m flag, as follows:

zulip-send --stream Denmark --subject Castle \
-m "Something is rotten in the state of Denmark." \
--user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5{% if api_site_required %} \
--site={{ external_api_uri_subdomain }}{% endif %}

You can omit the user{% if api_site_required %}, api-key, and site{% else %} and api-key{% endif %} arguments if you have a ~/.zuliprc file.

See also the full API endpoint documentation.

More examples and documentation can be found here.

const zulip = require('zulip');

const config = {
  username: 'othello-bot@example.com',
  apiKey: 'a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5',
  realm: '{{ external_api_uri_subdomain }}'
};

const client = zulip(config);

// Send a message
client.messages.send({
  to: 'Denmark',
  type: 'stream',
  subject: 'Castle',
  content: 'Something is rotten in the state of Denmark.'
});

// Send a private message
client.messages.send({
  to: 'hamlet@example.com',
  type: 'private',
  content: 'I come not, friends, to steal away your hearts.'
});

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

 

API keys

You can create bots on your settings page. Once you have a bot, you can use its email and API key to send messages.

Create a bot:

Look for the bot's email and API key:

If you prefer to send messages as your own user, you can also find your API key on your settings page.

When using our python bindings, you may either specify the user and API key for each Client object that you initialize, or let the binding look for them in your ~/.zuliprc, the default config file, which you can create as follows:

[api]
key=BOT_API_KEY
email=BOT_EMAIL_ADDRESS
{% if api_site_required %}site={{ external_api_uri_subdomain }}{% endif %}

Additionally, you can also specify the parameters as environment variables as follows:

export ZULIP_CONFIG=/path/to/zulipconfig
export ZULIP_EMAIL=BOT_EMAIL_ADDRESS
export ZULIP_API_KEY=BOT_API_KEY

The parameters specified in environment variables would override the parameters provided in the config file. For example, if you specify the variable key in the config file and specify ZULIP_API_KEY as an environment variable, the value of ZULIP_API_KEY would be considered.

The following variables can be specified:
1. ZULIP_CONFIG
2. ZULIP_API_KEY
3. ZULIP_EMAIL
4. ZULIP_SITE
5. ZULIP_CERT
6. ZULIP_CERT_KEY
7. ZULIP_CERT_BUNDLE

{% endblock %}