Sending WhatsApp messages from InterSystems IRIS production

In this article we are going to see how we can use the WhatsApp instant messaging service from InterSystems IRIS to send messages to different recipients. To do this we must create and configure an account in Meta and configure a Business Operation to send the messages we want.

Let's look at each of these steps in more detail.

Setting up an account on Meta

This is possibly the most complicated point of the entire configuration, since we will have to configure a series of accounts until we can have the messaging functionality.

Here you can read the official Meta documentation.

First we will create a personal Meta account, thus giving our soul to Zuckerberg:

The next step is the creation of a business account that will allow us to use WhatsApp services in our applications and that will be linked to our personal account:

And then we have registered as developers from here. The next step was, once inside the developers account, to create an application:

Following the instructions in the documentation, we select a type of application "Other":

And a type of company application:

In the last step we will assign the name of the application and link it with our business account to be able to use the WhatsApp functionalities.

Finally, after this long and tedious process of creating several accounts, we will have our application ready to configure it with the WhatsApp functionality.

You can see in the menu on the left that a new option called Whatsapp will be available once configured. By accessing the API Setup option you can see everything we need to connect to the messaging functionality.

What we see on this screen:

• We have a test number from which the messages will be sent (From) to our recipients identified with an ID that we will later use to make calls to the API from our IRIS.
• We have defined a destination number (To) to which we will send our test messages (we must register it previously to accept receiving the messages).
• An Authentication Token has been generated with a validity of 24 hours.
• In our call we must send our data in JSON format as follows:

  { 
      "messaging_product": "whatsapp", 
      "to": "", 
      "type": "template", 
      "template": 
          { 
              "name": "hello_world",
              "language": 
                  { "code": "en_US" } 
          } 
  }

   

For this example we are going to use a message template, although we could send any text. As you can also see, all we need is to make a POST HTTP call to the URL defined in the example:

https://graph.facebook.com/{{Version}}/{PhoneID}/messages

For our example we are going to create 3 different templates, so we can see how we could configure different messages. We have accessed this option from the link shown in step 2 of the API configuration.

Well, now we have everything to start sending messages to our client. Let's proceed to configure our IRIS instance.

Configuring IRIS

For our example we are going to configure a small production that simulates the reception of HL7 ORU type messages with glucose level data for a certain patient. Depending on the level received, we will send the patient one message template or another.

Business Service

We will start by creating a Business Service to capture HL7 messaging from a file:

And you will receive a message like this:

MSH|^~\&|HIS|HULP|APP||20230330133551||ORU^R01|71186|P|2.5.1
PID|||1502935519^^^SERMAS^SN~184001^^^HULP^PI||CABEZUELA SANZ^PEDRO^^^||20160627|M|||PASEO JULIA ÁLVAREZ 395 3 E^^MADRID^MADRID^28909^SPAIN||6XXXXXXXX^PRN^^PEDRO.CABEZUELA@GMAIL.COM|||||||||||||||||N|
PV1||O|||||0545128263Q^MARTÍNEZ FERNÁNDEZ^SUSANA^^MD^^^^|||||||1|||||173815|||||||||||||||||||||||||20230330133551|20230330133551
ORC|1|921099|131777||||^^^20231126133551||20230330133551|||0269410060K^URDANETA LÓPEZ^SUSANA^^MD^^^^|HULP||||||||HULP||||||||LAB
OBR|1|921099|131777|LAB^LABORATORY^L||||||||||||0269410060K^URDANETA LÓPEZ^SUSANA^^MD^^^^|||||||||F
OBX|1|NM|GLU^Glucosa|1|200|mg/dL|70-105|N|||F|||20231123124525||Lectura desde dispositivo de control|1|

Business Process

Once the message is received, we will send it to a Business Process that will transform the HL7 message into a type of message created by us and that will have the information that is relevant to us. As you can see it will be a very simple BPL:

If we take a look at the transformation we will see how, depending on the glucose level data and the defined limits, we will indicate the type of message template that we are going to use:

Business Operation

This component will be responsible for sending the POST call to the WhatsApp server. To do this, we will define the EnsLib.HTTP.OutboundAdapter class as the component's adapter. Here you can see the class code:

Class Whatsapp.BO.WhatsAppBO Extends Ens.BusinessOperation
{

Parameter ADAPTER = "EnsLib.HTTP.OutboundAdapter";
Parameter INVOCATION = "Queue";
Property Version As %String(MAXLEN = 5);
Property PhoneNumberId As %String(MAXLEN = 15);
Property Token As %String(MAXLEN = 1000);
Parameter SETTINGS = "Version,PhoneNumberId,Token";
Method SendMessage(pRequest As Whatsapp.Message.WhatsAppRequest, Output pResponse As Whatsapp.Message.WhatsAppResponse) As %Status
{
    set tSC=$$$OK
    set body = {
      "messaging_product": "whatsapp",
      "to": "",
      "type": "template",
      "template": {
          "name": "",
          "language": {
              "code": "en"
          }
      }
    }
    do body.%Set("to", pRequest.telephone)
    do body.template.%Set("name", pRequest.template)
    $$$TRACE(body.%ToJSON())

    set request = ##class(%Net.HttpRequest).%New()
    set request.Authorization = "Bearer "_..Token
    set request.ContentType = "application/json"
    set request.Https = 1
    set request.SSLConfiguration="default"
    set request.Location = "/"_..Version_"/"_..PhoneNumberId_"/messages"
    do request.EntityBody.Write(body.%ToJSON())    

    set status = ..Adapter.SendFormData(.response,"POST",request)
    $$$TRACE(response.StatusCode)

    set pResponse = ##class(Whatsapp.Message.WhatsAppResponse).%New()

    Quit tSC
}

XData MessageMap
{
<MapItems>
  <MapItem MessageType="Whatsapp.Message.WhatsAppRequest">
    <Method>SendMessage</Method>
  </MapItem>
</MapItems>
}

}

We have defined 2 new parameters for the component in which we will indicate:

• The version of the API we will invoke.
• The identifier of the phone from which the message will be sent and which we have seen previously in the information of our Meta developers account application.
• The token that we will send in the header of our call (remember that it is valid for 24 hours).

Since the required connection is HTTPS we have created a default SSL configuration:

Well, we would have everything configured to launch our messaging tests. We will try sending 3 HL7 files, each one with a different glucose value for our patient:

• Value 80: which will generate a notification message indicating that our levels are normal.
• Value 110: in which it will warn us that we are exceeding the limit and will urge us to exercise to lower the levels.
• Value 200: in which it will alert us of our level and urge us to visit a medical center.

Let's copy the messages to the defined folder:

*Attention, if you want to test the example with the associated project you must configure the HL7 message with your phone number (search and replace the value 6XXXXXXXX in the example message) and modify the DTL to take into account the national prefix of your test phone .

Let's see the result:

Here we have our 3 messages received. Another new success from InterSystems IRIS! If you have any questions or comments, you can write them in the comments and I will be happy to answer you.