Handling incoming messages



The SMS event gateway handles messages that are contained in deliver_sm PDUs. These PDUs request the gateway to deliver one of the following types of message:

  • A user- or application-generated text message

  • A message disposition response

Note: The SMS event gateway does not handle messages that are contained in data_sm PDUs.

The event gateway sends the object to event gateway services, which delivers it to the listener CFC. The CFEvent object that the listener CFC receives contains the following fields:

Note: Consider SMS messages and any other data that enters through an Event Gateway handler to be potentially hostile. For example, if SMS data is archived in a SQL database, an attacker could construct a message that modifies or deletes data, or even takes over the SQL Server. Therefore, be sure to perform Event Gateway input validation, just as you would validate web form input.

Field

Value

CfcMethod

Listener CFC method name

Data.dataCoding

Character set or the noncharacter data type of the message contents

Data.destAddress

Address to which the message was sent

Data.esmClass

Message type

Data.MESSAGE

Message contents

Data.messageLength

Length of the MESSAGE field

Data.priority

Message priority level, in the range 0-3

Data.protocol

GSM protocol; not used for other networks

Data.registeredDelivery

Requested type of delivery receipt or acknowledgment, if any

Data.sourceAddress

Address of the device that sent this message

GatewayType

Always SMS

OriginatorID

Address of the device that sent the message

For a detailed description of each field, see SMS Gateway incoming message CFEvent structure in the CFML Reference.

The CFC’s listener method extracts the message from the Arguments.CFEvent.Data.MESSAGE field and acts on it as appropriate for the application. If necessary, the listener can use two fields to determine the required action:

  • CFEvent.Data.esmClass indicates the type of information in the MESSAGE field.

  • CFEvent.Data.registeredDelivery indicates whether the sender requested any type of delivery receipt or acknowledgment.

CFEvent.Data.esmClass field

The CFEvent.Data.esmClass field identifies whether the CFEvent.Data.Message field contains a message, or any of the following types of message disposition responses. For these responses, the CFEvent object Data.MESSAGE field contains the acknowledgment or receipt information.

SMSC Delivery Receipt
An indication of the message’s final status, sent by the SMSC. The short message text includes the message ID of the original message, the number of messages sent and delivered (for messages sent to a distribution list), the date and time that the message was sent and delivered or otherwise disposed of, the message disposition, a network-specific error code (if available), and the first 20 bytes of the message. For details of the SMSC delivery receipt message structure, see Appendix B of the SMS 3.4 specification.

SME Delivery Acknowledgement
An indication from the recipient device that the user has read the short message. Supported by TDMA and CDMA wireless networks only.

SME Manual/User Acknowledgement
An application-generated reply message sent in response to an application request message. Supported by TDMA and CDMA wireless networks only.

Intermediate Delivery Notification
A provider-specific notification on the status of a message that has not yet been delivered, sent during the SMSC retry lifetime for the message. Intermediate Notification support depends on the SMSC implementation and SMSC service provider. For more information, see your provider documentation.

When you send a message, you can request any combination of message disposition responses in the outgoing message’s registered_delivery parameter. If your application requests responses, the listener CFC must be prepared to handle these messages, as appropriate.

CFEvent.Data.registeredDelivery field

The CFEvent.Data.registeredDelivery field indicates whether the message sender has requested a receipt or acknowledgment. Your application can respond to a request for an SME Delivery Acknowledgement or an SME Manual/User Acknowledgement. (Only the SMSC sends the other notification types.) For more information on these notification types, see the SMS 3.4 specification. Appendix B contains detailed information on the information that you must place in the shortMessage field of the returned acknowledgment message.

Incoming message handling example

The following example code is an SMS-only version of the echo.cfc example that is included in the ColdFusion gateway/cfc/examples directory. This example shows the minimal code required to receive and respond to an SMS message.

<cfcomponent displayname="echo" hint="Process events from the test gateway and return echo"> 
<cffunction name="onIncomingMessage" output="no"> 
    <cfargument name="CFEvent" type="struct" required="yes"> 
    <!--- Get the message ---> 
    <cfset data=cfevent.DATA> 
    <cfset message="#data.message#"> 
    <!--- where did it come from? ---> 
    <cfset orig="#CFEvent.originatorID#"> 
    <cfset retValue = structNew()> 
    <cfset retValue.command = "submit"> 
    <cfset retValue.sourceAddress = arguments.CFEVENT.gatewayid> 
    <cfset retValue.destAddress = arguments.CFEVENT.originatorid> 
    <cfset retValue.shortMessage = "echo: " & message> 
    <!--- send the return message back ---> 
    <cfreturn retValue> 
</cffunction> 
</cfcomponent>