Duress

Acknowledges an open duress incident on behalf of the user: it records that they are responding and can stop further escalation. Only open incidents can be acknowledged.

Always confirm first. Call without confirm to get the incident, tell the user what they are acknowledging, and call again with confirm: true only after they agree.

In a workflow, or from an Agent, this only works where the facility's response plan lets workflows acknowledge, resolve and raise alarms. To close an incident use duress_resolve_incident.

Reads the duress buttons at a facility: their status (battery, last heard, last tested), full profiles (label, room, zone, placement, linked cameras, doors and screens, muted alerts, supervision health), what they can be linked to, the screens that relay their presses, and a newly added button's setup test.

Battery: low is 30% or less (replace soon), critical 20% or less (replace now). Null battery and lastSeenAt mean no screen has heard the button yet. Times are ISO.

Actions:

• status: Button status. Each button with zone, room, battery, when a screen last heard it and when it was last tested. "Are the duress buttons working?", "Which need new batteries?"
• list: Button profiles. Each button's full profile: what duress_buttons_write update changes, plus signal, the screens that heard it in the last day, supervision health and a waiting setup test.
• link_options: Link options. The facility's cameras, doors, screens and access zones a button can be linked to (ids for duress_buttons_write update).
• receivers: Button receivers. The display screens at the facility that hear buttons and relay presses, and whether each is online. ready is false when nothing could hear a button.
• setup_test: Setup test. A newly added button's setup test: waiting (its first press is only a test), received, expired, ended or none, and whether a screen has heard it since it was added. Needs deviceSerialNumber.

Changes duress buttons at a facility: adding a new button, their profile (label, room, zone, placement, notes, linked cameras, doors, screens and access zone, muted device alerts), making one beep so staff can find it, ending a new button's setup test so it goes live, and removing a button.

Fields left out of update keep their values; null clears them. Read the current profile with duress_buttons_read list.

Actions:

• update: Update a button. Saves the button's profile at the facility it is registered to (needs Duress Configuration there). zone is 001 to 999 and unique at the facility. alertsMutedUntil (ISO, at most 30 days ahead) mutes its battery and offline alerts. Needs deviceSerialNumber.
• locate: Make a button beep. Makes the button beep and flash for 30 seconds so staff can find it, e.g. one that keeps reporting a low battery. A screen near it sends the command, so it must be in range of one. Not while it has an open alarm. Needs deviceSerialNumber.
• go_live: Put a new button live. Ends a newly added button's setup test now, so its next press is a real alarm. Check duress_buttons_read setup_test first. Needs Device Management or Duress Configuration at the facility. Needs deviceSerialNumber. Asks for confirmation.
• remove: Remove a button. Unpairs the button from the facility and deletes its profile, which frees its zone. Not while it has an open alarm. Needs Device Management at the facility. Needs deviceSerialNumber. Asks for confirmation.
• add: Add a button. Registers a new duress button at the facility by the serial printed on it. By default its first press in the next 30 minutes is only a test (setupTest). The facility needs a screen with Duress alarm monitoring on or an IoT Gateway. Needs Device Management at the facility. Needs deviceSerialNumber. Asks for confirmation.

Ends the duress test running at a facility now, so the next press is a real alarm. Results follow about 10 minutes later, as for any test.

Reads duress alarm incidents (staff pressed a duress button, or a workflow raised one): lists, one incident's timeline and deliveries, a postmortem report, and the CCTV footage around an alarm.

Statuses: open (nobody has acknowledged it yet), acknowledged (someone is responding), resolved (closed, with a disposition: genuine, false_alarm, test or unknown). active means open or acknowledged. Test incidents (isTest) come from button tests; testType 'unplanned' is an alarm raised as real that a responder resolved as a test.

Delivery status: sent, acknowledged (the receiver confirmed), failed (see error), shadow (dry run, nothing was sent). Deliveries to the monitoring centre are also totalled under monitoringCentre. Results name people but never include phone numbers or email addresses. Times are ISO.

Actions:

• list: List incidents. Newest first. scope: facility (default; the given or connected facility) or organisation (every facility in it you can see; defaults to the facility’s organisation).
• get: Get an incident. Status, the buttons pressed, the timeline (presses, escalations, acknowledgements, notes) and every notification or monitoring-centre delivery attempt with its result. Needs incidentId.
• report: Incident report. For a postmortem: the incident, seconds to acknowledge and resolve, steps reached, every timeline entry, what was sent per channel and what failed, and whether footage was kept. Pair with duress_incidents_write add_note to put the postmortem on the incident. Needs incidentId.
• footage_previews: Alarm footage. Each camera in the alarm's footage: its status, frame and clip counts, uploaded clips, and the frame nearest the press (posterSeconds). With cameraId, that camera only plus every frame's Unix seconds (frameSeconds). Needs CCTV at the facility. Needs incidentId.
• footage_frame: Alarm footage frame. One timelapse frame from the alarm footage, returned as an image: a kept copy once footage is kept, else the live frame inside the alarm window. seconds is a posterSeconds or frameSeconds value from footage_previews. Needs incidentId, cameraId, seconds.

Changes a duress incident without touching the alarm itself: names it, adds staff notes, and keeps or releases the CCTV footage around it. Nobody is alerted. To acknowledge, resolve or tell responders use duress_acknowledge_incident, duress_resolve_incident or duress_post_update.

Actions:

• rename: Name an incident. Names the incident so it is easy to find later, e.g. "Aggressive visitor at the front counter". An empty or null name removes it. Names show in the Duress console and reports. Needs incidentId.
• add_note: Add a note. Adds a note to the incident's timeline, e.g. what the user found or who attended. Any status; only staff see notes and they don't change the incident. Write it in the user's words and confirm the wording with them first. Needs incidentId, note.
• keep_footage: Keep alarm footage. Keeps the CCTV footage around a resolved real alarm so it isn't deleted with normal recordings, using the response plan's minutes and cameras. Happens a few minutes later, once uploaded. Not for tests, open alarms, or footage already kept or released. Needs incidentId.
• release_footage: Release kept footage. Gives up the footage kept for an alarm: clips return to normal retention and kept frames are deleted, so it can no longer be viewed once normal recordings expire. Needs Duress Configuration at the facility. Needs incidentId. Asks for confirmation.

Lifts a duress alarm's lockdown: the doors it locked let people in again. Works whatever the alarm's status.

Confirm first. Call without confirm to see the lockdown, tell the user, and call again with confirm: true once they agree.

Posts an update to the people responding to a duress alarm, e.g. "Police are on the way" or "All clear, the person has left". It appears on their alarm page and in the Duress app, and on a real alarm the response plan can also text it to everyone already texted about the alarm. Updates can be posted until 24 hours after the alarm is resolved.

Confirm first. Call without confirm to check the incident, show the user the exact wording, and call again with confirm: true once they agree. For something only staff should see, use duress_incidents_write add_note instead.

Raises a real duress alarm at the facility, as if a button were pressed: the response plan runs (people are alerted, escalation and reminders follow, response actions run) and the alarm says it was raised by this workflow, with the reason.

• reason: what happened, e.g. "Door forced open at the rear exit" (up to 200 characters).
• deviceSerialNumber: optional. A button whose location to use; only then is the monitoring centre told too, with that button's zone.

Only as a workflow step, at facilities whose response plan lets workflows acknowledge, resolve and raise alarms. While this workflow's alarm is open it won't raise another; it returns that alarm instead.

Duress compliance reporting for a facility, brand or organisation: response times (P50/P95), incidents by disposition and false-alarm rate, test coverage and overdue facilities, button uptime, monitoring-centre delivery success, and an incident-by-incident export. Plus the latest alarm's undelivered alerts at one facility.

Days are facility-local; periods over 400 days are shortened (range.capped). Real and test incidents are counted separately. Durations are in ms (p50Ms, p95Ms). Brand reports only cover the facilities you can reach unless you have organisation-wide access (scope.restrictedToAccessibleFacilities).

Actions:

• overview: Duress report overview. Totals, monthly trend and per-organisation, per-brand and per-facility metrics (incidents, testCoverage, deviceUptime, deliveries). Facilities are paged.
• compliance_summary: Duress compliance summary. What the compliance PDF shows: test coverage with overdue facilities, button uptime, delivery success, recent tests (testHistory), and per facility its last test, drill and real alarm with each button’s uptime. Facilities are paged.
• incident_export: Duress incident export. One row per incident, oldest first, with the CSV export’s columns: facility, test or real, status, disposition, local times, seconds to acknowledge and resolve, who acknowledged and resolved, buttons and delivery counts.
• delivery_problems: Undelivered alarm alerts. The facility's latest alarm or test (with its whole test window) and the alerts that never arrived, by channel. problems is null when everything got through. Needs Duress or Duress Configuration there.

Resolves a duress incident: it closes the alarm, stops escalation and records the outcome. Open and acknowledged incidents can be resolved.

• disposition: genuine (a real emergency), false_alarm, test or unknown.
• note: what happened. Required for a genuine alarm.

Always confirm first. Call without confirm to get the incident, tell the user which alarm they're closing and the outcome, and call again with confirm: true only after they agree.

In a workflow, or from an Agent, this only works where the facility's response plan lets workflows acknowledge, resolve and raise alarms.

Reads Duress settings: response plans (who is alerted, in which order and how, at a facility or as a brand template), the resolved plan the alarm engine actually uses, the people and roles that can be added, device alerts (battery, offline, coverage and delivery problems), brand contact rules and plan status, a brand's or organisation's button overview, and where alarms go to the monitoring centre.

A facility follows its brand's (else its organisation's) template, extends it with extra contacts (mode extend), or replaces it with its own plan (mode replace). Change settings with duress_settings_write. Times are ISO.

Actions:

• response_plan: Response plan. The plan in force at a facility (effective) and what each level holds (sources: facility, brand, organisation), or with only brandId the brand's template. Contacts are as saved, ready to edit and save back.
• resolved_plan: Resolved plan. Who the alarm engine contacts at the facility, tier by tier: roles expanded to people, channels each can be reached on, delays, and warnings to fix before an alarm. Names only, no phone numbers or emails.
• contact_options: Contact options. People and roles that can be added to the facility's plan (needs Duress Configuration there), or with only brandId to the brand's template, after the brand's contact rules.
• device_alerts: Device alerts. Who is told about low batteries, offline buttons, lost coverage and failed deliveries: the rules at each level and the facility’s resolved recipients, or with only brandId the brand’s rules.
• contact_rules: Brand contact rules. Which roles facilities in the brand may add to plans: allowAllExcept hides the listed roles, manual offers only them. Needs what editing the brand plan needs. Needs brandId.
• plan_status: Brand plan status. Each facility in the brand: whether it follows the template, extends it or has its own plan, how many contacts it added, and its plan's warnings. Needs brandId.
• buttons_summary: Buttons overview. Every facility in a brand or organisation: buttons, battery and offline counts, the next and last test. The Brands & Customisation and organisation overviews' data.
• monitoring: Monitoring centre routing. How alarms leave the facility: eaAlarmType none, cid (a monitoring centre call through eaAlarmProvider) or relay (a wired panel through eaRelayModel), and the providers it can use.

Changes Duress settings: response plans (at a facility, or a brand's or organisation's template), device alerts, brand contact rules, and where alarms go to the monitoring centre. Every change asks for confirmation because it changes who is alerted.

Pass one of facilityId (default: the connected facility), brandId or organisationId. Facility plans need Duress Configuration there; templates need an organisation admin with Duress Configuration, or for a brand Duress Configuration at every facility in it. Read first with duress_settings_read.

Actions:

• save_response_plan: Save a response plan. Tiers of contacts alerted afterSeconds after the press (ascending, first usually 0), ackRequired, reminders and responseActions. A facility can instead extend its template (mode extend) with additions. Fields left out keep their saved values; responseActions merge by action. Asks for confirmation.
• remove_response_plan: Remove a response plan. Deletes the plan saved at this level, so a facility follows its template again and a brand falls back to the organisation's. Asks for confirmation.
• save_device_alerts: Save device alerts. Replaces the device alert rules at this level: up to 10 rules, each a set of events and contacts (push, sms or email). Keep rule ids read from duress_settings_read device_alerts. Needs rules. Asks for confirmation.
• remove_device_alerts: Remove device alerts. Deletes the device alert rules at this level, so it follows the next level up again. Asks for confirmation.
• save_contact_rules: Save brand contact rules. Which roles the brand's facilities can add to plans: allowAllExcept hides roleIds, manual offers only roleIds. Contacts already saved stay; resolved plans refresh. Needs brandId, mode, roleIds. Asks for confirmation.
• save_monitoring: Save monitoring centre routing. Where alarms go: eaAlarmType none, cid (needs eaAlarmProvider, one of the providers duress_settings_read monitoring lists) or relay (eaRelayModel). Needs Duress Configuration at the facility. Needs eaAlarmType. Asks for confirmation.

Locks the facility down for a duress alarm: every door stops letting people in until the lockdown is lifted (duress_lift_lockdown, or from the console). An alarm only ever gets one lockdown.

Never for test or resolved alarms. Needs Door/Gate Access at the facility.

Confirm first. Call without confirm to check the incident, tell the user every door will lock, and call again with confirm: true once they agree.

Starts a duress test at a facility now. Until it ends, every press is a test, not a real alarm:

• walk: staff press each button; only the first step of the response plan is alerted, labelled TEST.
• drill: the whole response plan runs, labelled TEST.

The facility's test contacts are told it started and get results about 10 minutes after it ends. One test at a time per facility. End it early with duress_end_test; book tests ahead with duress_tests_write.

Confirm first. Call without confirm, tell the user presses won't raise real alarms for durationMinutes, and call again with confirm: true once they agree. In a workflow, or from an Agent, this only works where the facility's response plan lets workflows acknowledge, resolve and raise alarms.

Reads duress button tests: the schedules that book them (walk, comms or drill, once or repeating, for an organisation, brands or facilities), the test windows they create at each facility (scheduled, active, completed, cancelled, plus ad-hoc tests), and a window's results (which buttons were pressed or missed, who was told, monitoring-centre signals, acknowledgement times).

Who booked, changed or cancelled a test is left out; delivery receivers are redacted. Times are ISO; localDate and localStartTime are in the facility's time zone. Book or change tests with duress_tests_write; start one now with duress_start_test.

Actions:

• schedules: Test schedules. scope facility (default; every schedule covering it, including shared ones it skips or replaces), brand (brandId) or organisation (default: the facility’s). Newest change first.
• windows: Test windows. A facility's test windows from from to to (default about a week back to a month ahead), or with only organisationId the organisation's upcoming windows across its facilities.
• results: Test results. A window and its results: stored once sent, computed live while a test runs (the walk-test checklist), null for scheduled or cancelled windows. Needs Duress at the facility. Needs startsAtKey.

Books, changes and cancels duress test schedules, sets how one facility follows a shared schedule, and cancels a single upcoming test window. Every change books or rewrites future windows and emails the stakeholders, so each asks for confirmation.

Schedules need Duress Configuration over their whole target (an organisation admin for organisation-wide ones). Times are in each facility's time zone. Read schedules and windows first with duress_tests_read; start a test now with duress_start_test.

Actions:

• create_schedule: Book a test schedule. Books windows up to about a year ahead at every facility in target and emails a booking confirmation. Needs name, type, target, startDate, localStartTime and recurrence. Needs name, type, target, startDate, localStartTime, recurrence. Asks for confirmation.
• update_schedule: Change a test schedule. Fields left out keep their values. Future windows are rewritten (started ones are left) and stakeholders get a change notice. Use the ownerScope in the result afterwards. Needs ownerScope, scheduleId. Asks for confirmation.
• cancel_schedule: Cancel a test schedule. Cancels the schedule and its future windows, and emails the cancellation. Facilities with their own copy keep it. Needs ownerScope, scheduleId. Asks for confirmation.
• set_facility_override: Change a shared schedule for one facility. mode follow (run the shared schedule here again), skip (stop it here) or own (replace it here with a copy built from schedule). Needs Duress Configuration at that facility only. Needs ownerScope, scheduleId, mode. Asks for confirmation.
• cancel_window: Cancel one test window. Cancels one scheduled test at a facility (the schedule keeps going) and emails its stakeholders. Needs Duress at the facility; an active test is ended with duress_end_test instead. Needs startsAtKey. Asks for confirmation.

Unlocks the doors for a duress alarm, e.g. to let police or first aid in: the doors linked to the pressed button, else the response plan's doors. Leave doorIds out for all of them, or list some of them. Each unlock is on the incident timeline and in Access Logs.

Never for test or resolved alarms. Needs Door/Gate Access at the facility.

Confirm first. Call without confirm to see which doors would unlock, tell the user, and call again with confirm: true once they agree.