diff --git a/README.md b/README.md
index 43d9ddb..743f068 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,93 @@
-# voxtelesys_integration
+# Voxtelesys Integration for ERPNext Helpdesk
 
-Voxtelesys Voice API integration for ERPNext Helpdesk telephony
\ No newline at end of file
+Minimal Frappe app that receives an HTTP webhook from **3CX** when an inbound
+call arrives (via a Voxtelesys SIP trunk) and automatically creates an
+**HD Ticket** in Frappe Helpdesk.
+
+---
+
+## Architecture
+
+```
+Voxtelesys SIP trunk → 3CX PBX → CF_URLFetch (Call Flow) → ERPNext webhook → HD Ticket
+```
+
+---
+
+## Installation
+
+```bash
+cd ~/frappe-bench
+bench get-app https://forge.wilddragon.net/zgaetano/voxtelesys_integration.git
+bench --site erp.broadcastmgmt.cloud install-app voxtelesys_integration
+bench --site erp.broadcastmgmt.cloud migrate
+bench restart
+```
+
+---
+
+## Webhook Endpoint
+
+```
+POST https://erp.broadcastmgmt.cloud/api/method/voxtelesys_integration.api.inbound_call
+```
+
+### Parameters (POST body or query string)
+
+| Parameter    | Required | Description                          |
+|---|---|---|
+| `caller_id`  | Yes      | Inbound caller number e.g. `+12025551234` |
+| `called_did` | No       | DID that was dialled                 |
+| `call_id`    | No       | 3CX internal call ID (for deduplication) |
+
+### Response
+
+```json
+{ "ok": true, "ticket": "HD-TICKET-00001" }
+```
+
+---
+
+## 3CX Call Flow Setup
+
+1. Open **3CX Management Console → Call Flow Designer**
+2. Create a new Call Flow (or edit your inbound DID's flow)
+3. Add a **CF_URLFetch** block with these settings:
+   - **URL**: `https://erp.broadcastmgmt.cloud/api/method/voxtelesys_integration.api.inbound_call`
+   - **Method**: POST
+   - **Parameters**:
+     - `caller_id` = `[caller_id]` (3CX variable for inbound caller number)
+     - `called_did` = `[called_did]` (optional)
+     - `call_id` = `[call_id]` (optional, enables deduplication)
+4. Connect the block in your call flow — it can run in parallel with ringing, no need to wait for the response
+
+---
+
+## Optional: Webhook Secret
+
+To prevent unauthorized calls to the endpoint, add this to your site config:
+
+```bash
+bench --site erp.broadcastmgmt.cloud set-config voxtelesys_webhook_secret "yourtoken"
+```
+
+Then append `?secret=yourtoken` to the 3CX webhook URL.
+
+---
+
+## Optional: Custom Field for Deduplication
+
+To prevent duplicate tickets if 3CX retries the webhook, add a custom field
+to HD Ticket:
+
+- **DocType**: HD Ticket
+- **Field Name**: `custom_3cx_call_id`
+- **Field Type**: Data
+
+This can be done via **ERPNext → Customize Form → HD Ticket**.
+
+---
+
+## License
+
+MIT