IBM i Modernization - The User Interface
(Part 18)
This article discusses the idea of sending text messages to smart phones from IBM i applications. Please click on the following screen shot to try it.
Twilio
Twilio is a company that provides a number of web services, including a popular one for sending text messages to smart phones and similar devices.
Twilio issues an account number, a secret authentication token, and a phone number to individuals (or organizations) to enable them to send text messages via their web-service API.
Twilio bills your account for your use of the phone number ($1 per month at this time), plus a small fee (less than 1 cent for phones in the USA) per message processed. Volume discounts are available.
Twilio supports phone carriers all over the world. However I've limited the demo featured in this article to only phone numbers issued in the USA.
Use Cases
Text notifications and alerts for any type of application such as:
- 2-factor authentication.
- Appointment reminders.
- Dispatch notifications.
- Arrival notifications.
What the Demo Does
- Prompts users to enter a smart phone number and message text.
- The form's values are sent to an ILE RPG program named IUI106.
- The IUI106 program connects with the Twilio web service, queues the message for dispatch, and returns a confirmation (or error) to the browser.
Twilio supports up to 10 file attachments per message. However I've limited the scope of the demo to only 1024 characters of message text.
Twilio message queueing is not very prone to errors. Exceptions include malformed phone numbers, insufficient account funds, and such.
Twilio offers an optional call-back web service in the event that you're interested in tracking phone-carrier transmission errors that may occur down line.
The Form's JavaScript
The send() function is invoked when the form is submitted (via button click or the "enter" key).
function send() {
reqPost('/rdcaller/send.shtml?rwappid=iui106' ,fm.pd());
return false;
}
High-level explanation of send():
- The form's data elements are posted to the server (program IUI106 is called to process it).
- returning "false" overrides the default form submit (reqPost() uses AJAX instead).
The us() function is invoked by the response from the IUI106 program:
function us(rt) {
fm.sa('msg','value','');
fm.sf('phone');
um.innerHTML = rt;
}
High-level explanation of us():
- The IUI106 program returns a "confirmation" message.
- The value of the "msg" input element is set to an empty string.
- The focus is set to the "phone" input element.
Program IUI106
An RPG program named IUI106 responds to the "send" request. The code is as follows:
//-----------------------------------------------------------------
// procedure prototypes
//-----------------------------------------------------------------
/copy *libl/qrpglesrc,rdstrapi#1
/copy *libl/qrpglesrc,rdtwiapi#1
/copy *libl/qrpglesrc,rdwtnapi#1
//-----------------------------------------------------------------
// module level data
//-----------------------------------------------------------------
d rw e ds extname(rwpgmc) qualified
d s1 s * inz(*null)
d twilio ds likeds(twilio_t) import
d crlf s 2a inz(x'0D25')
d twisid s 64a dtaara(twisid)
d twisecret s 64a dtaara(twisecret)
d twifrom s 32a dtaara(twifrom)
//-----------------------------------------------------------------
// program entry
//-----------------------------------------------------------------
c *entry plist
c parm rw
/free
//-----------------------------------------------------------------
// set reference to UI template
//-----------------------------------------------------------------
if s1 <> *null;
wtnSetInst(s1);
endif;
//-----------------------------------------------------------------
// branch to subroutines based on requested actions
//-----------------------------------------------------------------
select;
when rw.action = 'INIT';
exsr do_init;
when rw.action = 'SEND';
exsr do_send;
endsl;
return;
//-----------------------------------------------------------------
// initialization
//-----------------------------------------------------------------
begsr do_init;
s1 = wtnOpen('IUI106');
clear twilio;
in twisid;
in twisecret;
in twifrom;
twilio.sid = %trimr(twisid);
twilio.secret = %trimr(twisecret);
twilio.from = %trimr(twifrom);
endsr;
//-----------------------------------------------------------------
// send message to phone
//-----------------------------------------------------------------
begsr do_send;
twilio.to = %char(strToInt(wtnFldGet('phone')));
twilio.body = wtnFldGet('msg');
twilio.body = strReplace(twilio.body:'\n':crlf);
if twilSendSms();
twilio.msg = 'Thanks for your message @ ' + %char(%date():*usa)
+ ' ' + %char(%time():*hms) + '.';
endif;
//-----------------------------------------------------------------
// send "confirmation" to browser
//-----------------------------------------------------------------
wtnRecSet('US');
wtnFldSet('um':twilio.msg);
wtnRecWrt('US');
endsr;
/end-free
High-level explanation of program IUI106:
- Program IUI106 binds to a service program named RDTWIAPI that implements an high-level interface with Twilio. Any ILE program or service program can bind to RDTWIAPI to send Twilio text messages.
- My Twilio account number, secret authorization token, and phone number are retrieved from IBM i data areas.
- A procedure named twilSendSms() is paired with a qualified data structure named "twilio" to send text messages.
- We should review the layout of the "twilio" data structure that is imported from the RDTWIAPI service program:
d twilio_t ds qualified template d sid 64a varying d secret 64a varying d from 32a varying d to 32a varying d body 1600a varying d media 8192a varying d msg 256a varying
- sid - your Twilio account number.
- secret - your secret authentication token.
- from - your Twilio phone number.
- to - your recipient's smart phone number.
- body - your message body.
- media - media attachments (up to 10 maximum).
- msg - message returned by Twilio (i.e. error).
Wrapping Up
There are quite a few use cases for sending text messages to smart phones from IBM i applications. Hopefully this article stirs some consideration.
This article was inspired in part by a GITHUB project of Rainer Ross, that uses Node.js to send Twilio texts from IBM i applications See here.