The Notification Events subsystem is responsible for pushing data out to clients when events occur.
The following calls are related to subscription of events
- Register for Client Notifications
- Register for Server Notifications
- Get WebPush Service Options
- Register for WebPush Notifications
- Unregister WebPush Notifications
Notification content is always JSON.
JSON Event Body
Name | Type | Description |
---|---|---|
accountId | string | The Account IdAccount Id - A unique non changing value to identify a particular Circle user account. Circle Account Id's are globally unique and are UUID v4 strings. The Account Id is not the same value as the Logitech Account Id found when introspecting an OAuth2 Authentication token. Example: 9385e6f9-70c3-45b2-62e4-ace3d027988a involved. |
eventType | string | Which event payload is contained in the eventData field. One of:
|
eventData | object | The event specific data payload defined below. |
userData | any | The |
Event Data Payloads
Each eventType has a specific payload format in the eventData field.
activity_created, activity_updated, and activity_finished
These events all contain the same object as you get from Get Activity by Id with the addition of an accessoryId field for the Accessory involved. All of these events are propagated in near real-time with a delay between occurrence and transmission ranging from several seconds to one minute. When receiving these events, there is no need to call Get Activity by Id, as the same data is present already in the eventData field.
activity_created
- Sent once after the initial Activity is created and the first analysis for Classifiers has been completed. The initial Activity meta-data is included in the notification.activity_updated
- Sent zero or more times depending on the length of the Activity. The Classifier meta-data can change and is cumulative for items detected. Relevance Level can change from the initial activity_created event.activity_finished
- Sent once and indicates that no further activity_updated events will happen. The meta-data is now finalized and calls to the Activities API functions such as Get Activity by Id, Get Activity DASH, Get Activity JPG File and Get Activity MP4 File are now idempotent.
activity_deleted
This event indicates that the user has performed an early delete of an ActivityActivity - An event that is represented by a start time, end time, relevance and other meta-data. Activities are used to represent videos or audio activity that is part of the same sequence of frames or content. Every Activity has a unique Activity Id. Activities will only be stored for as long your service plan dictates. An Activity belongs to an Accessory. For the full list of attributes on an Activity see Get Activity by Id. Activities can be referred to as "clips" or "recordings" in the Logi Circle application. . After this event is received, calls to the Activities API will fail with a 404 - Not Found. Media related to the Activity has already been purged when this event gets propagated.
Name | Type | Description |
---|---|---|
accessoryId | string | The Accessory IdAccessory Id - A unique non changing value to identify a particular Accessory. Accessory Id's are globally unique and are UUID v4 strings. A new Accessory Id is assigned by the servers when a device is associated to an account for the first time. If the same physical device is re-associated to the same account, it will receive the same Accessory Id again. If the same physical device is re-associated to a different account, it will receive a new Accessory Id. Example: 70e3e6f9-70c3-45b2-62e4-ace3d027988a involved. |
activityId | string | The Activity IdActivity Id - A unique non changing value to identify a particular Activity within an Accessory event stream. The API uses a short ISO8601 based timestamp format (YYYYMMDDTHHMMSSZ) with everything represented server side as UTC+0 or "zulu" format. Activity Id's are the short Timestamp of the initial time of Activity creation. However, the Activities startTime value may be later than the value represented by the Activity Id due to trimming and video processing. Activity Id's are not globally unique, but are unique for a given Accessory Id. involved. |
motion_started and motion_stopped
These events require the rarely granted Permissions scope of circle:notifications_motion.
These are raw, unfiltered and possibly high frequency events indicating that the camera has detected some kind of motion is in progress. Since motion events are unprocessed, an ActivityActivity - An event that is represented by a start time, end time, relevance and other meta-data. Activities are used to represent videos or audio activity that is part of the same sequence of frames or content. Every Activity has a unique Activity Id. Activities will only be stored for as long your service plan dictates. An Activity belongs to an Accessory. For the full list of attributes on an Activity see Get Activity by Id. Activities can be referred to as "clips" or "recordings" in the Logi Circle application. may not be created if the Classifiers engine later determines there is no Relevance Level for it. These events are propagated in real-time with a delay of 0 to 4 seconds from actual occurrence. A single motion_stopped event will always be sent if a motion_started event has occurred regardless if an ActivityActivity - An event that is represented by a start time, end time, relevance and other meta-data. Activities are used to represent videos or audio activity that is part of the same sequence of frames or content. Every Activity has a unique Activity Id. Activities will only be stored for as long your service plan dictates. An Activity belongs to an Accessory. For the full list of attributes on an Activity see Get Activity by Id. Activities can be referred to as "clips" or "recordings" in the Logi Circle application. was created. The payload for these events is an object containing the following keys:
Name | Type | Description |
---|---|---|
accessoryId | string | The Accessory IdAccessory Id - A unique non changing value to identify a particular Accessory. Accessory Id's are globally unique and are UUID v4 strings. A new Accessory Id is assigned by the servers when a device is associated to an account for the first time. If the same physical device is re-associated to the same account, it will receive the same Accessory Id again. If the same physical device is re-associated to a different account, it will receive a new Accessory Id. Example: 70e3e6f9-70c3-45b2-62e4-ace3d027988a involved. |
timestamp | string | The originating UTC TimestampTimestamp - An ISO8601 based format with everything represented server side as UTC+0 or "zulu" format. Takes the form of YYYY-MM-DDTHH:MM:SSZ - For example: 2015-04-04T00:43:29Z or 2016-05-28T23:12:59Z or 2016-11-04T12:00:00Z at the AccessoryAccessory - A unique device within the system. An accessory can be any of type and is represented by a unique Accessory Id. An accessory is linked to an account via an accountId. Within this API, a singular Circle camera is an Accessory. that the event occurred. The offset from wall-clock time can be used to determine overall event propagation delay if needed. |
accessory_added
This event contains the same object as you get from Get Accessory by Id and is triggered from an invocation of Create Accessory. Since the process of creating an Accessory is asynchronous and involves BLE setup, only the Accessory IdAccessory Id - A unique non changing value to identify a particular Accessory. Accessory Id's are globally unique and are UUID v4 strings. A new Accessory Id is assigned by the servers when a device is associated to an account for the first time. If the same physical device is re-associated to the same account, it will receive the same Accessory Id again. If the same physical device is re-associated to a different account, it will receive a new Accessory Id. Example: 70e3e6f9-70c3-45b2-62e4-ace3d027988a in the return set is considered valid. As the camera completes its WiFi setup and configuration, you will receive accessory_settings_changed
events with valid contents. An accessory is not considered fully setup until the firmwareVersion field is populated with a non-empty value.
accessory_deleted
This event contains the following object with just an "accessoryId" field for the AccessoryAccessory - A unique device within the system. An accessory can be any of type and is represented by a unique Accessory Id. An accessory is linked to an account via an accountId. Within this API, a singular Circle camera is an Accessory. involved. This event is triggered from an invocation of Delete Accessory by Id.
Name | Type | Description |
---|---|---|
accessoryId | string | The Accessory IdAccessory Id - A unique non changing value to identify a particular Accessory. Accessory Id's are globally unique and are UUID v4 strings. A new Accessory Id is assigned by the servers when a device is associated to an account for the first time. If the same physical device is re-associated to the same account, it will receive the same Accessory Id again. If the same physical device is re-associated to a different account, it will receive a new Accessory Id. Example: 70e3e6f9-70c3-45b2-62e4-ace3d027988a involved. |
accessory_settings_changed
This event means that a client (including yours) has changed a setting on the AccessoryAccessory - A unique device within the system. An accessory can be any of type and is represented by a unique Accessory Id. An accessory is linked to an account via an accountId. Within this API, a singular Circle camera is an Accessory. via the Set Accessory Config by Id call. This event contains the same object as you get from Get Accessory by Id.
service_plan_changed
This event contains the same object as you get from Get Accessory by Id and indicates that the Service Plan Features are now different.
summary_created
This event contains the bare
summary object as defined in Get Summary by Id. When this event is received the SummarySummary - A video clip that is comprised of one or more Activities with filler data placed between them. Summaries are generated via API calls and have numerous options which govern their creation. A summary is referred to as a "Day Brief" in the Logi Circle application. state is now processed
and ready to be viewed or downloaded.
firmware_update_started, firmware_update_progress, firmware_update_completed
If these events are received, but were initiated by your client, it means another party initiated the firmware update. You can then track the progress
firmware_update_started
- This indicates the firmware update process has begun.firmware_update_progress
- This reports a change in the firmware download percentage progress. You may not receive this event if the download goes very fast. You must handle the race condition between this event andaccessory_settings_changed
when the AccessoryAccessory - A unique device within the system. An accessory can be any of type and is represented by a unique Accessory Id. An accessory is linked to an account via an accountId. Within this API, a singular Circle camera is an Accessory. goes offline to reboot and finish the update.firmware_update_completed
- Sent once and indicates that the firmware update has ended. If the process goes fast, this may be the only event received. You must handle the race condition between this event andaccessory_settings_changed
when the AccessoryAccessory - A unique device within the system. An accessory can be any of type and is represented by a unique Accessory Id. An accessory is linked to an account via an accountId. Within this API, a singular Circle camera is an Accessory. comes back online after its reboot.
Name | Type | Description |
---|---|---|
accessoryId | string | The Activity IdActivity Id - A unique non changing value to identify a particular Activity within an Accessory event stream. The API uses a short ISO8601 based timestamp format (YYYYMMDDTHHMMSSZ) with everything represented server side as UTC+0 or "zulu" format. Activity Id's are the short Timestamp of the initial time of Activity creation. However, the Activities startTime value may be later than the value represented by the Activity Id due to trimming and video processing. Activity Id's are not globally unique, but are unique for a given Accessory Id. involved. |
completionStatus | string | One of the following which indicates success or failure:
|
downloadProgress | integer | This is a value from |
firmwareId | string | The Firmware Version Id being installed. You can match this to data from Get Firmware by Model Number. |
version | string | The user visible firmware version being installed. This is the same as the version field returned in Get Firmware by Model Number. |
account_deleted
This event is sent when an account is deleted from the Circle system. This is a rare event, but typically occurs due to the GDPR deletion requests. This event is propagated to all receivers even if it wasn't specified in the eventFilter for your registration. You will receive this event after receiving individual accessory_deleted
events. After the Circle servers propagate this event, all Notification registration will be automatically deleted and active WebSockets connections will be closed. There is no need for your client to invoke Unregister Server Notifications or Unregister WebPush Notifications. There is no additional payload in this event as the main payload already contains accountId
.
Examples
{
"accountId": "9385e6f9-70c3-45b2-62e4-ace3d027988a",
"eventType": "activity_created",
"eventData": { ... }
}
{
"accountId": "9385e6f9-70c3-45b2-62e4-ace3d027988a",
"eventType": "activity_created",
"eventData": { ... }
"userData": {
"foo": "bar"
}
}
{
"accountId": "9385e6f9-70c3-45b2-62e4-ace3d027988a",
"eventType": "account_deleted",
"eventData": {}
"userData": {
"foo": "bar"
}
}