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.




Listener CFC method name


Character set or the noncharacter data type of the message contents


Address to which the message was sent


Message type


Message contents


Length of the MESSAGE field


Message priority level, in the range 0-3


GSM protocol; not used for other networks


Requested type of delivery receipt or acknowledgment, if any


Address of the device that sent this message


Always SMS


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.

<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>

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy