CFMX7: SMS Applications
Made Easy
Damon Cooper
Director of Engineering, ColdFusion
Session Overview
•
•
•
•
•
•
•
Introduction to SMS & ColdFusion (10 min)
SMS App Development & Deployment (5 min)
ColdFusion Event Gateways (5 min)
ColdFusion SMS Gateway (5 min)
ColdFusion SMS Development Tools (5 min)
Setup, Binding and Message Handling (15 min)
Advanced Message Options (5 min)
•
•
•
Delivery & “Disposition Status” Receipts
Security, Authentication and Encryption
Tips & Next Steps (5 min)
Introduction to SMS & ColdFusion

About Short Message Service (SMS):
•
•
•
•
•
Designed for sending and receiving text messages to/from
mobile phones and devices.
Part of GSM cellular standard (1991)
SMS usage is extensive worldwide and increasing
pervasive in US:
• China: 550 Billion SMS messages in 2004, 1.4 Trillion
by 2006. (CHINA COMMS Network)
• UK: 23-25 Billion SMS messages for 2004 (MDA)
• Used by over 70% of mobile phone users worldwide
• Most messages delivered in <10 seconds
SMS US and Canadian carriers include: AT&T Wireless,
Verizon, Sprint, Cingular, Nextel, T-Mobile, Bell Mobility,
Rogers/AT&T, Telus Mobility and Microcell, etc.
Secure, reliable, virtually everywhere and basically
works the same regardless of handset or carrier.
Introduction to SMS & ColdFusion

•
•
•
•

•
•
•
Benefits
Fully mobile: available anywhere, anytime w/store-andforward
Secure: GSM has built-in authentication and encryption
Everywhere: No special hardware or software required for
users
Push or Pull: excellent for timely alerts, alerts with simple
responses, simple textual menus, info lookup, etc
Limitations
Limited message length (160 chars)
Device keypad interfaces make typing lengthy messages
cumbersome
Response time can vary and can impact app usability
and design
Introduction to SMS & ColdFusion

•
•
•
•
•
•
Key SMS Terminology
SMSC: Short Message Service Center (carrier or
aggregator). These provision SMPP accounts and
interface with mobile network.
SMPP:
• “Short Message Peer to Peer” protocol.
• ColdFusion uses this to talk to SMSC’s.
• Industry standard protocol simplifies integration of
custom applications with wireless mobile networks.
Widely deployed in mobile telecom industry.
• v3.4 is most widely in use currently but next version,
v5.0 is in draft.
MO: Mobile Originated. Messages sent from a device.
MT: Mobile Terminated. Messages sent to a device.
ESME: External Short Message Entity (your application)
Aggregator: Company providing a single interface (ie
SMPP account) to access multiple cellular provider
networks.
Introduction to SMS & ColdFusion


Technical Use Case Scenarios
•
•
•
•
•
PersonPerson (2-way chat)
AppPerson (1-way Push)
AppPerson (2-way interactive, Push)
PersonApp (2-way interactive, Pull)
AppApp (2-way interactive, Push or Pull)
SMS Application Examples
•
•
•
•
•
•
Airline 2-way flight change notification and rebooking
SMS Banking, ABC News, UPS Tracking, American Idol
Mass media & mobile apps (voting, contests, 411 lookups,
customer feedback, etc)
Stock & Weather Alerts (1- or 2-way Push or Pull)
Any mobile GSM device (transmit GPS & telemetry, remote
device monitoring, vending machines, gas pumps, even Coke
cans (Coca Cola US summer contest), etc.
YOUR ENTERPRISE APPS (PO approvals, critical
notifications, phone directory lookup, CEO dashboard &
alerts, meeting reminders, cancellations, SMS-Email bridging,
etc)
Introduction to SMS & ColdFusion
Introduction to SMS & ColdFusion

SMS Basic Operation:
•
•
•
•
Messages can be 160 chars (Latin) or 70 chars
(non-Latin, such as Arabic and Chinese)
Messages are sent from device to an SMSC
SMSC interacts with mobile network to figure out
user availability and location
SMS uses the GSM control channel (rather
than the voice channel)
• End user can receive an SMS whether or
not a voice call is in progress - the phone
need only be turned on
Introduction to SMS & ColdFusion
SMS Basic Operation (Cont’d):

•
If device is off, the SMSC holds message for
“Validity Period” (usually default of 72 hours) and
delivers message to device when turned on
•
If desired, message status receipts
(“delivered”, “undeliverable for validity period”,
etc) are sent to originator
•
With SMS the sender generally pays some permessage fee (bulk packages usually available)
• Big difference between SMS and email
(SPAM)
Introduction to SMS & ColdFusion

•
Building Mobile SMS-Enabled Applications
SMS is compelling as a pervasive platform for
many types of mobile applications, BUT
•
Building & deploying SMS mobile-enabled apps
today can be complex and costly
•
Menu-based or simple responses
•
Need session management
•
Need scalable, failsafe, throttling, metering,
monitoring, logging and auto-rebind capabilities
Introduction to SMS & ColdFusion

Building Mobile SMS-Enabled Applications
• ColdFusion MX 7 and SMS:
• Create new mobile applications or mobileenable existing apps
• Build and test with integrated SMS
development & testing tools
• Deploy on standard Java J2EE servers
quickly and simply
• Do all this in as little as 5 minutes with
ColdFusion MX 7
• Enterprise-Ready: (ie AT&T Wireless
Certified)
Introduction to SMS & ColdFusion

SMS App Development & Deployment
Overview
Development Process:
1. Design your application
2. Develop your ColdFusion CFCs, CFM pages, and any
other application elements
3. Test your application using built-in SMSC Test Server, preconfigured Test SMS Gateway instance and mobile device
client simulator

Deployment Process:
1. Establish an SMPP account with SMSC provider /
aggregator
2. Configure a new SMS Gateway instance to use your
SMSC’s SMPP Server. Configure the gateway using the
information provided by your provider
3. Test your application using the telecommunication
provider’s SMSC and target mobile devices and when
ready, go live!
ColdFusion Event Gateway Overview
 ColdFusion Event Gateways:
• Pluggable protocol-specific elements which allow ColdFusion
applications to respond and interact with the outside world
• Generate external events or messages from ColdFusion
applications
• Pass along external events or messages to ColdFusion
applications
• Some of the Gateways provided with ColdFusion MX 7:
• SMS Gateway
• XMPP/Jabber IM Gateway
• IBM/Lotus Sametime IM Gateway
• JMS Gateway
• Asynchronous CFML Gateway
• TCP/IP Socket Gateway
• Directory Watcher Gateway
• Example Gateway (with source)
ColdFusion Event Gateway Overview
 Event Gateway Architecture Features:
• Published Gateway API for 3rd parties who wish to create new
ColdFusion MX 7 Gateways
• Multithreaded, asynchronous message and event handling and
logging
• Gateway Type and Instance Administrative interface & API
• Allow Coldfusion MX 7 Gateway applications to be written using
just CFCs to listen for and respond directly to external events
• Can be used to Gateway-enable .NET, J2EE or legacy apps
• Require NO Java or threading knowledge to create Gateway
applications
• Full Gateway apps can be packaged and deployed as pure J2EE
EAR/WAR files on standard J2EE servers
• Provides automatic “Session” and persistent “Client” variable
scope management and logging facilities
• Highly tuned, scalable and lightweight for maximum performance
• Full textual menu-driven app framework included
ColdFusion Event Gateway Overview
The ColdFusion SMS Gateway
 SMS Gateway Overview
• Establishes a two-way SMPP-over-TCP/IP connection to
SMSC provider
• SMPP provider provides an address (telephone number or
Short Code), TCP/IP connection and SMPP configuration
setting information for account
• Must associate SMS Gateway “instances” with
configuration files. Default starting CFG files in
{cfusion}\gateway\config\*.cfg
• SMS Gateway conforms to SMPP 3.4 (most commonly
deployed currently), available from SMS Forum at
http://www.smsforum.net
The ColdFusion SMS Gateway
 SMS Gateway Overview (Cont’d)
• ColdFusion applications can initiate and send messages
(“push”) to SMS-enabled devices with the
“sendGatewayMessage()” function
• To use sendGatewayMessage(), specifiy:
• Destination mobile device telephone number
• SMS Gateway instance ID
• Message and advanced message options
• Mobile devices send messages to a ColdFusion listener
CFC by using SMS Gateway instance’s telephone
number or Short Code
• Incoming messages include the originating device’s
phone number, so listener CFCs can respond to messages
sent by mobile devices
ColdFusion SMS Development Tools
 Built-in tools
• SMSC Test Server
• Simulates the phone company or 3rd part aggregator’s
SMSC Server
• Started in the Administrtor
• Off by default on start
• Pre-configured SMSC Test Gateway Instance
• Pre-configured to talk to SMSC Test Server
• Not running by default
• Pre-configured to point to sample gateway menuing
application in {cfroot}\gateway\cfc\examples\menu.cfc
• SMSC Test Client Device
• Simulates basic cell phone with SMS “chat” mode
• Run from Windows Start Menu or batch file
• Pre-configured to talk to the SMSC Test Server
ColdFusion SMS Development Tools
 Demo
Setup, Binding and Message Handling
 SMS Gateway Setup:
• Create a new SMS Gateway instance and set Config and
CFC files
• SMS Gateway must bind to SMSC before handling
messages
• CFG file specifies all params and other key configurables
Setup, Binding and Message Handling
 SMS Gateway Setup:
• CFG file params include:
• CFC method to be called on incoming SMSC message.
Default=“onIncomingMessage”.
• Outbound message throttle rate (def=100, 0=unlimited)
• Mode (synchronous/asynchronous)
– Synchronous: wait for SMSC response.
SendGatewayMessage returns messageID or empty string
if error.
– Asynchronous: don’t wait for SMSC response. Empty
string returned.
• Retry behavior after specific types of errors.
• Bind connection EnquireLink check interval (checks if
connection is OK)
• Number of bind attempts before giving up (def -1 = try
forever)
• Bind retry interval. How long to wait between rebind
attempts. Def=10 seconds
Setup, Binding and Message Handling
 Logged events and exceptions go to
{cfusion}\log\eventgateway.log
 Inbound Message Handling
• Specially-handled messages:
• Unbind directive: SMS Gateway unbinds and
restarts and attempts to rebind
• EnquireLink or status request: SMS Gateway
responds with appropriate response
• Messages forwarded to your CFC can be new
incoming text messages or status notifications
about previously-sent messages
• A CFEvent structure is created & loaded with
short messages text, originator, recipient, etc and
passed to listener CFC method
Setup, Binding and Message Handling
 SMS Gateway CFEvent Structure:
CFEvent Field
OriginatorID
CfcMethod
Data.MESSAGE
Data.sourceAddress
Data.destAddress
GatewayType
 Example:
Value
Contents of PDU source_addr field (address of sending device)
Listener CFC method name. Value of configuration file cfc-method entry,
or "onIncomingMessage" if configuration file entry omitted
Contents of the short_message field of the PDU.
Address of the device that sent this message
Address to which message was sent; an address in the range
specified by the gateway configuration file address-range setting.
“SMS”
Simple “Echo” Pull SMS App
<cfcomponent>
<cffunction name="onIncomingMessage">
<cfargument name="CFevent" type="struct" required="YES">
<cfscript>
/* Create a return structure that contains the message. */
retValue = structNew();
retValue.command = "submit";
retValue.destAddress = arguments.CFEVENT.originatorid;
retValue.shortMessage = "Echo: " & CFEvent.Data.MESSAGE;
</cfscript>
<!--- send the return message --->
<cfreturn retValue>
</cffunction>
</cfcomponent>
Setup, Binding and Message Handling
 Sending Outbound Messages
• Put the command, destination and data in a
structure and then either:
• “Return” it in response to an incoming
message, OR
• Use the SendGatewayMessage(gatewyID,
data) function
• Typical outbound data structure:
Field
Command
shortMessage or
messagePayload
destAddress
sourceAddress
Contents
Command (ie "submit" or "submitMulti")
Message contents (max 254 bytes, usually max 160 for shortMessage,
64K for messagePayload if supported)
Address to which to send the message.
Address of this application (can be omitted if specified in the CFG file)
Setup, Binding and Message Handling
 Slightly more evolved SMS Demo
(temperature converter):
Sending SMS from a Web App
<cfscript>
/* Create a structure that contains the message. */
msg = structNew();
msg.command = "submit";
msg.destAddress = "5551234";
msg.shortMessage = form.SMSMessage;
ret = sendGatewayMessage("SMS Menu App - 5551212",
msg);
</cfscript>
Setup, Binding and Message Handling
 Sending SMS from a Web Page Demo:
Advanced Message Options
 Requesting Message Disposition Status
• Include a RegisteredDelivery field in Data
parameter of sendGatewayMessage() function or
return variable of CFC listener method:
• 0 = (Default) Do not return delivery information
• 1 = Return a receipt if the message is not
delivered before the time out (Validity Period)
• 2 = Return a receipt if the message is delivered
or fails.
• Some providers support intermediate delivery
notifications (see provider’s docs)
• Must use synchronous mode to get a
messageID
Advanced Message Options
 Handling Message Disposition Status
• Incoming message routine must handle these special
messages: need to parse and unload MessageID and Status
fields from “Data.Message”
• Format (from Appendix B of SMPP 3.4 Spec):
“id:IIIIIIIIII sub:SSS dlvrd:DDD submit
date:YYMMDDhhmm done date:YYMMDDhhmm
stat:DDDDDDD err:E Text: ...”
Advanced Message Options
 Handling Message Disposition Status
• Can match up status MessageID with any sent
MessageID and act accordingly.
– If a message expired before it was delivered, you might
send a new message to another person (ie emergency
personnel) or take some other action.
• For details of the SMSC delivery receipt
message structure, see Appendix B of the
SMPP 3.4 specification.
Advanced Message Options
 Requesting Message Disposition Status
• Sample CFEvent with SMSC Disposition Status:
Advanced Message Options
 Security, Authentication and Encryption
• Voice and data (including SMS message traffic) between
SMSC and mobile device is encrypted as part of the GSM
standard.
• The mobile user's identity is authenticated first, before
encrypted communication session begins.
• AT&T Wireless has a page that describes the various
security aspects of GSM and SMS:
http://www.attwireless.com/3G/TechnologyCenter/security/contro
ls_station.htm
• The connection between CF and SMSC:
• The SMPP standard provides for login/bind
authentication and authorization, but
• No inherent SMPP support encryption of message
traffic.
• Most SMSC providers require a secure hardware or
software VPN connection around the SMPP connection.
• The pervasiveness, mobility and security of the SMS
platform paves the way for development of some very exciting
business and m-commerce applications!
Tips & Next Steps
 Get ColdFusion MX 7 and get started now!
 Deployment considerations:
• 5-digit cross-carrier US Short-Code (like the American Idol
TV
show), needs to obtained via http://www.usshortcodes.com
and setup SMPP aggregator/provider account (ie m-Qube,
Mobileway, etc).
• Easy to setup, but takes 4-9 weeks, so allow lead time
• Short Codes come in a number of varieties:
• Carrier-specific (ie 4-digit AT&T Wireless Short Code)
• 5-digit US Short Code (http://www.usshortcodes.com)
$1k/month
• Universal Short Code (tougher to get)
Tips & Next Steps
 Cont’d
• If audience on only one carrier, going carrier-specific is
probably a good choice and provides lightening fast response
times
• If audience is US mixed-carrier, US Short Code and 3rd party
aggregator SMPP provider is good choice with very good
response times
• Can have a "SIM" modem setup at an aggregator or carrier, but
response times VERY slow, capacity very limited, but for
very small applications and audiences, this may suffice. Also much
cheaper.
• SMPP accounts range from $40/month for development
accounts to many thousands, based on volume. US AT&T
Wireless
SMPP account can be had for about $500/month:
http://www.attwireless.com/press/releases/2002_releases/052102.jhtml
CFMX7: SMS Applications
Made Easy
Damon Cooper
Director of Engineering, ColdFusion