Table des matières
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
En cas d'erreur
- 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.
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. |