L'API SMS permet l'envoi de SMS depuis vos applications, vers des mobiles de tous opérateurs dans le monde.

L'API peut être utile pour prévenir d'une livraison, rappeler un rendez-vous, diffuser des informations à une liste de clients, souhaiter un évènement à un groupe d'amis, créer un groupe de discussion par SMS, organiser un sondage lors de séminaires, ou alerter efficacement depuis vos scripts de supervision...

Nous avons déjà vu l'URL d'envoi de SMS, utilisée depuis un navigateur.

Voici quelques exemples, toujours très simples, dans des applications en PHP, Java, Python, VBScript

<?php
$phone_number = '33612345678';
$text_message = urlencode("Hello world, sent with Orange API in PHP !");
$api_access_key = 'a1234b56789';
$url = "http://sms.beta.orange-api.net/sms/sendSMS.xml?id=$api_access_key&amp;to=$phone_number&amp;content=$text_message";
$response = file_get_contents($url);
$xml = simplexml_load_string($response);
echo "Status: ",$xml->status->status_msg;
?>

import java.io.*;
import java.net.*;

import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.xpath.XPath;
import javax.xml.xpath.XPathFactory;

import org.w3c.dom.Document;

public class SendSMS {
	public static void main(String[] args) throws Exception {
		String phoneNumber = "33612345678";
		String textMessage = URLEncoder.encode(
				"Hello world, sent with Orange API in Java", "UTF-8");
		String apiAccessKey = "a1234b56789";
		String url = "http://sms.alpha.orange-api.net/sms/sendSMS.xml?id="
				+ apiAccessKey + "&to=" + phoneNumber + "&content="
				+ textMessage;

    // Send GET request
    URL client = new URL(url);
    URLConnection conn = client.openConnection();
    InputStream responseBody = conn.getInputStream();

	// Convert in XML document
	Document response = DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(responseBody);
	responseBody.close();
	// Xpath expression to get the status
	XPath xPath = XPathFactory.newInstance().newXPath();
	String status = xPath.evaluate("/response/status/status_msg", response);
	// display status
	System.out.println("Status: " + status);
	}
}

using System;
using System.Net;
using System.Xml;

namespace TestSendSMS
{
    class TestSendSMS
    {
        static void Main(string[] args)
        {
            // Init parameters
            String phoneNumber = "33612345678";
            String textContent = "Hello world, sent with Orange API in C#";
            String apiAccessKey = "a1234b56789";
            String url = "http://sms.alpha.orange-api.net/sms/sendSMS.xml?id=" + apiAccessKey
                + "&from=38100&to=" + phoneNumber + "&content=" + textContent;
            
            // Send GET request
            WebClient client = new WebClient();
            string result = client.DownloadString(url);
            Console.WriteLine("Result : " + result);

            // Parse the returned XML
            XmlDocument document = new XmlDocument();
            document.LoadXml(result);
            Console.WriteLine("Status code : " + document.GetElementsByTagName("status_code")[0].InnerText);
            Console.WriteLine("Status message : " + document.GetElementsByTagName("status_msg")[0].InnerText);
        }
    }
}

import urllib
import xml.etree.ElementTree as ET
phone_number = '33612345678'
text_message = 'Hello world, sent with Orange API in Python'
urlbase = 'http://sms.alpha.orange-api.net/sms/sendSMS.xml?'
urlparam = urllib.urlencode([('id','466b6e288fc'),('to',phone_number),('content',text_message)])
response = ET.parse(urllib.urlopen(urlbase+urlparam)).getroot()
print response.findtext('status/status_code')

Option explicit
Const ACCESS_KEY = "a1234b56789"
Dim stNumDest,stMessage 
stNumDest  = "33612345678"
stMessage = "Hello world, sent with Orange API in VBScript"
 
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 "Erreur envoi", vbCritical
	End if
End sub

Si vous avez besoin de vous assurer de la bonne remise du SMS sur le terminal, il est aussi possible de récupérer l'historique de cet appel avec un statut mis à jour.
Pour cela, utilisez l'API getHistory en passant le paramètre callid qui aura été retourné lors de l'envoi du SMS.

La réception de SMS est une fonctionnalité intéressante des API d'Orange car elle vous permet de disposer de votre propre shortcode associé à un mot-clé qui vous est réservé. Vos utilisateurs pourront envoyer des SMS précédés de votre mot-clé, à votre shortcode, qui seront ensuite transmis à votre application. Pour en savoir plus sur les shortcodes, vous pouvez consulter les articles suivants :
http://blog.api.orange.com/2010/05/les-shortcodes-sms-kezako.html et http://blog.api.orange.com/2010/05/le-ba-ba-du-sms.html. Sur le site http://api.orange.com, allez dans l'interface d'administration et choisissez :

• votre mot-clé associé au shortcode,
• votre méthode de réception : une adresse mail et/ou une URL (La plate-forme des API d'Orange fait alors une requête GET sur votre URL avec le contenu du message en paramètre).

Les shortcodes disponibles en France sont soit non-surtaxés (facturés comme un SMS classique à vos utilisateurs), soit surtaxés (une surtaxe est appliquée par l'opérateur à vos utilisateurs, et vous gagnez des crédits de revenue-share).

Exemple d'utilisation : Mini-sondage

Pour illustrer l'intérêt de la notification de réception d'un SMS, voici l'exemple d'un outil de sondage instantané par SMS.

• L'utilisateur envoie un SMS au numéro court 20345 avec le préfixe configuré par le développeur du mini sondage (imaginons que vous ayez configuré POLL comme préfixe s'il est encore disponible). Le SMS contient donc le mot POLL, une question et les réponses possibles commençant par A) ou B) ou C) ...
• Le script PHP (qui s'exécute sur votre serveur ou chez votre hébergeur) est notifié par le serveur d'Orange (HTTP GET avec en paramètre le contenu du SMS) d'un nouveau SMS et il renvoie aux participants du sondage la question et les réponses (une extension serait de pouvoir configurer la liste de diffusion)
• Les utilisateurs répondent avec la lettre correspondant à la réponse (SMS commençant par POLL suivi de la lettre A ou B ou ...)
• On peut voir en temps réel les résultats du sondage sur un site WEB (fichier html)

Dans un souci de simplicité, la liste de diffusion est configurée en dur dans le code, il n'y a pas de contrôle qu'un utilisateur ne vote pas deux fois et un seul sondage peut être organisé simultanément.

Mise en pratique :

Il faut tout d'abord configurer l'url de votre script dans l'interface Web de configuration des API orange et configurer un préfixe SMS (ou mot de code). Le code est découpé en 2 scripts PHP, le premier (dont l'URL doit être configurée dans l'interface d'administration) reçoit les SMS, stocke dans un fichier les réponses et diffuse le sondage à la liste de diffusion. Le second fichier mixte HTML et PHP pour afficher les résultats du sondage.

<?php
define('LIMIT_NEW_POLL_ANSWER',20);

$diffusion_poll_list = array('nicolas' => '33612345678','martin' => '33687654321');
$api_access_key = 'a1234b56789';

// save parameters from the receiveSMS method
$mobile_number = $_GET['from'];
$sms_content= $_GET['content'];

// remove the keyword from the text message
$sms_content = substr(strstr($sms_content,' '),1);

// is a new poll or answer
if (strlen($sms_content) > LIMIT_NEW_POLL_ANSWER) {
	// new poll
	// store the content of the current poll
	$fid = fopen('./data/poll_results.txt','w');
	fwrite($fid,'a=1 b=2 c=3 d=4 e=5\n'); // init the poll results
	fclose($fid);
	$fid = fopen('./data/poll_question.txt','w');
  fwrite($fid,$sms_content); // write the poll question
  fclose($fid);
	// forward the poll to diffusion list
	$text_message = urlencode("Poll from $mobile_number $sms_content");
	foreach ($diffusion_poll_list as $phone_number) {
		// send sms
		$url = "http://sms.alpha.orange-api.net/sms/sendSMS.xml?id=$api_access_key&amp;to=$phone_number&amp;content=$text_message";
		file_get_contents($url);
	}
}
else {
	// answer to poll
	$fid = fopen('./data/poll_results.txt','r');
	list($a,$b,$c,$d,$e) = fscanf($fid,'a=%d b=%d c=%d d=%d e=%d');
	fclose($fid);
  // the first letter after the keyword is considered as the answer
  $answer = strtolower($sms_content{0});
  if (strpos("abcde",$answer) != FALSE) {
    ${$answer}++;
  	$fid = fopen('./data/poll_results.txt','w');
  	fprintf($fid,'a=%d b=%d c=%d d=%d e=%d\n',$a,$b,$c,$d,$e);
  	fclose($fid);
  }
}
?>

<html>
  <title>Sondage</title>
  Sondage<br>
  <?php
    $fid = fopen('./data/poll_results.txt','r');
    list($a,$b,$c,$d,$e) = fscanf($fid,'a=%d b=%d c=%d d=%d e=%d');
    fclose($fid);
    $question = file_get_contents('./data/poll_question.txt'); // read the entire question
  ?>
  Question:<br>
  <?php echo $question ?>
  <br>
  Résultats:
  <ul>
    <li>Réponse A: <?php echo $a ?> votes</li>
    <li>Réponse B: <?php echo $b ?> votes</li>
    <li>Réponse C: <?php echo $c ?> votes</li>
    <li>Réponse D: <?php echo $d ?> votes</li>
    <li>Réponse E: <?php echo $e ?> votes</li>
  </ul>
</html>

Autre exemple d'utilisation : la M-Shoutbox

Un autre exemple d'utilisation est la M-Shoutbox : un système de messagerie instantanée permettant de contacter par SMS un ensemble de personnes ou de créer une boîte de discussion par SMS.

L'API MMS permet l'envoi et la réception de textes, images, photos ou vidéo avec les mobiles, depuis une application. Aujourd'hui, l'API fonctionne uniquement avec les mobiles Orange France.

L'API peut être utile pour partager des photos, faire du micro-blogging photo ou vidéo ...

En raison des fichiers à transmettre, les requêtes utilisent uniquement les méthodes POST de REST. Voici un exemple d'envoi de MMS via un formulaire HTML.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
</head>
<body id="body">
  <h2>MMS API form</h2>
  <form action="http://mms.alpha.orange-api.net/mms/sendMMS.xml" 
  target="_SELF" enctype="multipart/form-data" method="POST">
    <input type="hidden" name="id" value="a1234b56789">
    <input type="hidden" name="from" value="20345">
    <br/>
    <table border="0">
      <tr><td colspan="2">Mandatory  information :</td></tr>
      <tr><td><b>To :</b></td>
          <td><input size="30" id="to" name="to" type="text"></td></tr>
      <tr><td><b>Content :</b></td>
          <td><textarea id="content" name="content"></textarea></td></tr>
      <tr><td colspan="2" ><br />Optional information : </td></tr>
      <tr><td><b>Subject :</b></td>
          <td><input size="30" id="subject" name="subject" type="text"></td></tr>
      <tr><td colspan="2" ><br />The files size should not exceed 100ko</td></tr>
      <tr><td><b>Image :</b></td>
          <td><input type="file" id="image" name="image" size="30px"/></td></tr>
      <tr><td><b>Sound :</b></td>
          <td><input type="file" id="sound" name="sound" size="30px"/></td></tr>
      <tr><td><b>Video :</b></td>
          <td><input type="file" id="video" name="video" size="30px"/></td></tr>
      <tr><td></td><td><input type="submit" value="Send MMS"></td></tr>
    </table>
    </form>
  </body>
</html>

De la même manière que pour la réception de SMS, les API d'Orange permettent de recevoir des MMS sur un serveur web. Pour cela, vous devrez configurer au préalable votre URL de réception des MMS dans l'interface d'administration et utilise les mêmes préfixes que pour la réception de SMS.

L'API Location permet de localiser l'emplacement géographique d'un utilisateur mobile depuis une application. Actuellement, le service est disponible pour les mobiles du réseau Orange France (opérateurs partenaires MVNO inclus).

L'API peut être utile pour suivre une flotte de véhicules, organiser des évènements en temps réel, ou localiser les restaurants les plus proches de plusieurs personnes.

L'API retourne la position et la taille de la cellule du réseau mobile, au format GPS (longitude / latitude) directement exploitable dans d'autres API de cartographie par exemple. La taille de la cellule peut varier de 300 m (zone urbaine) à 30 km (zone rurale), selon son emplacement. Un avantage important de cette API est qu'elle permet la localisation de tout type de mobile, du plus moderne au plus ancien, et ne requiert aucune installation préalable de logiciel sur le terminal pour fonctionner.

Une autorisation préalable du propriétaire du mobile est bien entendue nécessaire avant de pouvoir obtenir les données de localisation.

1. Réception d'un 1er SMS d'invitation et réponse au 20345 avec le mot clé "oui" => autorisation du mobile pour ce service
2. Réception d'un 2nd SMS d'invitation et réponse au 20633 avec le mot clé "location" => autorisation du mobile à la plateforme Orange

A tout moment, si l'utilisateur souhaite retirer son autorisation, il lui suffit d'envoyer le mot clé " non " au 20345.

Pour demander une autorisation de localisation, il suffit de taper l'URL suivante, en mettant à jour la valeur des paramètres id et number :
http://location.beta.orange-api.net/location/createAuthorization.xml?id=[clé d'identification]&number=[numéro de téléphone à localiser]

Pour localiser un mobile, et seulement une fois que le propriétaire a donné son autorisation, il suffit de taper l'URL suivante, en mettant à jour en mettant à jour la valeur des paramètres id et number :
http://location.beta.orange-api.net/location/getLocation.xml?id=[clé d'identification]&number=[numéro de téléphone à localiser]

Voici un exemple de code PHP

<?php
// clé d'identification
$access_key = "a1234b56789";

// adresse de l'API location > getLocation
$adresse = "http://location.beta.orange-api.net/location/getLocation.xml";

// adresse de l'API location > getAuthorization
$adresse_authorize = "http://location.beta.orange-api.net/location/createAuthorization.xml";

// numéro de mobile à localiser (au format international)
$number = "33612345678";

// exécution de la requête > création de l'appel
$response = file_get_contents(
             $adresse . "?id=" . $access_key . "&amp;number=" . $number;

// récupération de la réponse de l'API
$xml=simplexml_load_string($response);
if ($xml->status->status_code = 450)
{
  // exécution de la requête > création de l'appel
  $response = file_get_contents(
               $adresse_authorize . "?id=" . $access_key . "&amp;number=" . $number;

  // récupération de la réponse de l'API
  $xml=simplexml_load_string($response);
  echo($xml->status->status_code . " - " . $xml->status->status_msg);
  echo "Suivez les instructions reçues par SMS et relancez le script";
} else {
  echo($xml->status->status_code . " - " . $xml->status->status_msg);
  echo($"Coordonnées . "$xml->location-> X- " . $xml->location->Y);
}
?>

L'API Click-2-Call permet de créer des appels vers les téléphones fixes et mobiles du monde entier, quel que soit l'opérateur, directement au sein d'une application. Il suffit de spécifier les deux numéros de téléphone de l'appelant et de l'appelé, et l'API se charge de mettre en relation, instantanément, les deux participants. Plusieurs options sont disponibles, comme l'affichage des numéros, la durée maximale de l'appel, ou la confirmation de l'appel par l'appelant...

L'API peut servir dans un formulaire web pour proposer à l'internaute de contacter un plateau téléphonique, sur votre blog pour être appelé sans divulguer votre numéro, ...

La requête la plus simple est la suivante :
http://call.beta.orange-api.net/call/createCall.xml?id=[clé d'identification]&from=[numéro appelant]&to=[numéro appelé]
ou si vous souhaitez utiliser toutes les options possibles :
http://call.beta.orange-api.net/call/createCall.xml?id=[clé d'identification]&from=[numéro appelant]&to=[numéro appelé]&private=[numéro visible ou masqué]&max_duration=$[durée maximale de l'appel]&call_confirmation=[validation de l'appel par l'appelant]&lang=[langue du call_confirmation]&audio_url=[fichier audio de mise en attente]&notification_url=[URL de réception des informations de l'appel]

<?php
// clé d'identification
$access_key = "a1234b56789";

// adresse de l'API click-to-call
$adresse = "http://call.beta.orange-api.net/call/createCall.xml";

// le numéro de l'appelant (au format international)
$from = "33XXXXXXXXX";
// numéro de téléphone du destinataire (au format international)
$to = "33XXXXXXXXX";
// confirmation de l'appel (par l'appelant)
$call_confirmation = true;

// exécution de la requête > création de l'appel
$response = file_get_contents($adresse . "?id=" . $access_key . "&amp;from=" . $from . "&amp;to=" . $to . "&amp;$call_confirmation=" . $call_confirmation);

// Affichage de la réponse de l'API
$xml=simplexml_load_string($response);
echo($xml->status->status_code . " - " . $xml->status->status_msg);

?> 

L'API Click-2-Conf permet d'organiser des réunions téléphoniques pour discuter à plusieurs. Plusieurs options sont disponibles, comme la durée de la conférence, la date et l'heure de début, le mode d'accès à la conférence (en appelant un numéro ou en se faisant appeler).

1. appel entrant avec code secret : le participant compose le numéro de téléphone de la conférence, puis saisit un code secret ("le room code") : c'est le mode d'accès appelé "room" dans l'API
2. appel entrant avec identification : le participant compose le numéro de téléphone de la conférence, il est reconnu automatiquement et n'a pas besoin de taper de "room code" : c'est le mode appelé "caller"
3. appel sortant : l'application déclenche un appel sortant depuis la conférence vers le participant, qui décroche, confirme en appuyant sur # et rejoint la conférence.

Les appels entrants se font sur un numéro Indigo 0825 qui sera facturé 0,15 €/min à chaque participant (actuellement, les appels entrants ne sont disponibles que pour la France). Chaque minute d'appel entrant vous donne droit à un partage de revenus, qui va alimenter votre balance de revenueshare. Cela peut vous permettre de consommer d'autres API pour enrichir votre service (envoyer des SMS d'invitation par exemple), ou être reversés sur votre compte bancaire. Les appels sortants vont consommer des crédits sur le compte qui déclenche l'appel, le coût variant en fonction des destinations des numéros appelés.

• la création de la conférence,
• l'ajout de participants,
• l'appel sortant des participants.

La création d'une conférence est une étape obligatoire. C'est elle qui définit le mode d'accès à la conférence : "room", "caller", "room+caller" ou "none". En mode " caller ", la liste des participants ne peut pas être vide. Dans les autres modes, ils peuvent être ajoutés ensuite.
http://conference.beta.orange-api.net/conf/createConference.xml?id=[clé d'identication]&access_mode=[type de conférence]&caller_numbers=[liste des numéros autorisés]&duration=[durée de la conférence]&when=[date et heure de début de la conférence]&greeting=[langue du message d'accueil]

Une fois la conférence créée, il est possible d'ajouter des nouveaux participants, pour les autoriser à intégrer la conférence existante.
http://conference.beta.orange-api.net/conf/addCaller.xml?id=[clé d'identification]&conf_id=[identifiant de la conférence]&caller_numbers=[numéro 1],[numéro 2]

Lorsqu'une conférence est créée et qu'il y a des participants enregistrés, il est possible de déclencher un appel vers un participant pour qu'il rejoigne la conférence.
http://conference.beta.orange-api.net/conf/createCall.xml?id=[clé d'identification]&from=[numéro de l'invité]&to=[identifiant de la conférence]&notification_url=[URL de notification]

Voici un exemple en PHP qui créée une conférence et déclenche les appels sortants vers tous les participants définis dans le paramètre $call_numbers

<?php
// clé d'identification
$access_key = "a1234b56789";
// adresse de l'API click-to-conf > CreateConf
$adresse = "http://conference.beta.orange-api.net/conf/createConference.xml";
// adresse de l'API click-to-conf > CreateCall
$adresse = "http://conference.beta.orange-api.net/conf/createCall.xml";
// les numéros à mettre en conférence (au format international)
$call_numbers = "331XXXXXXXX, 332XXXXXXXX, 333XXXXXXXX";
// le type de la conférence: (room, room+caller, none)
$access_mode = "none";
// durée de la conférence (en minutes)
$duration = 20;

// éxécution de la requête > création de la conférence
$response = file_get_contents($adresse . "?id=" . $access_key . "&amp;$access_mode=" . $access_mode . "&amp;duration=" . $duration);

// récupération de la réponse de l'API
$xml=simplexml_load_string($response);
// vérification de la création de la conférence
if ($xml->status->status_code = 200)
{
  // récupération de l'identifiant de la conférence
  $id_conf= $xml->conference->id;

  // appel des participants de la conférence
  $while ($from = each(explode(","$caller_numbers))
  {
    // exécution de la requête > création de la conférence
    $response = file_get_contents($adresse . "?id=" . $access_key . "&amp;from=" . $from . "&amp;to=" . $to);

    // récupération de la réponse de l'API
    $xml=simplexml_load_string($response);
    echo($xml->status->status_code . " - " . $xml->status->status_msg);
  } else {
    echo($xml->status->status_code . " - " . $xml->status->status_msg);
  }
}
?>

L'API interactive voice permet de mettre en place assez facilement un service vocal interactif - c'est-à-dire un dialogue automatisé composé de sons enregistrés et de textes vocalisés, pouvant être guidés grâce aux touches du téléphone en DTMF. L'API interactive voice ne nécessite pas de compétence particulière en téléphonie mais utilise le VoiceXML qui peut être utilisé facilement par un développeur web. La conception d'une interface vocale est cependant particulière, le cheminement de l'utilisateur doit rester très compréhensible, et le langage permet des fonctions nombreuses que l'on ne peut détailler ici. Vous trouverez sur le site api.orange.com quelques exemples prêts à l'emploi de VXML pour vous aider à démarrer, comme ci-dessous une question avec saisie de réponse DTMF. Les fonctions de base que vous pouvez utiliser dans les scripts VXML sont : vocaliser un texte, jouer un fichier son, enregistrer une saisie DTMF, enregistrer un son, et gérer les appels depuis votre service vocal : déclencher un appel sortant vers un téléphone, transférer un appel en cours, etc...

L'API peut servir pour automatiser des contacts clients (accueil téléphonique, service après-vente, ...), automatiser des campagnes d'appels, diffuser un message enregistré vers une liste de destinataires (le journal de bord des colonies de vacances par exemple), notifier des messages urgents, etc...

La requête est la suivante :
http://voicemashup.alpha.orange-api.net/call/createVoiceMashupCall.xml?id=[clé d'identification]&to= [numéro de téléphone]&url= [URL du premier fichier audio à lire]

<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <form id="start">
    <field name="color" >
      <prompt>
        Veuillez sélectionner votre couleur préférée
        <emphasis>1</emphasis>pour le jaune
        <emphasis>2</emphasis>pour le rouge
      </prompt>
      <!-- L'appelé choisit son option et le choix est enregistré. 
           La voix informe l'appelé. -->
      <option accept="approximate" dtmf="1" value="yellow" >one</option>
      <option accept="approximate" dtmf="2" value="red" >two</option>
    </field>
    <block>
      <prompt>Merci ! Votre choix a été enregistré.</prompt>
      <!-- Validation, envoi du formulaire et retour au début du script.-->
      <submit next="#" namelist="" method="post" />
    </block>
  </form>
</vxml>