From 16227ed23a81d3b88e86257ef870b69faad3839e Mon Sep 17 00:00:00 2001
From: Rohitt Vashishtha <aero31aero@gmail.com>
Date: Wed, 28 Aug 2019 00:29:12 +0000
Subject: [PATCH] docs/botserver: Explain how the botserver works.

Understanding the basic model can help people troubleshoot any
errors easily.
---
 templates/zerver/api/deploying-bots.md | 35 ++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/templates/zerver/api/deploying-bots.md b/templates/zerver/api/deploying-bots.md
index 08c4575de3..f6d0616fb5 100644
--- a/templates/zerver/api/deploying-bots.md
+++ b/templates/zerver/api/deploying-bots.md
@@ -30,6 +30,41 @@ the Outgoing Webhooks API, but the Botserver is designed to make it
 easy for a novice Python programmer to write a new bot and deploy it
 in production.
 
+### How Botserver works
+
+Zulip Botserver starts a web server that listens to incoming messages
+from your main Zulip server. The sequence of events in a successful
+Botserver interaction are:
+
+1. Your bot user is mentioned or receives a private message:
+
+    ```
+    @**My Bot User** hello world
+    ```
+
+1. The Zulip server sends a POST request to the Botserver on `https://bot-server.example.com/`:
+
+    ```
+    {
+      "message":{
+        "content":"@**My Bot User** hello world",
+      },
+      "bot_email":"myuserbot-bot@example.com",
+      "trigger":"mention",
+      "token":"XXXX"
+    }
+    ```
+
+    This url is configured in the Zulip web-app in your Bot User's settings.
+
+1. The Botserver searches for a bot to handle the message.
+
+1. The Botserver executes your bot's `handle_message` code.
+
+Your bot's code should work just like it does with `zulip-run-bot`;
+for example, you reply using
+[bot_handler.send_reply](writing-bots#bot_handlersend_reply)).
+
 ### Installing the Zulip Botserver
 
 Install the `zulip_botserver` package: