mirror of https://github.com/zulip/zulip.git
143 lines
7.8 KiB
HTML
143 lines
7.8 KiB
HTML
{% extends "zephyr/portico.html" %}
|
|
|
|
{# API information page #}
|
|
|
|
{% block portico_content %}
|
|
<div class="row-fluid">
|
|
<div class="span8">
|
|
<h1>We hear you like APIs...</h1>
|
|
<ul class="breadcrumb">
|
|
<li><a href="/">Home</a> <span class="divider">/</span></li>
|
|
<li class="active">API</li>
|
|
</ul>
|
|
|
|
<p>We have a <a href="/api/endpoints">well-documented API</a> that allows you to build custom integrations, in addition to our <a href="/integrations">existing integrations</a>. For ease-of-use, we've created a Python module that you can drop in to a project to start interacting with our API.</p>
|
|
<br/>
|
|
<a href="https://www.humbughq.com/dist/api/python-humbug_0.1.9.tar.gz" class="btn btn-large btn-primary btn-block"><i class="icon-download icon-white"></i> Download Python bindings and examples</a>
|
|
<span class="pull-right muted">Version 0.1.9</span>
|
|
|
|
<p> </p>
|
|
|
|
<h3>Installation instructions</h3>
|
|
<p>This package uses distutils, so you can just run <code>python setup.py install</code> after downloading.</p>
|
|
<p> </p>
|
|
|
|
<h3>API Keys</h3>
|
|
<p>You can create bots on your <a href="/#settings" target="_blank">settings page</a>.
|
|
Once you have a bot, you can use its email and API key to send messages.</p>
|
|
|
|
<p>Create a bot:
|
|
<img class="screenshot" src="/static/images/api/create-bot.png" /></p>
|
|
|
|
<p>Look for the bot's email and API key:
|
|
<img class="screenshot" src="/static/images/api/bot-key.png" /></p>
|
|
|
|
<p>If you prefer to send messages as your own user, you can also find your API key on your <a href="/#settings" target="_blank">settings page</a>.</p>
|
|
<p>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 <code>~/.humbugrc</code>, which you can create as follows:</p>
|
|
<div class="codehilite"><pre><span class="k">[api]</span>
|
|
<span class="na">key</span><span class="o">=</span><span class="s">BOT_API_KEY</span>
|
|
<span class="na">email</span><span class="o">=</span><span class="s">BOT_EMAIL_ADDRESS</span>
|
|
</pre></div>
|
|
|
|
<p><strong>Don't want to make it yourself?</strong> Humbug <a href="/integrations">already integrates with lots of services</a>.</p>
|
|
|
|
<p> </p>
|
|
|
|
<h3>Usage examples</h3>
|
|
<ul class="nav nav-tabs" id="api-example-tabs">
|
|
<li class="active"><a href="#curl" data-toggle="tab">curl</a></li>
|
|
<li><a href="#python" data-toggle="tab">Python</a></li>
|
|
<li><a href="#commandline" data-toggle="tab">humbug-send</a></li>
|
|
</ul>
|
|
|
|
<div class="tab-content">
|
|
|
|
<div class="tab-pane active" id="curl">
|
|
<p>No download required!</p>
|
|
|
|
{% comment %}
|
|
These code snippets are generated using our very own Humbug tool, by
|
|
sending them to myself in a code block, and then using the inspector
|
|
to pull out the resulting HTML :)
|
|
{% endcomment %}
|
|
|
|
<h4>Stream message</h4>
|
|
<div class="codehilite"><pre>curl https://api.humbughq.com/v1/messages <span class="se">\</span>
|
|
-u BOT_EMAIL_ADDRESS:BOT_API_KEY <span class="se">\</span>
|
|
-d <span class="s2">"type=stream"</span> <span class="se">\</span>
|
|
-d <span class="s2">"to=Denmark"</span> <span class="se">\</span>
|
|
-d <span class="s2">"subject=Castle"</span> <span class="se">\</span>
|
|
-d <span class="s2">"content=Something is rotten in the state of Denmark."</span>
|
|
</pre></div>
|
|
|
|
<h4>Private message</h4>
|
|
<div class="codehilite"><pre>curl https://api.humbughq.com/v1/messages <span class="se">\</span>
|
|
-u BOT_EMAIL_ADDRESS:BOT_API_KEY <span class="se">\</span>
|
|
-d <span class="s2">"type=private"</span> <span class="se">\</span>
|
|
-d <span class="s2">"to=wdaher@humbughq.com"</span> <span class="se">\</span>
|
|
-d <span class="s2">"content=I come not, friends, to steal away your hearts."</span>
|
|
</pre></div>
|
|
|
|
</div>
|
|
|
|
<div class="tab-pane" id="python">
|
|
<div class="codehilite"><pre><span class="c">#!/usr/bin/env python</span>
|
|
|
|
<span class="kn">import</span> <span class="nn">humbug</span>
|
|
<span class="kn">import</span> <span class="nn">sys</span>
|
|
|
|
<span class="c"># Keyword arguments 'email' and 'api_key' are optional if you are using ~/.humbugrc</span>
|
|
<span class="n">client</span> <span class="o">=</span> <span class="n">humbug</span><span class="o">.</span><span class="n">Client</span><span class="p">(</span><span class="p">email</span><span class="o">=</span><span class="s">"othello-bot@example.com"</span><span class="p">,</span>
|
|
<span class="n">api_key</span><span class="o">=</span><span class="s">"a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5"</span><span class="p">)</span>
|
|
|
|
<span class="n">stream_message</span> <span class="o">=</span> <span class="p">{</span>
|
|
<span class="s">"type"</span><span class="p">:</span> <span class="s">"stream"</span><span class="p">,</span>
|
|
<span class="s">"to"</span><span class="p">:</span> <span class="s">"Denmark"</span><span class="p">,</span>
|
|
<span class="s">"subject"</span><span class="p">:</span> <span class="s">"Castle"</span><span class="p">,</span>
|
|
<span class="s">"content"</span><span class="p">:</span> <span class="s">"Something is rotten in the state of Denmark."</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="n">private_message</span> <span class="o">=</span> <span class="p">{</span>
|
|
<span class="s">"type"</span><span class="p">:</span> <span class="s">"private"</span><span class="p">,</span>
|
|
<span class="s">"to"</span><span class="p">:</span> <span class="s">"wdaher@humbughq.com"</span><span class="p">,</span>
|
|
<span class="s">"content"</span><span class="p">:</span> <span class="s">"I come not, friends, to steal away your hearts."</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="k">print</span> <span class="n">client</span><span class="o">.</span><span class="n">send_message</span><span class="p">(</span><span class="n">stream_message</span><span class="p">)</span>
|
|
<span class="k">print</span> <span class="n">client</span><span class="o">.</span><span class="n">send_message</span><span class="p">(</span><span class="n">private_message</span><span class="p">)</span>
|
|
|
|
<span class="c"># Print each message the user receives</span>
|
|
<span class="n">client</span><span class="o">.</span><span class="n">call_on_each_message</span><span class="p">(</span><span class="k">lambda</span> <span class="n">msg</span><span class="p">:</span> <span class="n">sys</span><span class="o">.</span><span class="n">stdout</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="nb">str</span><span class="p">(</span><span class="n">msg</span><span class="p">)</span> <span class="o">+</span> <span class="s">"</span><span class="se">\n</span><span class="s">"</span><span class="p">))</span>
|
|
</pre></div>
|
|
</div>
|
|
|
|
|
|
<div class="tab-pane" id="commandline">
|
|
<p>You can use <code>humbug-send</code> (found in <code>bin/</code> in the tarball) to easily send Humbugs from the command-line, providing the message to be sent on STDIN.
|
|
|
|
<h4>Stream message</h4>
|
|
<div class="codehilite"><pre>humbug-send --stream Denmark --subject Castle \
|
|
--user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5</pre></div>
|
|
|
|
<h4>Private message</h4>
|
|
<div class="codehilite"><pre>humbug-send wdaher@humbughq.com --user othello-bot@example.com \
|
|
--api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5
|
|
</pre></div>
|
|
|
|
<h4>Passing in the message on the command-line</h4>
|
|
<p>If you'd like, you can also provide the message on the command-line with the <code>-m</code> flag, as follows:</p>
|
|
<div class="codehilite"><pre>humbug-send --stream Denmark --subject Castle \
|
|
-m <span class="s2">"Something is rotten in the state of Denmark."</span> \
|
|
--user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5
|
|
</pre></div>
|
|
|
|
</div>
|
|
<p>See also the <a href="/api/endpoints">full API endpoint documentation.</a></p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
{% endblock %}
|