Mobyt Intégration par Webservice TABLE DES MATIERES

Transcription

1 Mobyt Intégration par Webservice TABLE DES MATIERES INTRODUCTION... 2 CONFIGURATION DE LA LIBRAIRIE... 2 ENVOI DE SMS... 3 ÉTAT DES MESSAGES... 4 HISTORIQUE DES MESSAGES... 5 CRÉDIT SMS DISPONIBLE... 6 LECTURE DES MESSAGES REÇUS VIA LE SERVICE DE RÉCEPTION SMS... 6 Mobyt France SAS 2015 Page 1 / 7

2 INTRODUCTION Les serveurs Mobyt mettent à disposition des développeurs des interfaces WebService pour l'envoi et la réception de messages SMS permettant de récupérer les données concernant l'état des messages et l'historique SMS. Si vous souhaitez crypter la connexion, il est possible de faire les mêmes requêtes par le biais d'une connexion https. CONFIGURATION DE LA LIBRAIRIE le WSDL du WebService peut être obtenu à l'adresse : le WebService est compatible SOAP 1.1, maximum de compatibilité avec toutes les versions ; Les paramètres obligatoires des requêtes WebService sont username et password, qui représentent les codes d'authentification pour l'accès au portail mobyt ; un numéro de téléphone en format international est une quelconque séquence de chiffres précédées par le caractère '+' (exemple: +336xxxxxxxx); le type SMS est toujours codifiée par les deux suites de caractères suivantes : o L : SMS Direct (SMS de qualité maximale avec accusé de réception et expéditeur fixe), o N : SMS Top (SMS de qualité maximale avec accusé de réception et expéditeur personnalisé) ; toutes les requêtes qui ne sont pas exécutées lancent un WebService "Fault" (par exemple, dans un environnement.net c'est System.ServiceModel.FaultException) qui contient le code de l'erreur et une description textuelle dans le format suivant : <numeric-errorcode>:<errormessage> les codes nations utilisés ce sont des codes de 2 caractères standards ISO le charset utilisé est UTF-8. Mobyt France SAS 2015 Page 2 / 7

3 ENVOI DE SMS ENVOI DE SMS UNITAIRES : sendsms( String username, String password, String message_type, String sender, String recipient, String message, String order_id) : String ENVOI DE SMS EN NOMBRE : sendmultiplesms( String username, String password, String message_type, String sender, Array Of String recipients, String message, String order_id) : String ENVOI EN DIFFÉRÉ DE SMS UNITAIRES: schedulesms( String username, String password, String message_type, String sender, String recipient, String message, String order_id, Date send_when) : String ENVOI EN DIFFÉRÉ DE SMS EN NOMBRE: schedulemultiplesms( String username, String password, String message_type, String sender, Array of String recipients, String message, String order_id, Date send_when) : String L'envoi de SMS exige les paramètres suivants (paramètres obligatoires): message_type : type de message (N, L) ; recipient/recipients : un numéro ou une liste de numéros de téléphone, en format international ou en format national (en ce cas, la nation de référence est la nation du compte mobyt utilisé) ; message : le corps du message à envoyer peut être composé de 160 caractères (un seul SMS) ou jusqu'à 1000 caractères pour les SMS longs (concaténés). Si le corps du message dépasse les 160 caractères, x SMS de 153 caractères seront débités depuis le compte client. Attention: les caractères ^ { \ [ ~ ] comptent pour 2 caractères; si vous souhaitez fournir une solution de désinscription aux destinataires de vos messages, ajoutez la mention STOP %NUM% à la fin de votre message SMS (%NUM% sera automatiquement remplacé par le numéro court utilisé). Lorsque un destinataire enverra le mot clé STOP au numéro court indiqué, son numéro sera alors blacklisté il sera sur votre liste noire et ne recevra plus de SMS de votre part. sender: l'expéditeur personnalisé peut être un numéro de téléphone en format international jusqu'à un maximum de 16 caractères numériques ou une suite de 11 caractères alphanumériques maximum (ex: " " ou "NomSociete"). Le champ doit rester vide ou être nul pour les types de message sans émetteur personnalisé (N,L), autrement le serveur lance une exception! scheduled_delivery_time: la date et l'heure des envois en différé. Mobyt France SAS 2015 Page 3 / 7

4 Toutes les opérations restituent : order_id : une suite alphanumérique à associer à l'envoi, indispensable pour obtenir les informations concernant l'état des messages. La longueur maximum de ce champ est de 32 caractères; les caractères excédents ne seront pas considérés. Si ce paramètre n'est pas précisé, le serveur en créé un unique pour chaque envoi. ÉTAT DES MESSAGES getsmsstatus(string username, String password, String orderid): Array Of WSMessageStatus WSMessageStatus : class { String recipient String status Date deliverydate Après l'envoi des messages, il est possible d'en vérifier l'état. En utilisant comme seul paramètre le id du SMS (paramètre orderid) il est possible de demander au serveur le résultat de l'envoi. Notre serveur restitue une liste d'objets WSMessageStatus; chacun montre l'état de l'envoi pour chaque destinataire du message. Le champ delivery_date est valorisé exclusivement pour les SMS délivrés sans erreurs (état DLVRD). Le champ status peut prendre les valeurs suivantes : SCHEDULED // programmé, pas encore envoyé SENT // envoyé, il n'attend pas de delivery DLVRD // SMS reçu correctement ERROR // erreur dans l'envoi du SMS TIMEOUT // après 48h l'opérateur n'a pas fourni d'informations TOOM4NUM // trop de SMS pour le même destinataire dans les dernières 24 heures TOOM4USER // trop de SMS envoyés par l'utilisateur pendant les dernières 24 heures UNKNPFX // préfixe SMS invalide ou inconnu UNKNRCPT // numéro de téléphone du destinataire invalide ou inconnu WAIT4DLVR // message envoyé en attente de delivery WAITING // en attente, pas encore envoyé UNKNOWN // état inconnu Mobyt France SAS 2015 Page 4 / 7

5 Il est également possible de recevoir l'état des messages via HTTP/POST sur une adresse spécifique; les paramètres sont : order_id: identifiant univoque alphanumérique associé au SMS créé au moment de l'envoi ; recipient: numéro de téléphone du destinataire du SMS ; status: chaîne contenant l'état du message dont les valeurs possibles sont indiquées ci-dessus ;delivery_date: date/heure de réception du SMS sur le téléphone du destinataire, seulement pour les SMS effectivement délivrés sans erreurs (état DLVRD). Pour activer cette option, contactez-nous à l'adresse help@mobyt.fr. HISTORIQUE DES MESSAGES gethistory(string username, String password, Date from, Date to): Array Of WSSentMessage WSSentMessage : class { String messageid Date date String messagetype String sender int recipients Date sentwhen Il est possible de demander au serveur Mobyt la liste des SMS envoyés dans le laps de temps qui s'écoule entre deux dates spécifiques; le serveur restitue une liste d'objets WSSentMessage. Chaque objet contient le id du message, la date de création, le type de SMS, l'expéditeur (s'il s'agit d'un SMS avec expéditeur personnalisé, autrement le champ est vide), le numéro de téléphone des destinataire et la date/heure d'envoi programmé (si le SMS a été créé comme SMS différé, autrement le champ est vide). Mobyt France SAS 2015 Page 5 / 7

6 CRÉDIT SMS DISPONIBLE POUR APPLICATIONS UN SEUL PAYS / UN SEUL TYPE DE MESSAGE: getavailablesms(string username, String password, String messagetype, String nation) : Long Cette procédure permet de demander le nombre de SMS disponibles pour un messagetype spécifique dans un certain pays. C'est la procédure que nous conseillons d'utiliser en cas d'envoi de SMS destinés principalement à une seule nation. POUR APPLICATIONS COMPLEXES MULTI-NATION / MULTI-CRÉDITS: getcredits(string username, String password) : Array of WSSMSCredit WSSMSCredit : class { String messagetype; String nation; long credit; Permet de connaître la disponibilité de crédit de son compte mobyt. Notre serveur restitue une liste d'objets WSSMSCredit, chacun contenant le type de crédit, la nation d'appartenance (vide si le crédit est international) et la disponibilité de SMS. Le serveur restitue les crédits disponibles pour les types SMS TOP (N), SMS DIRECT (L), ainsi que les crédits pour l'envoi à l'étranger (EE). LECTURE DES MESSAGES REÇUS VIA LE SERVICE DE RÉCEPTION SMS L'utilisateur propriétaire d'un ou plusieurs services de réception SMS (dédié ou partagé) qui décide de demander les messages au serveur mobyt, peut utiliser indifféremment une des méthodes suivantes: getnewreceivedmessages(string username, String password) : Array of WSSRMessage Cette méthode n'a pas besoin de paramètres, elle permet de demander au serveur tous les nouveaux messages, c'est-à-dire, tous les messages reçus à partir de la dernière requête (attention: cette méthode doit être activée par One-etere; si vous souhaitez utiliser cette méthode, contactez-nous à l'adresse help@mobyt.fr. Pour l'intégration dans une application non-web nous conseillons d'utiliser cette méthode. getreceivedmessages(string username, String password, Date from, Date to) : Array of WSSRMessage demande au serveur tous les SMS reçus dans un laps de temps spécifique en utilisant les paramètres date_from et date_to. Mobyt France SAS 2015 Page 6 / 7

7 getreceivedmessagesbyid( String username, String password,long messageid) : Array of WSSRMessage demande tous les SMS reçus qui ont un identifiant univoque supérieur à celui passé comme paramètre; tous les identifiants sont des numéros entiers plus grands que zéro, donc, en passant zéro comme paramètre, vous obtenez en réponse tous les SMS reçu par l'utilisateur; le nom du paramètre de l'identifiant est messageid. Pour toute les requêtes, la réponse prend ce format: WSSRMessage : class { long messageid String receiver String sender String messagetext Date smsdate String keyword Plus précisément, le champ receiver est le numéro de téléphone de la carte SIM pour la réception des SMS et le champ sender est le numéro de téléphone de l'expéditeur du SMS; le champ keyword contient le premier mot du corps du SMS (pour les services de réception partagés). Il est aussi possible de recevoir les messages reçu par HTTP/POST à son adresse, les paramètres sont : id : identifiant univoque du SMS ; text : corps du SMS ; sender : expéditeur du SMS ; recipient : destinataire du SMS, c'est-à-dire, le numéro de son service de réception ; delivery_date : date de réception du SMS. Mobyt France SAS 2015 Page 7 / 7