This section 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 message is submitted by the gateway to service code for sending to the SMSC. ColdFusion logs errors that might 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.

The following example is an expansion of Example: Using the submit command in sendGatewayMessage function. 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 you 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>

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:

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

To use delivery notification, you must 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, you might want to specify a very short validity period (such as 15 minutes). 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 is a relative time period, not a date-time value. The time format 00001063000000R, for example, specifies a validity period of 0 years, 0 months, 1 day, 6 hours, 30 minutes.