Sending messages through ColdFusion SMS gateways

If you own a cell phone chances are you've either sent or received a Short Message Service (SMS) text message. SMS messages allow the sending of short messages between cellular phones, PDAs, and other devices. Although they are frequently used to send short missives between friends, you can use SMS messages for a wide array of practical applications, such as casting votes in contests like American Idol, or receiving financial information, ringtones, weather warnings, Amber alerts, and so forth.

With the latest release of ColdFusion (ColdFusion MX 7) you're able to use the new event gateways to work with SMS messages. The SMS Gateway is one of several that comes standard with the Enterprise Edition of ColdFusion. With this gateway ColdFusion can now send SMS messages as well as respond to incoming SMS messages all with the simplicity that ColdFusion developers have come to love.

In this article you'll be creating an application to receive a stock symbol and return the current quote all via SMS messaging. You'll learn how to configure the ColdFusion SMS Gateway to handle the SMS messages, both incoming and outgoing. You'll also be writing a ColdFusion component to get the stock quote as well as receive messages from and construct return messages to the ColdFusion SMS Gateway.

Requirements

To follow the steps in this tutorial, you'll need to download and install the following software:

• ColdFusion MX 7 Enterprise or Developer Edition (If you install ColdFusion MX 7, it will turn into the Developer Edition after 30 days).
• Dreamweaver 8 or other text editor

Sample files:

• smsstock.zip (ZIP, 4K), which contains:

• Application.cfc – This file is loads the component that gets the stock quotes into an application scope variable.
• stockTools.cfc – This component fetches the stock quote (delayed 20 minutes), based on the symbol, through a free web service.
• smsStock.cfc – This component does all of the heavy lifting. It receives the message from the ColdFusion gateway, gets the stock quote, and assembles the return message sent back to the gateway.
• smsStock.cfg – This is the configuration file that specifies the event gateway.

Prerequisite Knowledge

A general knowledge of ColdFusion, ColdFusion components, and the ColdFusion Administrator.

Using the stockTools component

The stockTools component is used to get the actual quote through a free web service. The stockTools component has one method called getQuote that takes one argument: symbol, and returns a structure quoteData that contains two keys: quote and symbol. The stockTools component gets loaded into the application scope so it doesn't have to be instantiated every time you want to use it through the Application.cfc file. Application.cfc was new to ColdFusion MX 7 and replaces Application.cfm. Read more about Application.cfc in the ColdFusion LiveDocs.

<cffunction name="onApplicationStart">
	<cfobject name="application.cfcStockTools" component="smsStock.components.stockTools">
</cffunction>

Listing 1. The code for Application.cfc loads the stockTools component into the application scope.

Now that you've loaded the stockTools component into the application scope, you can make calls to the getQuote method without having to create a new instance of the stockTools component each time you want to get a new quote.

<cfset quoteData = application.cfcStockTools.getQuote("ADBE")>

Listing 2. You can make a call to the stockTools component in the application scope now

The stockTools component uses a free web service to get a 20-minute delayed quote. Find more information about the service at:

http://www.webservicex.net/WS/WSDetails.aspx?CATID=2&WSID=9

Writing the smsStock component

The ColdFusion SMS gateway requires two files: a configuration file and the ColdFusion component. Let's look at the configuration file first.

By default, when an instance of the SMS gateway receives an SMS message, it calls the onIncomingMessage method of the component that is associated with it. It passes the argument to the onIncomingMessage method, in a structure called CFEvent. There are several pieces of information in the CFEvent structure that are pertinent to our application. Inside the CFEvent structure there is another structure called data. This CFEvent structure, contains the information you'll need to get the stock quote and create the return message.

• CFEvent.data.message – This variable holds the SMS message that the user sent. In this case it is a stock symbol.
• CFEvent.gatewayId – The ID of the gateway that handled the incoming message. In the case of multiple SMS Gateways running on the same server, this value ensures that you send the return message to the right gateway.
• CFEvent.originatorId – This is the address of the device that sent the message. In most cases it will be the phone number of the cellular phone that sent the message.

With this information, you can make the call to the getQuote method of the stockTools component. By passing the stockTools component the value in CFEvent.data.message, the component will return a 20-minute delayed quote. To send the return message, you must construct a structure with four keys: command, sourceAddress, destAddress, and shortMessage. Each of these variables serves a specific purpose. For the purpose of this application, you'll construct a structure called returnMessage.

• returnMessage.command – This key is not required, but if it is present its value must be "submit."
• returnMessage.sourceAddress – This key specifies the address of the application sending the message.
• returnMessage.destAddress – This key specifies the address to send the message to. In this application, the value will be the number of the cellular phone that sent the message.
• returnMessage.shortMessage – This key specifies the message that will be sent to the user's device. In this case it will be the stock symbol and the current price.

Now it's time to put it altogether. Using the stockTools component, the CFEvent structure, and the return structure you can write the smsStock component. If you need help understanding ColdFusion components, see Introduction to CFCs by Ben Forta and the ColdFusion LiveDocs.

<cfcomponent>
    <cffunction name="onIncomingMessage">
        <cfargument name="cfEvent" required="yes" type="struct">
        
        <cfset var symbol = "">
        <cfset var quoteData = StructNew()>
        <cfset var returnMessage = StructNew()>
        <cfscript>
            symbol = arguments.cfEvent.data.message;
            quoteData = application.cfcStockTools.getQuote(symbol);
        
            returnMessage.command = "submit";
            returnMessage.sourceAddress = arguments.cfEvent.gatewayId;
            returnMessage.destAddress = arguments.cfEvent.originatorId;
            returnMessage.shortMessage = quoteData.symbol & ":" & dollarformat(quoteData.quote);
        </cfscript>
        
        <cfreturn returnMessage>
    </cffunction>
</cfcomponent>

Listing 3. The full stockTools component

Looking at the SMS configuration File

The second of the two pieces you need in order to work with the SMS Gateway is the configuration file. There is a sample configuration file provided with ColdFusion at \cf_root\gateway\sms-test.cfg.

You don't need to change anything in the configuration file for this application. If you want to know more about the SMS configuration file, check out the ColdFusion LiveDocs.

Setting up the gateway instance

For the application to work, you must set up an instance of the SMS gateway through the ColdFusion Administrator.

If you haven't already, unzip the contents of smsStock to your ColdFusion web root.

Log into the ColdFusion Administrator. Click the Event Gateways tab > Gateway Instances. Set up your SMS gateway with the following settings:

In order to setup the instance you'll need to do four things.

• Enter a value for GatewayID. For this application you can call it smsStock.
• Select the SMS Gateway option from the Gateway Type pop-up menu.
• For the CFC Path browse to the smsStock.cfc file (in a default ColdFusion install, the location would be: C:\CFusionMX7\wwwroot\smsStock\components\smsStock.cfc, for instance).
• For the Configuration File browse to the smsStock.cfg file in your web root (in a default ColdFusion install, the location would be: C:\CFusionMX7\wwwroot\smsStock\config\smsStock.cfg).

Figure 1. The settings for the SMS gateway

Once you've entered all the information click "Add Gateway Instance". Your gateway will be listed in the Configured ColdFusion Event Gateway Instances list. Don't start the gateway yet. You must read the next section first. Now you're now ready to test your application.

Testing the application

For the application to work in the real world, you would need to have a short code and contract with a third-party aggregator. Fortunately ColdFusion comes with a built-in server that emulates a third-party aggregator and a Java applet that simulates an SMS enabled phone. The smsStock configuration file is already set up to work with these. If you want more information about short codes and third party aggregators, see http://www.usshortcodes.com/.

The SMS test server is off by default, so you must turn it on in the ColdFusion Administrator. On the Event Gateways tab, click the Settings link. You should see a button for Start SMS Test Server. Click it. The SMS test server should now be running.

Now you can start your smsStock gateway. Go to Event Gateways > Gateway Instances, and click the green arrow for your smsStock gateway to start it. Make sure that you don't start either the SMS Menu App or the Book Club Gateway instance.

Now you can test the application. Launch the phone emulator by double-clicking a batch file called SMSClient.bat this file in the /cf_root/bin folder. The setting screen for the emulator appears first (Figure 2).

Figure 2. The setting screen for the phone emulator appears

Click Connect. The SMSClient window appears with the emulator (Figure 3).

Figure 3. The SMS client window appears with the emulator

Enter a stock symbol such as ADBE for Adobe and click Send. The emulator will display the stock quote price for the ADBE stock (Figure 4).

Figure 4. The emulator returns the stock quote price for Adobe

Where to go from here

You can now use the ColdFusion SMS capability to do all sorts of things. However, there's one word of caution. It is not a cheap proposition to obtain your own short code or to contract with a third-party aggregator. If you are serious about using SMS messaging in a production environment, I would highly encourage researching the cost of implementing such a solution. The information above on short codes and third-party aggregators is a great place to start. If you decide to use SMS, ColdFusion makes it easy for you!

About the author