• Print
  • Share
  • Dark
    Light

Communications - Webhooks, Email and SMS Notifications

  • Updated on 29 Oct 2018
  • 14 minutes to read

Overview

This menu is used to setup the different manual and automated communications that can be initiated from Mambu, currently available for SMS, E-mail and Webhooks.

Initial Setup

4394aef6-9333-4c3c-9945-57746471b53d.png

Before creating any templates for SMS, emails or webhooks, an initial setup is required for each of them, please see the related articles for SMS, Email and Webhook setup. 

SMS - define SMS settings and automated SMS notification templates

Email - define Email configuration settings and automated Email notification templates

Webhooks - toggle webhooks notifications and define automated webhook notifications

Templates - define manual templates for creating Tasks or sending manual SMS or Email templates


Creating Communication Templates

To setup a new communication template:

Depending on the type of communication you want to use/edit go to the respective category (below an E-mail example):

  • Go to Administration > Email

  • Click Add Notification

  • Enter the template's name, Target, Trigger, Availability, Event and Action (explained below)

  • Save Changes.

eca92f30-fbe6-48e5-8fdc-6e1632727f57.png

Trigger

Defines the event that will launch the communication. There are two options

  • Manual - For Tasks, SMS, and Emails.

  • Automatic - For SMS, Emails, and Webhooks

Manual communications are triggered manually by Mambu users each time they need to be sent, whereas Automatic communications are triggered by events from the client or their accounts and sent by Mambu without human intervention.

 

Automatic retry mechanism for failed communications 

Mambu supports an auto-retry policy to resend all failed SMS, Email or Webhooks notifications . With this mechanism we will mitigate the communication outages by retrying any failed notification for a number of times.

Field Description
maxRetries The max number of retries to perform. {@code -1} indicates to retry forever.
backOffDelay The delay between retries, exponentially backing off to the maxDelay and multiplying successive delays by a factor
backOffMaxDelay The max delay between retries
delayFactor * backOffDelay Time to wait before retry between messages

By default the maximum number of retries to be performed is set to 4. Between each retry there is a delay range configured (measured in seconds) which is using an exponential factor to permit the servers to wait for longer intervals of time for each retry attempt.

Please Be Aware
Organizations on a shared environment are not currently able to adjust the default settings. Organizations with a dedicated environment can decide to disable this policy or to change the configuration settings, if needed.

Events

For Automatic communication templates, the event defines upon which action will the notification be sent.

Event Description
Client Created A new client has been created.
Client Approved A client's status has been changed to approved.
Client Rejected A client's status has been changed to rejected.
Client Activity Any client activity.
Credit Arrangement Created A credit arrangement is created.
Credit Arrangement Approved A credit arrangement is approved.
Credit Arrangement Rejected A credit arrangement is rejected.
Credit Arrangement Withdrawn A credit arrangement is withdrawn.
Credit Arrangement Account Added An account is added to a credit arrangement.
Credit Arrangement Closed A credit arrangement is closed.
Credit Arrangement Deleted A credit arrangement is deleted.
Group Activity Any group activity.
Loan Repayment A repayment transaction has been posted on the loan account.
Loan Repayment (Reversal) A repayment transaction is reversed on the loan account.
Loan Account Created A loan account has been created.
Loan Account Approval A loan account has been set to approved status.
Loan Account Closed (Repaid) A loan account has been set to closed status after being fully paid (i.e. closed with all obligations met, zero balance).
Loan Account Activity A detail change (a non-transactional change) was performed on the account. Every time any detail on the account is changed a notification will be sent if this Event is selected. If conditions are set to the notification (ie. when) then anytime a change is made on the account the notification is sent only if it meets the specified conditions.
Loan Write Off A loan is set to closed status with a write-off transaction.
Loan Account Rejection A loan account is marked as rejected in the loan application process.
Loan Account Rescheduled A loan account has been rescheduled into a new account.
Loan Account Refinanced A loan account has been refinanced into a new account.
Repayment Due The loan account has a repayment due in "x" days. You can define a reminder to be sent prior to due date.
Account in Arrears An account has changed its status to In Arrears (affected by arrears tolerance period).
Loan Disbursement A disbursement transaction has been posted on a loan account.
Loan Disbursement (Reversal) A loan disbursement transaction has been reversed.
Deposit Account Created A deposit account has been created.
Deposit A deposit transaction has been logged in a deposit account.
Deposit (Reversal) A deposit transaction has been reversed on a savings account.
Deposit Account Approval A deposit account has been set to approved status.
Deposit Account Activated A deposit account has been activated.
Deposit Account Closure A deposit account in Active or Matured state has been closed.
Deposit Account Rejection A deposit account has been rejected in the approval process.
Withdrawal A withdrawal transaction has been posted on a deposit account.
Withdrawal (Reversal) An withdrawal transaction on a deposit account has been reversed.
Deposit Account Activity A non-transactional change has been made on the deposit account (only for webhooks).
Portal Activated The Customer Portal has been activated for a client.
Portal Password Reset A Customer Portal password reset has been requested.
Loan Anticipated Disbursement Allows to specify how many days before anticipated disbursement the notification should be sent.

Target

  • Clients - Notifications will be triggered only by actions referring to individual clients or their accounts

  • Groups  - Notifications will be triggered only by actions referring to groups or their accounts

  • Loan Accounts - For manual templates, to be sent to the client from a loan account

  • Deposit Accounts - For manual templates, to be sent to the client from a loan account

If the Target refers to Groups, for any trigger other than Manual, it is possible to decide on the Group Recipient that given notification should be sent to. The drop-down list will include group roles as defined under Administration > General Settings > Group Roles.

Subscription Option

To receive Automatic notifications, clients must be subscribed to them first, this option defines which clients are subscribed by default, there are two options:

  • Opt In - Each client must be manually subscribed to the communication template

  • Opt Out - Each client is subscribed to the communication template by default

Conditions

SMS, Email and Webhook notifications can be sent if a set of conditions are met by the client or the account for which the notification is sent.

When defining a notification template, you can select the constraints that need to be met so the notification is sent. Then, when sending a notification, if the client or account details, after the action was performed, match the template constraints, the message will be sent.

b2fdc40b-b143-444f-8c31-2c7bd3fb72d0.png]

Based on the selected event (Client, Loan Account, Deposit Account or Transactions actions), a specific set of filters will be displayed on the interface.

This feature allows you to have separate templates for each branch, centre, product, user, custom fields and any other filter constraint available in custom views.

Example
You can create a notification for Repayment Entered, but if you want that notification to be sent only for a specific product, you can add a Product constraint.

Notifications that are linked to specific products are visible on the product profile, under the Communications tab. This tab displays all the templates that relate to the selected product and allow you to easily create another template for it.

bc419e97-0845-434f-aa7d-96a7168a3e89.png

Communication Text and Placeholders

The fixed text and placeholders constitute the body of the communication. Any placeholders included in the template will be used to automatically display the correspondent information when a notification is sent.

Email and Webhook templates can be created in HTML by clicking on View HTML 

You can customize your own CSS by using the <style> tag, however if the CSS is complex, then it must be extracted in a separate file, published on a public server and imported using:

<style>
@import url(http://css_path); 
@import url(http://css_path2); 
</style> 

Adding Placeholders

Select the field in the placeholder dropdown, copy the displayed placeholder text with the brackets in to the editor, where the field data should be displayed

Placeholders in Webhook URLs:

Organizations which would like to compute events inside Mambu via Webhooks, could use the placeholders directly in the URL.

See an example of a Webhook URL containing placeholders :

http://requestb.in/1bq31wx1?param1={ACCOUNT_ID}&param2={CF:LOAN:HAS MANY INSTALLMENTS}

Which will be parsed as:

://requestb.in/1bq31wx1?param1=AB123456&param2=Yes

Please Note
Placeholders can also be added to the E-mail Subject in the Communication E-mail Templates.

The complete list of the currently available Placeholders for Document Templates as well as Communications templates is available for download in our Placeholder Matrix.


Subscribing clients to communication templates

3cc9cd50-c015-4430-8615-00827d32e6a7.png

To define which notification an individual client should receive:

  • Go to the client

  • Click More > Set Notifications

  • Check the boxes next to the notification the client should receive

  • Save Changes.

Once subscribed, whenever the notification event happens, the notification will be sent.


Sending Notifications to Users

Users can send notifications (SMS or Email) to other users as well. This can be useful since some changes in clients' accounts need to be known by other users as well, and therefore a notification can be sent not only to the client but also to the user managing the account, for example.

In order for an SMS or Email to be sent to users, the user has to be associated with the Client. This is possible for Credit Officer user type, which allow being associated to Clients or through Custom Fields for User Link field type. See below examples for more details.

Sending Notifications to Credit Officers

When selecting Credit Officer as Recipient, the Credit Officer that is associated to the Client will receive an Email or SMS notification, based on the conditions set for the notification and the triggering event. If Opt Out is selected, automatically all Credit Officers will be subscribed to the notification, whereas for Opt In the Credit Officer can choose to subscribe to the notification manually from their profile.  

In order to send notifications to other users that are not Credit Officers a User Link type of custom field has to be defined for Clients. The same Opt in and Opt out behaviour will apply in terms of subscribing users, as described above for Credit Officers. Any User Link custom field defined at Client level can be used for notifications. See below example for a new custom field, defined for notification purposes.

Example:

  1. For our example we will create a new Custom Field Set "Email Notifications" for Clients and add under it a custom field "Subscribed Users". The field set can be optional or required, depending on business need.

dcc2d8f8-7147-41f1-beb6-75afa7fe1692.png

  1. When creating a new notification for users, under Recipient we will notice the newly created custom field "Subscribed Users" available for selection. Continue defining the conditions for the notification template, as for any other notification sent to clients.

ffc854d3-5a96-4c56-93a5-9198ee29f117.png

  1. When creating/editing a new Client, the new Custom field set we created will be available and will allow selecting the user which will receive the email notification for the conditions defined on the notification template.

fc4e7176-bfe3-49bc-b0b5-a3f8840c500d.png

Only Client custom fields of User Link type can be used for notifications. Any other user link custom fields defined for Accounts, Branches, Users etc will not be available when defining notifications.

Other Uses

When using User Link custom fields for sending notifications you can customise the notifications sent to users in multiple ways:

  • You can create several custom fields of User Link type so as to assign a notification to multiple users

  • You can create different custom fields for different types of notifications and users in your organisations; for example you can create a custom field for Supervisor and a custom field for Collections Agent, therefore when creating notifications you can define one for the Supervisor on Client Creation event, which will notify the Supervisor anytime a new client is created and another notification for Collections Agent on Account in Arrears event which will send a notification to the collections agent when the account goes into arrears.

  • You can define a new custom field set for email notifications (like in our example above) or use existing field sets at Client level and just add a new User Link custom field type under it for subscribing users.

  • You can make the custom field Required, so as to enforce user selection upon Client creation / editing.


Subscribing Users to Email and SMS Notifications

Users can subscribe themselves to email/SMS notifications or can be subscribed by administrators. In order to automatically subscribe a user to a notification, an Opt Out notification template has to be created.

  • For users -> Users can go to their profiles and under More - Set Notifications they can select to which notification to subscribe to

  • For administrators -> Administrators can manage users' subscription to notifications by going to the Users section, then selecting the user for which the change needs to be done and under More - Set Notifications the admin can manually select the notifications to subscribe the user to.


Deactivating and reactivating a notifications

Notification templates can be deactivated and reactivated at any time. When a notification is deactivated it will stop being sent to any clients.

  • To deactivate a notification,go to Administration > Communications > Templates > Actions > Deactivate.

  • To reactivate a notification just follow the same process as described above and click Reactivate.

Status

When a template is Active it's available and can be used. If the template is Inactive it means that it is currently disabled and that it can't be used to send notifications.

State

If a template is In Use it means that at least one notification has been sent using that template, whereas if it's Not In Use the template hasn't been used for any notifications yet.


Notification History

Here you can search your complete notification history by state, sender and date, it will make it easy for you to know which messages were delivered to your customers, when, to which destination and the contents of the message itself.

023a49fc-5f3a-4671-83d6-eb70ab0e4a9a.png

You can also view Communication historical data on:

  • Clients

  • Groups

  • Users

On the clients and groups Communications tab, you’ll see all the manual and automated notification messages sent to them. On the user’s Communications tab, you’ll see all the manual messages sent by that user. You can also apply filters on those messages, edit the displayed columns or export to Excel.

Notification States

State Description
QUEUED The notification is in the queue. It is waiting to be consumed by the worker.
WAITING_TO_BE_SENT The notification was picked up by the worker. The processing is pending.
SENT The notification was sent succesfully.
FAILED Sending the notification has failed for some reason.
WAITING_FOR_CLOSE_CIRCUIT
Webhook Notifications only
Notification will be sent when the Circuit Breaker is closed. See Circuit Breaker for more details.

Sending Time

After the templates for each trigger are defined and after the clients who should receive the notifications are selected, Mambu will perform daily checks at midnight to determine which clients should receive a notification on that day.

The actual notification will only be sent at 9am (organization's time).

Resending Failed Messages

If your notification gateway was not available when the message was sent (SMTP server was down, SMS provider was offline etc.), you can resend a message to the client. 

By clicking on the Failed State column or on the more button from the Message column, a dialog will be shown with the possibility to resend the message. 

Mambu will try to send the notification again and update the failure reason, success state and sent date in the message, for further investigations. 


Sender IP Addresses

WebHook requests to your endpoints and emails being sent through your SMTP server from Mambu will origin from a fixed set of IP addresses per Mambu region. These IP addressed can be whitelisted on your firewall. Any updates below set of IP addresses will be announced on our Status Page as well. 

Please contact us via support@mambu.com if you are on a private Mambu deployment and need to know the sender IP addresses for your dedicated environment.

US Region (N. Virginia) - Production

  • 52.200.155.158

  • 52.203.173.35

US Region (N. Virginia) - Sandbox

  • 52.201.89.67

EU Region (Ireland) - Production

  • 52.50.237.241

  • 52.51.211.17

EU Region (Ireland) - Sandbox

  • 52.51.53.69

Asia Pacific Region (Sydney) - Production

  • 52.62.39.183

  • 52.63.160.42

Asia Pacific Region (Sydney) - Sandbox

  • 52.63.147.33

  • 52.63.128.125