How to Send and Receive SMS with the Orange SMS API

• Download source - 28.29 KB

Introduction

Publishing one's APIs to developers and geeks has gained momentum over the Internet as a way to foster innovation and drive use for services. All Web players, including icons such as Yahoo, Google, Microsoft, Amazon and eBay, now offer a wide arrays of APIs. APIs have mushroomed in the last 4 years and telcos have eventually caught up.

In May 2008, Orange will offer its own portfolio of alpha, beta and commercial API services aimed at the developer communities. It will stimulate collaborative innovation with third parties for all types of Web 2.0, SaaS and Social Network solutions through a new streamlined access to the Orange services. Orange APIs encompass various types of consumer and business services, from inter-personal and group communication services to multimedia solutions. They will all be made accessible to developers over the orangepartner.com portal.

In the following, we are focusing on the Orange SMS API. The SMS service, exposed by the API, allows you to send and receive text messages, of up to 160 characters, to and from a mobile phone. Here, we do not consider SMS derived services such as binary or WAP Push SMS. Our SMS API can be used by developers to send/receive mobile text messages and they can select unique combinations of short codes/keywords to funnel the SMS straight to their applications. This SMS API will initially be offered free of charge in alpha mode. Usage will be capped at 10 SMS per day and it will be constrained to mobile subscribers on Orange networks in France and in the United Kingdom. Alpha mode restrictions should be lifted by the end of April 2008.

We will now describe how to send out a text message, using various computing languages (C#, VBScript), and how to receive an SMS into your application.

First of all, in order to use the Orange SMS API, a developer will need to procure an access key upon registration on the Orange Partner portal. The access key will yield access to the API methods. The access key is retrieved from the web administration page.

Send SMS

The easiest way to send an SMS is arguably to copy and paste the following URL in your WEB Browser:

http://sms.alpha.orange-api.net/sms/sendSMS.xml?id=[api access key]&
to=[mobile number]&content=[your text message]

A real-life example is:

http://sms.alpha.orange-api.net/sms/sendSMS.xml?id=568d6a389aa&to=44712345678&
content=Hello+World

Notice that you may use an HTTPS access if needed.

The API is using a REST-RPC format. Most programming languages are able to send out HTTP requests (GET or POST) and parse XML, thus the SMS API can be used with any programming language.

We will now write a Send SMS snippet to illustrate how the API can be used to send and receive SMS. Below are two examples of a program that send text messages in C# and VBScript:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Xml;
 
namespace ConsoleApplication1
{
    class Program
    {
        // define the URL to send an SMS
        const string ACCESS_KEY = "568d6a389aa";
        const string MESSAGE = "Hello+World";
        const string TO_PHONE_NUMBER = "33612345678";
        const string URL = "http://sms.alpha.orange-api.net/sms/sendSMS.xml?
		id="+ACCESS_KEY+"&to="+TO_PHONE_NUMBER+"&content="+MESSAGE;
        static void Main(string[] args)
        {
            // XmlDocument allowed to query a xml document with xpath expression
            XmlDocument xmldoc = new XmlDocument();
            xmldoc.Load(URL);
            Console.WriteLine("Status Message=" + xmldoc.SelectSingleNode
			("/response/status/status_msg").InnerText);
        }
    }
}        

//
// code Courtesy of Bbil
// 
Option explicit
Const ACCESS_KEY = "568d6a389aa"
Dim stNumDest,stMessage 
stNumDest  = "33612345678"
stMessage = "Hello Word"
 
EnvoiSms stNumDest,ACCESS_KEY,stMessage
 
Sub EnvoiSms(stNum, stACCESS_KEY, stMessage)
    Dim xmlDoc,stUrl 
    stUrl = "http://sms.alpha.orange-api.net/sms/sendSMS.xml?id=" & _ 
        stACCESS_KEY &"&to=" & stNum & "&content=" & Escape(stMessage)
    Set xmlDoc=CreateObject("Microsoft.XMLDOM")
    xmlDoc.Async="false"
    if xmlDoc.Load(stUrl) and not xmldOC.selectSingleNode_
	("/response/status/status_code") is Nothing Then
        Msgbox "Status_code = " & xmldOC.selectSingleNode_
	("/response/status/status_code").text
     else
        MsgBox "Error sender", vbCritical
    End if
End sub 

The SMS Sender application is friendlier. The application is very simple and reuses the code from the C# console program above.

The application use one Windows Form. There are two textbox controls on the form to get the recipient phone number and the content of the SMS.

The button triggers a call to the API via the XmlDocument object, at last a message box displays the status.

To keep the code short, no internal exception is caught.

Receive SMS

Through the web administrator interface, you can freely register a keyword. Each SMS, starting with this keyword and sent to a short-code number in the UK or France (i.e. 967482 in the UK and 20345 in France), will be routed to your email box.
There are two options for retrieving SMSs:

• Via a URL: The Orange server sends an HTTP GET request to a given URL with parameters specifying the content and the recipient.
• Via an email: The Orange server routes SMSs to your email box.

Hereafter, I am showing how to design a basic application which lists the received SMS and displays the content of each message. You should forward your SMS to your API orange email address in the WEB Administrator Interface.

The logic of the application is straightforward.
The core program comprises one method which refreshes the email lists. A call to the HTTP getMailList provides the list of emails/ each mail starting with “Sms from” is identified as an SMS and the program calls the HTTP getMail routine to get the SMS content. In the listbox, you will be able to scroll the received SMS. A click on the update button will refresh the SMS list.

private void UpdateSMSList() {
            string sbj; 	// Email subject
            string[] sbjw;	// the words of the email subject 
            int nsm; 	// number of email
            SMS sm; 	// SMS content, date, phone number
 
            listSMS.Clear(); 	// clear the arraylist of SMS
            			// get and parse the email lists 
            XmlDocument xmldoc = new XmlDocument();
            xmldoc.Load(URL_GET_MAIL_LIST);
            XmlNodeList nodes = xmldoc.SelectNodes("/response/list/message");
            // loop on each message
            foreach (XmlNode node in nodes) {
                sbj = node.SelectSingleNode("subject").InnerText;
                sbjw = sbj.Split(' ');
                if (sbjw.Length >= 3)
                {
                    if ((sbjw[0] == "Sms") & 
			(sbjw[1] == "from")) // this email is a forwarded SMS
                    {
                        sm = new SMS();
                        sm.phoneSender = sbjw[2]; // phone number of the SMS sender
                        nsm = Convert.ToInt32(node.SelectSingleNode("number").InnerText);
                        xmldoc.Load(URL_GET_MAIL+nsm); // get the body of the 
					// nsm email (i.e. content of the SMS)
                        sm.content = xmldoc.SelectSingleNode
				("/response/message/body").InnerText;
                        sm.date = xmldoc.SelectSingleNode
				("/response/message/date").InnerText;
                        listSMS.Add(sm); // add the SMS to the arraylist  
                    }
                }
            }
        } 

Conclusion

This document has provided you with an overview of the Orange SMS API. The applicative use cases are numerous, from Twitter-like solutions to SMS-enabled games or even an SMS Wall in Facebook. With this API, you can add a new communication channel into your application: Several examples are provided in the telcoapps blog. Along with the SMS API, Orange has posted a broad selection of API services on the Orange Partner portal including APIs on such personal Orange services as Calendar, Contacts, Photo, Mail, Authentication and User Profile. Some Orange APIs are available on business solutions, for instance the Contact Everyone API allowing developers to broadcast messages across more than 200 countries in SMS, voice mail, email and fax formats. Yet, other APIs will allow developers to tap into Orange’s social services such as the Pikeo online photo service.

Links

• Orange Partner
• Few examples in French
• Telco Apps

History

• V1.0 April 7^th, 2008, tutorial creation
• V1.1 April 7^th, 2008, added screenshot