Integrate With SMS Providers

Overview

DIGIT ships with SMSCountry as the default SMS provider. This document explains how to integrate with other SMS providers.

Note: Legal and regulatory requirements for SMS notifications vary across geographies. Adding an SMS provider is a configuration task and must be set up independently for each deployment. SMS messaging should always be configured in line with the acceptable standards and compliance obligations of the respective country.

Steps

1

Register the message template with the SMS provider

Finalise the SMS message to be sent out to the end user. Register the template with the SMS provider on their portal, following their guidelines. Each language template needs to be localised & separately registered.

Note:

1. Exact steps to do this will vary depending on the SMS provider.

2. The number of parameters per message, the number of characters and Unicode support for each local language may be limited depending on the SMS provider. Kindly check for these details on the SMS provider's website prior to registering the message templates.

3. SMS providers may also limit the messages per second that can be sent out.

2

Add the notification message to localisation

• Add your SMS or notification message (with placeholders like {id}, {date}) to the Localisation master.

• Use the Localisation Upsert API (provided in the Postman collection).

• Update the domain URL in API call.

• Example Entry:

  {
    "code": "PGR_CITIZEN_RESOLVE_RESOLVED_SMS_MESSAGE",
    "message": "Dear Citizen, Your complaint for {complaint_type} with ID {id} submitted on {date} has been resolved by {emp_name}.",
    "module": "rainmaker-pgr",
    "locale": "en_IN"
  }

Tip: To support multiple languages, add the same code with different locale values (e.g., hi_IN for Hindi, or en_IN for English or pa_IN for Punjabi.

3

Replace placeholders with real data in the code

• The code fetches the message and replaces placeholders like {id} with actual complaint details.

• In the backend, usually in NotificationService.java inside the getFinalMessage() function.

• Use simple replace logic - refer sample below:

  if (messageForEmployee != null) {
      messageForEmployee = messageForEmployee.replace("{complaint_type}", localisedComplaint);
      messageForEmployee = messageForEmployee.replace("{id}", serviceWrapper.getService().getServiceRequestId());
      messageForEmployee = messageForEmployee.replace("{date}", date.format(formatter));
      messageForEmployee = messageForEmployee.replace("{download_link}", appLink);
  }
  
  if (messageForEmployee.contains("{emp_name}")) {
      messageForEmployee = messageForEmployee.replace("{emp_name}",
         fetchUserByUUID(
           request.getWorkflow().getAssignes().get(0),
           request.getRequestInfo(),
           request.getService().getTenantId()
         ).getName());
  }

• Each notification is personalised to the citizen and complaint.

4

Send the notification

• Send the final message to both SMS and InApp (User Events) services.

• InApp: Use the user-events service (for app notifications/inbox). Sample code snippet for InApp (User Events) below:

if (!StringUtils.isEmpty(finalMessage)) {
    if (config.getIsUserEventsNotificationEnabled() != null && config.getIsUserEventsNotificationEnabled()) {
        for (Map.Entry<String, List<String>> entry: finalMessage.entrySet()) {
            for (String msg: entry.getValue()) {
                EventRequest eventRequest = enrichEventRequest(request, msg);
                if (eventRequest != null) {
                    notificationUtil.sendEventNotification(tenantId, eventRequest);
                }
            }
        }
    }
}

• SMS: Use the notification-sms service. Sample code snippet for SMS - notification-sms below:

if (config.getIsSMSEnabled() != null && config.getIsSMSEnabled()) {

    // Loop through each recipient group (CITIZEN or EMPLOYEE)
    for (Map.Entry<String, List<String>> entry : finalMessage.entrySet()) {

        if (entry.getKey().equalsIgnoreCase(CITIZEN)) {
            // Send SMS to CITIZEN
            for (String msg: entry.getValue()) {
                List<SMSRequest> smsRequests = new ArrayList<>();
                smsRequests = enrichSmsRequest(citizenMobileNumber, msg);

                if (!CollectionUtils.isEmpty(smsRequests)) {
                    notificationUtil.sendSMS(tenantId, smsRequests);
                }
            }
         } else {
            // Send SMS to EMPLOYEE or other recipients
            for (String msg: entry.getValue()) {
                List<SMSRequest> smsRequests = new ArrayList<>();
                smsRequests = enrichSmsRequest(employeeMobileNumber, msg);

                if (!CollectionUtils.isEmpty(smsRequests)) {
                    notificationUtil.sendSMS(tenantId, smsRequests);
                }
            }
        }
    }
}

Note: Make sure the below is enabled in your configuration:

isSMSNotificationEnabled: true

Checklist - Summary

• Message added to Localisation (all required languages)

• Placeholders are replaced with real data in the code

• Notification sent to SMS and InApp (user-events) channels

• Relevant config flags are enabled