Notifications

Endpoints

Method	Path	Description
POST	/api/v2/device/notifications	Sends new notification to device
GET	/api/v2/device/notifications	Returns the list of notifications in queue
DELETE	/api/v2/device/notifications/:id	Removes notification from queue or dismiss if it is visible

---

Display Notification

URL	/api/v2/device/notifications
Method	POST
Authorization	basic
Version	2.0.0

Description

Sends notification to the device.

Body

In order to send notification to a device you must post a Notification object.

{
  "priority": "[info|warning|critical]",
  "icon_type":"[none|info|alert]",
  "lifeTime":<milliseconds>,
  "model": {
   "frames": [
    {
       "icon":"<icon id or base64 encoded binary>",
       "text":"<text>"
    },
    {
      "icon": 298,
      "text":"text"
    },
    {
        "icon": 120,
        "goalData":{
            "start": 0,
            "current": 50,
            "end": 100,
            "unit": "%"
        }
    },
    {
        "chartData": [ <comma separated integer values> ]
    }
    ],
    "sound": {
      "category":"[alarms|notifications]",
        "id":"<sound_id>",
        "repeat":<repeat count>
    },
    "cycles":<cycle count>
  }
}

Since API 2.3.0 it is possible to use custom sounds

...
"sound": {
    "url": "<sound URL>",
    "type": "[mp3]",
    "fallback": {
       "category": "[alarms|notifications]",
       "id": "<sound_id>"
    }
}
...

Notification object

Property	Type	Description
model	Object	Message structure and data.
priority	Enum	Optional. Valid values are info, warning, critical
icon_type	Enum	Optional. Valid values: none, info, alert`
lifetime	Integer	Optional. Lifetime of the message in milliseconds.

Detailed Properties Description

• model

  Object that represents message structure and data. It consists of “frames”, “sound” and “cycles” properties.

  • frames – array, that describes the notification structure. Single frame can be simple, goal or spike chart.

    • simple frame consists of icon and text. Example:

      {
         "icon":"<icon_id or binary>",
         "text":"Message"
      }
      

      Icon can be defined as ID or in binary format. Icon ID looks like <prefix>XXX, where <prefix> is “i” (for static icon) or “a” (for animation). XXX - is the number of the icon and can be found at https://developer.lametric.com/icons or via Icons API. Binary icon string must be in this format (png):

      "data:image/png;base64,<base64 encoded png binary>"
      

      or gif:

      "data:image/gif;base64,<base64 encoded gif binary>"
      

    • goal frame consists of icon and goal data. Example:

      {
        "icon":120,
        "goalData":{
          "start": 0,
          "current": 50,
          "end": 100,
          "unit": "%"
         }
      }
      

    • spike chart consists of array of numbers and is displayed as graph. Example:

      {
         "chartData": [ 1, 2, 3, 4, 5, 6, 7 ]
      }
      

  • sound – object that describes the notification sound to play when notification pops on the LaMetric Time’s screen. Example:

    {
        "category":"notifications",
        "id":"cat",
        "repeat":1
    }
    

    • category – sound category. Can be notifications or alarms.

    • id – sound ID. Full list of notification ids:

      bicycle
      car
      cash
      cat
      dog
      dog2
      energy
      knock-knock
      letter_email
      lose1
      lose2
      negative1
      negative2
      negative3
      negative4
      negative5
      notification
      notification2
      notification3
      notification4
      open_door
      positive1
      positive2
      positive3
      positive4
      positive5
      positive6
      statistic
      thunder
      water1
      water2
      win
      win2
      wind
      wind_short
      

      Full list of alarm ids:

      alarm1
      alarm2
      alarm3
      alarm4
      alarm5
      alarm6
      alarm7
      alarm8
      alarm9
      alarm10
      alarm11
      alarm12
      alarm13
      

    • repeat – defines the number of times sound must be played. If set to 0 sound will be played until notification is dismissed. By default the value is set to 1.

    Since API 2.3.0 Sound object can also look like this:

    {
        "url":"<URL of an mp3 file>",
        "type":"mp3",
        "fallback": {
            "category" : "notifications",
            "id" : "cat"
        }
    }
    

    • url - can be any URL to the MP3 file. Currently we support the following audio formats:

    • Sample Rate: 44100, 32000, 24000, 22050, 16000, 12000, 11025, 8000
    • Channels: mono or stereo
    • Sample Size: 16bit

    • type - is an optional property, defines a type of the audio file. Currently mp3 is supported. If it is missing, device will try to detect the media type using Content-Type HTTP header.
    • fallback - object defines a built-in sound to play in case if there are any issues playing MP3 from the URL.

  • cycles – the number of times message should be displayed. If cycles is set to 0, notification will stay on the screen until user dismisses it manually or you can dismiss it via the API (DELETE /api/v2/device/notifications/:id). By default it is set to 1.

• priority

  Priority of the message

  • info – this priority means that notification will be displayed on the same “level” as all other notifications on the device that come from apps (for example facebook app). This notification will not be shown when screensaver is active. By default message is sent with “info” priority. This level of notification should be used for notifications like news, weather, temperature, etc.
  • warning – notifications with this priority will interrupt ones sent with lower priority (“info”). Should be used to notify the user about something important but not critical. For example, events like “someone is coming home” should use this priority when sending notifications from smart home.
  • critical – the most important notifications. Interrupts notification with priority info or warning and is displayed even if screensaver is active. Use with care as these notifications can pop in the middle of the night. Must be used only for really important notifications like notifications from smoke detectors, water leak sensors, etc. Use it for events that require human interaction immediately.

• icon_type

  Represents the nature of notification.

  • none – no notification icon will be shown.
  • info – “i” icon will be displayed prior to the notification. Means that notification contains information, no need to take actions on it.
  • alert – “!!!” icon will be displayed prior to the notification. Use it when you want the user to pay attention to that notification as it indicates that something bad happened and user must take immediate action.

• lifetime

  The time notification lives in queue to be displayed in milliseconds. Default lifetime is 2 minutes. If notification stayed in queue for longer than lifetime milliseconds – it will not be displayed.

Response

Returns success object with notification id.

{
  "success": {
    "id": "<notification id>"
  }
}

Example 1. Send notification

Request

REST:

POST https://<device ip address>:4343/api/v2/device/notifications

Authorization: Basic <Base64("dev:<device API key>")>
Content-Type: application/json
Accept: applciation/json

{
    "priority": "warning",
    "model": {
        "cycles": 1,
        "frames": [
           {
              "icon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAYAAADED76LAAAAUklEQVQYlWNUVFBgYGBgYBC98uE/AxJ4rSPAyMDAwMCETRJZjAnGgOlAZote+fCfCV0nOmA0+yKAYTwygJuAzQoGBgYGRkUFBQZ0dyDzGQl5EwCTESNpFb6zEwAAAABJRU5ErkJggg==",
              "text": "HELLO!"
           }
        ],
        "sound": {
            "category": "notifications",
            "id": "cat"
        }
    }
}

cURL:

$ curl -X POST -H -u "dev" -k \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
      "priority": "warning",
      "model": {
          "cycles": 1,
          "frames": [
          {
              "icon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAYAAADED76LAAAAUklEQVQYlWNUVFBgYGBgYBC98uE/AxJ4rSPAyMDAwMCETRJZjAnGgOlAZote+fCfCV0nOmA0+yKAYTwygJuAzQoGBgYGRkUFBQZ0dyDzGQl5EwCTESNpFb6zEwAAAABJRU5ErkJggg==",
              "text": "HELLO!"
          } ],
          "sound": {
              "category": "notifications",
              "id": "cat"
          }
      }
  }' \
  https://<device ip address>:4343/api/v2/device/notifications
$ Enter host password for user 'dev': <device API key>

Response

HTTP/1.1 200 OK

{ "success": { "id": "1" } }

Example 2. Send notification with custom sound

REST:

POST https://<device IP address>:4343/api/v2/device/notifications

Authorization: Basic <Base64("dev:<device API key>")>
Content-Type: application/json
Accept: application/json

{
    "priority": "warning",
    "icon_type": "info",
    "model": {
        "cycles": 1,
        "frames": [
           {
              "icon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAYAAADED76LAAAAUklEQVQYlWNUVFBgYGBgYBC98uE/AxJ4rSPAyMDAwMCETRJZjAnGgOlAZote+fCfCV0nOmA0+yKAYTwygJuAzQoGBgYGRkUFBQZ0dyDzGQl5EwCTESNpFb6zEwAAAABJRU5ErkJggg==",
              "text": "SOUND IS PLAYING!"
           }
        ],
        "sound": {
            "url":"https://dl.espressif.com/dl/audio/gs-16b-2c-44100hz.mp3",
            "fallback": {
                "category": "notifications",
                "id": "cat"
            }
        }
    }
}

cURL:

curl --request POST 'https://<device IP address>:4343/api/v2/device/notifications' \
-u "dev:<device API key>" -k \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "priority": "warning",
  "icon_type":"info",
  "model": {
      "cycles": 1,
      "frames": [
          {
            "icon":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAYAAADED76LAAAAUklEQVQYlWNUVFBgYGBgYBC98uE/AxJ4rSPAyMDAwMCETRJZjAnGgOlAZote+fCfCV0nOmA0+yKAYTwygJuAzQoGBgYGRkUFBQZ0dyDzGQl5EwCTESNpFb6zEwAAAABJRU5ErkJggg==",
            "text":"SOUND IS PLAYING!"
          }
      ],
      "sound": {
        "url": "https://dl.espressif.com/dl/audio/gs-16b-2c-44100hz.mp3",
        "fallback" : {
            "category": "notifications",
            "id": "cat"
        }
      }
    }
  }'

Response

HTTP/1.1 200 OK

{ "success" : { "id" : "5" } }

---

Get Notification Queue

URL	/api/v2/device/notifications
Method	GET
Authorization	basic
Version	2.0.0

Description

Returns the list of all notifications in the queue. Notifications with higher priority will be first in the list.

Response

Returns array of Notification objects with additional fields like created, exporation_date and type.

[
  {
    "id": "<id>",
    "type": "[internal|external]",
    "priority": "[info|warning|critical]",
    "created": "<isotime>",
    "expiration_date": "<isotime>",
    "model": {...}
  }
]

Property	Type	Description
id	String	Notification id
type	Enum	Notification type: internal or external. External ones come from API Internal ones come from native LaMetric Time apps
priority	Enum	Notification priority: info - put into notification queue along with internal notifications warning - has higher priority than internal notifications critical - interrupts other notifications and wakes the device from sleep (when screensaver is running)
created	String	Time when notification was created in ISO format.
expiration_date	String	Time when notification expires in ISO format.

Example

Request

REST:

GET https://<device ip address>:4343/api/v2/device/notifications

Accept: application/json

cURL:

$ curl -X GET -H -k -u "dev" \
  -H "Accept: application/json" \
  https://<device ip address>:4343/api/v2/device/notifications
$ Enter host password for user 'dev': <device API key>

Response

HTTP/1.1 200 OK

[
  {
    "id": "50",
    "type": "external",
    "priority": "info",
    "created": "2016-06-28T14:52:55",
    "expiration_date": "2016-06-28T14:54:55",
    "model": {
      "frames": [
        {
          "text": "HI!"
        }
      ]
    }
  }
]

---

Cancel or Dismiss a Notification

URL	/api/v2/device/notifications/:id
Method	DELETE
Authorization	basic
Version	2.0.0

Description

Removes notification from the queue or in case if it is already visible - dismisses it.

Response

Returns object with result.

{
  "success": true
}

or

{
  "errors": [
    {
        "message": "<error message>"
    }
  ]
}

Example

Request

REST:

DELETE https://<device ip address>:4343/api/v2/device/notifications/5

cURL:

$ curl -X DELETE -u "dev" -k https://<device ip address>:4343/api/v2/device/notifications/5
$ Enter host password for user 'dev': <device API key>

Response

HTTP/1.1 200 OK

{
  "success": true
}