From d3b62b9f2d7bb4f6e04222a77ce5f15d7eb5b562 Mon Sep 17 00:00:00 2001
From: Tim Abbott <tabbott@zulip.com>
Date: Fri, 28 Aug 2020 16:43:12 -0700
Subject: [PATCH] api: Further clean up outgoing webhook docs.

---
 templates/zerver/api/outgoing-webhooks.md | 52 ++++++++++++-----------
 1 file changed, 28 insertions(+), 24 deletions(-)

diff --git a/templates/zerver/api/outgoing-webhooks.md b/templates/zerver/api/outgoing-webhooks.md
index de85b1e17d..eb6e357dee 100644
--- a/templates/zerver/api/outgoing-webhooks.md
+++ b/templates/zerver/api/outgoing-webhooks.md
@@ -28,42 +28,40 @@ To register an outgoing webhook:
 ## Triggering
 
 There are currently two ways to trigger an outgoing webhook:
+
 1.  **@-mention** the bot user in a stream.  If the bot replies, its
     reply will be sent to that stream and topic.
 2.  **Send a private message** with the bot as one of the recipients.
     If the bot replies, its reply will be sent to that thread.
 
-## Zulip message format
-
-### Return values
-
-{generate_return_values_table|zulip.yaml|/zulip-outgoing-webhook:post}
-
-A correctly implemented endpoint will do the following:
-
-* It will calculate a response that we call the "content" of
-  the response.
-* It will encode the content in Zulip's flavor of Markdown (or
-  just plain text).
-* It will then make a dictionary with key of "content" and
-  the value being that content.  (Note that "response_string" is
-  a deprecated synonym for "content".)
-* It will encode that dictionary as JSON.
-
-If the bot code wants to opt out of responding, it can explicitly
-encode a JSON dictionary that contains `response_not_required` set
-to `True`, so that no response message is sent to the user.  (This
-is helpful to distinguish deliberate non-responses from bugs.)
-
-### Example incoming payload
+## Outgoing webhook format
 
 This is an example of the JSON payload that the Zulip server will `POST`
 to your server:
 
 {generate_code_example|/zulip-outgoing-webhook:post|fixture(200)}
 
+### Fields documentation
+
+{generate_return_values_table|zulip.yaml|/zulip-outgoing-webhook:post}
+
+## Replying with a message
+
+Many bots implemented using this outgoing webhook API will want to
+send a reply message into Zulip.  Zulip's outgoing webhook API
+provides a convenient way to do that by simply returning an
+appropriate HTTP response to the Zulip server.
+
+A correctly implemented bot will return a JSON object containing one
+of two possible formats, described below.
+
 ### Example response payloads
 
+If the bot code wants to opt out of responding, it can explicitly
+encode a JSON dictionary that contains `response_not_required` set
+to `True`, so that no response message is sent to the user.  (This
+is helpful to distinguish deliberate non-responses from bugs.)
+
 Here's an example of the JSON your server should respond with if
 you would not like to send a response message:
 
@@ -78,10 +76,16 @@ you would like to send a response message:
 
 ```
 {
-    "content": "Hey, we just received something from Zulip!"
+    "content": "Hey, we just received **something** from Zulip!"
 }
 ```
 
+The `content` field should contain Zulip-format markdown.
+
+Note that an outgoing webhook bot can use the [Zulip REST
+API](/api/rest) with its API key in case your bot needs to do
+something else, like add an emoji reaction or upload a file.
+
 ## Slack-format webhook format
 
 This interface translates Zulip's outgoing webhook's request into the