2013-07-29 23:03:31 +02:00
{% extends "zerver/portico.html" %}
2013-02-04 20:01:45 +01:00
{# API information page #}
{% block portico_content %}
2013-09-13 06:06:10 +02:00
< h1 class = "api-page-header" > We hear you like APIs...< / h1 >
2013-04-17 17:24:07 +02:00
2016-10-16 17:40:16 +02:00
< 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. There is also a < a href = "https://github.com/zulip/zulip-js" > JavaScript library< / a > that can be used either in the browser or in Node.js.< / p >
2013-08-02 19:46:48 +02:00
< p > < strong > Don't want to make it yourself?< / strong > Zulip < a href = "/integrations" > already integrates with lots of services< / a > .< / p >
2013-04-17 17:24:07 +02:00
< br / >
2013-10-07 20:26:37 +02:00
< div class = "centered-button" >
2017-01-29 02:56:25 +01:00
< a href = "https://www.zulip.org/dist/api/python-zulip_0.2.5.tar.gz" class = "btn btn-large btn-primary" > < i class = "icon-vector-download" > < / i > Download Python bindings and examples< span class = "button-muted" > Version 0.2.5< / span > < / a >
2013-10-07 20:26:37 +02:00
< / div >
2013-02-04 20:01:45 +01:00
< p > < / p >
< h3 > Installation instructions< / h3 >
2016-09-22 18:30:32 +02:00
< h4 > Python< / h4 >
2013-10-31 15:44:10 +01:00
< p > This package uses < tt > distutils< / tt > , so you can just run < code > python setup.py install< / code > after downloading.< / p >
< p > If you have < tt > setuptools< / tt > installed on your system then the application's dependencies will be downloaded and installed automatically from < a href = "https://pypi.python.org/" > PyPI< / a > . Otherwise, you'll need to make sure you have these Python libraries installed:< / p >
< ul >
< li > < tt > simplejson< / tt > < / li >
< li > < tt > requests< / tt > (0.12.1 or later)< / li >
< / ul >
2013-05-29 17:55:59 +02:00
< p > < / p >
2016-10-16 17:40:16 +02:00
< h4 > JavaScript< / h4 >
2016-09-22 18:30:32 +02:00
< p > Install it with < a href = "https://www.npmjs.com/package/zulip-js" > npm< / a > :< / p >
< pre > < code > npm install zulip-js< / code > < / pre >
2013-05-29 17:55:59 +02:00
2013-02-04 20:01:45 +01:00
< h3 > Usage examples< / h3 >
2013-08-02 19:46:48 +02:00
2013-02-04 20:01:45 +01:00
< ul class = "nav nav-tabs" id = "api-example-tabs" >
2013-04-19 18:20:46 +02:00
< li class = "active" > < a href = "#curl" data-toggle = "tab" > curl< / a > < / li >
< li > < a href = "#python" data-toggle = "tab" > Python< / a > < / li >
2013-08-07 17:52:53 +02:00
< li > < a href = "#commandline" data-toggle = "tab" > zulip-send< / a > < / li >
2016-10-16 17:40:16 +02:00
< li > < a href = "#javascript" data-toggle = "tab" > JavaScript< / a > < / li >
2013-02-04 20:01:45 +01:00
< / ul >
2013-04-17 17:24:07 +02:00
< div class = "tab-content" >
2013-04-19 18:20:46 +02:00
< div class = "tab-pane active" id = "curl" >
2013-04-17 17:24:07 +02:00
< p > No download required!< / p >
2016-04-21 08:48:33 +02:00
{#
2013-07-10 22:14:08 +02:00
These code snippets are generated using our very own Zulip tool, by
2013-04-17 17:24:07 +02:00
sending them to myself in a code block, and then using the inspector
to pull out the resulting HTML :)
2016-04-21 08:48:33 +02:00
#}
2013-04-17 17:24:07 +02:00
< h4 > Stream message< / h4 >
2016-08-14 09:44:12 +02:00
< div class = "codehilite" > < pre > curl {{ external_api_uri_subdomain }}/v1/messages < span class = "se" > \< / span >
2013-05-29 17:55:59 +02:00
-u BOT_EMAIL_ADDRESS:BOT_API_KEY < span class = "se" > \< / span >
2013-04-17 17:24:07 +02:00
-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 >
2013-08-02 19:46:48 +02:00
-d < span class = "s2" > "content=Something is rotten in the state of Denmark."< / span > < / pre >
< / div >
2013-04-17 17:24:07 +02:00
< h4 > Private message< / h4 >
2016-08-14 09:44:12 +02:00
< div class = "codehilite" > < pre > curl {{ external_api_uri_subdomain }}/v1/messages < span class = "se" > \< / span >
2013-05-29 17:55:59 +02:00
-u BOT_EMAIL_ADDRESS:BOT_API_KEY < span class = "se" > \< / span >
2013-04-17 17:24:07 +02:00
-d < span class = "s2" > "type=private"< / span > < span class = "se" > \< / span >
2013-08-08 20:08:09 +02:00
-d < span class = "s2" > "to=hamlet@example.com"< / span > < span class = "se" > \< / span >
2013-08-02 19:46:48 +02:00
-d < span class = "s2" > "content=I come not, friends, to steal away your hearts."< / span > < / pre >
< / div >
2013-04-17 17:24:07 +02:00
< / div >
2013-04-19 18:20:46 +02:00
< div class = "tab-pane" id = "python" >
2016-04-07 15:27:25 +02:00
< div class = "codehilite" > < pre > < span class = "c" > #!/usr/bin/env python< / span >
2013-04-17 17:24:07 +02:00
2013-08-07 17:51:03 +02:00
< span class = "kn" > import< / span > < span class = "nn" > zulip< / span >
2013-06-06 16:44:03 +02:00
< span class = "kn" > import< / span > < span class = "nn" > sys< / span >
2013-08-08 20:08:09 +02:00
< span class = "c" > # Keyword arguments 'email' and 'api_key' are not required if you are using ~/.zuliprc< / span >
2013-08-07 17:51:03 +02:00
< span class = "n" > client< / span > < span class = "o" > =< / span > < span class = "n" > zulip< / 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 >
2016-08-14 10:22:19 +02:00
< span class = "n" > api_key< / span > < span class = "o" > =< / span > < span class = "s" > "a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5"< / span > < span class = "p" > ,< / span >
< span class = "n" > site< / span > < span class = "o" > =< / span > < span class = "s" > "{{ external_api_uri_subdomain }}"< / span > < span class = "p" > )< / span >
2013-08-08 20:08:09 +02:00
< span class = "c" > # Send a stream message< / span >
< span class = "n" > client< / span > < span class = "o" > .< / span > < span class = "n" > send_message< / span > < span class = "p" > ({< / span >
2013-04-17 17:24:07 +02:00
< 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 >
2016-07-09 01:06:50 +02:00
< span class = "p" > })< / span >
2013-08-08 20:08:09 +02:00
< span class = "c" > # Send a private message< / span >
< span class = "n" > client< / span > < span class = "o" > .< / span > < span class = "n" > send_message< / span > < span class = "p" > ({< / span >
2013-04-17 17:24:07 +02:00
< span class = "s" > "type"< / span > < span class = "p" > :< / span > < span class = "s" > "private"< / span > < span class = "p" > ,< / span >
2013-08-08 20:08:09 +02:00
< span class = "s" > "to"< / span > < span class = "p" > :< / span > < span class = "s" > "hamlet@example.com"< / span > < span class = "p" > ,< / span >
2013-04-17 17:24:07 +02:00
< span class = "s" > "content"< / span > < span class = "p" > :< / span > < span class = "s" > "I come not, friends, to steal away your hearts."< / span >
2013-08-08 20:08:09 +02:00
< span class = "p" > })< / span >
2013-04-11 22:51:48 +02:00
< span class = "c" > # Print each message the user receives< / span >
2013-09-24 17:47:00 +02:00
< span class = "c" > # This is a blocking call that will run forever< / span >
2013-04-11 22:51:48 +02:00
< 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 >
2013-08-08 17:45:25 +02:00
< span class = "c" > # Print every event relevant to the user< / span >
2013-09-24 17:47:00 +02:00
< span class = "c" > # This is a blocking call that will run forever< / span >
< span class = "c" > # This will never be reached unless you comment out the previous line< / span >
2013-08-08 17:45:25 +02:00
< span class = "n" > client< / span > < span class = "o" > .< / span > < span class = "n" > call_on_each_event< / 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 >
2013-04-17 17:24:07 +02:00
< / pre > < / div >
< / div >
< div class = "tab-pane" id = "commandline" >
2016-07-09 01:06:50 +02:00
< p > You can use < code > zulip-send< / code > (found in < code > bin/< / code > in the tarball) to easily send Zulips from the command-line, providing the message to be sent on STDIN.< / p >
2013-04-17 17:24:07 +02:00
< h4 > Stream message< / h4 >
2013-08-07 17:52:53 +02:00
< div class = "codehilite" > < pre > zulip-send --stream Denmark --subject Castle \
2013-12-04 20:57:44 +01:00
--user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5{% if api_site_required %} \
2016-08-14 09:44:12 +02:00
--site={{ external_api_uri_subdomain }}{% endif %}< / pre > < / div >
2013-04-17 17:24:07 +02:00
< h4 > Private message< / h4 >
2013-12-04 20:57:44 +01:00
< div class = "codehilite" > < pre > zulip-send hamlet@example.com \
--user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5{% if api_site_required %} \
2016-08-14 09:44:12 +02:00
--site={{ external_api_uri_subdomain }}{% endif %}< / pre > < / div >
2013-04-17 17:24:07 +02:00
< 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 >
2013-08-07 17:52:53 +02:00
< div class = "codehilite" > < pre > zulip-send --stream Denmark --subject Castle \
2013-05-29 17:55:59 +02:00
-m < span class = "s2" > "Something is rotten in the state of Denmark."< / span > \
2013-12-04 20:57:44 +01:00
--user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5{% if api_site_required %} \
2016-08-14 09:44:12 +02:00
--site={{ external_api_uri_subdomain }}{% endif %}
2013-04-17 17:24:07 +02:00
< / pre > < / div >
2013-02-04 20:01:45 +01:00
2013-12-04 20:57:44 +01:00
< p > You can omit the < code > user< / code > {% if api_site_required %}, < code > api-key< / code > , and
< code > site< / code > {% else %} and < code > api-key< / code > {% endif %} arguments if you have a
< code > ~/.zuliprc< / code > file.
2016-07-09 01:06:50 +02:00
< / p >
2013-04-17 17:24:07 +02:00
< p > See also the < a href = "/api/endpoints" > full API endpoint documentation.< / a > < / p >
2013-02-04 20:01:45 +01:00
< / div >
2013-08-02 19:46:48 +02:00
2016-09-22 18:30:32 +02:00
< div class = "tab-pane" id = "javascript" >
< p > More examples and documentation can be found < a href = "https://github.com/zulip/zulip-js" > here< / a > .< / p >
< div class = "codehilite" > < pre > < span class = "kr" > const< / span > < span class = "nx" > zulip< / span > < span class = "o" > =< / span > < span class = "nx" > require< / span > < span class = "p" > (< / span > < span class = "s1" > 'zulip'< / span > < span class = "p" > );< / span >
< span class = "kr" > const< / span > < span class = "nx" > config< / span > < span class = "o" > =< / span > < span class = "p" > {< / span >
< span class = "nx" > username< / span > < span class = "o" > :< / span > < span class = "s1" > 'othello-bot@example.com'< / span > < span class = "p" > ,< / span >
< span class = "nx" > apiKey< / span > < span class = "o" > :< / span > < span class = "s1" > 'a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5'< / span > < span class = "p" > ,< / span >
< span class = "nx" > realm< / span > < span class = "o" > :< / span > < span class = "s1" > '{{ external_api_uri_subdomain }}'< / span >
< span class = "p" > };< / span >
< span class = "kr" > const< / span > < span class = "nx" > client< / span > < span class = "o" > =< / span > < span class = "nx" > zulip< / span > < span class = "p" > (< / span > < span class = "nx" > config< / span > < span class = "p" > );< / span >
< span class = "c1" > // Send a message< / span >
< span class = "nx" > client< / span > < span class = "p" > .< / span > < span class = "nx" > messages< / span > < span class = "p" > .< / span > < span class = "nx" > send< / span > < span class = "p" > ({< / span >
< span class = "nx" > to< / span > < span class = "o" > :< / span > < span class = "s1" > 'Denmark'< / span > < span class = "p" > ,< / span >
< span class = "nx" > type< / span > < span class = "o" > :< / span > < span class = "s1" > 'stream'< / span > < span class = "p" > ,< / span >
< span class = "nx" > subject< / span > < span class = "o" > :< / span > < span class = "s1" > 'Castle'< / span > < span class = "p" > ,< / span >
< span class = "nx" > content< / span > < span class = "o" > :< / span > < span class = "s1" > 'Something is rotten in the state of Denmark.'< / span >
< span class = "p" > });< / span >
< span class = "c1" > // Send a private message< / span >
< span class = "nx" > client< / span > < span class = "p" > .< / span > < span class = "nx" > messages< / span > < span class = "p" > .< / span > < span class = "nx" > send< / span > < span class = "p" > ({< / span >
< span class = "nx" > to< / span > < span class = "o" > :< / span > < span class = "s1" > 'hamlet@example.com'< / span > < span class = "p" > ,< / span >
< span class = "nx" > type< / span > < span class = "o" > :< / span > < span class = "s1" > 'private'< / span > < span class = "p" > ,< / span >
< span class = "nx" > content< / span > < span class = "o" > :< / span > < span class = "s1" > 'I come not, friends, to steal away your hearts.'< / span >
< span class = "p" > });< / span >
< span class = "c1" > // Register queue to receive messages for user< / span >
< span class = "nx" > zulip< / span > < span class = "p" > .< / span > < span class = "nx" > queues< / span > < span class = "p" > .< / span > < span class = "nx" > register< / span > < span class = "p" > ({< / span >
< span class = "nx" > event_types< / span > < span class = "o" > :< / span > < span class = "p" > [< / span > < span class = "s1" > 'message'< / span > < span class = "p" > ]< / span >
< span class = "p" > }).< / span > < span class = "nx" > then< / span > < span class = "p" > ((< / span > < span class = "nx" > res< / span > < span class = "p" > )< / span > < span class = "o" > => < / span > < span class = "p" > {< / span >
< span class = "c1" > // Retrieve events from a queue< / span >
< span class = "c1" > // Blocking until there is an event (or the request times out)< / span >
< span class = "nx" > zulip< / span > < span class = "p" > .< / span > < span class = "nx" > events< / span > < span class = "p" > .< / span > < span class = "nx" > retrieve< / span > < span class = "p" > ({< / span >
< span class = "nx" > queue_id< / span > < span class = "o" > :< / span > < span class = "nx" > res< / span > < span class = "p" > .< / span > < span class = "nx" > queue_id< / span > < span class = "p" > ,< / span >
< span class = "nx" > last_event_id< / span > < span class = "o" > :< / span > < span class = "o" > -< / span > < span class = "mi" > 1< / span > < span class = "p" > ,< / span >
< span class = "nx" > dont_block< / span > < span class = "o" > :< / span > < span class = "kc" > false< / span >
< span class = "p" > }).< / span > < span class = "nx" > then< / span > < span class = "p" > (< / span > < span class = "nx" > console< / span > < span class = "p" > .< / span > < span class = "nx" > log< / span > < span class = "p" > );< / span >
< span class = "p" > });< / span >
< / pre > < / div >
2013-08-02 19:46:48 +02:00
2016-09-22 18:30:32 +02:00
< / div >
2013-08-02 19:46:48 +02:00
< p > < / p >
< h3 > API Keys< / h3 >
2014-01-02 19:02:17 +01:00
< a name = "api_keys" > < / a >
2013-08-02 19:46:48 +02:00
< 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 >
2016-07-09 01:06:50 +02:00
< p > Create a bot:< / p >
< img class = "screenshot" src = "/static/images/api/create-bot.png" / >
2013-08-02 19:46:48 +02:00
< 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
2017-03-08 08:37:54 +01:00
them in your < code > ~/.zuliprc< / code > , the default config file, which you can create as follows:< / p >
2013-08-02 19:46:48 +02:00
< 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 >
2016-08-14 09:44:12 +02:00
{% if api_site_required %}< span class = "na" > site< / span > < span class = "o" > =< / span > < span class = "s" > {{ external_api_uri_subdomain }}< / span > {% endif %}< / pre > < / div >
2017-03-08 08:37:54 +01:00
< p > Additionally, you can also specify the parameters as environment variables as follows:< / p >
< div class = "codehilite" > < pre > < span > < / span > < span class = "nb" > export< / span > < span class = "nv" > ZULIP_CONFIG< / span > < span class = "o" > =< / span > /path/to/zulipconfig
< span class = "nb" > export< / span > < span class = "nv" > ZULIP_EMAIL< / span > < span class = "o" > =< / span > BOT_EMAIL_ADDRESS
< span class = "nb" > export< / span > < span class = "nv" > ZULIP_API_KEY< / span > < span class = "o" > =< / span > BOT_API_KEY
< / pre > < / div >
< p > The parameters specified in environment variables would override the parameters provided in the config file. For example, if you specify the variable < code > key< / code > in the config file and specify < code > ZULIP_API_KEY< / code > as an environment variable, the value of < code > ZULIP_API_KEY< / code > would be considered.< / p >
2017-03-08 08:39:51 +01:00
< p > The following variables can be specified:
2017-03-08 10:16:08 +01:00
< br / > 1. < code > ZULIP_CONFIG< / code >
< br / > 2. < code > ZULIP_API_KEY< / code >
< br / > 3. < code > ZULIP_EMAIL< / code >
< br / > 4. < code > ZULIP_SITE< / code >
< br / > 5. < code > ZULIP_CERT< / code >
< br / > 6. < code > ZULIP_CERT_KEY< / code >
< br / > 7. < code > ZULIP_CERT_BUNDLE< / code >
2017-03-08 08:39:51 +01:00
< / p >
2016-07-09 01:06:50 +02:00
< / div >
2013-02-04 20:01:45 +01:00
{% endblock %}