Using our short code and gateway APIs to create a game

The Concept

To create an interactive game using Text Messaging and to show how easy it is to create interactive experiences using your Text Marketer Account. The example uses both our short code API (to receive the customer responses) and then our  gateway API to send out the ‘answer’.

The Game

Guess the number of sweets in a jar. A simple game where the participant texts in the number of sweets they think is in the jar and then receives a message indicating if they are high,  low , close or have correctly guessed to the number of sweets. Download all the required classes.

Mechanics

Fig 1 shows the how the basic flow of the systems works. The game is initiated by an incoming text message (as shown in orange) to our 88802 shortcode. The text message contains a keyword  in this case sweets and the data you which you need to parse.

Once the text message has been received in your account you can enable a trigger to be sent to your own script residing on your own server. The trigger is a GET request with the parameters added to it as per our short code documentation.

Your application/script can then use the data to geenrate a response. In our case we find out whether the participant has guessed the correct number and we send back an apporprate response using the Text Marketer API  Gateway see documentation for details.

Creating the game and code examples

The Guess number of sweets in a jar game and all the code you need can be downloaded here. It’s written in PHP 5.

Once you have created yourself a free account you need to request a free shortcode keyword from Text Marketer.

Next login into your account and set the url your wish to use for accessing your script. To access the set up screen, select from the menu “Incoming SMS” => “Change Reply Settings” then click “Configure” next to the keyword. You’ll then be able to paste the URL into the API URL window. Then press submit.

 

The game is broken the code down into 4 classes.

Class Name	Purpose
SweetsInAJar	The entry point class
ExtractData	Parse the incoming data & extract the result
MessageLogic	Game logic and associated response
SendSMSXML	The SMS send class

class SweetsInAJar

{

    function __construct()

    {

    $sms = new SendSMSXML("myUsername","myPassword");

    $theData = new ExtractData("sweets",$_GET['message'],$_GET['number']);

    $logic = new MessageLogic();

    $logic->setClosenessRangeInPercent(15);

    if($theData->isValid()){

       $sms->send($theData->getNumber(),$logic->getMessage($theData->getData()),"GuessGame");

    }

    else

    {

       $sms->send($theData->getNumber(),$logic->getFailedMessage(),"GuessGame");

     }

   }

}

Explanation
This is our main class that calls all the relevant objects and class together. Simply the logic works like this:

1. Set up all the objects you need.
2. Set the closeness to the number of sweets you will need to get before the “your are close” message will get sent .
3. If there is data we can use from the incoming message,  select the correct response and send it.
4. Otherwise select the “invalid format message” and send that.

class ExtractData

{
   private $theData;
   private $theMobileNumber;
   private $keyword;
   private $valid=false;
	

   function __construct($keyword,$message,$number)
   {
      $this->keyword = $keyword;
      $this->valid = $this->getMessageInfo($message);
      $this->theMobileNumber = $number;
    }

    public function isValid()

    {		

       return $this->valid;

     }

     public function getData()

     {

       return $this->theData;

     }

      public function getNumber()
      {
        return $this->theMobileNumber;
      }

      private function getMessageInfo($m)
      {
         //remove the keyword and set the result
	 //remove extra spaces
         $m=trim($m);

         $m=str_ireplace($this->keyword,"",$m); /// remove keyword
         $m=ltrim($m); // remove any spaces

         if(is_numeric($m)) {

              $this->theData = $m;
              return true; // is it data?
          }

           else return false;
      }

}

Explanation
This simple class allows us to extract the data we need from the short code response. The response contains the enitre message so we need to remove the keyword and any spaces then check to see if the result is a number.  If it is then the object is “valid” else it’s not valid and we can use this state to send the “invalid format message” as described above.

class MessageLogic

{

    private static $lowGuess ="Bad Luck! There are more sweets in the jar than you think, try again.";
    private static $highGuess="Bad Luck! There are less sweets in the jar than you think, try again.";
    private static $correctGuess="Well done! You have guessed the correct amount.";
    private static $closeGuess="Close Guess! you are within {value}% of the correct answer.";
    private static $badData="We couldn't understand your answer please text in the word SWEETS and your answer, for example SWEETS 300";
    private $numSweets=5678; //default
    private $closenessRange=5;  //5 percent as default 

	
    public function setNumberOfSweets($value)

    {
         $this->numSweets=$value;
    }

    public function setClosenessRangeInPercent($value) //in percent
    {
         $this->closenessRange=$value;
    }

    public function getFailedMessage()

    {
         return self::$badData;
    }

    public  function getMessage($value)
    {
         /// some very simple rules
         if($value==$this->numSweets) return self::$correctGuess;
         $isClose = round(((abs($this->numSweets - $value)) / $this->numSweets) * 100); // calculate how close the number is
         if($isClose < $this->closenessRange) return str_replace("{value}",$this->closenessRange,self::$closeGuess);    // if with in the closeness range return close messsage
         else{
              if($value > $this->numSweets) return self::$highGuess;
              else return self::$lowGuess;
         }
     }
}

Explanation

This is the game logic class, the getMessage function requires the integer that we extracted using the ExtractData class.  There are then some simple rules that select the appropriate message as the returned value.

Popularity: 49%

---

Related posts:

1. PHP 5 SMS Send Class implementing listeners on our SMS Gateway
   Class Name: SendSMSNotifier This class is designed around the FREE Text Marketer SMS API, you need to sign up here...
2. Text Marketer short code / txtUs API options
   Introduction The keyword on your system (on short code 88802) or your txtUs number can be used to “route” incoming...
3. How to integrate our SMS Gateway API into your systems
   Introduction Adding SMS as a communication method to a system is often very useful, for instance you don’t have issues...
4. SMS Gateway API – Specification
   This blog post has been superseded with our website documentation It is recommended that you use the  RESTful version of the API which has largely superseded this document...
5. Using the SMS Gateway API, Automating Delivery Report Collection
   This blog post has been superseded with our website documentation Introduction If you are using the API / Gateway to send bulk SMS...
6. PHP 5 Delivery Report Helper Class for our SMS Gateway
   Class Name: ProcessDeliveryReport This class enables you to access your delivery reports in a nice simplified way. You can search for...
7. How can you benefit from our free SMS keyword and shortcode text response system?
   Ever seen a TV Ad’ that says, “Text BROCHURE to 69888 for more details”? Why do they do this instead...
8. The SMS Gateway
   How to use an SMS Gateway Continue reading →...
9. .NET Examples
   Example of a .NET Bulk SMS Gateway / API integration For more information regarding the bulk sending API click here....
10. Be Honest. Is Your Advertising Working?
    Most marketers start to feel a little uncomfortable when faced with such a stark question. They might shift uneasily in...

---