{% 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.

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


Download Python bindings and examples Version 0.2.0

 

Installation instructions

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

 

Usage examples

No download required!

{% comment %} 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 :) {% endcomment %}

Stream message

curl https://api.zulip.com/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 https://api.zulip.com/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")

# 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

Private message

zulip-send hamlet@example.com --user othello-bot@example.com \
--api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5

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

See also the full API endpoint documentation.

 

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, which you can create as follows:

[api]
key=BOT_API_KEY
email=BOT_EMAIL_ADDRESS
{% endblock %}