Webkoof

If you have not read first part of “Write an SMS Application”, read it here.

Continuing from next time, let’s assume that we registered a keyword ‘QUOTE’. It means that any message which starts with QUOTE (or quote or QuOtE) and sent to 56767888 will call our AppURL http://webkoof.com/quote.php. This is how it will exactly happen:

1. Someone sends QUOTE <anything after it> to 56767888. (Please note that the space after QUOTE is needed. QUOTER will not call your appURL)
2. SMSGupShup will recieve the message and will call our AppURL with sender’s phone number and content of the SMS.
3. They will pass the sender’s phone number and SMS to our application as GET parameters. Which means that if someone with phone number 9876543210 sends QUOTE to 56767888 then they will actually call http://webkoof.com/quote.php?msisdn=919876543210&content=QUOTE

Notice that parameter name for phone number is msisdn and for SMS content is content. Also notice that phone number is always prefixed by the country code (91 for India).

Our applicaton should start with GETting these parameters.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

<?php
$sender = $_GET["msisdn"];  // Get the phone number
$content = $_GET["content"]; // Get the message
 
/* Remember that an user can send anything after QUOTE to the application.
So, QUOTE GANDHI will also come to your application and so will QUOTE xxx.
Let's make sure that we recieved only QUOTE or send an error.           */
 
if ($content == 'QUOTE') 
       $reply = selectQuote();  //selectQuote is a function, which we need to define.
else
       $reply = 'You have sent wrong command. You should only send QUOTE to 56767888.';
 
fucntion selectQuote() {
 
       /* Do something and find out a quote. You can use a pre defined array of quotes 
          and pick one. or you can fetch a RSS feed of quotes from somewhere and pick one. 
          Right now, I'm returning a fixed quote every time. */
 
        $quote = "There is no gain without pain";
        return $quote; 
}

In the code till now, we decided what to send based on what we get. Please remember that choosing the quote (selectQuote function) can be a very simple algorithm which involves picking up one random quotes from a given array (or text file or even mysql database) or it may be a complex one involving RSS feeds. The way you select the quote is a programming problem and it may vary from user to user. In this case, we are returning the same quote every time because we want to learn the SMS App flow in simplistic manner.

So, we finally decided what to send back ($reply variable) and to whom ($sender variable). How will we send back the SMS then? It is not as complex as it may seem. If your script outputs in a given JSON or XML format, SMSGupShup will handle all the dirty work and automatically send the SMS. Acceptable formats are following:

1. JSON

[{ "msisdn":"919876543210", "content":"Our Reply here"},
{"msisdn":"919876543211", "content":"Another message to same or different number"}]

2. XML

<ApplicationResponse>
     <Response>
           <msisdn>919876543210</msisdn>
           <content>Our Reply here</content>
      </Response>
      <Response>
            <msisdn>919876543211</msisdn>
            <content>Another message to same or different number</content>
      </Response>
<ApplicationResponse>

Notice that a single incoming SMS can result in sending more than one messages as response to different numbers. But, for our simple application we only need to send one message to only one user. So, we need to format our response in the given format. We can use simple echo command or more advanced json_encode command. Continuing our quote.php file:

24
25
26

// Using simple echo fucntion
echo "[ { \"msisdn\":\"$sender\", \"content\":\"$reply\"}]"; 
?>

Alternatively, you can also use json_encode function (PHP5). Although it seem little complex but, for creating jsons in other complex cases are too much to handle using echo.

24
25
26
27
28

// Using more advanced json_encode function.
$reponseArray = array('msisdn'=>$sender, 'content'=>$reply);
$json_response = json_encode($responseArray);
echo "[$json_response]";
?>

Similarly you can also choose to output XML format. Again, it does not matter if you use echo to create your XML or you use other complex functions to write XML.

Hence, we created our first SMS application which is very simple but gives us good enough idea of the flow logic involved. Wait for complexities.

And ya…! Happy Holi.

We encounter SMS application on a daily basis. Voting on reality shows, opinion polls on newspaper or your daily horoscope on SMS – everything is an SMS Application (or as we lazy developers call it – SMS App). Just until few months back, it was very difficult for a novice programmer to write an SMS app. It was only expert’s cup of tea. But then SMSGupShup launched an application programming interface (API) using which anyone with little knowledge of programming can write an SMS App.

In order to write an application, first thing we need to know is how these apps work. Any app will have two clear parameters associated to it. First is shortcode (The number which is used to communicate with the app) and second Keyword (The first word of any SMS Response). Let’s understand this using an example. Consider an App designed to calculate love compatibility score between two persons. If you visit the actual app page here, you will see the line “SMS to 56767888: Love <name1> <name2> “. It indicates that if you want to calculate love score between JOHN and BIPASA then you need to send LOVE JOHN BIPASA to 5676788. In this example, shortcode is 56767888 and keyword is LOVE.

So, why shortcode and keywords are important? Well, shortcode are just like mobile numbers. So, the app will recieve only messages sent to a particular shortcode for the obvious reason and on a single shortcode there are various apps running, so the keyword determines which message should go to which app. SMSGupShup provides you a shortcode and keywords for any app you want to write. (Keywords. Because complex apps can have more than one keyword). To apply for API access go here. Did I mention it is FREE?

On the registration form you will see one unfamiliar Input field namely ‘App URL’. So, what is this AppURL? To understand appURL, you need to know how this API works internally. Let’s continue with our example of Love application. What happens (internally) if someone sends LOVE JOHN BIPASA to 56767888? (Assume that mobile number of the person is 9876543210.

1. Since the shortcode 56767888 is owned by SMSGupShup, the message goes to them.
2. Now SMSGupShup takes the message and reads the keyword, which is LOVE in this case.
3. Since everyone registered their own keywords with SMSGupShup, they send this whole message (LOVE JOHN BIPASA) and the incoming number (9876543210) to LOVE Application.
4. Love Application takes the number and the SMS. Process it. and calculated the love score using some algorithm (Say 80%). And send back a response to SMSGupShup containing what SMS to send (Your Love score is 80%) and Whom (9876543210). Responses are sent in XML or JSON format, which we will discuss later
5. SMSGupShup takes the response and sends the SMS to given number.

Read and understand the process completely.

Important step to note here is STEP 3. What does it mean that they send the message to love application? Well, Application is nothing but a file (written in PHP, Java or even C) somewhere on the web. SMSGupShup needs to know where to send the messages for your particular App. AppURL is URL of this particular file. (Which you can host anywhere on web)

So, if you are planning to put your application file (which will process the incoming SMS and gives back response to user) at http://example.com/app.php then this URL will be your AppURL. Now let’s assume that we want to develop an application QUOTE, which will send back a nice quote to the user.

AppName: Quotation

Keyword: QUOTE

AppURL: http://webkoof.com/quote.php (This is the file we have to write.)

Break Time. We will write our application (quote.php) in next session.