Home » Documentation » SMS to Web server, SMS to HTTP

SMS to Web server (website)

SMS Enabler allows you to programmatically receive and reply to incoming SMS messages on your website using any web programming language, such as PHP, ASP.NET and so forth.

How it works: SMS Enabler software connects to a GSM or 3G modem plugged in a computer. Each time a new SMS message arrives to that modem, the software forwards that message to your web server via HTTP, so that the message can be handled by your script or web application.

1. Creating a PHP script to handle incoming SMS messages
2. Using PHP to store incoming SMS messages in MySQL database
3. Creating an ASP.NET SMS handler to receive and reply to incoming SMS messages
4. Creating an SMS handler using other web languages

Using PHP to receive and reply to incoming SMS messages

The following is a short step-by-step summary on using PHP for sms processing and sending sms replies:

1. Create a PHP script by following the documentaion below
2. Put the script on your webserver (website)
3. Set the script's URL in the SMS-to-Webserver tab in the SMS Enabler's Settings dialog box

1.1 Processing incoming SMS message

Each time SMS Enabler receives a new SMS message, your PHP script is triggered. All SMS message information is passed to your script via the $_POST array. The most important parameters are:

$_POST['sender'] - Sender's phone number
$_POST['text'] - SMS message text.

Note, that such a script is not intended for viewing in a browser but for programmatically receiving and replying to incoming SMS messages. Therefore do not try to output any html with it.

1.2 Sending an SMS reply

To send an SMS reply back to the sender, use the echo() function. Put it in the end of the script. If the reply SMS can contain non-ASCII characters, you should specify the character encoding in the Content-Type header, as in the example below.

To send the reply SMS to a different recipient or to multiple recipients, you must add an "X-SMS-To" http header and set its value to the recipient's phone number. Multiple numbers can be specified by separating them with spaces. To add the header use the header() function.

1.3 Example:   Download PHP sample script

<?php

$senderPhone = $_POST['sender'];//sender's phone number
$messageText = $_POST['text'];  //text of the message

/* TODO: IMPLEMENT ANY PROCESSING HERE THAT YOU NEED TO PERFORM UPON RECEIPT OF A MESSAGE */


/* ---- Sending a reply SMS ---- */

/* Setting the recipients of the reply. Otherwise the reply is sent back to the sender of the original SMS message. */

// header('X-SMS-To: +97771234567 +15550987654');

// Setting the content type and character encoding
header('Content-Type: text/plain; charset=utf-8');
// Comment the next line out if you do not want to send a reply
echo 'Reply message text';
?>

The other parameters are:

$_POST['sc_datetime'] - Date and time when the message was sent, in the local time zone of the computer on which SMS Enabler is running, in YYYY-MM-DD HH:MM:SS format
$_POST['sc_datetime_utc'] - Date and time when the message was sent, in UTC, in YYYY-MM-DD HH:MM:SS format
$_POST['smsc'] - SMS center number (not supported when SMS Enabler is connected to a Nokia phone).
$_POST['tag'] - Tag value. You can define this in SMS Enabler's settings, and use it to pass additional information.

IMPORTANT: To enable replies from the script, set the source for the reply message text to the 'HTTP response content' in the Settings dialog box in the Reply SMS tab.

Using PHP to store incoming SMS messages in MySQL database

This is a step-by-step walkthrough for using our sample smstodb.php script to receive and store incoming SMS messages in a MySQL database table.

1. In your MySQL database, create a table named `sms_in` to store incoming SMS messages. Use the following SQL statement to create it:

CREATE TABLE sms_in (id int NOT NULL auto_increment,
 sms_text varchar(1600),
 sender_number varchar(50),
 sent_dt datetime,
 PRIMARY KEY (id)) default charset=utf8mb4;

2. Download the smstodb.php script to your computer

3. Open the smstodb.php script in the Notepad text editor and find the line containing the following code:

$con = new mysqli('mysql_hostname','username','password','db_name');

Change the parameter values to the actual ones.

4. Save the changes and upload smstodb.php to your webserver (website).

5. Enable SMS-to-web-server forwarding and set the script's URL in the SMS to Webserver tab in the Settings dialog box in SMS Enabler.

Start SMS Enabler and send an SMS message to it. After the message is received and forwarded to smstodb.php, the message will appear in the sms_in table.

Using ASP.NET for receiving and replying to incoming SMS

A short step-by-step sumary on how to add sms processing to your web application. Full details are given further below. You can also download an example project here.

1. Add a "Generic Handler" (.ashx file) to your web application project in Visual Studio.
2. Write your code to process SMS messages in the ProcessRequest() method of that handler.
3. Build the project and publish it on your webserver.
4. Set the URL of the handler in the SMS-to-Webserver tab in the Settings dialog box in SMS Enabler.

1. Adding a Generic Handler to your project

Add a new Generic Handler to your project in Visual Studio. To do so, right-click your project name in the Solution Explorer and choose Add -> New Item. The "Add New Item" dialog box will open. In the "Web" category, choose "Generic Handler". In the Name box type sms.ashx and then click Add.

If your project is an ASP.NET MVC project, you also need to edit the Global.asax.cs file of your project. Add the following line in the RegisterRoutes() method of the Global.asax.cs file:

routes.IgnoreRoute("sms.ashx/{*pathInfo}");

2. Processing incoming SMS and sending replies

Open the sms.ashx.cs file in the code editor and find the ProcessRequest() method. This method will be called each time a new SMS message arrives. ProcessRequest() is where you write your code to process incoming SMS messages.

All SMS message information is passed to ProcessRequest() via form variables. You can access them by their names via the context.Request.Form collection, where context is the parameter of ProcessRequest(). These variables are described in the example below.

To send a reply SMS back to the sender, write the content of the reply as plain text to the HTTP response output stream using the context.Response.Write() method.

To send the reply SMS to a different recipient or to multiple recipients, add an "X-SMS-To" header to the HTTP response and set its value to the recipient's phone number. Multiple recipients can be specified by separating the numbers with spaces.

3. Setting SMS Enabler

After publishing your project on your web server, set the URL of sms.ashx in the Settings dialog box in the SMS to Webserver tab. E.g: http://yoursite.com/sms.ashx

Example:   Download ASP.NET sample project

public class sms : IHttpHandler {

 // This method is called each time a new SMS message arrives
 public void ProcessRequest(HttpContext context) {
   // form variables (contain all sms message information)
   var sms = context.Request.Form;

   // sender's number
   string senderNumber = sms["sender"];
   // sms message text
   string messageText = sms["text"];
   // SMS center timestamp. You can consider this
   // as the date and time when the sender sent the message.
   DateTime sentTime = DateTime.ParseExact(sms["sc_datetime"],
         "yyyy'-'MM'-'dd HH':'mm':'ss", null);
   // SMS center number (not supported when using SMS Enabler
   // with a Nokia phone)
   string smscNumber = sms["smsc"];
   // Tag value. You can define this in SMS Enabler's settings,
   // and use it to pass additional information.
   string tag = sms["tag"];

   /* TODO:
      WRITE YOUR CODE FOR PROCESSING INCOMING SMS MESSAGES HERE */

   // Sending a reply SMS. If you don't want to send a reply,
   // just comment all the next lines out.
   context.Response.ContentType = "text/plain";

   // Add an X-SMS-To header to set the recipients of the reply.
   // If not set, the reply is sent to the sender of the
   // original SMS message.
   // context.Response.AddHeader("X-SMS-To",
   //      "+97771234567 +15550987654");

   // Write the text of the reply SMS message
   // to the HTTP response output stream.
   context.Response.Write("Reply SMS message");
 }

 public bool IsReusable {
   get {
      return false;
   }
 }
}

Using other web programming languages to create SMS processing scripts

HTTP Request and Response

SMS Enabler uses HTTP POST requests to forward received SMS messages to a web server. The server must return 200 OK or 204 No Content status to indicate success. Any other status code is taken by SMS Enabler as a failure, and causes the program to retry the request. The retry timeout interval is defined in the settings; the default is 30 seconds.

The request content type is application/x-www-form-urlencoded. This is the same content type that HTML forms use to post data to a web server. Without going into too much detail, the application/x-www-form-urlencoded content type is a set of field names and their corresponding values, which are used by SMS Enabler to carry all SMS message information. You can easily retrieve field values by their names using almost any modern web programming language. See field descriptions below:

Sending a Reply SMS from the Script

To send a reply SMS, your script should return it as plain text in the content of the HTTP response. The content length must be greater than 0, and the content type set to 'text/plain' or any other 'text/*' MIME type. The response status code must be 200 OK. If you are sending non-ASCII characters, it's important to specify the correct character set of the response.

To send a reply SMS message to a phone number other than one from which the original message has been received, add a custom HTTP header named 'X-SMS-To' to the HTTP response. The header's value must be set to a phone number to which you want the reply message to be sent. You can specify more than one number by separating the numbers with spaces.