2-Way Commands for SMS and MMS Processing (New 2014 Features)

Posted by on Jun 2, 2014 in Support Blog

Topic Keywords: , ,

The 2-Way command feature in NowSMS can be used to build automated SMS and MMS applications.  When an SMS or MMS message is received, NowSMS 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 program or script can perform actions based upon the message content, and optionally return a reply.

For the NowSMS 2014 release, we have made it easier for 2-Way commands to process both SMS and MMS messages.

Examples of tasks that might be implemented by a 2-way command include:

  • Database queries and updates
  • Processing an image or video submission
  • Keyword based retrieval of relevant content or images (for example real estate or product information)
  • Allowing end-users to sign up for mobile alert
  • Forwarding received messages to an email address

The “2-Way” configuration dialog contains settings relevant to the creation of 2-way applications.

2wayconfig1

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

The “Received SMS Command Table” lists all defined commands. Use the “Add” button to add a new 2-way command, or use the “Edit” or “Remove” buttons to manipulate a previously defined command.

The decision of how to process a received message is based upon the first word of the received SMS message, which is referred to as a “Keyword”. (Previous versions of NowSMS referred to this keyword as the “SMS Command Prefix”.) Based upon this keyword, NowSMS will execute a command associated with the keyword. If the received message does not match any defined keyword, then it is considered to be a match for a special wildcard keyword, denoted as *

2wayconfig2

2wayconfig22wayconfig3

The 2-way command processor also looks at the phone number to which the message is addressed, or in other words, 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. Or if connected to an SMS service provider, this may be a short code number associated with your service.  This way different 2-way commands can be defined for processing messages that arrive via different SMSC connections. The “Receive Phone Number” can be left blank if a command applies to all phone numbers.

One or more of the following actions can be taken to process the received message:

“Send Text Reply” – Use this option to send a simple automated response when the message is processed.

“Include Image with Reply” – Use this option to send a GIF, PNG or JPEG format image with the response. This will force the response to be sent out as an MMS message instead of as an SMS message.

“Forward To E-Mail Address” – Use this option to forward the received message to an e-mail address. Note that for this setting to work properly, e-mail settings must be configured. For more information on e-mail configuration, refer to http://www.nowsms.com/tag/e-mail.

“Add To Distribution List” – Use this option to cause the sender address to be added to the public distribution list specified.  (If the distribution list does not exist, it will be added when the first request is processed.)

“Remove From Distribution List” – Use this option to cause the sender address to be removed from the public distribution list specified.  (If the distribution list is empty after removal, it will be deleted.)

“Run HTTP or Local Command” – Use this option to run a local program (EXE) or connect to an HTTP URL to process the message content.

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.
Note: When SMS messages are received via a dedicated (non-Android) GSM modem, NowSMS preserves the SMSC time stamp, and returns this time value for the 2-way command place holders @@MSGDATE@@ and @@MSGTIME@@.
@@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 (“Reply to sender with command output” 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”.

An example 2-way command that runs a local VBScript that creates a log file of received messages can be found at http://www.nowsms.com/discus/messages/1/333.html.

To specify an HTTP command, the command should start with the prefix http:// … for example, http://server:port/path?sender=@@SENDER@@&message=@@FULLSMS@@.

NowSMS will issue an HTTP GET request using the variable names specified in the command definition. NowSMS can also use a standard URL encoded HTTP POST format. Specify httppost:// instead of http:// and the variables after the ? will be net using HTTP POST instead of HTTP GET.

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

Some useful examples can be found at http://www.nowsms.com/discus/messages/1/4520.html.

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

 

2-Way Commands and MMS

MMS messages are more difficult to process with 2-way commands, because they can contain image, video, or other additional content types.

NowSMS supports using an HTTP file upload format, where the entire MMS message content is posted to an application using HTTP POST.  A PHP script that demonstrates this interface can be found in the following article: Receiving MMS Messages with a PHP Script.

Based upon customer feedback, starting with the 2014.05.30 release of NowSMS, an additional option is available which allows MMS messages to be processed together with SMS messages using the same 2-way commands. This option is enabled when “Process Received MMS Messages” and “Use SMS 2-Way Commands” are both checked.

URL references to retrieve any images or other content objects will be added to the 2-way command automatically using variables AttachFile1, AttachFile2, AttachFile3, etc. The URL reference for the file attachment will contain a path only.

This is best explained with an example. Consider the following 2-way command:

http://nowsmslocal/php/log.php?sender=@@SENDER@@&text=@@FULLSMS@@

When an MMS message that includes an image is received, the resulting 2-way command will be similar to this:

http://nowsmslocal/php/log.php?sender=%2B447777777777&text=Test%20Message&AttachFile1=/SMSAttachFile/534E8AEE/IMG_6815.jpg

To retrieve this object, connect to the NowSMS web interface port, including the IP address or host name, such as:

http://127.0.0.1:8800/SMSAttachFile/534E8AEE/IMG_6815.jpg

If multiple files are attached, additional URL parameters will be added using the sequence AttachFile2, AttachFile3, etc.

 

Using PHP Scripts Without A Separate Web Server

PHP scripts are often used for 2-way SMS or MMS processing, providing a convenient mechanism for processing the received message content in an application, and optionally replying back to the received message, updating or querying a database, or taking other action upon the message which could involve sending one or more messages to other parties.

NowSMS interfaces with PHP scripts via an HTTP interface, which usually requires a separate HTTP web server with PHP installed. NowSMS also features the ability to interface locally with PHP without requiring a separate web server. More information on this capability can be found in the following article: http://www.nowsms.com/now-sms-native-php-scripts

For comments and further discussion, please click here to visit the NowSMS Technical Forums (Discussion Board)...