Adobe ColdFusion 8

About SMS and ColdFusion

Short Message Service (SMS) is a system designed for sending short, often text, messages to and from wireless devices, such as mobile phones or pagers. SMS is widely used in Europe and Asia and is becoming increasingly popular in the United States and elsewhere. Some uses for SMS include the following:

  • Performing banking transactions
  • Sending authentication codes, for example, to be used to access web resources
  • Voting, such as popularity voting for reality television shows
  • Initiating an action (such as a server reboot) and getting a response
  • Notifying users of events such as package shipments or restaurant table availability, or providing stock or weather alerts
  • Sending person-to-person text messages
  • Presenting interactive text-based menus on a cell phone
  • Providing cellular phone updates, such as direct download of logos
  • Providing telematics and mobile or remote wireless device applications, such as soda machines, vehicle tracking, smart gas pumps, and so on

SMS protocol features include, but are not limited to, the following:

  • Authentication verification is built in.
  • Communications can be secure.
  • Store and forward communication is performed in near real time.
  • Communications can be two-way and session-aware.
  • Mobile devices such as cell phones already include support; there is nothing to install on the client.

About SMS

The following discussion simplifies SMS technology and describes only a typical use with a ColdFusion application. For a more complete discussion of SMS, see the publicly available literature, including the several books that discuss SMS.

In a ColdFusion SMS application, a mobile device such as a mobile phone communicates (via intermediate steps) with a message center, such as a short message service center (SMSC). For example, a mobile phone user calls a telephone number that the SMS provider has associated with your account; the SMSC gets the messages that are sent to this number. The SMSC can store and forward messages. A ColdFusion application can initiate messages to wireless devices, or it can respond to incoming messages from the devices.

The SMSC communicates with a ColdFusion SMS event gateway using short message peer-to-peer protocol (SMPP) over TCP/IP. Information is transferred by exchanging Protocol Data Units (PDUs) with structures that depend on the type of transaction, such as a normal message submission, a binary data submission, or a message intended for multiple recipients.

Because the SMSC is a store-and-forward server, it can hold messages that cannot be immediately delivered and try to deliver them when the receiving device is available. The time that a message is held on the server for delivery is configured by the SMSC provider. For example, AT&T Wireless saves messages for 72 hours; after that time, any undelivered messages are deleted. Your messages can request a different time-out (by specifying a ValidityPeriod field). The message can also use a registeredDelivery field to tell the SMSC to inform the you about whether and when the message is delivered.

SMS communication can be secure. Voice and data communications, including SMS message traffic between the SMSC and the mobile device is encrypted as part of the GSM standard. The mobile user's identity is also authenticated by the SMSC before the encrypted communication session begins. You must secure the communications between ColdFusion and the SMSC. Typically, you do this by using a secure hardware or software VPN connection around the SMPP connection.

The following image shows the SMS path between mobile devices and ColdFusion gateways:

Using the SMS event gateway, ColdFusion establishes a two-way (transceiver) connection to the SMSC of the telecommunications carrier or other SMPP account provider. The SMPP provider assigns an address for your account, and you associate an event gateway instance with the address. Addresses are normally telephone numbers, but carriers often support "short code" addresses that do not require a full 10-digit number. You also configure the gateway instance to communicate with the provider's specified TCP/IP address using a system ID and a password.

Note: The ColdFusion SMS event gateway conforms to the SMPP 3.4 specification, which you can download from the SMS Forum at www.smsforum.net/.

A ColdFusion application can initiate and send messages to SMS-enabled devices by specifying the destination mobile device telephone number, or mobile devices can send messages to a ColdFusion listener CFC by using the gateway instance's telephone number. Incoming messages include the sender's number, so listener CFCs can respond to messages sent by mobile devices.

About SMS application development and deployment

The following sections introduce the ColdFusion SMS application development tools and process, and discuss SMS messaging providers:

  • ColdFusion SMS application tools
  • Application development and deployment process
  • About SMS providers

ColdFusion SMS application tools

ColdFusion provides the following tools for developing SMS applications:

SMSGateway: The class for the SMS event gateway type

SMS test server: A lightweight SMSC simulator

SMS client simulator: A graphical interface for sending and receiving SMS messages with the SMS test server

You implement your SMS application by creating a ColdFusion application that uses an instance of the SMSGateway class to communicate with one or more SMSCs. You can use the SMS testing server and client simulator to test your application without requiring an outside SMS service provider.

Application development and deployment process

The following is a typical process for developing and deploying an SMS application:

  1. Design your application.
  2. Configure an SMS event gateway instance to use the ColdFusion SMS test server.
  3. Write your ColdFusion CFCs, CFM pages, and any other application elements.
  4. Test your application using the test server and client simulator.
  5. Establish an SMPP account with a telecommunications provider.
  6. Reconfigure your event gateway, or create a new event gateway instance, to use your telecommunications provider's SMSC. Configure the gateway using the information supplied by your provider.
  7. Test your application using the telecommunications provider's SMSC and target mobile devices.
  8. Make the application publicly available.

About SMS providers

Before you can deploy an SMS application, you must establish an account with a provider that supports SMPP 3.4 over TCP/IP. There are generally two kinds of providers:

  • Telecommunications carriers such as nation-wide cellular phone providers
  • Third-party SMPP aggregators

The type of provider and specific provider you use should depend on your needs and provider capabilities and price structures. Less expensive providers may have slower response times. Telecommunications carriers might be more expensive but might provide more throughput and faster SMPP response times.

How the SMS event gateway and provider SMSC interact

This section provides a brief overview of the interactions between the ColdFusion SMS event gateway and the SMPP provider's SMSC. It is designed to help you to understand the basics of SMPP interactions, and defines the terms necessary to for you to understand gateway configuration and message handling. For more details, see the SMPP specification, which is available at www.smsforum.net/.

A typical interaction between an SMSC and a ColdFusion SMS event gateway instance consists of messages, or PDUs sent between the two entities, such as a mobile device and a ColdFusion event gateway instance (and therefore, and event gateway application). The following sections describe these interactions and how you handle them in ColdFusion.

Gateway binding

The event gateway must bind to the SMSC before they can communicate. The SMS event gateway instance initiates a binding by sending a bind_transceiver PDU to the SMSC, which includes the gateway's ID and password. If the initial bind request fails, the gateway retries the bind at the rate specified by the gateway configuration file retry-interval value until either the bind is successful or the gateway reaches the maximum number of retries, specified by the retries configuration value. If the bind operation fails, ColdFusion logs an error to the eventgateway.log file, and you must restart the gateway instance in the ColdFusion Administrator to establish the connection.

Note: Some SMSCs can send a prohibited status in response to a bind request. If the gateway receives such a status response, it sets the retry interval to one minute and the maximum number of retries to 15. The SMS gateway detects SMPP 5.0-compliant and AT&T prohibited status responses.

When the SMSC accepts the bind request, it returns a bind_transceiver_resp PDU. The binding remains in effect until the gateway instance shuts down and sends an unbind PDU to the SMSC. Because the gateway binds as a transceiver, it can initiate messages to the SMSC, and the SMSC can send messages to it.

Incoming PDU handling

If the ColdFusion SMS event gateway gets an Unbind PDU from the SMSC, it sends an unbind_resp PDU to the SMSC, does a restart, and attempts to rebind to the SMSC.

When the event gateway receives an EnquireLink or any other request PDU from the SMSC, it sends a default response to the SMSC.

The gateway receives incoming messages from the SMSC in deliver _sm PDUs; it does not handle data_sm PDUs. Deliver_sm PDUs can contain user- or application-generated messages, or disposition responses for messages that the gateway has sent. The gateway extracts the short message field and source and destination addresses from the PDU, puts them in a CFEvent object, and sends the object to ColdFusion event gateway services for delivery to the listener CFC. For information on how the CFML application must handle these incoming messages, see Handling incoming messages.

Outgoing message handling

The gateway supports three types of outgoing messages from ColdFusion applications. The CFML sendGatewayMessage function or a listener CFC method cfreturn tag can specify the following commands:

submit: Sends a submit_sm PDU with the message contents to the SMSC. This PDU sends a message to a single destination.

submitMulti: Sends a submit_multi PDU with the message contents to the SMSC. This PDU sends a message to multiple destinations.

data: Sends a data_sm PDU with the message contents to the SMSC. This is an alternative to the submit command, and is typically used by interactive applications such as those provided via a wireless application protocol (WAP) framework.

The SMS gateway lets you control the contents of all of the fields of these PDUs. For more information on the individual commands, see Sending outgoing messages.

When you send a message, if the SMSC responds with a status that indicates that the message was rejected or not sent, ColdFusion logs information about the failure in the eventgateway.log file. If the SMSC indicates that the service type is not available (SMPP v5 ESME_RSERTYPUNAVAIL status or AT&T Serviced denied status), and the gateway configuration file transient-retry value is set to yes, the gateway also tries to resend the message.

Outgoing message synchronization and notification

The gateway and SMSC communicate asynchronously: the gateway does not wait for a response from the SMSC for one message before it sends another message. However, you can configure your gateway instance so that the CFML sendGatewayMessage function behaves asynchronously or synchronously.

  • In asynchronous mode, the function returns when the message is queued in ColdFusion gateway services.
  • In synchronous mode, the function waits until the SMSC receives the message and returns a message ID, or an error occurs.

For more information on configuring message synchronization and sending messages synchronously, see Controlling SMS message sending and response.