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

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


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 generate a response. In our case, we find out whether the participant has guessed the correct number and we send back an appropriate response using the Text Marketer API  Gateway see the documentation for details.

Creating the game and code examples

The Guess number of sweets in a jar game and all the code you need is below. 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 to your account and set the url your wish to use for accessing your script. To access the setup 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();

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 “you 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=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;

This simple class allows us to extract the data we need from the short code response. The response contains the entire 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)
 public function setClosenessRangeInPercent($value) //in percent
 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
 if($value > $this->numSweets) return self::$highGuess;
              else return self::$lowGuess;

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.