Sending outgoing messages



Your ColdFusion application can send submit, submitMulti, and data commands to the event gateway in an outgoing message.

The submit command

To send a message to a single destination address in an SMPP SUBMIT_SM PDU, the structure used in the Data parameter of a SendGatewayMessage function or the return variable of the CFC listener method normally has the following fields:

Field

Contents

command

If present, the value must be "submit". If you omit this field, the event gateway sends a submit message.

shortMessage

or

messagePayload

The Message contents. specify one of these fields, but not both. The SMPP specification imposes a maximum size of 254 bytes on the shortMessage field, and some carriers could limit its size further. The messagePayload field can contain up to 64 K bytes; it must start with 0x0424, followed by 2 bytes specifying the payload length, followed by the message contents.

destAddress

The address to which to send the message (required).

sourceAddress

The address of this application. You can omit this field if it is specified in the configuration file.

You can also set optional fields in the structure, such as a field that requests a delivery receipt. For a complete list of fields, see submit command in the CFML Reference. For detailed descriptions of these fields, see the documentation for the SUBMIT_MULTI PDU in the SMPP3.4 specification, which you can download from the SMS Forum at www.smsforum.net/.

Note: To send long messages, you can separate the message into multiple chunks and use a submit command to send each chunk separately. In this case, a CFC would use multiple SendGatewayMessage functions, instead of the cfreturn function.

Example: Using the submit command in sendGatewayMessage function

The following example from a CFM page uses a sendGatewyMessage CFML function with a submit command to send an SMS messages that you enter in the form. This example uses the SMS gateway that is configured in the ColdFusion installation, and sends the message to the SMS client simulator. 

<h3>Sending SMS From a Web Page Example</h3> 
<cfif IsDefined("form.oncethrough") is "Yes"> 
<cfif IsDefined("form.SMSMessage") is True AND form.SMSMessage is not ""> 
    <h3>Sending Text Message: </h3> 
        <cfoutput>#form.SMSMessage#</cfoutput><br> 
        <cfscript> 
        /* Create a structure that contains the message. */ 
        msg = structNew(); 
        msg.command = "submit"; 
        msg.destAddress = "5551234"; 
        msg.shortMessage = form.SMSMessage;     
        ret = sendGatewayMessage("SMS Menu App - 5551212", msg); 
        </cfscript> 
</cfif> 
<hr noshade> 
</cfif> 
<!--- begin by calling the cfform tag ---> 
<cfform action="command.cfm" method="POST"> 
    SMS Text Message: <cfinput type="Text" name="SMSMessage" value="Sample text Message" required="No" maxlength="160"> 
<p><input type = "submit" name = "submit" value = "Submit"> 
<input type = "hidden" name = "oncethrough" value = "Yes"> 
</cfform> 
</body> 
</html>

For a simple example of a listener CFC uses the submit command to echo incoming SMS messages to the message originator, see Incoming message handling example.

The submitMulti command

To send a single text message to multiple recipients using an SMPP SUBMIT_MULTI PDU, the Data parameter of a SendGatewayMessage function or the return variable of the CFC listener method normally has the following fields:

Field

Contents

command

Must be "submitMulti".

shortMessage

or

messagePayload

The message contents. Specify one of these fields, but not both. The SMPP specification imposes a maximum size of 254 bytes on the shortMessage field, and some carriers could limit its size further. The messagePayload field can contain up to 64 K bytes; it must start with 0x0424, followed by 2 bytes specifying the payload length, followed by the message contents.

destAddress

A ColdFusion array of destination addresses (required).

You cannot specify individual TON and NPI values for these addresses; all must conform to a single setting.

sourceAddress

The address of this application; you can omit this field if it is specified in the configuration file.

You can also set optional fields in the structure, such as a field that requests delivery receipts. For a complete list of fields, see submitMulti command in the CFML Reference. For detailed descriptions of these fields, see the documentation for the SUBMIT_MULTI PDU in the SMPP 3.4 specification, which you can download from the SMS Forum at www.smsforum.net/.

Example: Using the submitMulti command in an onIncomingMessage method

The following example onIncomingMessage method sends a response that echoes an incoming message to the originator address, and sends a copy of the response to a second address. To test the example, run two instances of the ColdFusion SMS client application. Use the default phone number of 5551212 for the first, and set the second one to have a phone number of 555-1235. (Notice that the second phone number requires a hyphen (-).) Send a message from the first simulator, and the response appears in both windows.

<cffunction name="onIncomingMessage" output="no"> 
    <cfargument name="CFEvent" type="struct" required="yes"> 
    <!--- Get the message. ---> 
<cfset data=CFEvent.DATA> 
<cfset message="#data.message#"> 
    <!--- Create the return structure. ---> 
    <cfset retValue = structNew()> 
    <cfset retValue.command = "submitmulti"> 
    <cfset retValue.sourceAddress = arguments.CFEVENT.gatewayid> 
    <cfset retValue.destAddresses=arraynew(1)> 
    <!--- One destination is incoming message originator;  
                    get the address from CFEvent originator ID. ---> 
    <cfset retValue.destAddresses[1] = arguments.CFEvent.originatorid> 
    <cfset retValue.destAddresses[2] = "555-1235"> 
    <cfset retValue.shortMessage = "echo: " & message> 
<cfreturn retValue> 
</cffunction> 
</cffunction>

The data command

To send binary data to a single destination address in an SMPP DATA_SM PDU, the Data parameter of a SendGatewayMessage function or the return variable of the CFC listener method must have the following fields:

Field

Contents

command

Must be "data" .

messagePayload

Message data. To convert data to binary format, use the ColdFusion toBinary function.

destAddress

Address to which to send the message.

sourceAddress

Address of this application; can be omitted if specified in the configuration file.

You can also set optional fields in the structure, such as a field that requests a delivery receipt. For a complete list of fields, see data command in the CFML Reference. For detailed descriptions of these fields, see the documentation for the SUBMIT_MULTI PDU in the SMPP3.4 specification, which you can download from the SMS Forum at www.smsforum.net/.

Example: Using the data command

The following example onIncomingMessage method converts an incoming message to binary data, and sends the binary version of the message back to the originator address:

<cffunction name="onIncomingMessage" output="no"> 
    <cfargument name="CFEvent" type="struct" required="yes"> 
    <!--- Get the message. ---> 
<cfset data=CFEvent.DATA> 
<cfset message="#data.message#"> 
    <!--- Create the return structure. ---> 
    <cfset retValue = structNew()> 
    <cfset retValue.command = "data"> 
    <!--- Sending to incoming message originator; get value from CFEvent. ---> 
    <cfset retValue.destAddress = arguments.CFEvent.originatorid> 
    <cfset retValue.messagePayload = tobinary(tobase64("echo: " & message))> 
    <cfreturn retValue> 
</cffunction>

Controlling SMS message sending and response

This documentation describes some of the more common options for sending messages, and how they affect your application. For information on other ways to configure outgoing message, see the SMPP specification.

Synchronization mode

You can specify asynchronous or synchronous message mode in the gateway configuration file.

  • If you specify asynchronous mode, the sendGatewayMessage function returns an empty string when the gateway submits the message to service code for sending to the SMSC. ColdFusion logs errors that occur after this point, such as if a message sent by the gateway to the SMSC times out or if the gateway gets an error response; the application does not get notified of any errors.

  • If you specify synchronous mode (the default), the sendGatewayMessage function does not return until the gateway gets a response from the SMSC or the attempt to communicate times out. If the message is sent successfully, the function returns the SMPP message ID string. If an error occurs, the function returns an error string.

Use synchronous mode if your application must determine whether its messages reach the SMSC. Also use synchronous mode if the application requests return receipts.

Note: If you use synchronous mode and the SMSC returns the messgeID as a hexadecimal string, ColdFusion converts it automatically to its decimal value.

The following example is an expansion of Example: Using the submit command in sendGatewayMessage function discussed in The submit command. It checks for a nonempty return value and displays the message number returned by the SMS. This example uses the SMS gateway that is configured when ColdFusion is installed. If you change the gateway specified in the SendGatewayMessage function, make sure that your gateway’s configuration file specifies synchronous mode.

<h3>Sending SMS From a Web Page Example</h3> 
 
<cfif IsDefined("form.oncethrough") is "Yes"> 
    <cfif IsDefined("form.SMSMessage") is True AND form.SMSMessage is not ""> 
         <h3>Sending a Text Message: </h3> 
            <cfoutput>#form.SMSMessage#</cfoutput><br><br> 
 
        <cfscript> 
            /* Create a structure that contains the message. */ 
            msg = structNew(); 
            msg.command = "submit"; 
            msg.destAddress = "5551234"; 
            msg.shortMessage = form.SMSMessage;     
            ret = sendGatewayMessage("SMS Menu App - 5551212", msg); 
        </cfscript> 
    </cfif> 
    <cfif isDefined("ret") AND ret NEQ ""> 
        <h3>Text message sent</h3> 
        <cfoutput>The Message Id is: #ret#</cfoutput> 
        <br><br> 
    </cfif>     
    <hr noshade> 
</cfif> 
 
<!--- begin by calling the cfform tag ---> 
<cfform> 
    SMS Text Message: <cfinput type="Text" name="SMSMessage"  
        value="Sample text Message" required="No" maxlength="160"> 
    <p><input type = "submit" name = "submit" value = "Submit"> 
    <input type = "hidden" name = "oncethrough" value = "Yes"> 
</cfform>

Optional parameters for outgoing SMS message

To set the optional parameters for outgoing text messages, you can specify parameters using the optionalparameter attribute.

Message disposition notification

You can request the SMSC to return a message disposition response to indicate the fate of your message. To request a delivery receipt, include a RegisteredDelivery field in the Data parameter of a SendGatewayMessage function or the return variable of the CFC listener method. This field can have the following values:

Value

Meaning

0

(Default) Do not return delivery information.

1

Return a receipt if the message is not delivered before the time-out.

2

Return a receipt if the message is delivered or fails.

Some providers also support intermediate delivery notifications. For more information, see your provider’s documentation.

To use delivery notification, send your message using synchronous mode, so you get a message ID. Your incoming message routine must be able to handle the receipts (see Handling incoming messages).

Validity period

You can change the length of time that the SMSC keeps a message and tries to deliver it. (Often the default value is 72 hours.) For a message sent to an emergency worker, for example, a short validity period (such as 15 min.) can be appropriate. To change this value, include a validityPeriod field in the Data parameter of a SendGatewayMessage function or the return variable of the CFC listener method. To specify a time period, use the following pattern: YYMMDDhhmmsst00R. In this pattern, t indicates tenths of seconds, and 00R specifies that this value is a relative time period, not a date-time value. The time format 000001063000000R, for example, specifies a validity period of 0 years, 0 months, 1 day, 6 hours, 30 minutes.