Configuring an SMS event gateway

You provide SMS-specific configuration information to the SMS event gateway in a configuration file. You specify the configuration file location when you configure the SMS event gateway instance in the ColdFusion Administrator. ColdFusion provides a sample SMS event gateway configuration file in cf_root\WEB-INF\cfusion\gateway\config\sms-test.cfg on J2EE configurations, and cf_root\gateway\config\sms-test.cfg on server configurations. The following table describes the configuration file contents.

Note: The following configuration information describes the configuration fields, but does not include detailed explanations of SMPP-specific terminology, listings of all valid values of properties that are defined in the SMPP specification, or explanations of how to select appropriate SMPP-specific values for your application. For further information, see documentation on the SMPP 3.4 protocol at www.smsforum.net/ and other publicly available documentation. Your SMS service provider generally specifies requirements for several of these configuration values. Consult the provider documentation.

Property

Default

Description

ip-address

 

IP address of the SMSC, as specified by the SMPP provider. For the ColdFusion SMS test server, you normally use 127.0.0.1.

port

0

Port number to bind to on the SMSC. The ColdFusion SMS test server uses port 7901.

system-id

 

Name that identifies the event gateway to the SMSC, as established with the SMPP provider. To connect to the ColdFusion SMS test server, the system-id must be cf.

password

 

Password for authenticating the event gateway to the SMSC. To connect to the ColdFusion SMS test server, the password must be cf.

source-ton

1

Type of Number (TON) of the source address, that is, of the address that the event gateway uses for outgoing messages, as specified in the SMPP specification. Values include 0, unknown; 1, international number; 2, national number.

source-npi

1

Numeric Plan Indicator (NPI) of the source address as specified in the SMPP specification. Values include 0, unknown; 1, ISDN.

source-address

empty string

Address (normally, a phone number) of the event gateway. Identifies the sender of outgoing messages to the SMSC.

addr-ton

1

TON for the incoming addresses that this event gateway serves.

addr-npi

1

NPI for the incoming addresses that this event gateway serves.

address-range

 

The range of incoming addresses (phone numbers) that remote devices can use to send messages to the event gateway instance; often, the same as the source-address.

message-rate

100

Integer or decimal value that specifies the number of messages the gateway is allowed to send to your service provider per second. 0 is unlimited.

mode

synchronous

Message transmission mode:

  • synchronous The gateway waits for the response from the server when sending a message. In this mode, the SendGatewayMessage CFML function returns the SMS messageID of the message, or an empty string if an error occurs.

  • asynchronous The gateway does not wait for a response. In this mode, the SendGatewayMessage CFML function always returns an empty string.

network-retry

no

Gateway behavior when a network error occurs while trying to deliver a message:

  • yes The gateway queues the message for delivery when the gateway is able to rebind to the SMSC. Retrying is useful if the gateway is in asynchronous mode, where the CFML SendGatewayMessage function does not return an error.

  • no The gateway does not retry sending the message.

transient-retry

no

Gateway behavior when the SMSC returns an error that indicates a transient error, where it may be able to accept the message in the future:

  • yes The gateway attempts to resend the message. Retrying is useful if the gateway is in asynchronous mode, where the CFML SendGatewayMessage function does not return an error.

  • no The gateway does not retry sending the message.

cfc-method

onIncomingMessage

Listener CFC method for ColdFusion to invoke when the gateway gets incoming messages.

destination-ton

1

Default TON of addresses for outgoing messages.

destination-npi

1

Default NPI of addresses for outgoing messages.

service-type

empty string

Type of messaging service; can be empty or one of the following values: CMT, CPT, VMN, VMA, WAP, or USSD.

system-type

empty string

Type of system (ESME, External Short Message Entity ); used when binding to the SMSC. Some SMSCs might be able to send responses that are specific to a given type of ESME. Normally set to SMPP.

receive-timeout

-1 (do not time out)

The time-out, in seconds, for trying to receive a message from the SMSC after it establishes a connection. To wait indefinitely until a message is received, set the receive-timeout to -1.

ping-interval

60

Number of seconds between EnquireLink messages that the event gateway sends to the server to verify the health of the connection.

retries

-1 (try forever)

Number of times to retry connecting to the SMSC to send a message before the gateway goes into a failed state. If the gateway is in a failed state, the getStatus method returns FAILED, and theColdFusion Administrator shows the gateway status as Failed. The gateway must be restarted before it can be used.

retry-interval

10

Number of seconds between connection retries.

You can also set the following values in each outgoing message: source-ton, source-npi, source-address, destination-ton, destination-npi, and service-type. The message field names differ from the configuration file property names.