Two-way SMS communication

improve this page | report issue


Two-way SMS communication enables communication between mobile phones and the IBM MobileFirst Server over an SMS channel. Mobile-originated SMS messages can be sent to the MobileFirst Server via the SMS gateway and the MobileFirst Server can send a response back.
Short codes or keywords are configured with an SMS gateway from an independent software vendor. The gateway must be configured to forward the requests to MobileFirst Server or to a reverse proxy URL, depending on the topology in your environment.
The SMS messages that are sent from mobile devices are forwarded to an adapter procedure on the MobileFirst Server side, as configured by the developer.
The adapter procedure includes the logic to process the request, or the procedure can forward the request to a back end for processing. The response is sent back through the MobileFirst notification framework.

Topics covered, are:

Device support

IBM MobileFirst Platform Foundation supports two-way SMS communication on any mobile devices that support SMS functions.



An adapter registers SMS event handlers on the MobileFirst Server. The event handler registration specifies what
adapter procedure callback is called.

SMS messages are sent from mobile devices to the SMS gateway, which is configured with a MobileFirst project. The gateway details are specified in SMSConfig.xml, in the MobileFirst project.

The SMS gateway forwards SMS messages to the configured MobileFirst URL. Configure the SMS gateway with the keyword and the MobileFirst Server URL to which it must forward the messages. For more information, refer to the specification of your gateway.

An SMS servlet on the MobileFirst Server matches the parameters with filters as defined in SMS event handlers, and calls the adapter procedure callback.

The adapter can process SMS messages and send them to a mobile device by using the SMS API. An adapter procedure can use the SMS server -side APIs for subscription and unsubscription. The procedure uses the SMS notification framework to send the response back to the mobile device.

API for two-way SMS

    Registering SMS event handlers

                            		{keyword: WL.Server.configuration['sms.keyword.subscribe']},
                            		{keyword: WL.Server.configuration['sms.keyword.unsubscribe']},
                            		unsubscribeSMS, WL.Server.configuration['']
The name-value parameters sent from the SMS gateway that match the filters are passed to handlerFunction. For example, if the SMS gateway is sending the following parameters:

  • from: from number
  • text: SMS text
  • keyword: a keyword configured in the SMS gateway

The filterparameter can be defined as {keyword:"myKey"}. In this case, when the MobileFirst Server receives a request from the SMS gateway, it looks for a keyword with myKeyas its value, and forwards the resulting request to handlerFunction.

handlerFunctionreceives an SMS event that has all parameters sent from the SMS gateway.

gatewayIDcorresponds to the SMS gateway that is configured in SMSConfig.xml. This gateway is used to receive SMS messages.

    Server-side SMS API

The MobileFirst Server uses SMS notification to send SMS messages. Before SMS messages can be sent, the server must subscribe to a phone number.

var subscription = WL.Server.subscribeSMS(eventSourceID, phoneNumber, gatewayID);
This method takes the following parameters:

  • eventSourceId:the event source to which the phone number is subscribing.
  • phoneNumber:the user’s phone number
  • gatewayID:the ID that identifies the gateway through which SMS messages are sent.

The method returns an SMS subscription object. Along with the WL.Server.notifyDeviceSubscriptionmethod, this object can be used to send an SMS message to the specified phone number.

If the phone number is already subscribed, get the subscription object and send an SMS message.

function sendSMS(phoneNumber, smsText) {
var subscription = WL.Server.getSMSSubscription(eventSourceId, phoneNumber);
if (subscription == null) {
		return { result: "No subscription found for user :: " + phoneNumber };
	var notification = WL.Server.createDefaultNotification(smsText, 1, {});
	WL.Server.notifyDeviceSubscription(subscription, notification);
	return { result: "Notification sent to user :: " + phoneNumber };
}<br />

A phone number can unsubscribe from the event source by a call to the following method:
WL.Server.unsubscribeSMS(eventSourceID, phoneNumber);


The SMSConfig.xmlfile specifies gateway details for both receiving and sending SMS messages.

<gateway id="myGateway" hostname="" port="80" programName="backendProgram" toParamName="to" textParamName="text" fromParamName="from">
    <parameter encode="false" name="param1name" value="param1value"/>
    <parameter encode="false" name="param2name" value="param2value"/>

You can externalize the keywords, gateway identifier, and other parameters that the SMS event handler uses to the configuration file.


By default, the SubscribeServletobject that receives the request from the gateway is protected by a security test. This security test takes a RejectingLoginModuleparameter which by default rejects any request. To enforce the security mechanism that is supported by your gateway, comment out or modify the default security test.

<br />
<resource id="subscribeServlet" securityTest="SubscribeServlet">

If you are using a reverse proxy in front of the MobileFirst Server, you can specify a mapping to the reverse proxy to allow only requests from specific hosts or IP addresses (SMS gateway). If the application server that is running MobileFirst directly receives the request from a gateway, the application server needs to be configured to allow requests from the specific hosts or IP addresses.

Run the sample

    1. A user subscribes for SMS notifications by sending the keyword subfrom his mobile device to the predefined short code or phone number that is registered with a gateway from an independent software vendor.
    2. The BookStoreAdapteradapter subscribes the phone number to receive notifications.
    3. The BookStoreAdapteradapter sends a notification to the user when there is a discount offer.
    4. The user can unsubscribe for SMS notifications by sending the unsubkeyword to the predefined short code or phone number.
Last modified on November 09, 2016