Messaging Service

danger

The Messaging Service is under maintenance (bug fixes and security updates only) and will reach end-of-life in December 2025.

The plugin is deprecated in favor of the Notification Manager, which inherits all the Messaging Service features and APIs.

Messaging Service allows sending messages to your users through various channels, namely e-mail, SMS, push notification and voice.

To send those messages, this service leverages three other Mia-Platform plugins:

• SES Mail Notification Service
• SMS Service
• Kafka2Firebase Service

caution

In order to send a message through a particular channel, you need to deploy the corresponding plugin. This is not needed for the voice channel, for which there is a direct interaction with Kaleyra APIs.

The notification can also be triggered directly by a Flow Manager command. See the Configuration section for more information.

Users clustering

In order to send messages to a particular group of users, the service supports users clustering.

Each user in your users CRUD may belong to one or more groups, saved in a property called clusters (the property can actually be named however you want, as explained in the dedicated section).

In the body of a send request, you can use clusters parameter to specify the groups that should receive the messages. The service will pick as receivers all the users that belongs to at least one of those clusters.

tip

In the body of the request you can also specify a list recipients that will receive the messages regardless of the clusters.

If a user belongs to a cluster listed in the clusters parameter and its identifier is listed in the recipients, he/she will receive the messages only one time.

Messages templates

To standardize the messages you send to your users, you can create and save on an appropriate CRUD messages templates. They are pre-defined messages for the various channels that can be referenced in your send requests using the templateId body parameter.

tip

Templates supports message interpolation.

Messages interpolation

Whether you use a template or you provide a message in the body of the send request, you can use interpolation to insert in the text some dynamic information.

The syntax to be used is the Handlebars. A Handlebars expression is an expression enclosed by double or triple curly brackets, like {{ user.firstName }} or {{{ appointment.notes }}}. They only difference is that HTML characters are escaped automatically only when using double curly brackets, which are safer and recommended to use unless you need to preserve text formatting.

danger

Be very careful sanitizing your input when using triple curly brackets, otherwise your users may be exposed to code injection attacks.

When the text is compiled, these expressions are replaced with values from an input object. The input objects that can be used in the Notification Manager are:

• the user object (i.e., the data of the user to which you are sending the message)

• the data object of the body of the send request

In addition, you can use the following custom helpers:

• (dateNow): return the current date/time as ISO string

{{ dateNow }} // e.g. 2023-10-15T09:30:00.123Z

• dateFormat: format a date/time value in a given time zone (default: UTC)

{{ dateFormat data.startDate format='DD/MM/YYYY' tz='Europe/Rome' }} // e.g. 15/10/2023

Property	Type	Values	Default
format	string	Any format supported by Dayjs	ISO8601 format
tz	string	Any timezone supported by ECMAScript2020 section 6.4	UTC

• toLocale (available since version 2.3.0): return a string representing a value in a given locale, if the value is undefined an empty string is returned instead

{{ toLocale data.amount }} // Use default locale -- e.g. 1.234.567,89
{{ toLocale data.amount locale='it-IT' }} // e.g. 1.234.567,89

Property	Type	Values	Default
locale	string	A BCP 47 language tag	[DEFAULT_LOCALE][environment-variables]

For example, given the following user object

{
  "name": "Mario",
  "surname": "Rossi",
}

and the following data object in the body of the send request

{
  "appointmentDate": "01/01/2021",
  "serviceAmount": 1234567.89
}

this message

'Hello, {{user.name}}! You have a new appointment on {{data.appointmentDate}} and you are going to pay ${{toLocale data.serviceAmount "en-US"}}'

will be compiled in

'Hello, Mario! You have a new appointment on 01/01/2021 and you are going to pay $1,234,567.89'

Handlebars helpers

info

v1.3.0. Advanced interpolation is available only since version 1.3.0.

You can use the functions provided by the handlebars-helpers library to perform advanced interpolation of the messages.

In the following example, firstName and lastName are fields of the data object that are displayed only if the type field is set to patients.

{{#if (eq data.type "patients")}}{{data.firstName}} {{data.lastName}}{{/if}}

In this case the eq function is provided by the handlebars-helpers library.