SMS Distribution Lists with PHP

Posted by on May 16, 2011 in Support Blog

Topic Keywords: ,

An earlier post described the HTTP URL formats for working with NowSMS distribution lists.

This post provides some example PHP functions that can be used to simplify this process.  Now that NowSMS can support PHP scripts natively without a separate web server, it is even easier to prototype SMS applications with NowSMS.

In this example, we’ll use these example PHP functions to allow users to send an SMS message to the NowSMS server to add or remove themselves from a distribution list, and allow any member of a distribution list to send a message that is broadcast to all distribution list members.

This is intended as an example only, and a starting point for adding further logic.

nowsmsdlist.php is a PHP include file that contains functions for working with NowSMS distribution lists.  This file can be downloaded at the following link:  http://www.nowsms.com/examples/nowsmsdlist-php.txt.

The following function are defined in nowsmsdlist.php:

<?php

// NowSMSDListExists - Returns true if distribution list exists, otherwise false.

// Parameters:

//  $nowsmsIP - IP Address or host name of NowSMS server (127.0.0.1 for local host)

//  $nowsmsPort - Web interface port number of NowSMS server (8800 for default configuration)

//  $nowsmsUser & $nowsmsPassword - user name and password for account defined under "SMS Users"

//  $dlistName - Distribution list name



function NowSMSDListExists ($nowsmsIP, $nowsmsPort, $nowsmsUser, $nowsmsPassword, $dlistName) {



   $urlString = "http://" . $nowsmsIP . ":" . $nowsmsPort . "/DLists?";

   if (!is_null($nowsmsUser) && ($nowsmsUser != "")) {

      $urlString = $urlString . "User=" . urlencode($nowsmsUser) . "&Password=" . urlencode($nowsmsPassword) . "&";

   }

   $urlString = $urlString . "DListAction=List&DListName=" . urlencode($dlistName);

   $response = file_get_contents($urlString);

   if (!strncasecmp ($response, "OK", 2)) return true;

   else return false;



}



// NowSMSDListCheckMember - Returns true if member of distribution list, otherwise false.

// Parameters:

//  $nowsmsIP - IP Address or host name of NowSMS server (127.0.0.1 for local host)

//  $nowsmsPort - Web interface port number of NowSMS server (8800 for default configuration)

//  $nowsmsUser & $nowsmsPassword - user name and password for account defined under "SMS Users"

//  $dlistName - Distribution list name

//  $dlistMember - Distribution list member phone number



function NowSMSDListCheckMember ($nowsmsIP, $nowsmsPort, $nowsmsUser, $nowsmsPassword, $dlistName, $dlistMember) {



   $urlString = "http://" . $nowsmsIP . ":" . $nowsmsPort . "/DLists?";

   if (!is_null($nowsmsUser) && ($nowsmsUser != "")) {

      $urlString = $urlString . "User=" . urlencode($nowsmsUser) . "&Password=" . urlencode($nowsmsPassword) . "&";

   }

   $urlString = $urlString . "DListAction=List&DListName=" . urlencode($dlistName);

   $response = file_get_contents($urlString);



   $memberArray = explode("\r\n",$response); 



   for ($i = 1; $i < count($memberArray); $i++) {

      $idxDash = strpos ($memberArray[$i], " -");

      if ($idxDash !== false) {

         $memberArray[$i] = substr ($memberArray[$i], 0, $idxDash);

      }

      if (!strcasecmp ($memberArray[$i], $dlistMember)) return true;

   }



   return false;



}



// NowSMSDListAddMember - Add member to distribution list

// Parameters:

//  $nowsmsIP - IP Address or host name of NowSMS server (127.0.0.1 for local host)

//  $nowsmsPort - Web interface port number of NowSMS server (8800 for default configuration)

//  $nowsmsUser & $nowsmsPassword - user name and password for account defined under "SMS Users"

//  $dlistName - Distribution list name

//  $dlistMember - Distribution list member phone number



function NowSMSDListAddMember ($nowsmsIP, $nowsmsPort, $nowsmsUser, $nowsmsPassword, $dlistName, $dlistMember) {



   $urlString = "http://" . $nowsmsIP . ":" . $nowsmsPort . "/DLists?";

   if (!is_null($nowsmsUser) && ($nowsmsUser != "")) {

      $urlString = $urlString . "User=" . urlencode($nowsmsUser) . "&Password=" . urlencode($nowsmsPassword) . "&";

   }

   $urlString = $urlString . "DListMemberAction=Add&DListName=" . urlencode($dlistName) . "&DListMember=" . urlencode($dlistMember);

   $response = file_get_contents($urlString);



}



// NowSMSDListDeleteMember - Delete member from distribution list

// Parameters:

//  $nowsmsIP - IP Address or host name of NowSMS server (127.0.0.1 for local host)

//  $nowsmsPort - Web interface port number of NowSMS server (8800 for default configuration)

//  $nowsmsUser & $nowsmsPassword - user name and password for account defined under "SMS Users"

//  $dlistName - Distribution list name

//  $dlistMember - Distribution list member phone number



function NowSMSDListDeleteMember ($nowsmsIP, $nowsmsPort, $nowsmsUser, $nowsmsPassword, $dlistName, $dlistMember) {



   $urlString = "http://" . $nowsmsIP . ":" . $nowsmsPort . "/DLists?";

   if (!is_null($nowsmsUser) && ($nowsmsUser != "")) {

      $urlString = $urlString . "User=" . urlencode($nowsmsUser) . "&Password=" . urlencode($nowsmsPassword) . "&";

   }

   $urlString = $urlString . "DListMemberAction=Delete&DListName=" . urlencode($dlistName) . "&DListMember=" . urlencode($dlistMember);

   $response = file_get_contents($urlString);



}



// NowSMSDListDeleteMemberAllLists - Scan all distribution lists and remove member

// Parameters:

//  $nowsmsIP - IP Address or host name of NowSMS server (127.0.0.1 for local host)

//  $nowsmsPort - Web interface port number of NowSMS server (8800 for default configuration)

//  $nowsmsUser & $nowsmsPassword - user name and password for account defined under "SMS Users"

//  $dlistMember - Distribution list member phone number



function NowSMSDListDeleteMemberAllLists ($nowsmsIP, $nowsmsPort, $nowsmsUser, $nowsmsPassword, $dlistMember) {



   $urlString = "http://" . $nowsmsIP . ":" . $nowsmsPort . "/DLists?";

   if (!is_null($nowsmsUser) && ($nowsmsUser != "")) {

      $urlString = $urlString . "User=" . urlencode($nowsmsUser) . "&Password=" . urlencode($nowsmsPassword) . "&";

   }

   $urlString = $urlString . "DListAction=List";

   $response = file_get_contents($urlString);



   $dlistArray = explode("\r\n",$response); 



   // Loop through all distribution lists and remove member

   for ($i = 0; $i < count($dlistArray); $i++) {

      if ($dlistArray[$i] != "") {

         if (NowSMSDListCheckMember ($nowsmsIP, $nowsmsPort, $nowsmsUser, $nowsmsPassword, $dlistArray[$i], $dlistMember)) {

            NowSMSDListDeleteMember ($nowsmsIP, $nowsmsPort, $nowsmsUser, $nowsmsPassword, $dlistArray[$i], $dlistMember);

         }

      }

   }



}



// NowSMSDListSendSMS - Send an SMS text message to a distribution list

// Parameters:

//  $nowsmsIP - IP Address or host name of NowSMS server (127.0.0.1 for local host)

//  $nowsmsPort - Web interface port number of NowSMS server (8800 for default configuration)

//  $nowsmsUser & $nowsmsPassword - user name and password for account defined under "SMS Users"

//  $dlistName - Distribution list name



function NowSMSDListSendSMS ($nowsmsIP, $nowsmsPort, $nowsmsUser, $nowsmsPassword, $dlistName, $smsText) {



   $urlString = "http://" . $nowsmsIP . ":" . $nowsmsPort . "/?";

   if (!is_null($nowsmsUser) && ($nowsmsUser != "")) {

      $urlString = $urlString . "User=" . urlencode($nowsmsUser) . "&Password=" . urlencode($nowsmsPassword) . "&";

   }

   $urlString = $urlString . "PhoneNumber=" . urlencode($dlistName) . "&Text=" . urlencode($smsText);

   $response = file_get_contents($urlString);

   if (strpos ($response, "MessageID=") === false) return false;

   else return true;



}

?>
dlist-example.php is an example implementation of a 2-way command that uses these functions.  This example is intended to show how these PHP functions can be used.  This example is available at the following link:  http://www.nowsms.com/examples/dlist-example-php.txt

This example supports receiving the following commands via SMS:

“JOIN dlistname” or “START dlistname” to join a distribution list

“STOP dlistname” or “LEAVE dlistname” to be removed from a distribution list.

“STOP” by itself will remove the user from all distribution lists.

“SEND dlistname” followed by some text allows any member of the distribution list to broadcast a message to the entire list.

<?php



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



// dlist-example.php - This is an example to describe PHP functions for adding and deleting members from an SMS distribution list.

//

// Expected 2-way command format:  http://server/dlist-example.php?sender=@@SENDER@@&text=@@FULLSMS@@

//

// This example supports receiving the following commands via SMS:

//   "JOIN dlistname" or "START dlistname" to join a distribution list

//   "STOP dlistname" or "LEAVE dlistname" to be removed from a distribution list.

//   "STOP" by itself will remove the user from all distribution lists.

//   "SEND dlistname " allows any member of the distribution list to broadcast a message to the entire list.



$nowsmsIP = "127.0.0.1";

$nowsmsPort = "8800";

$nowsmsUser = "test";

$nowsmsPassword = "test";



require_once "nowsmsdlist.php";   // PHP function file that contains functions for working with NowSMS distribution lists



/* Performs explode() on a string with the given delimiter and trims all whitespace for the elements */

function explode_trim($str, $delimiter = ',') {

    if ( is_string($delimiter) ) {

        $str = trim(preg_replace('|\\s*(?:' . preg_quote($delimiter) . ')\\s*|', $delimiter, $str));

        return explode($delimiter, $str);

    }

    return $str;

} 



// Check for required URL parameters, sender and text

// Expected 2-way command format:  http://server/dlist.php?sender=@@SENDER@@&text=@@FULLSMS@@



if (!isset($_REQUEST['sender'])) {

echo "ERROR : 'sender' parameter missing!\r\n";

exit();

}



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

echo "ERROR : 'text' parameter missing\r\n";

exit();

} 



$array = explode_trim($_REQUEST['text'],' '); 



// If a list name was not specified, set array with blank value

if (count($array) < 2) $array[1] = "";



if (!strcasecmp($array[0],"JOIN") || !strcasecmp($array[0],"START")) {

   // Check if distribution list exists

   if (NowSMSDListExists ($nowsmsIP, $nowsmsPort, $nowsmsUser, $nowsmsPassword, $array[1])) {

      // Distribution list exists, check if sender is already a member

      if (NowSMSDListCheckMember ($nowsmsIP, $nowsmsPort, $nowsmsUser, $nowsmsPassword, $array[1], $_REQUEST['sender'])) {

         echo "You have already joined list " . $array[1] . ".  Reply STOP " . $array[1] . " to leave.";

      }

      else {

         // Add member to distribution list

         NowSMSDListAddMember ($nowsmsIP, $nowsmsPort, $nowsmsUser, $nowsmsPassword, $array[1], $_REQUEST['sender']);

         // Verify that member was added to distribution list

         if (NowSMSDListCheckMember ($nowsmsIP, $nowsmsPort, $nowsmsUser, $nowsmsPassword, $array[1], $_REQUEST['sender'])) {

            echo "You have joined list " . $array[1] . ".  Reply STOP " . $array[1] . " to leave.";

         }

         else {

            echo "An error occurred attempting to join list " . $array[1];

         }

      }

   }

   else {

      echo "List " . $array[1] . " does not exist.";

   }

}

else if (!strcasecmp($array[0],"LEAVE") || !strcasecmp($array[0],"STOP")) {

   // If a list name was not specified, remove from all lists.

   if ($array[1] == "") {

      NowSMSDListDeleteMemberAllLists ($nowsmsIP, $nowsmsPort, $nowsmsUser, $nowsmsPassword, $_REQUEST['sender']);

      echo "You have been removed from all lists";

   }

   // Check if distribution list exists

   else if (NowSMSDListExists ($nowsmsIP, $nowsmsPort, $nowsmsUser, $nowsmsPassword, $array[1])) {

      // Distribution list exists, check if sender is a member

      if (NowSMSDListCheckMember ($nowsmsIP, $nowsmsPort, $nowsmsUser, $nowsmsPassword, $array[1], $_REQUEST['sender'])) {

         // Remove member from distribution list

         NowSMSDListDeleteMember ($nowsmsIP, $nowsmsPort, $nowsmsUser, $nowsmsPassword, $array[1], $_REQUEST['sender']);

         // Verify that member was removed

         if (!NowSMSDListCheckMember ($nowsmsIP, $nowsmsPort, $nowsmsUser, $nowsmsPassword, $array[1], $_REQUEST['sender'])) {

            echo "You are no longer subscribed to list " . $array[1] . ".";

         }

         else {

            echo "An error occurred attempting to leave list " . $array[1];

         }

      }

      else {

         echo "You are not subscribed to list " . $array[1] . ".";

      }

   }

   else {

      echo "List " . $array[1] . " does not exist.";

   }

}

else if (!strcasecmp($array[0],"SEND")) {

   // Check if distribution list exists

   if (NowSMSDListExists ($nowsmsIP, $nowsmsPort, $nowsmsUser, $nowsmsPassword, $array[1])) {

      // Distribution list exists, check if sender is already a member

      if (NowSMSDListCheckMember ($nowsmsIP, $nowsmsPort, $nowsmsUser, $nowsmsPassword, $array[1], $_REQUEST['sender'])) {

         $smsText = $array[1] . ":" . $_REQUEST['sender'];

         for ($i = 2; $i < count($array); $i++) {

            $smsText = $smsText . " " . $array[$i];

         }

         if (NowSMSDListSendSMS ($nowsmsIP, $nowsmsPort, $nowsmsUser, $nowsmsPassword, $array[1], $smsText)) {

            echo "Message sent";

         }

         else echo "Error sending message";

      }

      else echo "You are not subscribed to list " . $array[i] . ".";

   }

   else echo "Unknown list " . $array[i] . ".";



}

else {

   echo "Unknown request " . $array[0];

}



?>

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