From b36decec30415b3ba01cbe00e717fbc2f4a2fdbb Mon Sep 17 00:00:00 2001
From: ahmedforge <ahmedali.xhassan@gmail.com>
Date: Fri, 2 Oct 2026 18:32:35 +0500
Subject: [PATCH] botserver: Document loading custom bots from Python files.

---
 zulip_botserver/README.md | 54 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/zulip_botserver/README.md b/zulip_botserver/README.md
index cb5750f55..7f6440389 100644
--- a/zulip_botserver/README.md
+++ b/zulip_botserver/README.md
@@ -28,3 +28,57 @@ bot names to dictionary of their configuration; for example:
 
     ZULIP_BOTSERVER_CONFIG='{"helloworld":{"email":"helloworld-bot@zulip.com","key":"value","site":"http://localhost","token":"abcd1234"}}' \
       zulip-botserver --use-env-vars
+
+## Running a custom bot from a Python file
+
+Custom bots do not need to be copied into the `zulip_bots` package. The
+Botserver can load an existing `.py` file that defines `handler_class`, as
+in the [Hello World bot](../zulip_bots/zulip_bots/bots/helloworld/helloworld.py).
+
+For a single custom bot, save a configuration file such as `botserverrc`:
+
+```ini
+[my_bot]
+email=my-bot@example.com
+key=YOUR_BOT_API_KEY
+site=https://your-organization.zulipchat.com
+token=YOUR_OUTGOING_WEBHOOK_TOKEN
+```
+
+Replace the example values with your bot's email, API key, organization URL,
+and outgoing webhook token. Keep this file private; it contains credentials.
+
+Pass the path to your bot file using `--bot-name`:
+
+```sh
+zulip-botserver --config-file ./botserverrc --bot-name ./my_bot.py
+```
+
+In single-bot mode, the Botserver uses the configuration section matching
+`--bot-name`, or the first section if there is no match. In this example,
+it uses `[my_bot]`. Other sections are ignored.
+
+Relative file paths are resolved from the directory where you run the
+command, not from the configuration file's directory. To run the command
+from another directory, use absolute paths:
+
+```sh
+zulip-botserver --config-file /path/to/botserverrc --bot-name /path/to/my_bot.py
+```
+
+### Troubleshooting custom bot loading
+
+- If the Botserver reports that the bot does not exist, check that the
+  path passed to `--bot-name` points to an existing file ending in `.py`.
+- If your bot imports third-party packages, install them in the Python
+  environment used to run `zulip-botserver`.
+- If your bot imports your own modules, make those modules importable in
+  the same environment. For example, add their containing directory to
+  `PYTHONPATH` for the command:
+
+  ```sh
+  PYTHONPATH=/path/to/helpers zulip-botserver --config-file /path/to/botserverrc --bot-name /path/to/my_bot.py
+  ```
+
+  Loading a bot by its file path does not automatically add its directory
+  to Python's module search path.