Une API est disponible pour envoyer des SMS à partir de votre système d'information.

Seuls les envois vers des mobiles français sont gérés par l'API. Les envois sont effectués en direct opérateur (SMS Premium), cela permet de gérer les réponses et les désabonnement sur un numéro court.

Contrairement à la plateforme d'envoi SMS, les heures d'envoi ne sont pas restreintes, cependant notez bien que les envois de SMS marketing sont interdits entre 20h et 8h, ainsi que les dimanches et les jours fériés. Seuls les SMS transactionnels sollicités sont autorisés dans ces plages horaires.

Le point d'entrée est : https://www.eml-srv.com/_api_rest/api_sms_submit

Authentification

L'API est au format REST et est accessible à l'aide d'une authentification HTTP Basique.

Fonctionnement de l'authentification

Si votre nom d'utilisateur est "monlogin" et votre mot de passe monmotdepasseABC
Vous devez créer la chaine suivante : monlogin:monmotdepasseABC
Puis l'encoder en base 64 : bW9ubG9naW46bW9ubW90ZGVwYXNzZUFCQw==

La propriété suivante devra être ajoutée à votre en-tête HTTP :
"Authorization" : "Basic bW9ubG9naW46bW9ubW90ZGVwYXNzZUFCQw=="

Exemple en PHP avec CURL

Curl permet de gérer facilement l'authentification HTTP BASIC :

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://www.eml-srv.com/_api_rest/api_sms_submit');
curl_setopt($ch, CURLOPT_USERPWD, "monlogin:monmotdepasseABC");
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
$output = curl_exec($ch);

Envoyer un SMS

Attention, toutes les chaînes de caractère, et notamment le message qui peut contenir des caractères spéciaux, doivent être encodés en UTF-8.

Les paramètres doivent être formatés en JSON.

Paramètres

Text : le texte de votre message

TrackingId : La chaine de caractères de votre choix. Il s'agit de la référence de votre tâche qui sera rappelée par la suite et vous permettra de retrouver facilement votre envoi.
Ce champ est optionnel.

AdhocRecipients : La liste des numéros de mobile à qui doivent être envoyés le message.
Il s'agit d'un tableau ayant pour clé "Number" et comme valeur le numéro de mobile du destinataire.

Sender : Une chaine de 11 caractères maximum ne pouvant contenir que des lettres et des chiffres (1-Za-z0-9), des espaces ou des points.
Ce champ est optionnel. S'il est vide ou omis, l'expéditeur du SMS sera un numéro court français.
Si ce champ est personnalisé, les destinataire ne pourra pas répondre au SMS, ni se dés inscrire en répondant "STOP".
Si ce champ est personnalisé le texte "STOP XXXXX" sera automatiquement ajouté à votre message. Cette chaine fait 16 caractères.

Formats de numéros acceptés

Deux formats sont acceptés :

  • Français : 06XXXXXXXX ou 07XXXXXXXX
  • International : +336XXXXXXXX ou +337XXXXXXXXX

Exemples de requête

Envoi avec personnalisation de l'expéditeur sur un seul destinataire

{
     "Text": "Ceci est un test", 
     "TrackingId": "mon_id_de_suivi",
     "AdhocRecipients": [
          {
               "Number": "+337xxxxxx"
          }
     ]
}

Envoi sans personnalisation de l'expéditeur sur deux destinataires

{
     "Text": "Ceci est un test", 
     "TrackingId": "mon_id_de_suivi",
     "AdhocRecipients": [
          {
               "Number": "+337xxxxxx"
          },
          {
               "Number": "+336xxxxxx"
          }
     ],
     "Sender": "Ediware"
}

Exemple d'envoi en PHP

$url = 'https://www.eml-srv.com/_api_rest/api_sms_submit';

$username = 'monlogin';
$password = 'motmotdepasse';

$msg = 'Ceci est un message encodé en UTF-8';

// Création du tableau de paramètres

$data_to_post = array(
    'Text' => $msg,
    'TrackingId' => 'mon_id_de_tracking_interne',
    'AdhocRecipients' => array(
        array(
            'Number' => '+336XXXXXXXX'
        ), // je peux ajouter jusqu'à 100 numéros
    ),
'Sender' => 'EDIWARE',
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_USERPWD, "$username:$password");
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data_to_post));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
$output = curl_exec($ch);
curl_close($ch);



// die($output); // pour débogguer facilement

$output = json_decode($output);

// var_dump($output); // traitement de la réponse

Gestion de la réponse

La réponse est au format JSON.
En cas d'erreur
{"Message":"détail du message d'erreur"}
Les erreurs possibles sont :
  • Auth protocol error : le login ou le mot de passe ne sont pas défini, ou le protocole est erroné
  • Auth error : le protocole est correct mais les identifiants sont faux
  • Unknown error - no id : erreur système interne
  • SMS Module desactivated for this account : le module SMS n'est pas activé sur votre compte
  • No more SMS credits : vous n'avez plus de crédits d'envoi
  • Empty message : le message à envoyer est vide
  • Message too long, nothing was sent : le message doit faire moins de 700 caractères
  • Wrong number nothing was sent : un numéro était au mauvais format. Dans ce cas la totalité du process est abandonné.
En cas de réussite

Un numéro de process est communiqué. Ce numéro est à stocker de votre côté, c'est un moyen de retrouver facilement le statut des envois.
Le nombre de crédits décomptés par le process est également indiqué pour information.

Exemple : {"JobNumber":"Numero unique du process", "Cost":"1"}

A propos de la longueur des messages

Un SMS ne peut contenir que 160 caractères.

Si l'expéditeur est personnalisé, 12 caractères sont utilisés pour ajouter un moyen de se désabonner (STOP XXXXX). La loueur maximale est donc de 148 caractères.

Si vous envoyez un message plus long, un ou plusieurs crédits supplémentaires seront décomptés.
Pour SMS avec expéditeur non personnalisé, le forfait sera donc de :
1 crédit jusqu'à 160 caractères
2 crédits jusqu'à 306 caractères
3 crédits jusqu'à 459 caractères
4 crédits jusqu'à 612 caractères
5 crédits jusqu'à 612 caractères
6 crédits au delà, cependant nous ne pouvons pas envoyer de SMS de plus de 700 caractères.

Une particularité : le sigle € compte pour deux caractères en raison du fonctionnement de l'encodage des SMS.

Récupérer le statut de ses envois

Via un webhook HTTP

L'URL sur laquelle doivent être postés les événements doit être renseignée dans la rubrique Campagnes SMS >  API > Webhooks.

Via l'interface Web

Dans la rubrique Campagnes SMS > API, vous pouvez visualiser les derniers envois effectués ainsi que leur statut.
Vous avez également la possibilité de télécharger les réponses via la page Campagnes SMS > Réponses