SMS Messaging from Oracle ERP with ORDS and Twillio

Introduction

​Twillio has become the gold standard for automating the sending and receiving of SMS messages. They have a well-documented and easy to use API, with features designed to make sending and managing SMS messages easy. In our latest engagement, JMJ Cloud is using Twillio to help our customer provide important and timely information (from Oracle e-Business Suite) to their employees via SMS. In this post I will review the requirement and the architecture we put in place to make it all happen.

---

​The Requirement

​Our customer needs to notify employees when certifications they hold are approaching their expiration date. Details of the employee’s certifications are maintained in Oracle e-Business Suite (EBS) on their HR record. The nature of their work dictates that these employees cannot perform their job without a current certificate. The work takes employees all over the world and being able to reach them when they are out of the office made SMS a great choice.
 
The customer also has plans to send a number of other SMS messages from EBS and other internal systems. Building a generic outbound and inbound queuing process was necessary to facilitate re-use of the solution by these other sources.

A Little Bit about Twillio

​If you have used Lyft, Airbnb, or Netflix, you have probably used Twilio. In fact, Twilio powers communications for over 40,000 businesses around the world. Simply put, Twilio is a developer platform for communications. Software teams use Twilio APIs to add capabilities like voice, video, and messaging to their applications.

There are a couple of things you need to setup in Twillio before you can start sending SMS messages:

• Signup for an account.
• Purchase a number. This is the outbound phone number that will appear on message recipients’ phones. It is also the number Twillio is watching to handle responses to SMS messages. Numbers range in price from $1 / month to thousands for shortened numbers. You do get to choose the number you want to use from a list of available numbers. The process is a little like choosing a cell phone number. You may end up needing multiple numbers based on your requirements, especially if you need to handle SMS responses differently for each requirement.
  
• Configure a Web Hook to receive responses. For each number you buy, you can configure a URL which Twillio will POST to whenever someone responds to a text message sent from that number. This web hook will post the number the response was sent from as well as the response message itself. As you will see from the architecture diagram below, we chose to configure an ORDS REST service to receive these responses.

---

​Architecture

​Outbound Flow

1. The outbound flow starts with a feeder system (in our case Oracle HR) adding an SMS to the outbound queue table. Each feeder system is categorized by a ‘channel’ column on the table. The table also stores the SMS message, the to and from number, key identifying information for the recipient (name, internal id etc.) and status columns.
2. A scheduled Outbound Queue processing concurrent program runs every hour (during the day). This program performs the following actions:
   1. Calls the Twillio SMS API to Queue the message with Twillio.
   2. Calls the Twillio message status API to confirm previously queued messages were actually delivered.
   3. Logs Twilio’s unique message id to the outbound queue table.
   4. Logs any errors (e.g. invalid mobile number) to the outbound queue table
   5. Sends an email with failed deliveries to all interested parties.
3. When Twillio receives a request, it will:
   1. Check to see if the number the SMS is being sent to has opted out of receiving SMS messages from your sending number. If it has then it will return an error message and not send the SMS.
   2. Perform basic validations on the recipients’ number and return an error if applicable.
   3. If there are no errors, it will queue the message to be sent.

Note: Twillio does not send the SMS synchronously. Just because you get a success message back from the send API, does not mean the message was delivered. You need to call a second message status API to confirm successful delivery.

​Response / Inbound Flow

1. The inbound flow starts with an employee responding to an SMS. Possible reasons for responding to an SMS are:
   1. Request to opt out of future SMS messages.
   2. Response to a question as part of a ‘conversation’ with one of your systems.
2. When Twillio receives the response, it does the following:
   1. If the user responds with an opt out message e.g. ‘STOP’ then it will tag that number as blocked and prevent you from sending further messages to that number until they opt back in.
   2. Formats the message and information about the responder into a JSON document and posts the response to the web hook you configured (ORDS POST Service).
3. The ORDS POST service adds the response to a queue table sitting in Exadata Express.
4. A scheduled inbound queue Concurrent Program runs to pick up new responses from Exadata Express. It does this by calling another ORDS web service on Exadata Express which returns the responses. The Concurrent Program then copies the data to a local table in the EBS database.
5. A final concurrent program runs which handles responses received in the local table. This includes activities such as updating the employees HR record based on their response. This program also sends out an email digest of all received SMS responses to the managers of the employees who have responded.

Monitoring
A. An APEX dashboard provides administrators the ability to monitor both the inbound and outbound queues and respond to errors etc.

​Considerations

This section focuses on some key considerations when implementing an SMS solution.

Data Cleansing and Managing Errors​

​Chances are, the phone numbers you have stored in your ERP system are not being used by an automated solution such as this. When a human sees a number like +11234567890, 1234567890 or (123)456-7890 they can figure out the number and the country code.

A computer system, however needs a more exact format to follow. It is also likely you will not have mobile numbers for everyone. Twillio requires that you send the country code with each SMS message.  All of this means you will have to work at collecting mobile numbers for everyone and introduce a standard for storing these numbers that includes the international dialing code (e.g. +1 or +44). Twillio can help with the data cleansing aspect by providing APIs that you can call to validate a number.
 
As well as an initial data cleansing effort, you will need to provide mechanisms to make managers aware when SMS messages fail to get sent due to invalid numbers. A business process also needs to be put in place to correct or add numbers to keep the process flowing smoothly.

---

Handling SMS Conversation

​Even though Twillio POSTs all the data you need to your web hook, there is no way of knowing which piece of an ongoing thread the user is responding to. If you look at the text history between you and a friend, you will often see responses out of sequence with the questions. Each interaction on an SMS thread does not have an identifier to help you keep a specific conversation together. In view of this, your back-end processing logic will need to be smart and look for key words and context clues. You also need to be very specific in the message you send out to make sure the user knows exactly how to respond.​

---

Using Different From Numbers

If you have different use cases for sending text messages and you need to handle responses to messages differently, then you may want to consider buying more than one outbound number. Having multiple numbers will make it easier to know the context of a response and handle processing of it more accurately.
 
One other thing to note is that the recipient is not going to recognize the number the SMS is being sent from. The first 15-20 characters of your SMS needs to clearly indicate who it is from and its urgency. For example, start your message with ‘From: ABC INC…’​

When to Send SMS Message

​Receiving timely information can make a huge impact. Having said that, SMS messages are a far more intrusive form of communication than email. You should not use it as the go-to method of communication (especially with employees). Use it sparingly and only when it really adds value.

​CAUTION:  do not schedule outbound messages to be sent in the middle of the night. Be careful when scheduling outbound messages, that you don’t send them in the middle of the night. The only thing more annoying than a text from your boss is one that is sent at midnight when your boss is sound asleep!

---

Opting Out​

​​Opting out of receiving SMS messages is an important part of the end-to-end flow. Twillio handles opting out very well but you need to provide instructions to the recipient on how they can opt out (and opt back in). You will also need to make managers aware of those people who have opted out.

---

Conclusion

Sending automated SMS messages is by no means a new thing. The technology and services that are available today, however, are making it far easier to do. Used correctly, SMS can provide the information your employees or customers need right when they need it.
 
Yet again, the RAD stack provides many of the technologies you need to integrate modern and innovative technology solutions such as Twillio into your existing ERP. One more reason to install APEX and ORDS today!