Engagement Service Integration

The Engagement Service turns building and event data into personalized, contextual notifications delivered to your end users. The MOOST rule engine evaluates incoming events against your configured rules and generates recommendations that are pushed to your system via the fulfillment channel of your choice.

How It Works

1. You send events to the MOOST platform (see Common Integration).

2. The rule engine evaluates each event against the active rules for the building.

3. When a rule matches, a notification is generated with localized text.

4. The notification is delivered through the configured fulfillment channel.

Receive Notifications

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

The endpoint to be used can be configured per customer, per end-user, or a combination of both via the MOOST admin frontend: admin.moost.io/settings.

REST Endpoint

To receive notifications via REST, the endpoint has to be exposed on a public domain accessible via the Internet. Any REST endpoint accessible via Internet should be protected via authentication.

Authentication

The MOOST Platform can authenticate against your REST endpoint via the following methods:

Method	Description
Username / Password	Basic authentication with username and password.
API-Token	Authentication using an API token.
Bearer-Token	Authentication using a bearer token.
OAuth	OAuth client credentials authentication.

API Throttling

If your REST endpoint is protected against DDOS attacks with request throttling, please inform MOOST during the integration phase about the limitations in place. MOOST will configure the platform accordingly.

If the limits are exceeded, the MOOST Platform will not be able to send all notifications back to your REST endpoint. Ensure that the chosen limitation is in line with the expected notifications per time unit.

Notification Schema

The notification object is posted to your 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"
}

Notification Fields

Field	Description
id	Unique notification ID. Used to return interactions.
notification.actionQualifier	Maps action names (e.g. primary, secondary) to action qualifier types.
notification.texts	Localized notification content keyed by language code (e.g. en, de, fr). Each entry contains title, message, and optional actions.
notification.command	Optional command field for machine-to-machine instructions. Customer-specific; initially empty but can be defined by the customer.
createdAtTimeMillis	Timestamp when the notification was created (milliseconds).
customerId	The customer ID.
customerBuildingId	The building that this notification is for.
ruleId	The rule that triggered this notification.
priority	Notification priority (high or normal).

Actions and Action Qualifiers

A notification includes two actions that should be presented to the end-user. Each action consists of a text field (presented to the user in different languages) and an action qualifier that describes the type of action.

Action Qualifier	Description
DISMISS	The push notification should be dismissed.
OPENAPP	The app should be opened. The optional parameter attribute may contain a language-specific value, such as a URL or use-case name.
STOPDELIVERY	The notification should be dismissed and the action qualifier returned to the MOOST API, indicating that no more notifications of this type should be sent to the end-user.
OPENWEB	A browser should be opened. The optional parameter attribute typically contains a language-specific URL.

Firebase Cloud Messaging

To integrate MOOST notifications into your mobile application, you can use Firebase Cloud Messaging (FCM). With FCM you have a centralized tool to send notifications to your end-users on both Android and iOS apps.

iOS Notification Handling

iOS differentiates between the action that happens when pressing the notification and the quick actions presented when long-pressing a notification.

Example (Swift):

func userNotificationCenter(_ center: UNUserNotificationCenter,
    didReceive response: UNNotificationResponse,
    withCompletionHandler completionHandler: @escaping () -> Void) {
    
    let userInfo = response.notification.request.content.actions
    let url = userInfo["parameter"]["en"] as! String
    
    switch response.actionIdentifier {
    case "OPENAPP":
        sharedAppManager.openApp()
    case "STOPDELIVERY":
        sharedAppManager.sendStopDelivery()
    case "OPENWEB":
        sharedAppManager.openWeb(url)
    default:
        sharedAppManager.openApp(url)
    }
    
    completionHandler()
}

Notifications and Interactions

Load Notifications of a Building

Your app may need to display the history of generated notifications (e.g. in a Notification Center). Use the following API:

GET https://api.moost.io/pushnotifications/buildings/{customerBuildingId}/v1?deliveryStatus=DELIVERED

Parameter	Required	Description
customerBuildingId	yes	The building identifier.
deliveryStatus	no	Filter by DELIVERED or DROPPED.

Example with CURL:

curl -X GET \
  "https://api.moost.io/pushnotifications/buildings/99900000ECA31C6E/v1?deliveryStatus=DELIVERED" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Return Notification Interaction

To train our algorithms based on the actions taken by end-users, it is important that the action qualifier is returned to the MOOST Platform.

POST https://api.moost.io/pushnotifications/{pushNotificationId}/interactions/v1

Request body:

{
  "actionQualifier": "OPENAPP",
  "userId": "[email protected]"
}

Example with CURL:

curl -X POST \
  "https://api.moost.io/pushnotifications/668b8e708f308b0123074cb7/interactions/v1" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"actionQualifier":"OPENWEB"}'

Notification interactions must be returned to MOOST on every interaction the end-user has with a notification. This includes: pressing the primary button, pressing the secondary button, pressing on the notification itself, and dismissing the notification (swipe left).

Rules API

Rules define the conditions under which notifications are triggered. They are typically created and managed through the MOOST admin frontend, but can be read and managed via the API.

Method	Endpoint	Description
GET	/rules/v1?tags=solar	Get all rules. Optionally filter by tags.
GET	/rules/tags/v1	Get all distinct tags used across rules.
GET	/buildings/{customerBuildingId}/rules/v2	Get active rules of a specific building.
PUT	/buildings/{customerBuildingId}/rules/{ruleId}/v1?status=active	Activate or deactivate a rule for a building. Set status to activeor inactive.

This allows you to enable or disable specific rules per building — for example, to let end users opt out of certain notification types.

Integration Checklist

• Obtain API credentials (clientId, clientSecret) from MOOST.

• Implement authentication (see Common Integration).

• Register your buildings with devices and tariff settings.

• Configure a fulfillment channel in admin.moost.io/settings (REST webhook, email, or FCM).

• If using REST: expose an authenticated endpoint and inform MOOST of any throttling limits.

• Begin sending events at the recommended interval (~15 min per sensor).

• Verify notifications are being delivered via GET /pushnotifications/buildings/{id}/v1.

• Implement interaction tracking — return the actionQualifier for every user interaction.

• Build a Notification Center in your app using the push notifications API.