API FTP SMSENVOI V1.1

Transcription

1 API FTP SMSENVOI V1.1 Publiée le 11/09/2015 Contrairement à nos autres API, l activation de l API FTP se fait uniquement sur demande auprès de nos conseillers. L utilisation de cette API se fait en deux étapes : 1) Dépot d un fichier XML par FTP. 2) Requête HTTP POST permettant de programmer la campagne. Nous vous recommandons d effectuer la requête HTTP de programmation de la campagne le plus tôt possible. N attendez pas l heure d envoi souhaitée de votre campagne pour effectuer cette requête. Effectivement, le traitement du fichier de campagne peut prendre plusieurs minutes si le nombre de destinataires est très important. Nous vous recommandons pour cette raison de ne pas programmer de fichier campagne contenant plus de destinataires. Biensûr, il vous est tout à fait possible de créer autant de fichiers campagnes que vous le souhaitez. Fichier XML : Les fichiers de campagnes sont à transmettre au format XML. Ceux cis doivent porter le nom : campaign_xxx.txt où XXX contient l'id temporaire de campagne de votre choix. La seule restriction est de donner à cet id temporaire une valeur numérique sous forme de nombre entier réel.

2 Voici l'exemple type d'un fichier XML à nous transmettre: <?xml version='1.0' encoding='utf 8'?> <campaign> <scheduledate> </scheduledate> <scheduletime> 14:50 </scheduletime> <sign> e012da255f0ad7zea67bc5fb934a9a3cf0287 </sign> <senderlabel> Test </senderlabel> <messagetype> SMS </messagetype> <messagesubtype> PREMIUM </messagesubtype> <messagecontent> Bonjour #firstname#, comment allez vous? </messagecontent> <recipients> <recipient> <name></name> <firstname> Pierre </firstname> <telephone> </telephone> <fax></fax> < ></ > <field1></field1> <field2></field2> <field3></field3> <field4></field4> <field5></field5> </recipient> </recipients> </campaign> Explication détaillée du format de fichier XML : campaign est la balise principale, contenant l'ensemble des autres balises. scheduledate contient la date à laquelle vous souhaitez que l'envoi soit effectué au format YYYY mm dd scheduletime content l'heure à laquelle vous souhaitez que l'envoi soit effectué au format HH:mm sign contient le md5 du résultat de la concaténation de votre APIKEY avec l id de votre campagne. ( md5(apikey. IDCAMPAGNE) ). senderlabel contient le nom d expéditeur du message messagetype contient SMS

3 messagesubtype contient la gamme dans laquelle vous souhaitez effectuer vos envois : LOWCOST / STANDARD / PREMIUM / CONTATENE / WORLD messagecontent contient le contenu de votre message. Celui ci peut être personnalisé pour chaque destinataire si vous utilisez les variables destinataire (voir recipient ). Le nom des variables que vous souhaitez insérer devra être précédé et suivi d un #. recipients contient la liste de vos destinataires recipient chaque balise recipient contient l un de vos destinataires. Les informations contenues dans la balise recipient concernent les informations relatives à ce destinataire. Seule la balise telephone est requise pour l envoi de SMS. Les autres vous permettent de substituer certaines portions de votre message par des variables destinataire, ce qui vous permet notamment de faire du publipostage. Liste exhaustive des variables insérables, entourées de symboles # : name, firstname, telephone, fax, , field1, field2, field3, field4, field5, url (facultatif) Notes concernant l option Rich SMS Vous pouvez utiliser l option Rich SMS via l API FTP en ajoutant les éléments supplémentaires : shorturl_option Cette balise vous permet de choisir le mode de raccourcissement de votre choix. Elle peut contenir les valeurs 1, 2 ou 3. En utilisant l option 1, l ensemble des destinataires seront redirigés depuis une seule et unique adresse raccourcie vers une même adresse de destination. Chaque destinataire accédera donc à la même page et vous ne pourrez donc pas savoir qui a cliqué sur le lien. Cette option coûte 1 crédit Rich SMS par campagne. En utilisant l option 2, l ensemble des destinataires seront redirigés vers une même adresse de destination depuis des adresses raccourcies distinctes. Vous pourrez donc obtenir des statistiques sur les clics détaillées pour chaque destinataire. Cette option vous coûte 1 crédit par destinataire. En utilisant l option 3, chaque destinataire sera dirigé vers une adresse de destination distincte depuis une adresse raccourcie distincte. Vous pourrez donc obtenir des statistiques sur les clics détaillées pour chaque destinataire et acheminer chacun d entre eux vers une page personnalisée. Cette option vous coûte 1 crédit par destinataire. Important : si vous utilisez l option 1 ou l option 2, vous devrez transmettre l adresse de destination dans une balise supplémentaire : shorturl_url. Si vous utilisez l option 3, vous devrez transmettre l adresse de destination souhaitée pour chaque destinataire, dans la balise field1 de chaque élément recipient. Quelle que soit l option utilisée, vous devrez insérer la variable url ( #url# ) dans votre message.

4 Le fichier devra être encodé en UTF 8. Veuillez vous assurer de respecter les normes d échappement de caractères relatives au format XML. Requête HTTP : Une fois le fichier XML déposé dans votre compte FTP, vous devez effectuer une requête HTTP POST afin de lancer la programmation de la campagne. Un fichier XML transmis par erreur ne sera pas automatiquement traité et pourra être remplacé sans crainte tant que la requête HTTP n aura pas été lancée. Les paramètres POST à transmettre sont les suivants : de votre compte apikey : apikey de votre compte campaign : id temporaire de la campagne ( indiqué dans le nom du fichier) nbrecipients : nombre de destinataires de la campagne. Ce nombre doit être identique au nombre de destinataires présents dans le fichier XML test : paramètre facultatif. Pour un envoi en mode normal, vous ne devez pas le transmettre. Si vous souhaitez effectuer un test, envoyez nous ce paramètre en lui donnant pour valeur 1. Le SMS ne sera pas envoyé et des informations relatives à la campagne vous seront retournées. URL : Notes concernant l ID de campagne : L id temporaire que vous indiquez sera uniquement utilisé pour vous permettre de déposer plusieurs fichiers simultanément sur notre serveur FTP et vous permettre de désigner le fichier de votre choix lors de vos requêtes HTTP. Toute programmation de campagne réussie résultera en une chaîne XML contenant l ID que nous avons attribué à cette campagne. C est cet ID que nous vous communiquerons qui devra être utilisé dans l intégralité de nos échanges ultérieurs. ( Récupération d accusés de réception, conversation avec notre support technique..) Réponses retournées par l API : <result><success>0</success><info>authentification error</info></result> problème d authentification <result><success>0</success><info>campaign ID not provided</info></result> Le paramètre campaign n a pas été correctement communiqué par votre requête HTTP <result><success>0</success><info>campaign File not found</info></result> Le fichier de campagne correspondant à l ID communiqué n a pas été trouvé

5 <result><success>0</success><info>campaign sign error</info></result> La signature présente dans le fichier campagne est erronnée <result><success>0</success><info>number of Recipients Error</info></result> Les nombres de destinataires ne correspondent pas <result><success>0</success><info>you dont have enough credits</info><creditsrequired>xx</creditsrequired></result> Vous ne disposez pas de suffisamment de crédits <result><success>0</success><info>you dont have enough RICH SMS credits</info><creditsrequired>xx</creditsrequired></result> Vous ne disposez pas de suffisamment de crédits Rich SMS (en cas d utilisation de shorturl_option) <result><success>1</success><info>campaign successfully scheduled</info><creditsrequired>xx</creditsrequired><message_id>yy</message_id></resul t> La campagne a été programmée avec succès. L ID que vous devrez utiliser pour obtenir plus d informations sur cette campagne est contenu dans la balise message_id Pour plus d informations techniques sur cette API, contactez Stephane Nachez s.nachez@smsenvoi.com