SMS gateway configuration

An SMS gateway, or SMS aggregator, is a third-party entity which is used to forward SMS notification messages to a destination mobile phone number. IBM Worklight routes the SMS notification messages through the SMS gateway.

To send SMS notifications from IBM Worklight, one or more SMS gateways must be configured in the SMSConfig.xml file, which is in the /server/conf folder of your project. To configure an SMS gateway, you must set the values of the following elements, subelements, and attributes in the SMSConfig.xml file. The Worklight Server must be restarted when any changes are made in the SMSConfig.xml file.

SMSConfig.xml elements and subelements

Element Element Value
gateway Mandatory. The <gateway> element is the root element of the SMS gateway definition. It includes 6 attributes:
  • hostname
  • id
  • port
  • programName
  • toParamName
  • textParamName

These attributes are described in Table 2

parameter Optional. The <parameter> subelement is dependent on the SMS gateway. Each SMS gateway may have its own set of parameters. The number of <parameter> subelements is dependent on SMS gateway-specific parameters. If an SMS gateway requires the user name and password to be set, then these parameters can be defined as <parameter> subelements. Each <parameter> subelement has the following attributes:

  • name
  • value

<gateway> element attributes

Attribute Attribute Value
hostname Mandatory. The host name of the configured SMS gateway.
id Mandatory. A unique ID that identifies the SMS gateway. Application developers specify the ID in the application descriptor file, application-descriptor.xml, when they develop an application.
port Optional. The port number of the SMS gateway. The default value is 80.
programName Optional. The name of the program that the SMS gateway expects. For example, if the SMS gateway expects the following URI:


...then programName="sendsms"

toParamName Optional. The name that is used by the SMS gateway to specify the destination mobile phone number. The default value is to. The destination mobile phone number is sent as a name-value pair when SMS notifications are sent; that is, toParamName=destination mobile phone number.
textParamName Optional. The name that is used by the SMS gateway to specify the SMS message text. The default value is text.

If the SMS gateway expects an HTTP post in the following format to forward SMS messages to a mobile device:

The SMSConfig.xml file is configured as follows:

<?xml version="1.0" encoding="UTF-8"?>

<sms:config xmlns:sms="" 

	<gateway hostname="myhost" 

		<parameter name = "username" value = "fcsuser" />
		<parameter name = "password" value = "fcspass" />



Parent topic IBM Worklight Server administration