# 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](https://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 ```json { "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):** ```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:** ```bash 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:** ```json { "actionQualifier": "OPENAPP", "userId": "user@example.com" } ``` **Example with CURL:** ```bash curl -X POST \ "https://api.moost.io/pushnotifications/668b8e708f308b0123074cb7/interactions/v1" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"actionQualifier":"OPENWEB"}' ``` {% hint style="warning" %} 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). {% endhint %} ## 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 `active`or `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](https://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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://doc.moost.io/technical-integration/cloud-to-cloud-integration/engagement-service-integration.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.