Tenant Initiated Notifications

Eclipses 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 the specific mustache template so you need to use the same keys as are used in the template.

e.g. "data": "{"name" : ""Richard"}" will pass in the value "Richard" to be replace key "name" in the mustache template.

For easy sending of custom SMS' 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\" : \"SMS content to send\", \"phone\" : \"072381234\"}",
	"templateId": "generic"
}

The permission Notification.CREATE.Allowed needs to be enabled for the user that initiates the request (typically this is the TENANT_SYSTEM user).

SMS Gateways

Eclipse has the following SMS Gateway integrations:

The SMS Gateway to be used is controlled by tenant configs:

• smsProviderClass - this defines the default SMS Gateway e.g. com.ukheshe.libraries.messaging.sms.SnsSmsProvider
• smsRoutingConfig - this allows custom SMS gateway routing based on prefix e.g. ^27=com.ukheshe.libraries.messaging.sms.ApprenticeValleySmsProviderV2
• infobip.sms.config.url - this determines where to retrieve the infobip configs e.g. https://qy6pl2.api.infobip.com/sms/2/text/advanced
• infobip.sms.config.apiKey - API key to connect to Infobip
• infobip.sms.config.from - this determines the From name in calls to infobip

In Application Push Notifications

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

Prerequisites

• Tenant config messaging.firebase.config needs to be set to the firebase key for the particular mobile application.

Tokens can be registered to a particular customer using the device tokens endpoint:

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/device-tokens    
{
  "tokenType": "FCM",
  "token": "63456345645"
}

And 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": {
    "body": "Test",
    "title": "Test"
  },
  "messageType": "FCM",
  "tokenId": 63456345645
}

Limitations

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

Unified Template for Tenant Initiated Notifications

Eclipse also 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 template, call one of the following endpoints:

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

{  
  "customerId": 11,  
  "data": "{\"sender\": \"Pratik\", \"userId\" : \"11\"}",  
  "templateId": "testTemplate",  
  "type": "TEMPLATE",  
  "deviceMessage": {  
    "title": "The msg"  
  }  
}

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 placeholders.

This template example sends communications based on the customer prefererence 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}}
This is the sample SMS.
Sent by {{data.sender}}
#SMS-End
{{/if}}

{{#eq user.communicationPreference "EMAIL"}}
#Email-Start
#From: ++comms.email.address++
#To: {{user.email1}}
#Subject: dev-test-template-1
This is Sample email Template.
Sent by {{data.sender}}
#Email-End
{{/eq}}

{{#eq user.communicationPreference "PUSH"}}
#PushNotification-Start
This is the PushNotification template
Sent by {{data.sender}}
#PushNotification-End
{{/eq}}

This template example will send a push notification only to certain wallets based on preferences stored on the customer wallet:

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

{{#eq wallet.channelPreference "PUSH"}}
#PushNotification-Start
This is Push only for this wallet.
#PushNotification-End
{{/eq}}