Services mobiles et services vocaux pour le web

Les API d’Orange sont des web services puissants et simples de mise en œuvre, qui permettent d’intégrer des services mobiles ou vocaux dans vos sites web et applications métier. Sans restriction d’usage, elles peuvent être utilisées à titre personnel ou professionnel, et ne sont généralement pas limitées au réseau Orange, mais couvrent la plupart des opérateurs dans le monde. Cet article propose un tour d’horizon rapide de quelques-unes des API d’Orange, avec des exemples de mise en oeuvre, et des pistes pour aller plus loin si vous le souhaitez :

• les API d’Orange orientées mobile :
  • envoi et réception de SMS et MMS
  • géolocalisation de mobiles Orange

• les API d’Orange orientées voix :
  • click-to-call création d'appels entre 2 téléphones
  • click-to-conf pilotage de conférences téléphonique à plusieurs
  • interactive voice ou comment créer son répondeur vocal interactif avec des technologies web

Les API d’Orange sont accompagnées d’exemples de code, de tutoriels, et de SDK (php, java, C#) disponibles gratuitement. En complément des API d’Orange présentées dans cet article, vous pourrez aussi trouver des outils et des offres complémentaires sur le site orange.api.com : un bac à sable, un explorateur des API permettant de tester en direct les API, des services assez simples et prêts à l’emploi, intégrables en quelques clics dans vos sites (les « Easy Solutions »), et des services plus spécifiques (les « Custom Solutions »).

Pour utiliser les API d’Orange, il suffit de ...

Tout d’abord vous devez vous enregistrer sur le site http://api.orange.com - l’inscription est gratuite et donne droit à 200 crédits pour faire vos premiers pas. Vous pourrez récupérer votre clé d’accès dans votre espace personnel, cette clé sera utilisée ultérieurement pour identifier tous vos appels aux API d’Orange. (Il est bien sûr important de ne jamais la divulguer.)

Il existe des API gratuites, des API payantes, et des API rémunératrices. Pour consommer des API payantes, vous devrez disposer de crédits que vous pouvez acheter avec une carte bancaire ou par prélèvement, ou selon certains contrats spécifiques, mais pour le moment vous pouvez utiliser vos premières APIs avec les crédits de bienvenue.

Les API d’Orange sont basées sur un style hybride REST-RPC, c’est-à-dire une interface XML sur HTTP(s). Pour les invoquer, vous pouvez utiliser un simple browser, (le plus simple pour démarrer), ou n’importe quel langage de programmation capable d’effectuer simplement des requêtes http GET et POST et de parser les résultats en XML … le choix est donc très large !

Envoyer un SMS

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 …

Envoyez cette requête en mettant à jour tous les paramètres (id, to, content), depuis votre navigateur web, et vous obtiendrez une réponse en XML, avec au minimum, un code et un message de statut de la réponse. Le numéro du mobile de destination doit être au format international. Ex : 3312345678 (France) ou 441234567890 (Royaume-Uni).

http://sms.beta.orange-api.net/sms/sendSMS.xml?id=[clé d’identification]&to=[numéro de téléphone]&content=[message à envoyer]

Voici un exemple très simple dans une application en PHP :

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

// adresse de l'API SMS
$adresse = "http://sms.beta.orange-api.net/sms/sendSMS.xml";

// numéro de téléphone du destinataire (au format international)
$to = "33XXXXXXXXX";

// contenu du message
$content = "Hello world !";

// exécution de la requête > envoi du SMS
$response = file_get_contents($adresse . "?id=" . $access_key . "&to=" . $to . "&$content=" . $content);

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

?>

Recevoir un 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é 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).

Mettre en relation 2 téléphones

L’API Click-to-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]&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]

Voici un exemple de code PHP à insérer dans votre application :

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

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

// 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 . "&to=" . $to . "&$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);

?>

Liens utiles

le site des API d’Orange

http://api.orange.com/

l’espace personnel pour la configuration des API, le self-care

http://api.orange.com/fr/mon-espace-personnel/mes-api

les documentations de l’ensemble des API 

http://api.orange.com/fr/all-api

Les FAQs, les tutoriaux, les forums, les SDK et l’Explorer tool

http://api.orange.com/fr/support-api

la communauté des API d’Orange

http://feedback.api.orange.com

le blog des API d’Orange

http://blog.api.orange.com