2-Way SMS Support

Automatic SMS Reply and More …

The “2-Way” configuration dialog contains settings relevant to the creation of 2-way applications that can receive SMS messages, and return a response based upon the content of the received SMS message.

The “Process Received SMS Messages” checkbox must be checked in order to enable the gateway to receive and process SMS messages.

When an SMS message is received, the gateway will evaluate the content of the message, and can either execute a program, or connect to an HTTP URL, based upon the content of the message. The decision of how to process a received message is based upon the first “word” of the received SMS message. In the terminology of the gateway, this first word of the received message is called the “SMS Command Prefix”. Based upon this “SMS Command Prefix”, the gateway will execute a command associated with the prefix. If the received prefix does not match any defined prefix, then it is considered to be a match for a special wildcard prefix, denoted as “*”.

The 2-way command processor also looks at the phone number to which the message is addressed, that is to say, the receiving (or recipient) phone number. For example, if the message was received by a GSM modem connected to the NowSMS server, the “Receive Phone Number” would be the phone number associated with that modem. This way different 2-way commands can be defined for processing messages that arrive via different SMSC connections.

When a command is executed based upon the receipt of an inbound message, the command line for the program or HTTP request can include replaceable parameters from the contents of the SMS message. The following replaceable parameters are supported:

@@SENDER@@ The phone number of the sender of the SMS Message.
@@SMSPREFIX@@ The first word of the SMS message.
@@SMS@@ The content of the SMS message, except the first word of the message.
@@FULLSMS@@ The complete content of the SMS message.
@@RECIP@@ If available, the phone number that is intended to receive (or did receive, if the message was received via a GSM modem connection) this message.
@@MESSAGEID@@ The local, NowSMS defined ID of the message file in the SMS-IN directory.
@@RECEIPTMESSAGEID@@ If this message is a delivery receipt, this is the message id of the originally sent message. Otherwise, this parameter is blank.
@@SERVICETYPE@@ If this message was received via SMPP, this will contain the service_type value associated with the message. Otherwise, this parameter is blank.
@@SMSCROUTE@@ Identifies the SMSC connection from which this message was received. This will either be the name of the SMSC connection (e.g., Bluetooth Modem or SMPP – a.b.c.d:xyz), or if the SMSC specific section of the SMSGW.INI has a RouteName= setting associated with the SMSC, this parameter will have the value of the RouteName= setting.
@@MSGDATE@@ Date on which the message was received by NowSMS in YYYYMMDD format.
@@MSGTIME@@ Time at which the message was received by NowSMS in HHMMSS format.
@@BINARY@@ Set to “1” if the message is in binary format, “0” otherwise. (Note: Binary messages will only be routed to a 2-way command if the “Command to Execute” is HTTP based, and @@BINARY@@ is present in the “Command to Execute” field.)
@@UDH@@ User Data Header of the received message. (Only for binary messages, see @@BINARY@@ parameter definition.)
@@PID@@ Protocol ID field (PID) of the received message. (Only for binary messages, see @@BINARY@@ parameter definition.)
@@DCS@@ Data Coding Scheme (DCS) of the received message. (Only for binary messages, see @@BINARY@@ parameter definition.)

To return results back to the user, the command can either return a simple text response directly to the gateway (“Command returns response text” is checked), or the command can generate a more complex response to the gateway via a separate HTTP request to the gateway. An executable program returns a simple text response to the gateway by printing results to the screen, where the gateway captures the screen output, and generates an SMS response to send the screen output text back to the sender via SMS. An HTTP request returns a simple text response to the gateway by returning content of the MIME type “text/plain”.

The example dialog above illustrates a simple command that can be used for testing this 2-way capability.

Define an “SMS Command Prefix” of “*” (wildcard), or any prefix of your choosing.

Define “Command to Execute” as “c:\windows\system32\cmd.exe /c echo Echo @@FULLSMS@@“.

Check “Command returns response text”.

Press “Add” to add the command to the “Received SMS Command Table”.

When an SMS is received that matches this SMS command prefix (in the case of “*”, any SMS that doesn’t match another defined prefix), the gateway launches a command processor (CMD) that simply echoes the text back to the screen adding the word “Echo” to the beginning of the received text. In this example, the sender of the SMS message will receive an “Echo” back of the command that they sent in to the gateway. While not an extremely useful command, this is a useful way of testing to see that the gateway is alive and capable of receiving SMS messages.

In addition to supporting the launch of command line programs, the “Command to Execute” field can also be an HTTP command, causing the gateway to connect via HTTP to another application server to inform the application server of details regarding the received message. For example, http://server:port/path?sender=@@SENDER@@&message=@@FULLSMS@@.

When an HTTP command is used, if the command is to return a response to the gateway directly, the HTTP response must be of the MIME content type “text/plain”.

It is also possible for any HTTP command to return an HTTP redirect response to the gateway, which instructs the gateway to fetch an alternative URL, even a URL command that contains parameters to tell the gateway to submit a message. This can be useful for creating a 2-way command script that responds with binary message content.

If an HTTP command requires HTTP authentication with a username and password, the URL format of “http://username:password@host.name/path” is supported. When a URL command is defined in this format, the gateway will connect to “http://host.name/path” using an authorization header of the specified username and password.

The “Command to Execute” field can also specify an e-mail address, in which case any received SMS messages that match the configured “SMS Command Prefix” will be forwarded to the specified e-mail address. To specify an e-mail address for the “Command to Execute”, use the format “mailto:user@domain.com”.

If the wildcard SMS command prefix is not associated with any command, any inbound SMS messages that do not match a prefix will be saved to the SMS-IN directory with a file extension of “.SMS”, and they may be processed by another application independent of the gateway.

Some troubleshooting tips for 2-way commands, as well as simple examples using PHP, ASP and Windows scripting can be found on the NowSMS discussion board at http://www.nowsms.com/discus/messages/1/4520.html.