Responding to SMS Messages

Sending messages is one thing, responding to them is a different matter. As with IM gateway, our SMS gateway is always listening for incoming messages to answer. Modify your gateway CFC (sms.cfc) as below:

 <cffunction name="onIncomingMessage">          <cfargument name="CFEvent" type="struct" required="YES">          <!--- Generate and return the message.--->          <cfscript>          msg = structNew();          msg.command = "submit";          msg.destAddress = arguments.CFEvent.originatorID;          msg.shortMessage = Trim(arguments.CFEvent.data.message);                   return msg;         </cfscript> </cffunction>  

While this is quite similar to the IM gateway onIncomingMessage() function you will notice that there is a very different set of properties exposed to you. In particular the originatorID, or the phone number from which the message was generated.

Ensuring Delivery of Your Messages

Now that you have sent your message, it would be nice to make sure that your user has received it. This can be done with the SMS protocol but it does require a little more work.

First you will need to make sure that your gateway is configured for synchronous message delivery and that when you call the SendGatewayMessage() function you capture the messageID as it comes back and store it for future reference, typically this would be in a database somewhere.

Next when you submit your message to the gateway you will need to include a RegisteredDelivery field in the message request. This takes one of three options:

• 0 This is the default, do not return any status 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

The second two options instruct the SMSC to return a message back to our gateway reporting on the status of the message. You will need to recode your onIncomingMessage() method of the gateway CFC to look for these messages and separate them out from regular incoming messages. Figure 32.5 shows the format of a tracking package as it would be returned from the SMSC server.

Figure 32.5. The format of a tracking package.

This message is returned in following format:

[View full width]
 "id:IIIIIIIIII sub:SSS dlvrd:DDD submit date:YYMMDDhhmm done date:YYMMDDhhmm stat:DDDDDDD  err:E Text: ..." 

Now that you have the status of the message, you can query your messageID database table and make an intelligent decision about what should be done with this message. Whether we choose to resend this message or maybe escalate this to another user.

Sessions and SMS

As with standard ColdFusion, the first time an SMS user sends a message to our gateway ColdFusion generates a session for that user. As the users' interaction with the server is much more limited than it would be if they were using a browser, this session becomes much more important. It allows us to store and track information about their past interactions with the gateway.

For example, in our helpdesk application, if they asked for a new case to be assigned to them and then asked for the details of their cases, it would be fairly safe to assume that they only really want the details of their latest opened case to be sent to their phone, not the details of every single case. This allows us to reduce the amount of keystrokes that a user may be required to send to the gateway to get the details that they need. There is nothing fancy that you need to add to your application beyond the normal session code that you would add in a normal ColdFusion application.