Recordings & Retention

For compliance and privacy, you can adjust the recording and retention settings for various alarm events.

Set Settings

Topic

Publish to: api_client/<client_name>/<location_id>/<device_id>/retention_policy/set

Payload

Not retained
QoS: 1

{
  "fall": {
    "secondsBefore": 30,
    "secondsAfter": 30,
    "retentionHours": 72
  },
  "helpCall": {
    "secondsBefore": 30,
    "secondsAfter": 30,
    "retentionHours": 72
  },
  "noise": {
    "secondsBefore": 30,
    "secondsAfter": 30,
    "retentionHours": 72
  },
  "outOfBed": {
    "secondsBefore": 30,
    "secondsAfter": 30,
    "retentionHours": 72
  },
  "outOfRoom": {
    "secondsBefore": 30,
    "secondsAfter": 30,
    "retentionHours": 72
  },
  "outOfSeat": {
    "secondsBefore": 30,
    "secondsAfter": 30,
    "retentionHours": 72
  },
  "wandering": {
    "secondsBefore": 30,
    "secondsAfter": 30,
    "retentionHours": 72
  },
  "roomStateChange": {
    "secondsBefore": 0,
    "secondsAfter": 0,
    "retentionHours": 72
  }
}

• The payload keys are event types. Possible values are fall, helpCall, noise, outOfBed, outOfRoom, outOfSeat, wandering, and roomStateChange. Each value is either null, which leaves the current retention settings unchanged, or an object with the following properties:

  • secondsBefore: Number of seconds to record before the event was detected. The amount of footage kept in a ring buffer before and after an event depends on the detection type. All detections support at least 10 seconds of footage before the event. If secondsBefore exceeds the maximum for the detection type, the maximum is used.
  • secondsAfter: Number of seconds to record after the event was detected. Not all detections support footage after the event. If secondsAfter exceeds the maximum for the detection type, the maximum is used. This maximum is 0 if the detection does not support footage after the event.
  • retentionHours: Number of hours to retain the recording. For internal compliance reasons, the maximum retention period is two years. If retentionHours exceeds 17520, the maximum is used.

If retentionHours is set to 0, or if both secondsBefore and secondsAfter are set to 0, no footage is retained for the event.

Note that roomStateChange supports neither secondsBefore nor secondsAfter. Room state changes are not necessarily linked to an alarm or event and occur frequently, so only the 15 seconds preceding a change are stored.

Get Settings

Topic

Subscribe to: api_client/<client_name>/<location_id>/<device_id>/retention_policy

Publish to: api_client/<client_name>/<location_id>/<device_id>/retention_policy/get

Payload

Publish an empty payload.

Response

Not retained
QoS: 1

See the payload in the “Set Settings” section above. The response contains the current settings. If no configuration has been set for an event type yet, its value is null.

Get Recordings

Alarm event messages that support footage retention contain audio and video properties with URLs to the respective recordings. If either property is null or omitted, no corresponding recording is expected for the event.

Event messages are sent as soon as an alarm is detected. Because retention can be configured to continue recording after the event, the footage might not yet be available at these URLs when the message is sent.

Once the recordings for an event are available, their URLs are published again via MQTT on the topic described below.

The codec and container are as follows:

The audio track in a video file (MP4) is also AAC-encoded.

Topic

Subscribe to: api_client/<client_name>/<location_id>/<device_id>/retention_policy/recordings

Payload

Not retained
QoS: 1

{
  "eventId": "f3e1c2d4-5b6a-4c7d-8e9f-0a1b2c3d4e5f",
  "eventType": "fall",
  "audio": "https://example.com/audio.m4a",
  "video": "https://example.com/video.mp4"
}

• eventId: Unique identifier of the event (UUID).
• eventType: Type of event. Possible values are fall, helpCall, noise, outOfBed, outOfRoom, outOfSeat, wandering, and roomStateChange.
• audio: Optional URL of the event’s audio recording.
• video: Optional URL of the event’s video recording.

The URLs are valid for five minutes. After they expire, you must request new ones.

If a URL is null, no recording is available or expected to become available for the event in subsequent requests. This may be because the event type does not support footage retention or retention was disabled at the time of the event.

Request Recording

Request the recording associated with an event by publishing the event ID.

Topic

Publish to: api_client/<client_name>/<location_id>/<device_id>/retention_policy/recordings/get

Payload

{
  "eventId": "f3e1c2d4-5b6a-4c7d-8e9f-0a1b2c3d4e5f"
}

• eventId: Unique identifier of the event (UUID).

Response

See the topic and payload in the “Get Recordings” section above.