Docs menu
SOS and escalation
An SOS opens an incident, shares the agent's live location while it's open, and alerts the right people. It stays open until a supervisor resolves it, your system resolves it, or the agent says they're safe.
| SDK | API (session token) | What happens |
|---|---|---|
sos.start(note) | POST /v1/org/sos | Opens the SOS (or updates the agent's open one) with their location, then keeps sending location every 10 seconds and checks every 5 seconds who is responding. |
| (automatic) | POST /v1/org/sos/{id}/location | A new position while it's open. |
sos.onUpdate / updates | GET /v1/org/sos/{id} | Status, escalation step, and the name of the supervisor responding. |
sos.safe(note) | POST /v1/org/sos/{id}/safe | The agent is safe. Everyone alerted is told; location stops. |
sos.cancel(note) | POST /v1/org/sos/{id}/cancel | Raised by mistake: closed as a false alarm, and everyone alerted is told. |
sos.resume() | GET /v1/org/me | After the app restarts, picks up an SOS that's still open and carries on. |
Who gets alerted
- Straight away: the supervisors of the agent's team or site (or every supervisor, if none match; or the admins, if you have no supervisors). They get a push on the Hospify for Organisations app, and an SMS if push doesn't reach them.
- If nobody acknowledges within your organisation's time limit (60 seconds unless you change it in org.hospify.cloud, Escalation): every admin and the owner.
- All along: your webhooks and event feed, so your own control room sees it too.
Supervisors act on the Live SOS Board at org.hospify.cloud: see the agent on a map with their trail, acknowledge, add notes, resolve. Your own back office can do the same through the API.
States
open → acknowledged (someone is responding) → closed as resolved or false_alarm. escalation_step is 0 (supervisors) or 1 (every admin).
Location in the background
On phones, an SOS should keep sending location when the agent locks the screen. Turn on background location for your app: on Android a foreground service with the location type, on iOS the "location" background mode. The React Native and Flutter pages show the settings.