Cette page décrit les différentes fonctionnalités de l’API d’Axialys pour l’envoi de SMS ainsi que la façon de procéder pour les mettre en oeuvre.Vous pourrez ainsi :envoyer des SMSrecevoir les accusés de réception de vos envoisHaut de page
1. Activation de votre compteLors de la création de votre compte, vous pouvez nous fournir l’adresse IP de la machine qui interrogera le serveur ainsi que l’adresse et l’URI du serveur auquel les accusés de réception devront être renvoyés (si vous souhaitez activer cette fonctionnalité). Une fois votre compte créé, une clé vous sera fournie, accompagnée des paramètres du serveur à interroger.Haut de page
2. Les différentes variables utiliséesChampsDescriptionLongueur cleClé permettant d’identifier le client. Elle doit être systématiquement envoyée. Il est également possible de définir l’adresse IP de la machine autorisée à accéder à votre compte.16ma_clepassMot de passe. Peut-être changé, systématiquementfourni.16passeIDIdentifiant d’envoi. Ce champ est facultatif, vous pouvez mettre ce que vous voulez ; il vous permettra ensuite de faire correspondre un accusé de réception ou un message reçu, à un envoi.16testID2Champ facultatif. Peut servir à vos propres identifiants clients par exemple.16client 1ID3Champ facultatif. Peut servir à vos propres identifiants clients par exemple.16client 2listeIdentifiant d’une liste101numeroNuméro de téléphone au format e1642033619000000nomPermet la personnalisation des messages à l’aide de ##NOM##32DupontprenomPermet la personnalisation des messages à l’aide de ##PRENOM##32Patrickusr1Permet la personnalisation des messages à l’aide de ##USR1##32patusr2Permet la personnalisation des messages à l’aide de ##USR2##32patnumerosListe de numéros au format e16420contenuContenu du message à envoyer ou reçu.Les messages envoyés ne doivent pas faire plus de 160 caractères.160Ceci est un message de test !typeSTANDARD : envoi d’un SMS simple. REPONSE : possibilité de recevoir les réponses8STANDARDdateDate approximative à laquelle le message doit être délivré ou date à laquelle un message a été reçu. Elle a le format YYYYMMDDHHiiSS1420160806181000emetteurPermet de configurer l’émetteur du message, on peut utiliser une chaîne de caractère ou un numéro au format e164. La personnalisation de l’émetteur n’est pas compatible avec la réception d’éventuels messages de retour.16AxialysttlDate limite d’envoi au-delà de laquelle le message ne pourra plus être transmis.1420160806181000marketingPermet de spécifier le type d’envoi : 1 : envoi marketing 0 : envoi de type notificationformatPermet de sélectionner le format de sortie de l’API, actuellement sont disponibles :* csv (défault ancien format, l’entête du CSV retourné n’est pas toujours disponible) * csv_header * json jsonencodageUTF-8 : permet de passer certaines données en UTF-8 à la place de l’ISO-8859- 1 mode_envoiLATIN1 : utilisation d’un sous ensemble de l’ISO-8859- 1 ETENDU : utilisation des caractères étendus (ATTENTION, la taille des SMS est fortement réduite, voir Tableau de la section VI, de plus il est alors nécessaire de passer le contenu du message à envoyer en UTF-8 )LATIN1 Attention selon le type de contrat souscrit, le type de SMS ne sera pas forcément pris en compteHaut de page
3. Gestion des abonnés de listeIl est possible de définir des listes d’abonnés, afin de pouvoir envoyer par la suite un message à un ensemble de personnes prédéfinies.Pour les gérer vous disposez de 5 fonctionnalités :get_abonnes : Pour obtenir l’ensemble des abonnés d’une liste.add_abonne : Pour ajouter un abonné à une liste.del_abonne : Pour supprimer un abonné d’une listereset_abonnes : Pour supprimer tous les abonnés d’une liste.update_abonne : Pour mettre à jour les données d’un abonné (basées sur le numéro).add_liste : Pour ajouter une liste.update_liste : Pour mettre à jour les attributs d’une liste.3.1. Méthode « GET_ABONNES »Les variables utilisées par cette méthode sont :Obligatoires : cle, pass, listeFacultatives : –L’URL appelée a la forme suivante : http://api-sms.sites.axialys.net/get/get_abonnes.php?cle=macle&pass=pass&liste=10&numero=336100000000Cet appel retourne alors une page contenant l’ensemble des numéros appartenant à cette liste ainsi que les données associées (nom, prenom, usr1, usr2). Seuls les champs contenant une valeur sont retournés, voici un exemple renvoyant 2 résultatsOK 33619471505;ddEn absence de données, c’est alors un message d’erreur qui est retourné. La liste des codes erreurs retournés se trouve en annexe.3.2. Méthode « ADD_ABONNES »Les variables utilisées par cette méthode sont :Obligatoires : cle, pass, liste, numeroFacultatives : pseudo, nom, prenom, usr1, usr2, encodageL’URL appelée a la forme suivante : http://api-sms.sites.axialys.net/get/add_abonne.php?cle=macle&pass=pass&liste=10&nom=david&prenom=davidSi l’insertion se passe correctement, l’appel renvoi ‘OK’.3.3. Méthode « DEL_ABONNE »Les variables utilisées par cette méthode sont :Obligatoires : cle, pass, liste, numeroFacultatives : –L’URL appelée a la forme suivante : http://api-sms.sites.axialys.net/get/del_abonne.php?cle=macle&pass=pass&liste=10&numero=336100000000Cet appel renvoie ‘OK’, si la suppression réussie.3.4. Méthode « RESET_ABONNES »Les variables utilisées par cette méthode sont :Obligatoires : cle, listeFacultives : encodageCette méthode s’utilise de la même façon que « get_abonnes », elle renvoie le message ‘OK’ si la suppression de tous les abonnés réussie.3.5. Méthode « UPDATE_ABONNE »Les variables utilisées par cette méthode sont :Obligatoires :cle, liste, numeroFacultatives : pseudo, nom, prenom, usr1, usr2Cette méthode s’utilise de la même façon que « add_abonne », elle renvoie le message ‘OK’ si la mise à jour réussie.3.6. Méthode « ADD_LISTE »Les variables utilisées par cette méthode sont :Obligatoires : cle, pass, nomFacultatives : –L’URL appelée a la forme suivante : http://api-sms.sites.axialys.net/get/add_liste.php?cle=macle&pass=pass&nom=maPetiteListeCette méthode renvoie le message ‘OK’ en cas de succès.3.7. Méthode « UPDATE_LISTE »Les variables utilisées par cette méthode sont :Obligatoires : cle, pass, liste, nomFacultatives : –L’URL appelée a la forme suivante : http://api-sms.sites.axialys.net/get/update_liste.php?cle=macle&pass=pass&liste=1&nom=maPetiteListeCette méthode renvoie le message ‘OK’ suivi de l’identifiant attribué à la liste.3.8. Méthode « CANCEL »Les variables utilisées par cette méthode sont :Obligatoires : cle, passFacultatives : numero,liste, type, date, ttl, ID2, emetteurL’URL appelée a la forme suivante : http://api-sms.sites.axialys.net/get/cancel.php?cle=macle&pass=pass&numeros[]=33670200200&format=jsonCette méthode permet d’annuler un envoi, elle retourne ‘OK’ si la suppression a été effectuée, ainsi que le nombre de lignes supprimées.Haut de page
4. Envoi des SMSUn message peut être envoyé à un ou plusieurs numéros, il est également possible de l’envoyer à une liste de diffusion prédéfinie avec les méthodes vues précédemment. Les variables utilisées par cette méthode sont :Obligatoires : cle, IDFacultatives : numero, liste, type, date, ttl, ID2, ID3, emetteur, mode_envoiAttention, au minimum une liste ou un numéro doit être défini(e) afin de pouvoir envoyer un message.Voici la forme d’un message envoyé à une liste de diffusion : http://api-sms.sites.axialys.net/get/send.php?cle=dd&ID2=axe&ID3=test&pass=pass&liste=10&id=ax&contenu=coucou+dd&emetteur=AXIALYSVoici la forme d’un message envoyé à plusieurs numéros : http://api-sms.sites.axialys.net/get/send.php?cle=dd&ID2=axe&pass=pass&numeros[]=336100000000&numeros[]=336100000001&id=ax&contenu=coucou+ddTout comme les précédentes méthodes, l’appel renvoie ‘OK’, une fois les données intégrées. Si le SMS à envoyer est de type ETENDU, le texte du SMS doit être au format UTF-8.ATTENTION, la taille des SMS est fortement réduite, un texte contenant 135 caractères compte pour 3 SMS, voir Tableau de la section 5.Haut de page
5. Réception des SMS MOSi un utilisateur répond à un message, il est possible de récupérer son message. L’url à laquelle sera envoyée la réponse est la même que pour les notifications.Les variables reçues sont les suivantes :Variable TypeMOIDIdentifiant du message fourni lors de l’envoinumeroNuméro concerné au format e164dateDate de réception d’un acquittement ou suivi du messageEtatMessage retournéHaut de page
6. Décompte des SMSPour se mettre en conformité avec la législation, lors des envois marketing, une information est ajoutée pour l’utilisateur afin que ce dernier puisse cesser l’envoi des SMS. Il lui suffit en effet de répondre “STOP” au message reçu. Il faut déduire du message envoyé la longueur du message d’annonce.Marketing avec personnalisation : STOP XXXXX (10 caractères)Marketing sans personnalisation : STOP XXXXX (10 caractères)Ceci est valable uniquement pour la France pour le moment.Pour rappel, un SMS fait 160 caractères, et les SMS composés sont constitués de maximum 5 SMS, chaque portion valant 140 caractères. Les retours à la ligne comptent pour 2 caractères. Type/Coût1 SMS2 SMS3 SMS4 SMS5 SMSNotification160280420560700Marketing sans personnalisation150270410550690Marketing avec personnalisation150270410550690Caractères étendus70134201268335Haut de page
7. Réception des accusés de réceptionSi vous disposez d’un serveur capable de recevoir des requêtes HTTP, et après l’envoi des informations concernant votre serveur nom et URI à utiliser, vous avez la possibilité de recevoir toutes les informations concernant le statut du message envoyé. Pour un même message envoyé à un téléphone donné, vous pouvez recevoir plusieurs informations de statut. Par exemple au moment de l’envoi, le mobile peut être en dehors de la zone de couverture du réseau, le message sera alors reçu quand le téléphone se trouvera dans une zone de couverture. On est alors averti à chaque changement d’état, jusqu’à ce que le message soit transmis. Voici ci-dessous les valeurs retournées :Variable TypeACKIDIdentifiant du message fourni lors de l’envoinumeroNuméro concerné au format e164dateDate de réception d’un acquittement ou suivi du messageEtatLa liste des états possibles se trouve en annexeHaut de page
8. Envoi des SMS via e-mailNotre plateforme offre également la possibilité d’envoyer des SMS en envoyant un mail. Afin d’envoyer des SMS tous les paramètres concernant le ou les envois sont envoyés dans le corps du mail sous la forme suivante : <nom variable>: <valeur>Le mail sera ensuite envoyé à l’adresse [email protected] En cas de problème : variable manquante, problème d’authentification… Un message d’erreur vous sera renvoyé contenant la description du problème rencontre.8.1. AuthentificationL’authentification est effectuée par rapport à l’adresse de l’expéditeur qui nous a été fournie lors de l’activation de votre API. Il est également possible de nous fournir une liste d’adresses IP autorisées à renvoyer des SMS sous votre compte.8.2. Les variables obligatoiresPour effectuer votre envoi, nous avons d’abord besoin de savoir à qui il est destiné. Pour cela nous devons obligatoirement renseigner les variables ‘numero’ ou ‘liste’ qui sont respectivement un numéro de téléphone ou le nom d’une liste sur laquelle nous souhaitons effectuer notre envoi. Dans le cas d’utilisation de la variable ‘numero’, il est possible d’indiquer plusieurs numéros de téléphone en les séparant par une virgule.Nous devons ensuite renseigner notre message avec la variable ‘contenu’ en faisant bien attention qu’elle ne contienne pas de caractères non autorisés.Dans le cas d’envoi à une liste, il est également possible de personnaliser le message pour chaque contact de cette liste à l’aide des variables :##NOM##, ##PRENOM##, ##USR1##, ##USR2##liste:axialyscontenu:Bonjour ##PRENOM## ##NOM##, vous avez gagné ##USR1##8.3. Les variables facultativesIl est ensuite possible de programmer l’envoi à une date donnée ou de fixer une date de fin de validité avec respectivement les variables ‘date’ et ‘ttl’.Attention, ces variables devront toujours préciser la variable ‘contenu’.Et enfin, vous disposez de 3 variables vous permettant d’identifier vos envois ou éventuellement faciliter la facturation de vos clients : ID, ID2 et ID3.liste:axialysdate:20111010101010ttl:20111020101010Haut de page
9. Envoi des SMS via FTPL’envoi des SMS peut être effectué par dépôt d’un fichier FTP. Le dépôt est constitué des répertoires ci-dessous :attente : dossier dans lequel doit être déposé le fichier à traitertraitement : données en cours de traitementarchive : sauvegarde des données traitées.Le fichier à traiter doit être au format ISO-8859- 1, sauf si l’on souhaite utiliser les caractères étendus ; dans ce cas le fichier sera au format UTF-8 et devra obligatoirement avoir le format suivant : « *_ETENDU.csv ».Les colonnes disponibles sont :ID : identifiant messagee164 : numéro de téléphone auquel envoyer le SMScontenu : message à envoyerdate : date d’envoi du messageemetteur : nom à afficher dans l’émetteur du messagettl : non utiliséref : référence du messagemarketing : permet d’activer le mode marketing quand le champ est à « 1 ».Attention ce champ n’est utilisé que si votre compte a accès aux envois marketing et aux alertes.Haut de page
10. Annexes10.1. Les erreurs retournées lors des appels HTTPVoici la liste des codes erreurs retournés :CodeDescription1Méthode non trouvée2Problème d’identification3La liste retournée est vide4L’ajout d’un abonné a échoué5La suppression d’un abonné a échoué6Le champ numéro est mal rempli7Aucune liste ou numéro de destination n’a été configuré(e)8Aucun message n’a été paramétré9La date limite est inférieure à la date d’envoi10Envoi échoué13Erreur interneLes messages d’erreur ont la forme suivante : NO;<code erreur>;<message d’erreur>10.2. Les différents états possible d’un messageVoici la liste des différents états par lesquels un message envoyé peut passer :CodeDescription1Message envoyé2Problème plateforme5Message expiré6Syntaxe invalide7Hors zone de couverture8Erreur inconnue9Service temporairement indisponible10Abonné inconnu11Numéro porté12En cours13Message reçu14Destination non incluse dans le forfait15Destination black-listée16Téléphone incompatible17Solde insuffisant18Message indélivrable20En attente d’envoi21En attente d’envoi massif (interne)23Numéro invalide24Abonné inaccessible10.3. Jeu de caractères autorisés dans les SMSLe jeu de caractères supporté par Axialys dans le contenu du message est un sous ensemble du ISO-8859- 1. Comme défini dans le tableau ci-dessous.ATTENTION, si le client envoie un caractère en dehors de la liste ci-dessous, il sera remplacé par un caractère similaire, voir supprimé. Pour forcer l’utilisation de caractères non latin, il faut configurer la variable «mode_envoi » avec la valeur « ETENDU ».Haut de page
11. Modifications/EvolutionsDateVersionModifications/évolutions01/20151.7Gestion des caractères étendus06/20141.6Gestion du STOP et du retour02/20131.5Mise à jour04/20111.3Personnalisation de l’émetteur10/20101.2Possibilité d’envoyer un SMS par mail01/20081.1Version initialeHaut de page