Tenant Initiated Notifications

Eclipse allows tenants to send notifications to their customers in the form of SMS, email, and in-application push notifications.

SMS and Email Notifications

Email and SMS notifications can be sent to customers using the notifications endpoint.

Eclipse uses the Mustache web template system to define the content of the email or SMS. Mustache parameters are passed in the data field in JSON format. Data is bound to a specific Mustache template, so the keys in data must match the placeholder keys used in the template.

For example, "data": "{\"name\": \"Thabo\"}" will pass the value "Thabo" to replace the {{name}} key in the Mustache template.

For easy sending of custom SMS messages there is a pre-existing generic Mustache template that allows tenants to send custom messages to customers as follows:

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/notifications
{
  "type": "SMS",
  "data": "{\"data\": \"Your OTP is 482917. Valid for 5 minutes.\", \"phone\": \"+27823456789\"}",
  "templateId": "generic"
}

The permission Notification.CREATE.Allowed must be enabled for the user initiating the request (typically the TENANT_SYSTEM user).

Sending an Email Notification

To send an email using a custom template:

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/notifications
{
  "type": "EMAIL",
  "templateId": "transactionReceiptTemplate",
  "data": "{\"name\": \"Thabo Nkosi\", \"amount\": \"250.00\", \"currency\": \"ZAR\", \"reference\": \"TFR-20240315-0042\"}"
}

The template transactionReceiptTemplate must be defined as a global property on the tenant (see Template Structure below).

SMS Gateways

Eclipse supports multiple SMS gateway integrations. The gateway used for a given tenant and phone number prefix is controlled by tenant configuration.

The SMS gateway is controlled by the following tenant config keys:

SA Routing Example: To route all South African numbers (+27) through Apprentice Valley while keeping all other traffic on AWS SNS, set smsRoutingConfig to ^27=com.ukheshe.libraries.messaging.sms.ApprenticeValleySmsProviderV2 and smsProviderClass to com.ukheshe.libraries.messaging.sms.SnsSmsProvider.

In-Application Push Notifications

Eclipse can send in-app push notifications using the device messages endpoint. Currently Firebase Cloud Messaging (FCM) is supported.

Prerequisites

• Tenant config messaging.firebase.config must be set to the Firebase service account key JSON for the specific mobile application.

Step 1: Register a Device Token

FCM device tokens must be registered against a customer before push notifications can be sent. Tokens are typically captured by the mobile app at startup and submitted to Eclipse:

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/device-tokens
{
  "tokenType": "FCM",
  "token": "fGz3kP9mT8...long-fcm-registration-token"
}

Step 2: Send a Push Notification

Once a token is registered, push notifications can be sent to the customer using the device messages endpoint:

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/device-messages
{
  "deviceMessage": {
    "title": "Payment Received",
    "body": "R250.00 was deposited into your wallet. Available balance: R1 050.00."
  },
  "messageType": "FCM",
  "tokenId": 63456345645
}

The tokenId in the request is the numeric identifier returned by Eclipse when the device token was registered (not the FCM token string itself).

Limitations

• Push notifications are not supported for web-based tokens in the Safari browser due to Firebase limitations.
• Progressive Web Applications (PWAs) running on iOS do not support push notifications.

Unified Template for Tenant Initiated Notifications

Eclipse provides a single unified template mechanism for all customer communications. This design offers:

• Dynamic channel selection per user or request.
• Reduced redundancy by consolidating templates across channels.
• Simplified template management with a single definition controlling multiple outputs.

Templates are implemented using Handlebars, enabling powerful runtime logic to determine which channels and what content to deliver based on user preferences or context.

To send a notification using a unified template, call one of the following endpoints:

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/notifications
POST /eclipse-conductor/rest/v1/global/notifications

Example request body using a unified template:

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/notifications
{
  "customerId": 12345,
  "data": "{\"sender\": \"Thabo Nkosi\", \"userId\": \"12345\", \"amount\": \"500.00\", \"currency\": \"ZAR\"}",
  "templateId": "walletCreditTemplate",
  "type": "TEMPLATE",
  "deviceMessage": {
    "title": "Funds Received"
  }
}

The templateId refers to the name of the Handlebars template stored as a global property on the tenant (see Template Structure below).

Template Structure

Templates support multi-channel content definitions within a single Handlebars file. Channels can include SMS, Email, and Push Notifications. Dynamic content can be fetched from an external URL data source using the #UrlDataSource directive.

Template Header Directives

This template example sends communications based on the communication preference stored on the customer object:

#Type: Handlebars
#UrlDataSource: user=/rest/v1/users/{{data.userId}}

{{#if (or (eq user.communicationPreference "SMS") (eq user.communicationPreference null))}}
#SMS-Start
#To: {USER.PHONE1}
Hi {USER.FIRSTNAME}, you received R{{data.amount}} from {{data.sender}}.
#SMS-End
{{/if}}

{{#eq user.communicationPreference "EMAIL"}}
#Email-Start
#From: ++comms.email.address++
#To: {USER.EMAIL1}
#Subject: Payment received
Hi {USER.FIRSTNAME}, R{{data.amount}} has been credited to your account from {{data.sender}}.
#Email-End
{{/eq}}

{{#eq user.communicationPreference "PUSH"}}
#PushNotification-Start
R{{data.amount}} received from {{data.sender}}.
#PushNotification-End
{{/eq}}

This template example sends a push notification only when the wallet's channel preference is set to PUSH:

#Type: Handlebars
#UrlDataSource: user=/rest/v1/users/{{data.userId}}

{{#eq wallet.channelPreference "PUSH"}}
#PushNotification-Start
Your wallet received R{{data.amount}}.
#PushNotification-End
{{/eq}}

Storing Templates as Global Properties

Unified Handlebars templates are stored as global properties on the tenant. The property name is used as the templateId in the notification request.

For example, to store the template walletCreditTemplate:

POST /eclipse-conductor/rest/v1/global/properties
{
  "name": "handlebar.template.{tenantId}.walletCreditTemplate",
  "value": "<template content as above>"
}

Replace {tenantId} with the numeric tenant ID. The handlebar.template.{tenantId}. prefix is required for Handlebars templates.