{% extends "zephyr/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.


Download Python bindings and examples Version 0.1.9

 

Installation instructions

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

 

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

[api]
key=BOT_API_KEY
email=BOT_EMAIL_ADDRESS

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

 

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.humbughq.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.humbughq.com/v1/messages \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    -d "type=private" \
    -d "to=wdaher@example.com" \
    -d "content=I come not, friends, to steal away your hearts."

#!/usr/bin/env python

import humbug
import sys

# Keyword arguments 'email' and 'api_key' are optional if you are using ~/.humbugrc
client = humbug.Client(email="othello-bot@example.com",
                       api_key="a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5")

stream_message = {
    "type": "stream",
    "to": "Denmark",
    "subject": "Castle",
    "content": "Something is rotten in the state of Denmark."
}

private_message = {
    "type": "private",
    "to": "wdaher@example.com",
    "content": "I come not, friends, to steal away your hearts."
}

print client.send_message(stream_message)
print client.send_message(private_message)

# Print each message the user receives
client.call_on_each_message(lambda msg: sys.stdout.write(str(msg) + "\n"))

You can use humbug-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

humbug-send --stream Denmark --subject Castle \
--user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5

Private message

humbug-send wdaher@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:

humbug-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.

{% endblock %}