Guide Solutions MKT

Le guide des solutions MKT

Retour au guide

API SMS

1 - Introduction

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 SMS
  • recevoir les accusés de réception de vos envois

2 - Activation de votre compte

Lors 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.

3 - Les différentes variables utilisées

Champs Description Longueur Exemple
cle
Clé 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.
16
ma_cle
pass
Mot de passe. Peut-être changé, systématiquementfourni.
16
passe
ID
Identifiant 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.
16
test
ID2
Champ facultatif. Peut servir à vos propres identifiants clients par exemple.
16
client 1
ID3
Champ facultatif. Peut servir à vos propres identifiants clients par exemple.
16
client 2
liste
Identifiant d’une liste
10
1
numero
Numéro de téléphone au format e164
20
33619000000
nom
Permet la personnalisation des messages à l’aide de ##NOM##
32
Dupont
prenom
Permet la personnalisation des messages à l’aide de ##PRENOM##
32
Patrick
usr1
Permet la personnalisation des messages à l’aide de ##USR1##
32
pat
usr2
Permet la personnalisation des messages à l’aide de ##USR2##
32
pat
numeros
Liste de numéros au format e164
20
contenu
Contenu du message à envoyer ou reçu.Les messages envoyés ne doivent pas faire plus de 160 caractères.
160
Ceci est un message de test !
type
STANDARD : envoi d’un SMS simple. REPONSE : possibilité de recevoir les réponses
8
STANDARD
date
Date approximative à laquelle le message doit être délivré ou date à laquelle un message a été reçu. Elle a le format YYYYMMDDHHiiSS
14
20160806181000
emetteur
Permet 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.
16
Axialys
ttl
Date limite d’envoi au-delà de laquelle le message ne pourra plus être transmis.
14
20160806181000
marketing
Permet de spécifier le type d’envoi : 1 : envoi marketing 0 : envoi de type notification
format
Permet 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
json
encodage
UTF-8 : permet de passer certaines données en UTF-8 à la place de l’ISO-8859- 1
mode_envoi
LATIN1 : 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
URL
##TRACKINGURL## utilisé par le shorturl, et sera remplacé par une adresse axialys plus courte sous la forme « axia.ly/XXXXXXX » sans le préfixe http/https que tout mobile est en mesure d’interpréter aujourd’hui. Par contre bien préciser « http/https » lors de la configuration de cette variable et éviter les accents et ne pas dépasser les 128 caractères
128
https://guide.axialys.com/welcome

4 - Gestion des abonnés de liste

Il 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 liste
  • reset_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.
4.1. Méthode « GET_ABONNES »

Les variables utilisées par cette méthode sont :

  • Obligatoires : cle, pass, liste
  • Facultatives : –

L’URL appelée a la forme suivante : http://api-sms.axialys.net/get/get_abonnes.php?cle=macle&pass=pass&liste=10&numero=336100000000

Cet 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ésultats

OK 33619471505;dd

En 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.

4.2. Méthode « ADD_ABONNES »

Les variables utilisées par cette méthode sont :

  • Obligatoires : cle, pass, liste, numero
  • Facultatives : pseudo, nom, prenom, usr1, usr2, encodage

L’URL appelée a la forme suivante : http://api-sms.axialys.net/get/add_abonne.php?cle=macle&pass=pass&liste=10&nom=david&prenom=david

Si l’insertion se passe correctement, l’appel renvoi ‘OK’.

4.3. Méthode « DEL_ABONNE »

Les variables utilisées par cette méthode sont :

  • Obligatoires : cle, pass, liste, numero
  • Facultatives : –

L’URL appelée a la forme suivante : http://api-sms.axialys.net/get/del_abonne.php?cle=macle&pass=pass&liste=10&numero=336100000000

Cet appel renvoie ‘OK’, si la suppression réussie.

4.4. Méthode « RESET_ABONNES »

Les variables utilisées par cette méthode sont :

  • Obligatoires : cle, liste
  • Facultives : encodage

Cette 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.

4.5. Méthode « UPDATE_ABONNE »

Les variables utilisées par cette méthode sont :

  • Obligatoires :cle, liste, numero
  • Facultatives : pseudo, nom, prenom, usr1, usr2, encodage

Cette méthode s’utilise de la même façon que « add_abonne », elle renvoie le message ‘OK’ si la mise à jour réussie.

4.6. Méthode « ADD_LISTE »

Les variables utilisées par cette méthode sont :

  • Obligatoires : cle, pass, nom
  • Facultatives : –

L’URL appelée a la forme suivante : http://api-sms.axialys.net/get/add_liste.php?cle=macle&pass=pass&nom=maPetiteListe

Cette méthode renvoie le message ‘OK’ en cas de succès.

4.7. Méthode « UPDATE_LISTE »

Les variables utilisées par cette méthode sont :

  • Obligatoires : cle, pass, liste, nom
  • Facultatives : –

L’URL appelée a la forme suivante : http://api-sms.axialys.net/get/update_liste.php?cle=macle&pass=pass&liste=1&nom=maPetiteListe

Cette méthode renvoie le message ‘OK’ suivi de l’identifiant attribué à la liste.

4.8. Méthode « CANCEL »

Les variables utilisées par cette méthode sont :

  • Obligatoires : cle, pass
  • Facultatives : numero,liste, type, date, ttl, ID2, emetteur

L’URL appelée a la forme suivante : http://api-sms.axialys.net/get/cancel.php?cle=macle&pass=pass&numeros[]=33670200200&format=json

Cette 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

5 - Envoi des SMS

Un 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, ID
  • Facultatives : numero, liste, type, date, ttl, ID2, ID3, emetteur, mode_envoi, URL

Voici la forme d’un message envoyé à une liste de diffusion : http://api-sms.axialys.net/get/send.php?cle=dd&ID2=axe&ID3=test&pass=pass&liste=10&id=ax&contenu=coucou+dd&emetteur=AXIALYS

Voici la forme d’un message envoyé à plusieurs numéros : http://api-sms.axialys.net/get/send.php?cle=dd&ID2=axe&pass=pass&numeros[]=336100000000&numeros[]=336100000001&id=ax&contenu=coucou+dd

Tout 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.

6 - Réception des SMS MO

Si 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 Description
Type
MO
ID
Identifiant du message fourni lors de l’envoi
numero
Numéro concerné au format e164
date
Date de réception d’un acquittement ou suivi du message
Etat
Message retourné

7 - Décompte des SMS

Pour 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.

Type/Coût 1 SMS 2 SMS 3 SMS 4 SMS 5 SMS
Notification
160
280
420
560
700
Marketing sans personnalisation
150
270
410
550
690
Marketing avec personnalisation
150
270
410
550
690
Caractères étendus
70
134
201
268
335

8 - Réception des accusés de réception

Si 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 Description
Type
ACK
ID
Identifiant du message fourni lors de l’envoi
numero
Numéro concerné au format e164
date
Date de réception d’un acquittement ou suivi du message
Etat
La liste des états possibles se trouve en annexe

9 - Envoi des SMS via e-mail

Notre 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 : :

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.

9.1. Authentification

L’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.

9.2. Les variables obligatoires

Pour 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:axialys

contenu:Bonjour ##PRENOM## ##NOM##, vous avez gagné ##USR1##

9.3. Les variables facultatives

Il 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:axialys

date:20111010101010

ttl:20111020101010

 

10 - Envoi des SMS via FTP

L’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 à traiter
  • traitement : données en cours de traitement
  • archive : 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 message
  • e164 : numéro de téléphone auquel envoyer le SMS
  • contenu : message à envoyer
  • date : date d’envoi du message
  • emetteur : nom à afficher dans l’émetteur du message
  • ttl : non utilisé
  • ref : référence du message
  • marketing : permet d’activer le mode marketing quand le champ est à « 1 ».
  • inutilisé
  • URL : l’URL qui sera remplacé par un short URL, elle n’est valable qu’un mois, le lien sera sous la forme « axia.ly/XXXXXXX » sans le préfixe http/https que tout mobile est en mesure d’interpréter aujourd’hui. Dans le cas de l’utilisation du shorturl, ne pas oublier d’utiliser dans le message «##TRACKINGURL## » qui sera remplacé par la short URL

.

11 - Annexes

11.1. Les erreurs retournées lors des appels HTTP

Voici la liste des codes erreurs retournés :

Code Description
1
Méthode non trouvée
2
Problème d’identification
3
La liste retournée est vide
4
L’ajout d’un abonné a échoué
5
La suppression d’un abonné a échoué
6
Le champ numéro est mal rempli
7
Aucune liste ou numéro de destination n’a été configuré(e)
8
Aucun message n’a été paramétré
9
La date limite est inférieure à la date d’envoi
10
Envoi échoué
13
Erreur interne

Les messages d’erreur ont la forme suivante : NO;<code erreur>;<message d’erreur>

11.2. Les différents états possible d’un message

Voici la liste des différents états par lesquels un message envoyé peut passer :

Code Description
1
Message envoyé
2
Problème plateforme
5
Message expiré
6
Syntaxe invalide
7
Hors zone de couverture
8
Erreur inconnue
9
Service temporairement indisponible
10
Abonné inconnu
11
Numéro porté
12
En cours
13
Message reçu
14
Destination non incluse dans le forfait
15
Destination black-listée
16
Téléphone incompatible
17
Solde insuffisant
18
Message indélivrable
20
En attente d’envoi
21
En attente d’envoi massif (interne)
23
Numéro invalide
24
Abonné inaccessible
11.3. Jeu de caractères autorisés dans les SMS

Le 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.

Pour forcer l’utilisation de caractères non latin, il faut configurer la variable «mode_envoi » avec la valeur « ETENDU ».

12 - Modifications/Evolutions

Date Version Modifications/évolutions
08/2017
1.8
Gestion des shorts URL.
01/2015
1.7
Gestion des caractères étendus
06/2014
1.6
Gestion du STOP et du retour
02/2013
1.5
Mise à jour
04/2011
1.3
Personnalisation de l’émetteur
10/2010
1.2
Possibilité d’envoyer un SMS par mail
01/2008
1.1
Version initiale
  • Table des matières