Préambule

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.

Les URL déclarées dans le module "Lien URL" peut être utilisées dans vos messages envoyés via l'API. Les cliqueurs seront identifiés dans les rapports.

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_v2

La présentation de la plateforme SMS Ediware est ici.

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_v2');
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

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 ainsi que le message associé.
Il s'agit d'un tableau ayant deux clés : "Number" et "Text" et comme valeurs le numéro de mobile du destinataire ainsi que le message.

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

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

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

{
     "AdhocRecipients": [
          {
               "TrackingId": "mon_id_de_suivi",
               "Number": "+337xxxxxx",
               "Text": "Message pour le premier destinataire"
          },
          {
               "TrackingId": "mon_id_de_suivi", 
               "Number": "+336xxxxxx",
               "Text": "Message pour le second destinataire"
          }
     ],
     "Sender": "Ediware"
}

Exemple d'envoi en PHP

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

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


// Création du tableau de paramètres

$data_to_post = array(
    'AdhocRecipients' => array(
        array(
            'TrackingId' => 'mon_id_de_tracking_interne',
            'Number' => '+336XXXXXXXX'
            'Text'   => 'Message de test'
        ), // 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 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

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.

Données envoyées par le webhook de l'API SMS

Il est possible d'envoyer un webhook de test via l'interface pour faciliter vos développements.

Le dictionnaire des valeurs retournées est ci-dessous :

id : identifiant numérique arbitraire généré par la plateforme à usage interne.

date_envoi : date d'envoi du SMS

TrackingId : la référence de votre tâche, définie lors de l'envoi du SMS à l'API, qui est rappelée pour identifier facilement votre envoi

JobNumber_api : identifiant unique de process généré par la plateforme. Il s'agit du même identifiant retourné lors de l'envoi du SMS à l'API.

tel : le numéro du destinataire du SMS

messagelength : la longueur du message calculée par la plateforme

credits : le nombre de crédits décomptés

status : statut global de l'envoi

code_status : statut détaillé de l'envoi (valeurs possibles à la fin de l'article)

date_status : date de la dernière modification du statut de l'envoi

error_code : résultat de la transmission (valeurs possibles à la fin de l'article)

error_detail : résultat de la transmission "human readable" (valeurs possibles à la fin de l'article)

clicked : 1 si un lien a été cliqué dans le message, NULL sinon

answer : le texte de la réponse du destinataire au SMS le cas échéant.

Dictionnaire des données pour les webhooks de l'API SMS

Les valeurs retournées par "statut", "error_code", "error_detail" et "code_statut" retournent toutes le résultat de l'envoi du SMS, avec un niveau de détail différent.

Pour la majorité des projets le traitement de la valeur "statut" suffit. Le traitement des valeurs "error_code", "error_detail" et "code_statut" est intéressant dans un but de nettoyage d'une base de numéros.

Valeurs possibles pour "statut"
1 SMS envoyé à l'opérateur
2 SMS délivré sur le mobile du destinataire
3 SMS non délivré
4 STOP SMS
9 En cours d'envoi
Valeurs possibles pour "error_code" et "error_detail"
error_code error_detail
S Sent
A Expired message
B N/A
C Other operator errors
D Unreachable recipient
E System error
F Incorrect message
G Incorrect number
H Mobile error
Z Canceled, blocked or duplicated
Valeurs possibles pour "code_status"

Le traitement de ces codes est facultatif. Ils permettent de savoir de manière extrêmement détaillée pour quoi un SMS n'est pas passé.

Le code 10201 équivaut à une confirmation de lecture du SMS.

S Transmis à l'agrégateur
127 Z Doublon
188 Z Destinataires présent dans la Black List utilisateur
10000 E Partially sent SMS
10001 B IntermediatePhoneRelated
10002 B DelivererRelated
10005 D MessageFailed
10006 D FinalStatusUnknown
10007 B IntermediateCreditRelated
10008 A MessageExpiredWithinOperator
10020 F PermanentOperatorError
10021 C TemporaryCreditRelated
10022 C TemporaryCreditRelated
10023 G PermanentAbsent
10024 D TemporaryAbsent
10025 D OperatorNetworkFailure
10026 H TemporaryPhoneRelatedError
10027 F PermanentPhoneRelatedError
10028 G Spam
10029 F ContentRelatedError
10030 C SubscriberMessageLimitExceeded
10031 C SubsciberUnableToBeBilled
10037 C SubscriptionRelatedFailure
10038 C InvalidSubscriptionOperator
10039 D Portability Error
10073 D Portability Error
10075 C RefundDenied
10200 B Accepted By Operator
10201 S Delivered To Mobile Device
10300 A Message Expired (SMPP)
10301 F Empty message
10302 G Empty Phone Number
10303 Z Profile is unavailable
10398 E Didn't receive the asynchronous transmission notification
10399 E Generic system error
10401 E Invalid Header parameters
10402 E Invalid parameters in the Notification
10403 E Profile could not be used
10404 E Message could not be forwarded to mBlox
10405 E Client reference could not be found
10406 E Error in message data
10407 E Message contains illegal characters
10408 E General sending error
10409 E Private connection configuration error
10410 E Send timed out (Success unknown)
10413 E The prefix of the destination number is blacklisted
10416 E The mBlox server is currently too busy.
10417 E You are not allowed to use this value in the reply parameter.
10418 E Syntax error, the parameters are not specified correctly.
10420 E General problem.
10421 E General problem.
10422 E General problem.
10423 E You cannot send using this profile.
10424 E The username used when you logged in is faulty.
10425 E You are not allowed to send binary messages using this profile.
10426 E There is currently no available route for this message.
10427 E There is currently no available route for this message.
10428 E There is currently no available route for this message.
10429 E There is currently no available route for this message.
10430 E There is currently no available route for this message.
10431 E There is currently no available route for this message.
10432 E There is currently no available route for this message.
10433 E There is currently no available route for this message.
10434 E There is currently no available route for this message.
10435 E There is currently no available route for this message.
10436 E There is currently no available route for this message.
10437 E There is currently no available route for this message.
10438 E There is currently no available route for this message.
10439 E There is currently no available route for this message.
10440 E There is currently no available route for this message.
10441 E There is currently no available route for this message.
10442 E Error while trying to use a special functionality named "locally forced".
10443 E Error while trying to use a special functionality called "originator indexing". The originator for this index could not be found.
10444 E The available destination queues are full.
10445 E The client account is currently blocked on this server.
10446 E You supplied an illegal value in the billingRef parameter.
10447 E You are not allowed to send messages to this destination operator.
10448 E There is currently too much incoming traffic on this destination operator.
10449 E This sequence has been used earlier among the X last sent messages on this server. X is most likely 50, but it can vary.
10452 E Premium services only. The destination cannot be found for your supplied values. Verify the values used in the originator, tariff and operator fields.
10453 E Premium services only. The destination cannot be found for your supplied values. Verify the values used in the originator, tariff and operator fields.
10454 E There is no available route that supports the requested message features.
10455 E This product does not support the supplied features. Please verify your use of the profile parameter.
10456 E The text content of this message is prohibited on this product.
10457 E The number portability operator lookup failed.
10458 E The operator parameter is required when a MT is sent through the PsmsPlex application.
10459 E The MT could not be routed in the PsmsPlex application.
10460 E An unknown exception encountered when handling tags.
10461 E The tag is not configured in the Database.
10462 E The name of the tag is not valid.
10463 E The value of the tag is not valid.
10464 E The tag is not allowed for this destination operator.
10465 E Syntax error in tag/value pair.
10466 E Too many tags are submitted in the message.
10467 E A tag is duplicated.
10468 E Invalid ServiceDesc. Do not retry.
10469 E Default ServiceDesc not configured. Do not retry.
10470 E Invalid ContentType. Do not retry.
10471 E Default ContentType not configured. Do not retry.
10472 E ContentType not configured for Operator. Do not retry.
10473 E Invalid ContentType. Do not retry.
10474 E Default ServiceId not configured. Do not retry.
10475 E ServiceId not configured for Operator. Do not retry.
10476 E Timeout waiting for mBlox core platform to respond (Success unknown)
10477 E Invalid Subscriber
10478 E SubscriberNumber missing
10479 E Destination busy
10498 E Unknown Error
10499 E An error occured during the submission of the MtRequest
12001 S SMS Delivered
12002 G SMS Delivery failed
12401 E Login failed
12402 E Source IP is invalid
12403 E Text is not set
12404 E Text is invalid
12405 E Language is invalid
12406 E Telno is not set
12407 E Telno is invalid
12408 E Text is too long
12409 E Receive ID is not found
12410 E Receive ID and Telno is not matched
12411 E Telno is out of our range
12412 E Service is not available
12413 E Unknown Error
12497 E The MT Request result is badly formatted
12498 E The error code of the MT request result is unknown
12499 E Error occured during the submission of the NotificationRequest
13000 C Unknown Error (SMPP)
13001 C Internal routing error
13002 C Internal routing error
13003 C Internal routing error
13004 C Internal routing error
13005 C Internal routing error
13006 C Internal routing error
13007 C Internal routing error
13008 C Internal routing error
13009 G Unsupported number plan
13010 G Unsupported type of number
13011 C Message not deliver
13012 G Dialling zone not found
13013 C Not home zone and IMSI not allowed
13014 C Not home zone and IMSI fetch failed
13015 C Screening block
13016 C Terminating IMSI blocked
13017 G Destination network type unknown
13018 C ESME error
13019 C Originating location mismatch
13040 C Internal error
13050 C Internal error
13051 C Internal error
13052 C Internal error
13053 C Internal error
13054 C Internal error
13055 C Internal error
13060 C Error, originator blocked
13061 C Error, destination blocked
13062 C Error, keyword blocked
13063 C Error, SC address blocked
13064 C Error, blocked due to exceeded quota
13065 C Error, loop detected
13066 C Error, data coding scheme blocked Exemple : SMS unicode envoyé vers opérateur qui ne l'accepte pas (Bouygues Telecom).
13067 C Error, information element identifier blocked
13070 C Internal error
13071 C Internal error
13072 C Internal error
13073 C Internal error
13074 C Internal error
13075 C Internal error
13076 C Internal error
13077 C IMSI lookup blocked
13100 D Unidentified Subscriber
13101 C Facility not supported
13102 C System failure
13103 F Unexpected data value
13104 F Data missing
13105 C Equipment protocol error
13106 C Unknown service centre address
13107 C Service centre congestion
13108 C Invalid short message entity address
13109 D Subscriber not service centre subscriber
13110 D Reject
13111 D Local Cancel
13112 D Abort
13113 C Exception (internal)
13114 C Unknown error
13150 G Unknown subscriber
13151 G Call barred
13152 C Teleservice not provisioned
13153 A Absent subscriber (Expired SFR & Free)
13154 F Facility not supported
13155 A System failure (Expired SFR & Free)
13156 C Unexpected data value
13157 C Data missing
13158 H Memory capacity exceeded
13159 D Mobile subscriber not reachable
13160 D Reject
13161 D Local Cancel
13162 D Abort
13163 C Exception (internal)
13164 C Unknown error
13200 D Unidentified subscriber
13201 G Absent subscriber, IMSI detached
13202 G Absent subscriber, no page response
13203 A Subscriber busy for MT SMS (Expired Orange)
13204 F Facility not supported
13205 G Illegal subscriber
13206 H Illegal equipment
13207 C System failure
13208 C Unexpected data value
13209 C Data missing
13210 H Memory capacity exceeded
13211 H Equipment protocol error
13212 H Equipment not short message equipped
13213 D Reject
13214 A Local Cancel (Expired Bouygues)
13215 D Abort
13216 C Exception (internal)
13217 C Unknown error
13250 C Error, personal service barring, MO Personal Determined Barring White List
13251 C Error, personal service barring, MO Personal Determined Barring Black List
13252 C Error, personal service barring, MO Operator Determined Barring White List
13253 C Error, personal service barring, MO Operator Determined Barring Black List
13254 C Error, personal service barring, MT Personal Determined Barring White List
13255 C Error, personal service barring, MT Personal Determined Barring Black List
13256 C Error, personal service barring, MT Operator Determined Barring White List
13257 C Error, personal service barring, MT Operator Determined Barring Black List
13300 G Invalid destination address
13301 G Invalid destination numbering plan
13302 G Invalid destination type of number
13303 C Invalid destination flag
13304 C Invalid number of destinations
13310 C Invalid source address
13311 C Invalid source numbering plan
13312 C Invalid source type of number
13320 G ESME Receiver permanent error
13321 D ESME Receiver reject error
13322 D ESME Receiver temporary error
13330 C Invalid command length
13331 C Invalid service type
13332 C Invalid operation
13333 C Operation not allowed
13334 C Invalid parameter
13335 C Parameter not allowed
13336 C Invalid parameter length
13337 C Invalid optional parameter
13338 C Optional parameter missing
13339 C Invalid validity parameter
13340 C Invalid scheduled delivery parameter
13341 C Invalid distribution list
13342 C Invalid message class
13343 C Invalid message length
13344 C Invalid message reference
13345 C Invalid number of messages
13346 C Invalid predefined message
13347 C Invalid priority
13348 C Invalid replace flag
13349 C Request failed
13350 C Invalid delivery report request
13360 C Message queue full
13361 C Extenal error
13362 C Extenal error
13370 C Cannot find information
13399 C Unknown
13498 G Invalid desintation address (recipient/destination phone number is not valid)
13499 E An error occured during the submission of the MtRequest (SMPP)
13505 C Failed because of a network problem on the operator
13507 C Failed because of an insufficient credit (for prepaid customers)
13520 G Failed because of no matching operator for the destination number
13524 G Failed because of an invalid destination number
13588 D Failed because of mobile blocked by operator
13599 F Failed because of SMS is not allowed – For MT Premium, it is the case when Billed SMS is sent to a mobile unsubscribed.