From c796358a1bf19fc57a6dcf0ce101492b5e6aacc3 Mon Sep 17 00:00:00 2001
From: vickytechkey <vichunice@gmail.com>
Date: Sun, 20 Sep 2026 19:30:59 +0530
Subject: [PATCH] docs: create comprehensive API documentation

---
 API_DOCUMENTATION.md | 112 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 112 insertions(+)
 create mode 100644 API_DOCUMENTATION.md

diff --git a/API_DOCUMENTATION.md b/API_DOCUMENTATION.md
new file mode 100644
index 0000000..bf87f07
--- /dev/null
+++ b/API_DOCUMENTATION.md
@@ -0,0 +1,112 @@
+# WhatsApp SMS Service API Documentation
+
+This document describes the REST API for the WhatsApp SMS Service, which acts as a gateway to send WhatsApp messages using MSG91 templates.
+
+## Base URL
+```
+http://betawhatsapp.tradhox.com/api/
+```
+*(Or your local/production domain accordingly)*
+
+---
+
+## Endpoint: Send WhatsApp Message
+
+Sends a WhatsApp message using a dynamically loaded MSG91 JSON template.
+
+**URL:** `/send/`  
+**Method:** `POST`  
+**Content-Type:** `application/json`
+
+### Request Body Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `mobile_number` | String | Yes | The recipient's mobile number, including the country code (e.g., `"919600494039"`). |
+| `otp_code` | String | Yes | The dynamic variable value (e.g., OTP or verification code) to populate in the template. |
+| `template_name` | String | No | The name of the MSG91 template to use. Must match a `.json` file located in the `template jsons/` directory. Defaults to `"mobile_number_verification"`. |
+
+### Example Request
+
+```bash
+curl -X POST http://betawhatsapp.tradhox.com/api/send/ \
+-H "Content-Type: application/json" \
+-d '{
+  "mobile_number": "919600494039",
+  "otp_code": "123456",
+  "template_name": "mobile_number_verification"
+}'
+```
+
+### Example Response (Success)
+The API passes through the response from MSG91 directly.
+
+**Status Code:** `200 OK`
+```json
+{
+  "status": "success",
+  "message": "Message successfully submitted."
+}
+```
+
+### Example Response (Failure/Missing Parameters)
+**Status Code:** `400 Bad Request`
+```json
+{
+  "error": "mobile_number and otp_code are required"
+}
+```
+
+### Example Response (Template Not Found)
+**Status Code:** `400 Bad Request`
+```json
+{
+  "status": "error",
+  "message": "Template custom_promo not found"
+}
+```
+
+---
+
+## Adding New Templates
+
+To add support for a new MSG91 template:
+1. Create a new `.json` file in the `template jsons/` folder. The filename (without `.json`) will be the `template_name` used in the API request.
+2. The JSON file must strictly match the MSG91 payload structure.
+3. Keep the `to` and dynamic `value` fields empty in the template file, as the API service will automatically populate them dynamically at runtime!
+
+Example file (`template jsons/mobile_number_verification.json`):
+```json
+{
+    "integrated_number": "918610694498",
+    "content_type": "template",
+    "payload": {
+        "messaging_product": "whatsapp",
+        "type": "template",
+        "template": {
+            "name": "mobile_number_verification",
+            "language": {
+                "code": "en",
+                "policy": "deterministic"
+            },
+            "namespace": null,
+            "to_and_components": [
+                {
+                    "to": [""],
+                    "components": {
+                        "body_1": {
+                            "type": "text",
+                            "value": ""
+                        },
+                        "button_1": {
+                            "subtype": "url",
+                            "type": "text",
+                            "value": ""
+                        }
+                    }
+                }
+            ]
+        }
+    }
+}
+```