Manuel d intégration API FTP SMS ALLMYSMS.COM

Manuel d intégration API FTP SMS ALLMYSMS.COM 29/01/2014

TABLE DES MATIERES 1. ENVOI DE SMS (SMS-MT PUSH)... 3 1.1. GENERALITES... 3 1.1.1. Adresse FTP... 3 1.1.2. Paramètres de connexion... 3 1.1.3. Remarques... 3 1.2. FORMAT DES FICHIERS DEPOSES... 3 1.2.1. Structure Générale... 3 1.2.2. Envoi de SMS... 3 1.2.3. Contenu des fichiers déposés... 4 1.2.4. Remarques et restrictions concernant les messages SMS... 4 1.3. TRAITEMENT DES FICHIERS... 5 1.4. NOTIFICATIONS PAR EMAIL... 6 2. SUPPORT... 7 3. GLOSSAIRE... 8

OBJECTIF DU DOCUMENT Ce document présente la façon d utiliser l API FTP AllMySMS.com pour envoyer vos SMS. L API FTP fonctionne par transmission de fichiers au format CSV vers le répertoire FTP de l utilisateur Allmysms. Ce document présente également le formatage à utiliser et les façons d encoder vos données. Il est impératif de lire la documentation dans son ensemble avant de s interfacer à l API FTP AllMySMS.com.

1. ENVOI DE SMS (SMS-MT PUSH) 1.1. GENERALITES L API FTP d envoi de SMS fonctionne par dépôt de fichiers au format CSV via le protocole ftp sur le compte FTP de l utilisateur fourni par la société MS Innovations. Cette API est réservée aux comptes en abonnement. Veuillez faire la demande d ouverture de compte FTP auprès du service technique de MS Innovations à l adresse support@msinnovations.com 1.1.1. ADRESSE FTP ftp://ftp.allmysms.com 1.1.2. PARAMETRES DE CONNEXION login pass : login du compte Allmysms du client : mot de passe du compte Allmysms du client 1.1.3. REMARQUES Pour des envois de volumes conséquents, il est à noter que la taille maximale des fichiers déposés ne doit pas dépasser 8Mo 1.2. FORMAT DES FICHIERS DEPOSES 1.2.1. STRUCTURE GENERALE Une fois connecté au serveur FTP, le client accède aux sous-répertoires suivants: SERVEUR_FTP LOGIN DU CLIENT o ARCHIVES (contient les archives de fichiers déjà traités) o INVALIDS (contient les fichiers déclarés invalides après traitement) o PROCESSING (contient les fichiers en cours de traitement) o SEND_SMS (contient les fichiers à envoyer) 1.2.2. ENVOI DE SMS Pour envoyer des SMS, les fichiers doivent être déposés sur le FTP, dans le répertoire SEND_SMS.

Afin d éviter une prise en charge des fichiers avant la fin de l upload, il est conseillé d uploader des fichiers temporaires, avec extension.tmp, jusqu à ce que le fichier soit uploadé. Une fois l upload terminé, remplacer l extension.tmp par.csv afin que le traitement démarre. Les fichiers déposés sur le FTP doivent être au format CSV avec séparateur point-virgule et délimité par des guillemets (format de fichier CSV standard, encodé en UTF-8). Tout autre format de fichiers CSV sera refusé ou pourra ne pas être traité correctement. Le nom de fichier doit correspondre au formalisme suivant séparés par des _ : - Nom de la campagne, composé uniquement de lettres et de chiffres, sans espace ni caractère spécial - Date d envoi au format YYMMDDHHIISS (ex : 20130716120000 pour un envoi à 12h le 16 Juillet 2013) - Qualité de l envoi (HQ pour Haute qualité et LC pour du Low Cost) Exemple de nommage de fichier correct : CampagneFtp_20130716120000_HQ.csv Attention: Si le nom de fichier ne correspond pas au bon format et n est pas un fichier temporaire, le fichier sera déclaré invalide et déplacé dans le dossier INVALIDS. 1.2.3. CONTENU DES FICHIERS DEPOSES Le fichier déposé sur le serveur FTP doit contenir 2 colonnes. La première colonne correspond aux numéros de téléphones au format international (+336 pour la France, +32 pour la Belgique) ou 06xxxxxxxx/07xxxxxxxx pour les numéros Français. La seconde colonne contient le message (160 caractères maximum) à envoyer au numéro correspondant. Les numéros de téléphones doivent être uniques. Le système supprimera automatiquement les doublons et enverra le dernier message associé au numéro dupliqué. Exemple de contenu correct : "33671717171";"Contenu du SMS" 1.2.4. REMARQUES ET RESTRICTIONS CONCERNANT LES MESSAGES SMS Longueur: o La longueur du message SMS ne doit pas dépasser 160 caractères, en prenant en compte les longueurs de caractères spéciaux détaillées ci-après Encodage : o Le message doit être encodé en UTF-8. Caractères spéciaux : o Le signe n est pas géré par les téléphones portables d ancienne génération ni par certains opérateurs. Dans le cas où vous l utiliseriez, il sera remplacé par un E. o Le retour à la ligne est encodé par \n. Il compte double dans le calcul de la longueur du message. o En Low Cost, certains caractères comptent double : é, É, è, È, ë, Ë, à, À, á, Á, ä, Ä, ç, Ç, ', ", ì, Ì, í, Í, ï, Ï, ò, Ò, ó, Ó, ö, Ö, ù, Ù, ú, Ú, ü, Ü

o En Low Cost, certains caractères ne sont pas supportés : ^, [, ], {, },, \\, `,,, µ, â, ê, û, î, ô, Â, Ê, Û, Î, Ô Formatage des numéros Vers la France, trois formats possibles : 06xxxxxxxx (ou 07xxxxxxxx) 336xxxxxxxx (ou 337 xxxxxxxx) +336 xxxxxxxx (ou +337 xxxxxxxx) Vers l international, deux formats possibles : +CCxxxxxxxx CCxxxxxxxx Où CC est l indicatif pays (Country Code, 1 à 3 chiffres selon les destinations, par exemple 44 pour la Grande Bretagne ou 33 pour la France). Les longueurs étant spécifiques à chaque opérateur international, il n y a pas de vérification effectuée quant à la longueur des numéros de téléphones étrangers. Tout envoi vers un téléphone fixe ou un numéro ne respectant pas le formatage défini ci-dessus sera rejeté. Attention: Si le message envoyé à l API FTP n est pas encodé en UTF-8 ou contient des caractères nonsupportés, les messages seront rejetés ou envoyés avec un formatage incorrect. 1.3. TRAITEMENT DES FICHIERS L API traitera automatiquement les nouveaux envois à effectuer une fois que le dépôt des fichiers temporaires sera terminé, et que ceux-ci auront été renommés en.csv. Un fichier en cours de traitement par les serveurs AllMySMS sera déplacé du dossier SEND_SMS vers le dossier PROCESSING. Après traitement, l API déplacera les fichiers du répertoire PROCESSING vers le répertoire ARCHIVES si l exécution du fichier s est bien déroulé ou le répertoire INVALIDS si une erreur est survenue lors de l exécution. Exemple de fichier traité et archivé: TreatedByMSI_Envoiftp_20131002100000_HQ.csv Dans le cas d un fichier invalide, le nom du fichier contiendra la raison de l erreur : - Not Sub : Le compte n est pas en abonnement et ne peut utiliser l API FTP - Empty File : Fichier vide ou ne contenant aucun numéro valides - Incorrect FileName : Nom de fichier incorrect Exemple de fichier invalide renommé: TreatedByMSI_Incorrect_FileName_Envoiftp_20131002100000_HQ.csv

1.4. NOTIFICATIONS PAR EMAIL Un mail récapitulatif sera envoyé au client sur l adresse email renseignée sur son profil Allmysms.com dans lequel seront indiqués les fichiers traités, le nombre de SMS envoyés, la date d envoi ainsi que les raisons d échec d exécution si certains fichiers ne sont pas valides.

2. SUPPORT Pour de plus amples renseignements, contactez le service technique AllMySMS.com qui vous répondra dans les plus brefs délais : Téléphone E-mail support@allmysms.com

3. GLOSSAIRE Accusé de réception : Acquittement relatif à un envoi. Permet par exemple de connaître le statut de la réception d un message HTTP (HyperText Transfer Protocol) : Protocole utilisé sur Internet pour transférer des données entre un navigateur ou une application cliente et un serveur web. Pull : Voir SMS Push-Pull SMS (Short Message Service) : Désigne le service de messagerie permettant l'envoi et la réception de messages alphanumériques ou binaires depuis un terminal mobile. SMS-C (SMS Center): Centre serveur de l opérateur mobile qui gère l envoi et la réception des SMS-MO et des SMS-MT. SMS-MO (Short Message Service Mobile Originated) : Désigne un SMS émis par un Utilisateur depuis son terminal mobile. SMS-MT (Short Message Service Mobile Terminated) : Désigne un SMS reçu par Utilisateur sur son terminal mobile. SMS Push-Pull : Littéralement, Pousser-Tirer. Il s agit en fait d un modèle bi-directionnel qui consiste à envoyer des SMS-MT (Push) pour solliciter des SMS-MO réponses en retour (Pull). Ainsi, vous envoyez votre campagne de SMS-MT à l ensemble de vos contacts et recevez directement leurs réponses par SMS-MO. XML (extensible Markup Language): Evolution du langage SGML, XML permet aux concepteurs de documents HTML de définir leurs propres marqueurs, dans le but de personnaliser la structure des données qu'ils comptent présenter. Alors qu'html précise comment les éléments d'une page seront présentés, XML définit ce que contiendront ces éléments.