Enviando mensajes de WhatsApp con InterSystems IRIS

En este artículo vamos a ver como podemos utilizar el servicio de mensajería instantanea de WhatsApp desde InterSystems IRIS para enviar mensajes a diferentes destinatarios. Para ello deberemos crear y configurar una cuenta en Meta y configurar un Business Operation para enviar los mensajes que deseemos.

Veamos con más detalle cada uno de estos pasos.

Configurando una cuenta en Meta

Este es posiblemente el punto más enrevesado de toda la configuración, ya que deberemos configurar una serie de cuentas hasta poder disponer de la funcionalidad de mensajería.

Aquí podéis leer la documentación oficial de Meta.

Primeramente crearemos una cuenta personal de Meta entregando de esta forma nuestro alma a Zuckerberg:

El siguiente paso es la creación de una cuenta empresarial que nos va a permitir utilizar los servicios de Whatsapp en nuestras aplicaciones y que quedará ligada con nuestra cuenta personal:

Y a continuación nos hemos dado de alta como desarrolladores desde aquí. El siguiente paso ha sido, una vez dentro de la cuenta de desarrolladores, crear una aplicación:

Siguiendo las indicaciones de la documentación seleccionamos un tipo de aplicación "Otra":

Y un tipo de aplicación de empresa:

En el último paso asignaremos el nombre de la aplicación y la vincularemos con nuestra cuenta empresarial para poder hacer uso de las funcionalidades de Whatsapp.

Finalmente, después de este largo y tedioso proceso de creación de cuentas varias ya dispondremos de nuestra aplicación preparada para configurarla con la funcionalidad de Whatsapp.

Podréis ver en el menú de la izquierda que una nueva opción llamada Whatsapp estará disponible una vez configurado, accediendo a la opción de API Setup podréis ver todo lo que necesitamos para conectarnos a la funcionalidad de mensajería.

Qué observamos en esta pantalla:

• Disponemos de un número de pruebas desde el que se enviarán los mensajes (From) a nuestros destinatarios identificado con un ID que usaremos posteriormente para realizar las llamadas a la API desde nuestro IRIS.
• Tenemos definido un número de destino (To) al que enviaremos nuestros mensajes de pruebas (deberemos registrarlo previamente para aceptar la recepción de los mensajes).
• Se ha generado un Token de autenticación con una validez de 24 horas.
• En nuestra llamada deberemos enviar nuestros datos en formato JSON de la siguiente forma:

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

   

Para este ejemplo vamos a usar una plantilla de mensaje, aunque podríamos enviar un texto cualquiera. Como también podéis observar lo único que necesitamos es realizar una llamada HTTP de tipo POST a la URL definida en el ejemplo:

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

Para nuestro ejemplo vamos a crear 3 diferentes plantillas, así podremos ver como podríamos configurar diferentes mensajes. Hemos accedido a esta opción desde el vínculo que se nos muestra en el paso 2 de la configuración del API.

Pues bien, ya lo tenemos todo para empezar a enviar mensajes a nuestro cliente. Procedamos a configurar nuestra instancia de IRIS.

Configurando IRIS

Para nuestro ejemplo vamos a configurar una pequeña producción que simule la recepción de mensajes de HL7 de tipo ORU con datos de niveles de glucosa de un determinado paciente. Dependiendo del nivel recibido enviaremos al paciente una plantilla de mensaje u otra.

Business Service

Empezaremos creando un Business Service para capturar la mensajería HL7 de un fichero:

Y recibirá un mensaje de este tipo:

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

Una vez recibido el mensaje lo enviaremos a un Business Process que nos transformará el mensaje HL7 a un tipo de mensaje creado por nosotros y que tendrá la información que nos resulte relevante. Como podéis ver será un BPL muy sencillo:

Si echamos un ojo a la transformación veremos como, dependiendo del dato de nivel de glucosa y los límites definidos le indicaremos el tipo de la plantilla de mensaje que vamos a utilizar:

Business Operation

Este componente será el responsable de enviar la llamada POST al servidor de WhatsApp, para ello definiremos como adaptador del componente a la clase EnsLib.HTTP.OutboundAdapter, aquí podéis ver el código de la clase:

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>
}

}

Hemos definido 2 nuevos parámetros para el componente en el que indicaremos:

• La versión de la API a la que invocaremos.
• El identificador del teléfono desde el que se enviará el mensaje y que hemos visto anteriormente en la información de nuestra aplicación de la cuenta de desarrolladores de Meta.
• El token que enviaremos en la cabecera de nuestra llamada (recordad que tiene 24 horas de validez).

Dado que la conexión requerida es HTTPS hemos creado una configuración SSL por defecto:

Pues ya tendríamos todo configurado para lanzar nuestras pruebas de mensajería. Probaremos enviado 3 ficheros HL7, cada uno con un distinto valor de glucosa para nuestro paciente:

• Valor 80: que nos generará un mensaje de notificación indicando que nuestros niveles son normales.
• Valor 110: en el que nos avisará que estamos superando el límite y nos instará a realizar ejercicio para bajar los niveles.
• Valor 200: en el que nos alertará de nuestro nivel y nos instará a visitar un centro médico.

Copiemos lo mensajes a la carpeta definida:

*Atención, si deseáis probar el ejemplo con el proyecto asociado deberéis configurar el mensaje de HL7 con vuestro número de teléfono (buscad y reemplazad en el mensaje de ejemplo el valor 6XXXXXXXX) y modificar el DTL para contemplar el prefijo nacional de vuestro teléfono de pruebas.

Veamos el resultado:

Aquí tenemos nuestros 3 mensajes recibidos. ¡Otro nuevo éxito de InterSystems IRIS! Si tenéis alguna duda o comentario podéis escribirla en los comentarios y estaré encantado de contestaros.