Topic Keywords: 2-way MMS, 2-way SMS, PHP

PHP scripts are a great tool for integrating NowSMS into another application environment, or extending the functionality of NowSMS.

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.

PHP scripts are also frequently used to implement accounting or routing callbacks. Accounting callbacks can be used to record messaging activity, and to integrate with external billing or accounting systems. These accounting callbacks also support the ability to block messaging activity when external billing criteria indicates that a message operation should be be allowed. Routing callbacks can be used to provide additional control for selecting the outbound route to be used for message delivery, such as interfacing into mobile number portability databases or HLR lookups.

NowSMS interfaces with PHP scripts via an HTTP interface, which has historically required a separate HTTP web server with PHP installed. By using an HTTP interface, NowSMS can integrate with other web based scripting languages and environments, including ASP, ASP.Net, Java and Perl.

The separate web server requirement can make it more difficult to develop 2-way command scripts or accounting callbacks, especially when prototyping an application.

Beginning with the 2011.04.19 version of NowSMS (currently in test release at https://nowsms.com/download/nowsms20110419.zip), NowSMS supports the ability to interface with a locally installed copy of PHP, without requiring a separate web server to manage PHP callbacks.

To enable this support, it is necessary to first install PHP on the PC that is running NowSMS by following these steps:

1.) Download and run the Windows installer for PHP at http://windows.php.net/download/.  We recommend using a thread safe version of the current build (5.3.6 at the time this article was written).

2.) When the PHP installer displays its “Web Server Setup” selection screen, be sure to select “Other CGI”.

3.) The default PHP installation does not include many popular PHP libraries and extensions.  You may want to consider installing other “Extensions” and “Extras”.  At a minimum, we recommend installing PEAR, which is listed under “Extras”.   (In particular, the mail functions built into PHP are extremely limited, and the PEAR Mail Package is frequently used for sending e-mails from PHP scripts.)

4.) After PHP has been installed, let’s continue and install PEAR and the PEAR Mail package.  Open a Command Prompt window by right clicking on “Command Prompt” (usually under Programs/Accessories) and selecting “Run as Administrator”.  Once the Command Prompt window is open, change to the directory in which PHP was installed.

5.) To install PEAR, type go-pear and press Enter.  Unless you are an expert at installing and configuring PEAR, accept all of the defaults presented by the installation routine by pressing Enter each time prompted.

6.) To install the PEAR Mail Package, from that same command prompt window, type:

 pear install Mail

7.) Mail requires an additional PEAR package to function properly: Net_SMTP.  To install the PEAR Net_SMTP Package, from that same command prompt window, type:

 pear install Net_SMTP

8.) PHP installation is complete.  Now it is necessary to configure NowSMS to use the locally installed copy of PHP.  In the NowSMS configuration, go to the “2-Way” page, and select “Enable Local PHP Processing”.

NowSMS interfaces with php-cgi.exe, which should have been installed by the PHP installation program.  When “Enable Local PHP Processing” is first checked, NowSMS will verify that it can locate php-cgi.exe.  If it cannot locate this file, an error message will be displayed.

You are now ready to create your first PHP script.

What You Need To Know About NowSMS and Local PHP Scripts

The “2-Way” command page displays the directory location of the directory that should contain any local PHP scripts, as shown above, where it displays “http://nowsmslocal/php resolves to C:\ProgramData\NowSMS\PHP\”.

This indicates that PHP scripts need to be placed in the C:\ProgramData\NowSMS\PHP directory.  It is possible to change this directory by editing SMSGW.INI, and under the [SMSGW] header, adding PHPDir=c:\path

If, after adding a PHPDir= configuration parameter, the “2-Way” page does not update to the new location, uncheck “Enable Local PHP Process”, and then recheck this setting.

When defining a 2-way command (or accounting callback) that points to a local PHP script, the script URL should start with http://nowsmslocal/php (example for a script named echo.php: http://nowsmslocal/php/echo.php&sender=@@SENDER@@&text=@@FULLSMS@@).

It is also possible to access these PHP scripts from a web browser installed on the same machine by referencing the script via the local loopback address, http://localhost:8800/php or http://127.0.0.1:8800/php (assuming that the NowSMS web interface is running on port 8800, otherwise change this port number).  By default, PHP scripts can only be accessed locally.  If access required from other systems, check “Allow External Web Access to PHP Scripts”.  When “Allow External Web Access to PHP Scripts” is enabled, the scripts will be accessible to any system that can access the NowSMS web interface (i.e., the “Allowed/Blocked” list on the “Web” configuration dialog).

Let’s start with a simple 2-way command example.

echo.php is a simple PHP script that parses the text of a received message, and replies back with the same text:

<?php

header ("Content-Type: text/plain");

if (isset($_REQUEST['text'])) {

   $text = $_REQUEST['text'];

   echo $text;

}

else {

   echo "Invalid request, text= parameter expected.";

}

?>

This simple example provides a good starting point for building more complex 2-way commands.

Cut and paste the above script into a file named echo.php in your NowSMS PHP directory.

From a web browser on the same machine, access http://127.0.0.1:8800/php/echo.php.  A text page should be returned that says “Invalid request, text= parameter expected.”  This indicates that local PHP support is fully configured and operational.

Now let’s configure NowSMS to execute this command every time it receives an SMS message, sending an echo response back to the sender.

Before continuing, ensure that “Process received SMS Messages” is checked.

In the “SMS Command Prefix” field, enter a single asterisk character: *  This character is a wildcard, indicating that the command will match all received messages.  If you want to use this test script for a particular keyword match only (such as “echo”), then enter that keyword instead of *.

The “Receive Phone Number” field can be left blank for the purposes of this test.

“Command to Execute” should be http://nowsmslocal/php/echo.php?text=@@TEXT@@&sender=@@SENDER@@

This particular command returns its response directly in the script, so “Command returns response text” should also be checked.

Press “Add” to add the command to the table, and “Apply” to save changes.  Restart the NowSMS service.

The simple version of the echo.php script only checks the “text=” parameter, which is accessible in the script as $_REQUEST[‘text’].

Try sending an SMS message in to the script. If the “SMS Received” counter on the “Service” page of the NowSMS configuration dialog is not showing an increase in received messages, your messages are not making it as far as NowSMS.  There are some helpful troubleshooting tips for this situation in a post on the NowSMS discussion board at https://nowsms.com/discus/messages/1/4520.html.

Note that it is very dangerous to implement a script that blindly replies back to all received messages, as it is possible to get stuck in an infinite reply loop with other SMS robots.  It is advisable that you include logic in your script to limit replies, especially error replies.  Also, beware of loops where you accidentally send an SMS message from your modem to itself.  You can include a check at the beginning of a PHP script to guard against sending to yourself by checking the number from which the message was received, and make sure it does not match the sending number:

if (!strcmp($_REQUEST[‘sender’],”+447777777777″)) { return; }

This is a real simple example intended to help you get started.

Instead of replying back to the SMS message, your script can issue new requests back to NowSMS to send messages (see Send SMS from PHP Script and Send MMS Message from PHP Script for these examples).  Or your PHP script could query and/or update a database.  There are many possibilities.

Additional NowSMS PHP examples and information are available at the following links:

https://nowsms.com/faq/api

https://nowsms.com/tag/php

Additional resources for general PHP API information include:

http://www.php.net/

http://pear.php.net/