From 395d74c08af74a7341511c00d37631b69b233f38 Mon Sep 17 00:00:00 2001 From: Steve Howell Date: Wed, 10 Oct 2018 10:58:45 +0000 Subject: [PATCH] api docs: Clean up outgoing webhooks section. I rewrote the section explaining what the endpoint sends back to the server. This fixes a few typos, emphasizes the normal case, and starts to favor "content" as the key for content. --- templates/zerver/api/outgoing-webhooks.md | 24 +++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/templates/zerver/api/outgoing-webhooks.md b/templates/zerver/api/outgoing-webhooks.md index 3b96b9ec85..f96710df4e 100644 --- a/templates/zerver/api/outgoing-webhooks.md +++ b/templates/zerver/api/outgoing-webhooks.md @@ -93,17 +93,21 @@ Some of the important fields in the `message` dict include the following: A correctly implemented endpoint will do the following: -* For a successful request, it should return receives either a json - encoded dictionary, describing how to respond to the user. -* If the dictionary contains `response_not_required` set to `True`, no - response message is sent to the user. -* If the dictionary contains `response_string` key, the corresponding - value is used as the `content` for a Zulip message sent in response; - otherwise, a generic default response message is sent. -* For a failed request, the endpoint should return data on the - error. +* 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. -### Example payload +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 {generate_code_example|zulip-outgoing-webhook-payload|fixture}