# Voxtelesys Integration for ERPNext / Frappe Helpdesk

Frappe app that wires the **Voxtelesys** voice + SMS platform into ERPNext —
giving Helpdesk agents click-to-call, inbound call popups, agent routing,
call recording, SMS send/receive, and auto-ticketing on missed calls.

Two architectures are supported and can run side by side:

| Path | Use when | Endpoint |
| --- | --- | --- |
| **Direct API** (v2.x) — ERPNext talks to Voxtelesys directly | You want click-to-call, agent routing, SMS, and recording driven from the desk UI | `api.voxtelesys.handle_inbound_call`, `api.sms.handle_inbound_sms` |
| **3CX bridge** (v1.x, legacy) — 3CX brokers calls, ERPNext just auto-creates tickets | Your 3CX PBX already routes inbound calls and you only want ticketing on the ERPNext side | `api.inbound_call` |

---

## Architecture overview

### Direct API path
```
Caller ── PSTN ──→ Voxtelesys ──webhook──→ ERPNext
                                         │
                                         ├─ writes Voxtelesys Call Log
                                         ├─ creates HD Ticket on missed call
                                         ├─ rings agent (Round Robin / Availability)
                                         └─ returns VoXML <Dial> → call connects to agent's phone
```

### 3CX bridge path
```
Caller ── PSTN ──→ Voxtelesys SIP trunk ──→ 3CX PBX
                                              │
                                              ├─ rings extensions normally
                                              └─ CF_URLFetch ─→ ERPNext (creates HD Ticket only)
```

---

## 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
```

After install, three custom fields are added via fixtures:

- `User.custom_voxtelesys_number` — E.164 number to ring for inbound routing
- `HD Ticket.custom_voxtelesys_call_sid` — dedup for direct-API missed-call tickets
- `HD Ticket.custom_3cx_call_id` — dedup for 3CX-bridge tickets

---

## Configuration (direct API path)

1. **Get a Voxtelesys API token** from the [Voxtelesys developer portal](https://developer.voxtelesys.com/apis/authorization/).
2. Open **Voxtelesys Settings** in ERPNext and fill in:
   - **Voxtelesys API Token** (Bearer token)
   - **Default Caller ID** (E.164, used for outbound voice and SMS)
   - **Public Base URL** (e.g. `https://erp.broadcastmgmt.cloud`)
   - **Webhook Signing Secret** (optional but recommended — HMAC-SHA256)
   - **Enable Call Recording** if desired
   - **Inbound Call Routing** (`Round Robin`, `Availability-Based`, or `Direct (no routing)`)
3. Copy the two **Webhook URLs** shown in Voxtelesys Settings and paste them into:
   - Voice API Profile → Answer URL: `…/api/method/voxtelesys_integration.api.voxtelesys.handle_inbound_call`
   - SMS Profile → Inbound Webhook: `…/api/method/voxtelesys_integration.api.sms.handle_inbound_sms`
4. Tick **Enabled** and save.
5. Test with the **Test API Connection** button on Voxtelesys Settings.

### Agent routing setup

For Round Robin / Availability-Based routing to work, each agent's **User**
record needs a `Voxtelesys Number` set (the field is added automatically by
the fixture). This is the actual phone number Voxtelesys will dial — usually
the agent's cell or desk phone DID, in E.164.

---

## Configuration (3CX bridge path)

1. **3CX → Management Console → Call Flow Designer**
2. Create or edit the Call Flow for your inbound DID
3. Add a **CF_URLFetch** block:
   - **URL**: `https://erp.broadcastmgmt.cloud/api/method/voxtelesys_integration.api.inbound_call`
   - **Method**: POST
   - **Parameters**:
     - `caller_id` = `[caller_id]`
     - `called_did` = `[called_did]` (optional)
     - `call_id` = `[call_id]` (recommended — enables dedup)
4. Optional secret token: `bench --site … set-config voxtelesys_webhook_secret yourtoken` and append `?secret=yourtoken` to the URL.

---

## Usage

### Click-to-call

- **HD Ticket form**: a "Voxtelesys → Call ..." button appears in the
  toolbar whenever the ticket's linked Contact has a mobile / phone number.
- **Lead / Contact forms**: same button group; works on any Phone field via
  the `frappe.phone_call.handler` override.
- A floating call bar appears at the bottom of the screen showing live call
  status. Clicking "Open Log" jumps to the Call Log entry.

### Inbound calls

When a call hits the inbound webhook, the agent on shift gets a popup with
the caller's number and a "Ringing…" indicator. If no agent answers, a
**missed-call HD Ticket** is auto-created (toggle via Voxtelesys Settings →
*Auto-create Helpdesk Ticket on Missed Call*).

### SMS

- **Send**: "Voxtelesys → Send SMS" button on HD Ticket and Lead forms.
- **Receive**: inbound MO messages from a known Contact with an open HD
  Ticket are automatically appended as a `Communication` row on the ticket
  thread (toggle via Voxtelesys Settings → *Auto-attach Inbound SMS to Open
  Ticket*).
- All messages are persisted to the **Voxtelesys SMS Log** doctype with
  Dynamic Link entries for cross-referencing.

---

## DocTypes

| Name | Purpose |
| --- | --- |
| **Voxtelesys Settings** | Single — global config |
| **Voxtelesys Call Log** | One row per call (in or out) with status, duration, recording URL, links |
| **Voxtelesys SMS Log** | One row per SMS (in or out) with body, status, delivery receipt, links |

---

## Scheduled jobs

- `sync_pending_call_logs` runs every 5 minutes to reconcile any Call Log
  rows stuck in `Ringing` or `In Progress` because a status webhook was
  missed. Configured in `hooks.py:scheduler_events`.

---

## Whitelisted API surface

| Method | Auth | Purpose |
| --- | --- | --- |
| `voxtelesys_integration.api.voxtelesys.handle_inbound_call` | guest | Voxtelesys voice webhook |
| `voxtelesys_integration.api.voxtelesys.handle_call_status` | guest | Voxtelesys status callback |
| `voxtelesys_integration.api.voxtelesys.make_outbound_call` | user | Click-to-call from desk UI |
| `voxtelesys_integration.api.voxtelesys.test_connection` | sysmgr | Settings → Test button |
| `voxtelesys_integration.api.voxtelesys.get_linked_call_logs` | user | Form sidebar history |
| `voxtelesys_integration.api.sms.send_sms` | user | Send SMS from desk UI |
| `voxtelesys_integration.api.sms.handle_inbound_sms` | guest | Voxtelesys SMS webhook |
| `voxtelesys_integration.api.sms.get_linked_sms_logs` | user | Form sidebar SMS history |
| `voxtelesys_integration.api.inbound_call` | guest | Legacy 3CX CF_URLFetch entrypoint |

Guest endpoints verify a HMAC-SHA256 signature in the
`X-Voxtelesys-Signature` header against the **Webhook Signing Secret** in
settings (if configured). The legacy 3CX endpoint uses a query-string
`?secret=` token from `site_config.json` instead.

---

## Development

```bash
cd ~/frappe-bench/apps/voxtelesys_integration
git remote -v   # should point at forge.wilddragon.net
bench --site erp.broadcastmgmt.cloud clear-cache && bench restart
```

To export updated fixtures after editing custom fields in the UI:

```bash
bench --site erp.broadcastmgmt.cloud export-fixtures --app voxtelesys_integration
```

---

## License

MIT