# Escalation trees and voice calls

**Where:** Admin → 📞 Escalation (`/settings/escalation`). Voice provider: Settings → Teleconsult, ABDM & calls (or Caresoft's shared account in the platform console).

## How it works
1. An alert is raised → normal notification (WhatsApp / email / push) = step 0.
2. The best matching **active policy** attaches (ward-specific before hospital-wide, then priority): match on alert type and severity.
3. The worker (every minute) runs each step at its delay **from when the alert was raised**, while the alert is still **open**.
4. Acknowledging anywhere stops the tree: on screen, from the WhatsApp link, or by **pressing 1** on the call.
5. Pressing **2** ("cannot attend") runs the next step immediately.
6. Device alarms that end at the device close the alert and stop the tree.

Targets: care team (enrolment doctor + coordinator + admitting doctor; falls back to hospital alert roles), everyone with a role, a named user, or any phone number (e.g. the duty phone). Channels: voice, WhatsApp, SMS, email. Up to 10 people per step.

The demo has two policies: *Critical patient alerts* (5 min call care team → 10 min call doctors → 15 min WhatsApp + call admin) and *Cold chain excursions* (15 min call biomedical → 30 min call admin).

## Voice providers
| Provider | Settings | Set-up |
|---|---|---|
| `log` | – | Default. No call; written to `storage/logs/voice.log`. Use for testing. |
| Exotel (India) | SID, API key + token, subdomain (`api.in.exotel.com` for the Mumbai cluster), ExoPhone as caller ID, flow (app) ID | Build one flow in the Exotel dashboard: **Greeting** applet → "dynamic text from URL" `https://<host>/api/v1/voice/<client>/exotel/say` → **Gather** (1 digit) → **Passthru** to `https://<host>/api/v1/voice/<client>/exotel/digits`. Each call is placed with *Connect number to call flow*; `CustomField` carries the call token. Use a transactional ExoPhone; DLT / TRAI rules apply. |
| Twilio | Account SID, auth token, caller ID | Nothing to build: TwiML `<Gather>` is sent inline. Request signatures are verified (`voice_twilio_verify`). |
| Other (Ozonetel, Knowlarity, Plivo…) | Webhook URL + key | CarePulse POSTs `{to, message, token, digits_url, status_url, caller_id}`; the adapter places the call, then POSTs `{"digits":"1"}` to `digits_url` and `{"status":"completed|no-answer|busy|failed"}` to `status_url`. |

The script read on the call: hospital, severity, patient + ward/bed (or location), the alert text, then "Press 1 to acknowledge and attend. Press 2 if you cannot attend." Keep alert texts short – they are read aloud.

## Testing
Escalation page → **Test call to my mobile** (uses the user's mobile on their account). The call log on the same page and on each alert shows status: calling, answered, acknowledged, declined, no answer, busy, failed.

## Go-live checks
- Every user who can be called has a correct mobile number.
- Duty phone numbers for night shifts (use a `phone` target).
- Ward policies for ICU / NICU with shorter delays.
- Agree with the medical director that escalation supplements, not replaces, the bedside response.
