Whatever message this page gives is out now! Go check it out!
Handling incoming messages-SMS event gateway
Last update:
May 18, 2026
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:
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> </cffunction> </cfcomponent> |
We're glad. Tell us how this page helped.
We're sorry. Can you tell us what didn't work for you?
Share additional feedback to help us improve.
0/255
|
