Receive Notifications

Introduction

MOOST delivers the generated notifications to a REST Endpoint which can be specified by you ("Customer"). You can then deliver these notifications to your households ("End-users") e.g. via Firebase Cloud Messaging.

The MOOST Recommender Platform delivers Notifications to Customer’s specified REST Endpoint. The Endpoint that should be used can be configured as a per Customer, per End-user or a combination of both.

REST Endpoint

To send notifications to the REST Endpoint, the Endpoint has to be exposed on a public domain that can be accessed via Internet. Any REST Endpoint that is accessible via Internet should be protected via authentication. The MOOST Recommender Platform is able to authenticate against a Customer’s REST Endpoint via various authentication methods.

Authentication

The Recommender Platform is able to authenticate against a Customer REST Endpoint via various authentication methods as listed below.

Username / Password

The Recommender Platform can be configured to authenticate against a customer’s REST endpoint with username and password (i.e. “Basic” authentication).

API-Token

The Recommender Platform can be configured to use an API-Token to authenticate against a customer REST Endpoint.

Bearer-Token

The Recommender Platform can be configured to use a Bearer Token to authenticate against a Customer REST Endpoint.

API Throttling

If the Customer’s REST Endpoint is protected against DDOS attacks with some kind of request throttling the Customer should inform MOOST during the integration phase about the limitations that are in place. MOOST will configure the Recommender Platform accordingly.

If the limits are exceeded, the MOOST Recommender Platform will not able to send all notifications back to the Customer’s REST Endpoint. Cusermers are encouraged to ensure that the chosen limitation is in line with the expected notifications per time unit.

Notification Schema

An example of a notification object which will be sent to the Customer’s REST Endpoint is shown below. The notification object will be posted to the specified Customer’s REST Endpoint as a JSON message in the body.

Format

{
  "id": "631b3a453d6ddc7effeebb17",
  "notification": {
    "actionQualifier": {
      "primary": "OPENAPP",
      "secondary": "STOPDELIVERY"
    },
    "texts": {
      "de": {
        "title": "Ihr täglicher Energiebericht",
        "message": "'Ihre Solaranlage hat gestern 1000 kWh produziert. Eigenverbrauchsrate: 70%. Autarkiegrad: 40%.'",
        "actions": {
          "primary": {
            "text": "DETAILS"
          },
          "secondary": {
            "text": "NICHT ERNEUT ANZEIGEN"
          }
        }
      },
      "en": {
        "title": "Your daily energy report",
        "message": "'Your PV system generated 1000 kWh yesterday. Self-consumption rate: 70%. Self-sufficiency rate: 40%.'",
        "actions": {
          "primary": {
            "text": "DETAILS"
          },
          "secondary": {
            "text": "DON'T NOTIFY AGAIN"
          }
        }
      },
      "fr": {
        "title": "Votre rapport énergétique journalier",
        "message": "'Votre système a produit hier 1000 kWh. Taux d'auto-consommation: 70%. Degré d'autonomie: 40%.'",
        "actions": {
          "primary": {
            "text": "DÉTAILS"
          },
          "secondary": {
            "text": "NE PLUS NOTIFIER"
          }
        }
      }
    },
    "command": null
  },
  "createdAtTimeMillis": 1662728773479,
  "customerId": "6149884d0aafc84cb196d4c8",
  "customerBuildingId": "6149884d0aafc84cb196d4c8",
  "ruleId": "61e19fc6c7e5a80a4c764213",
  "priority": "high"
}

Old Format (Deprecated)

{
    "id": "631b3a453d6ddc7effeebb17",
    "message": {
      "de": "Sie haben gerade den Abwesenheitsmodus aktiviert, aber es scheint, dass noch Strom fliesst.",
      "en": "Away mode activated, but device [NAME] is still pulling full energy. Would you like to set up an automation to turn off your switch when leaving home?",
      "fr": "Vous venez d'activer le mode d'extinction, mais il semble que le courant continue de circuler."
    },
    "title": {
      "de": "Aktiver Stromfluss Erkannt",
      "en": "Power consumption",
      "fr": "Flux de courant actif"
    },
    "actions": [{
      "actionQualifier": "DISMISS",
      "text": {
        "de": "Schliessen",
        "en": "Dismiss",
        "fr": "Rejeter"
      }
    },
    {
      "actionQualifier": "OPENAPP",
      "text": {
        "de": "App öffnen",
        "en": "Open app",
        "fr": "Ouvrir l'application"
      },
      "parameter": {
        "de": "https://myapp.com/de/aktiver_stromfluss",
        "en": "https://myapp.com/en/power_consumption",
        "fr": "https://myapp.com/fr/flux_de_courant"
      }
    }
  }],
  "createdAtTimeMillis": 1662728773479,
  "customerId": "6149884d0aafc84cb196d4c8",
  "userId": "6149884d0aafc84cb196d4c8",
  "ruleId": "61e19fc6c7e5a80a4c764213",
  "priority": "high"
}

Actions

A notification includes two actions that should be presented to the End-user. The actions consists out of a text field which contains the text that should be presented to the End-user in the different languages, and a action qualifier field, which describes the type of action (and which should be returned to the MOOST API when the action is selected by the end-user).

The Recommender Platform has the following action qualifiers:

• DISMISS

• OPENAPP

• STOPDELIVERY

• OPENWEB

  "actionQualifier": {
    "primary": "OPENAPP",
    "secondary": "STOPDELIVERY"
  },
  "texts": {
    "de": {
      "actions": {
        "primary": {
          "text": "DETAILS",
          "parameter": "https://myapp.com/de/aktiver_stromfluss"
        },
        "secondary": {
          "text": "NICHT ERNEUT ANZEIGEN"
        }
      }
    },
    "en": {
      "actions": {
        "primary": {
          "text": "DETAILS",
          "parameter": "https://myapp.com/en/power_consumption"
        },
        "secondary": {
          "text": "DON'T NOTIFY AGAIN"
        }
      }
    },
    "fr": {
      "actions": {
        "primary": {
          "text": "DÉTAILS",
          "parameter": "https://myapp.com/fr/flux_de_courant"
        },
        "secondary": {
          "text": "NE PLUS NOTIFIER"
        }
      }
    }
  }

DISMISS

The DISMISS actionQualifier states that the push notification should be dismissed when this action is selected be the end-user.

OPENAPP

The OPENAPP action states that when this action is selected by the the end-user, then the app should be opened. The optional parameter attribute may contain a language specific value, such as e.g. an URL or a use case name.

STOPDELIVERY

The STOPDELIVERY action states that when this action is selected the push-notification should be dismissed and the actionQualifier should be returned to the MOOST API implicating that no more notifications of this type should be sent to the End-user.

OPENWEB

The OPENWEB action states that when this action is selected by the the end-user, then a browser should be opened. The optional parameter attribute may contain a language specific value, typically an URL.

Command

Optionally, you may specify a command when defining a notification in a rule. The command field may contain an instruction for a machine-to-machine interface so that some changes could be triggered.

As this is customer specific, this field is initially empty, but can be defined by the customer to his preferred format.