|SMS with Clickatell|
||MMAIL integration of Clickatell SMS service|
Some MMAIL users are asking for some SMS support through MMAIL.
Mainly they need to raise partner attention to urgent messages sent via e-mail.
After some investigations we found that Clickatell offers a simple integration into their SMS service.
This is why we have added to MMAIL some facilities for interfacing the Clickatel SMS server.
1. A few words about Clickatell
- They offer a free test service, limited to three given recipients phone numbers, that you have to pre-define.
- When you migrate your "integration" to production, you may send SMS to any phone number without pre-defining it, and ... you start to pay.
2. Prerequisites for MMAIL support of Clickatell SMS
- At least operating system release V4R1.
- Scott Klement's library LIBHTTP with service programs HTTPAPIR4 and XPAT.
- Optionally Easy400.net-delivered utility EZ4WEBSERV.
3. How to start a Clickatell SMS test service
- Go to the Clickatell home page.
- Click the link Register in the top right corner.
- You receive a page named Create your free account. Fill in the requested data
then push the button Register.
- do not miss to enter the phone number of the smart phone you will be using for test
- take a note of your "Account name" and "password"
- Check your inbox for an email containing a link to validate your registration. You’ll be able to log in after activation.
- Press the validation link to receive the Clickatell Login screen, press the Login button.
You are prompted another Login screen with your credentials: your e-mail address and the password that you did define minutes before.
Complete the login.
- You receive a welcome page. Press the Next button.
- You receive a SMS page. Press the link Get started with Single API for SMS only.
- You receive a "Details" page. Type your "integration name" (example: BudJones) and "description" (example: My fun). Take the other defaults and press
the Next button.
- You receive a "Features" page. Select One-way messaging and Standard. Press the Next button.
- On the next page just take the defaults and press the Next button.
- You receive a "Phone numbers" page stating that "You do not currently have any test phones linked to your account". Forget it and press the Next button.
- You receive a "Save integration" page. Press the Finish button.
- You receive a "Create integration" page. Just stop it by clicking the circled X button.
- You receive a "Get Started with SMS" page made of three sections: 1-Set up you test phones, 2-Create and test a SMS integration, 3-Setup your account.
Do the following:
- In section 2 you will see two "API key" green links.
These are the keys that will allow your SMS requests to work with Clickatell SMS service.
- Click the first one.
- You get a "Details" page. Copy and save this 24 characters API-key.
- Go back one page and perform the saving of the second 24 characters API-key.
Then go back again to the previous page.
- In section 1 press the button Add test phones.
You receive a screen that allows to define your test phone
- Enter the phone number and press button Add phone.
- A unique validation code is sent to your phone: enter it on the screen.
(you may add two more test phones. You can do it now, ao at a later time after signing in.
- You are done and you can leave the Clickatell page.
4. Setting up MMAIL databases for Clickatell SMS integration
A few MMAIL programs have been built to allow IBM i to work as a client in requesting SMS service to Clickatell.
However, to make their use as simple as possible, a number of MMAIL database files have been created and they must be loaded with data in order to make programs work.
All these databases are in library MMAILDATA (which is not affected by subsequent MMAIL releases).
At the time being data loading must be performed via DFU. Specifications follow.
- File MMAILDATA/CLICKAINT
This file documents the so called "integrations" available for you at Clickatell (usually two "integrations" are made available for test from Clickatell).
Record fields as follow:
|Integration ID:||A numeric sequence number assigned by you as identifier of a Clickatell "integration" Api-key|
|T=Test P=Production:||Whether the following Clickatell "integration" Api-key is in Test or in Production at Clickatell|
|Integration API-key:||A 24 char integration" Api-key obtained from Clickatell (Example: V7n2Mgk9SGmpJ0TRotsl5A== )|
|Integration name:||(Optional) - The name of the "Integration" for this Api-key as registered at Clickatell|
- File MMAILDATA/CLICKAUTPH
This file documents the pre-registered test phone numbers defined at Clickatell for testing the "integrations" still under test
(A maximum of three test phones can be defined at Clickatell for a couple of test "integrations").
Phone numbers must start with the appropriate country phone code (example: 33 for France).
Record fields as follow:
|Authorized phone number:||A pre-defined phone number used for test|
- File MMAILDATA/CLICKABOOK
This file is the SMS Phone Book used by command MMAIL/CLICKATELL to send SMS (see later).
Record fields as follow:
Note 1. When the "integration" used for a given phone number is still in test, the phone number must exist in file CLICKAUTHPH.
|Person identifier:||A short identifier for a given person (example: myself)|
|Person full name:||Full name of this person (example: Edith Plaff)|
|Phone number:||Phone number of this person|
|Integr. ID to be used:||Integration ID for the Api-key (SEE file CLICKAINT) to be used when sending SMS to this phone number|
Note 2. This SMS Phone Book may also be maintained with the WEB program WRKSMS.
5. MMAIL command to send SMS
The MMAIL command to send SMS via Clickatell is named CLICKATELL and looks as follow:
Send SMS via Clickatell (CLICKATELL)
Type choices, press Enter.
Recipient ID . . . . . . . . . . TO _________________________________________
Message to be sent . . . . . . . MSG _________________________________________
The execution of this command simulates a client HTTP connection to the Clickatell SMS server.
The query string of the URL contains the integration Api-key, the destination phone number and the message text.
- Recipient ID (TO) - ID of the person that will receive the SMS.
This ID must be documented in field "Person identifier" a record of file MMAILDATA/CLICKABOOK.
This parameter is case sensitive.
- Message text (MSG) - The message text to be sent. Up to 700 characters are allowed.
This parameter is case sensitive.
- All the parameters are checked by the command validation program.
- A feeback string is returned from the Clickatell SMS server and reports the result of this SMS request.
This string is rendered to a short sentence containing a two characters "OK" if the SMS sending was accepted.
This feedback string
- shows up in a joblog message
- is stored in the environment variable CLICKATELL_RESPONSE .
Therefore, if the command is issued from a program and the program needs to know if the SMS request was accepted,
the program should just retrieve the environment variable CLICKATELL_RESPONSE and check if the "OK" is there.
6. SMS log
Command CLICKATELL maintains a log in database file MMAILDATA/CLICKALOG.
The log contains the following information:
This log can be displayed by the WEB program WRKSMS (see next).
- Integration name
- Integration type: T for test, P for production
- Destination phone number
- Number of characters in the message
- SMS status: O for OK, 1 for failed.
7. Work with SMS from your Internet browser
After installing the HTTP instance MMAIL (available in stream file /mmail/conf/httpd.conf),
using the URL http://...:8035/mmailp/wrksms.pgm
you may run the WEB CGI program WRKSMS.
It features the following menu:
Through this menu you can:
|Work with SMS|
- Send SMS messages
- Display the SMS log entries for the last day, week, month, 6 months or year
- Maintain the SMS phone book
- Display your Clickatell Integration API-keys.
8. Measuring the delivery time of Clickatell SMS messages
A critical point of your testing with Clickatell SMS integrations is that of measuring the time taken in delivering the SMS messages.
The message delivery system may not be Message delivery may not be steady: some messages could be delivered in one second, some other in a few minutes,
some other in hours, and - the worst case - multiple messages could be delivered in a single batch shot.
If you are asking for "time critical SMS", you must make sure that all messages are delivered within 2 seconds.
In order to obtain what you need, you have better contacting the Clickatell support (email@example.com)
providing evidence of the delivery times you are experiencing.
There are a few commands that may help in providing such evidence:
- Command TESTSMS
Use this command to run a never-ending test on Clickatell SMS delivery response times. This is how it works:
Test Clickatell SMS responses (TESTSMS)
Type choices, press Enter.
Recipient ID . . . . . . . . . . TOID
Interval (min.s) between SMS's INTERVAL 120 15-1440
It is then your duty to manually record delivery response times as follow:
- In this command, parameter TOID identifies an entry in the SMS phone book (file MMAILDATA/CLICKABOOK) documenting the phone
number of a given person. It is suggested that this destination phone number is that of some personal smart phone of yours.
- The command submits a job - named TESTSMS - for batch execution.
- This job sends, at a given rate (specified in parameter INTERVAL), SMS messages (via command MMAIL/CLICKATELL) to the
specified phone number. Each message contains the date (yyyy-mm-dd) and the time (hh.mm) when that SMS request was posted. Example:
"Test message sent on 2019-09-06 at 11.56" .
- A log of such SMS requests is maintained in file MMAILDATA/TESTSMSDAT.
You may then use command MMAIL/TESTSMSP at any time to provide a performance report from the SMS request log file (MMAILDATA/TESTSMSDAT).
- Start a DFU on the SMS request log file (MMAILDATA/TESTSMSDAT).
- As soon as your smart phone receives a Clickatell SMS, you must update the related SMS request log record
(the one posted on the date and time specifed in the message) as follow:
- Field Date Received - the date (yyyy-mm-dd) when that message was received
- Field Time Received - the time (hh.mm) when that message was received
- Field Sending phone number - The phone number or the ID of the last network phone delivering that SMS message
- Field Response time (mm) - Leave it as it is. It will be computed later on by command MMAIL/TESTSMSP.
- Command TESTSMSP
Use this command to generate a report about performance of the SMS test requests (logged on file MMAILDATA/TESTSMSDAT by command MMAIL/TESTSMS).
Report SMS delivery response (TESTSMSP)
Type choices, press Enter.
Date (format yyyymmdd) . . . . . DATE *TODAY yyyymmdd, *TODAY, *ALL
This report is made of two parts:
- REPORT 1 - by "SENT DATE &TIME" - This part lists the SMS requests by descending SMS request timestamp and provides the
delivery time (in minutes) for each SMS. The average delivery time is reported in the bottom line.
- REPORT 2 - by "SENDING PHONE NUMBER" AND "DELIVERY DATE & TIME" - This part lists the SMS requests by "Last delivering phone number"
and SMS "delivery timestamp".
From this report one can easily find cases where multiple deliveries occurred at the same time.
Such cases are not acceptable and should be reported to Clickatell support organization.
Example of performance report
CLICKATELL SMS TESTS ON DATE 2019-09-06
REPORT 1 - by "SENT DATE &TIME"
REQUEST DELIVERED DELIVERY SENDING
DATE TIME DATE TIME TIME (min.s) PHONE NUMBER
2019-09-06 22.00 2019-09-06 22.00 0 INFOmessage
2019-09-06 20.00 2019-09-06 20.01 1 INFOmessage
2019-09-06 18.00 2019-09-06 18.00 0 INFOmessage
2019-09-06 17.32 2019-09-06 17.32 0 INFOmessage
2019-09-06 17.01 2019-09-06 17.01 0 INFOmessage
2019-09-06 16.13 2019-09-06 16.14 1 INFOmessage
2019-09-06 15.43 2019-09-06 15.44 1 INFOmessage
2019-09-06 15.13 2019-09-06 15.13 0 INFOmessage
2019-09-06 14.56 2019-09-06 14.56 0 INFOmessage
2019-09-06 14.26 2019-09-06 14.26 0 INFOmessage
2019-09-06 13.56 2019-09-06 13.56 30 +385 97 6456 129
2019-09-06 13.26 2019-09-06 13.26 0 +393 66 3832 764
2019-09-06 12.56 2019-09-06 14.15 79 +385 97 6456 130
2019-09-06 12.26 2019-09-06 12.54 28 +385 97 6455 997
2019-09-06 11.56 2019-09-06 12.16 20 +385 97 6455 989
2019-09-06 11.26 2019-09-06 11.31 5 +393 79 1672 585
2019-09-06 11.19 ***NO-DELIVERY
2019-09-06 11.10 2019-09-06 12.16 66 +385 97 6455 989
2019-09-06 10.40 2019-09-06 12.16 96 +385 97 6455 989
2019-09-06 10.10 2019-09-06 11.57 107 +385 97 6463 265
2019-09-06 09.40 2019-09-06 11.57 137 +385 97 6463 265
AVERAGE DELIVERY TIME: 21 minutes
REPORT 2 - by "SENDING PHONE NUMBER" AND "DELIVERY DATE &TIME"
SENDING DELIVERY REQUEST DELIVERY
PHONE NUMBER DATE TIME DATE TIME TIME (min.s)
+385 97 6455 989 2019-09-06 12.16 2019-09-06 10.40 96
2019-09-06 11.10 66
2019-09-06 11.56 20
+385 97 6455 997 2019-09-06 12.54 2019-09-06 12.26 28
+385 97 6456 129 2019-09-06 13.56 2019-09-06 13.56 30
+385 97 6456 130 2019-09-06 14.15 2019-09-06 12.56 79
+385 97 6463 265 2019-09-06 11.57 2019-09-06 09.40 137
2019-09-06 10.10 107
+393 66 3832 764 2019-09-06 13.26 2019-09-06 13.26 0
+393 79 1672 585 2019-09-06 11.31 2019-09-06 11.26 5
INFOmessage 2019-09-06 22.00 2019-09-06 22.00 0
20.01 2019-09-06 20.00 1
18.00 2019-09-06 18.00 0
17.32 2019-09-06 17.32 0
16.14 2019-09-06 16.13 1
15.44 2019-09-06 15.43 1
15.13 2019-09-06 15.13 0
14.56 2019-09-06 14.56 0
14.26 2019-09-06 14.26 0
|Data collected on test SMS log file MMAILDATA/TESTSMSDAT:|
| ||entered by command TESTSMS|
| ||manually enter by user via DFU upon SMS message delivery|
| ||computed by command TESTSMSP|
Usefullness of this report
Since then the SMS response time is keeping the same excellent level.
- On September 6, 2019 at hours 9.40 we entered command MMAIL/TESTSMS. In this way we started a non-ending job which was sending an SMS every 30 minutes to
out test phone number.
- The first SMS was sent at 9.40, the second SMS was sent at 10.10.
Nothing was delivered to our test phone until hours 11.57. At that time, both the first and the second message were delivered by phone number +385 97 6463 265 .
- The following SMS's behaved more or less the same way (incidentally, one was never delivered).
- At about noon we raised by e-mail an issue to Clickatell Support, providing the report from command MMAIL/TESTSMSP (a subset of the report above).
- Things continued that unacceptable way until hours 14.26, when the delivery started being almost immediate.
- Meanwhile we received an e-mail message from Clickatell support saying that they upgraded their network path to us.