From 4abce1783f538b4a2dffaf3f79a9b816564af0eb Mon Sep 17 00:00:00 2001 From: Rishi Gupta Date: Thu, 11 Oct 2018 16:12:16 -0700 Subject: [PATCH] api docs: Restructure integrations section and add an overview. --- templates/zerver/api/integrations-overview.md | 65 +++++++++++++++++++ templates/zerver/api/sidebar_index.md | 11 ++-- 2 files changed, 69 insertions(+), 7 deletions(-) create mode 100644 templates/zerver/api/integrations-overview.md diff --git a/templates/zerver/api/integrations-overview.md b/templates/zerver/api/integrations-overview.md new file mode 100644 index 0000000000..656c9bc7ad --- /dev/null +++ b/templates/zerver/api/integrations-overview.md @@ -0,0 +1,65 @@ +# Integrations overview + +Integrations allow you to send data from other products into or out of +Zulip. Zulip natively integrates with dozens of products, and with hundreds +more through Zapier, IFTTT, and Hubot. + +Zulip also makes it very easy to write your own integration, and (if you'd +like) to get it merged into the main Zulip repository. + +Integrations are one of the most important parts of a group chat tool like +Zulip, and we are committed to making integrating with Zulip as easy as +possible. + +## Set up an existing integration + +Most existing integrations send content from a third-party product into +Zulip. + +* Search Zulip's [list of native integrations](/integrations) for the + third-party product. Each integration has a page describing how to set it + up. + +* Check if [Zapier](https://zapier.com/apps) has an integration with the + product. If it does, follow [these instructions](/integrations/doc/zapier) + to set it up. + +* Check if [IFTTT](https://ifttt.com/search) has an integration with the + product. If it does, follow [these instructions](/integrations/doc/ifttt) + to set it up. + +* Check if [Hubot](https://github.com/hubot-scripts) has an integration with + the product. If it does, follow + [these instructions](/integrations/doc/hubot) to set it up. + +* If the product can send email notifications, you can + [send those emails to a stream](/help/message-a-stream-by-email). + +## Write your own integration + +We've put a lot of effort into making this as easy as possible, but all of +the options below do require some comfort writing code. If you need an +integration and don't have an engineer on staff, reach out to +`support@zulipchat.com` and we'll see what we can do. + +### Sending content into Zulip + +* If the third-party service supports outgoing webhooks, you likely want to + build an [incoming webhook integration](/api/incoming-webhooks-overview). + +* Otherwise, you can + [send messages using Zulip's API](/api/send-message). + +### Sending and receiving content + +* To react to activity inside Zulip, look at Zulip's + [Python framework for interactive bots](/api/running-bots) or + [Zulip's real-time events API](/api/get-events-from-queue). + +* If what you want isn't covered by the above, check out the full + [REST API](/api/rest). The web, mobile, desktop, and terminal apps are + built on top of this API, so it can do anything a human user can do. Most + but not all of the endpoints are documented on this site; if you need + something that isn't there check out Zulip's + [REST endpoints](https://github.com/zulip/zulip/tree/master/zproject/urls.py) + or email `support@zulipchat.com` and we'll help you out. diff --git a/templates/zerver/api/sidebar_index.md b/templates/zerver/api/sidebar_index.md index 1a04632bef..7d35b1fe10 100644 --- a/templates/zerver/api/sidebar_index.md +++ b/templates/zerver/api/sidebar_index.md @@ -1,12 +1,9 @@ ## Integrations -* [Overview](/api/integration-guide) -* [Existing integrations](/integrations) - -## Incoming webhooks - -* [Overview](/api/incoming-webhooks-overview) -* [Walkthrough](/api/webhook-walkthrough) +* [Overview](/api/integrations-overview) +* [Incoming webhook integrations](/api/incoming-webhooks-overview) +* [Hello world walkthrough](/api/webhook-walkthrough) +* [Non-webhook integrations](/api/integration-guide) ## Interactive bots (beta)