API Campaign

Ce document vous présente l’API campaign, c'est un complément de notre API d’envoi de SMS.

Celle-ci permet d’envoyer des sms par paquet mais pour que ce système soit efficace, nous vous demandons de n’utiliser l’API campaign que pour des envois de taille suffisante (et notamment de lui préférer impérativement l'API unitaire pour des envois uniques comme cela serait le cas pour des SMS transactionnels).

Inscription

Pour utiliser cet API, merci de contacter support@mtarget.fr avec comme sujet de mail "création d'un compte API campaign" et avec vos coordonnées : nom, prénom, nom de la société, SIRET et numéro de téléphone.

Envoyer des SMS

L'API CAMPAIGN est préconisé dans le cas ou l'API SMS unitaire n'est pas adapté à votre contexte. Nous devons échanger au préalable avec vous afin de déterminer vos besoins et l'adéquation avec cette offre.

Votre username et votre password vous seront nécessaires afin de vous authentifier pour chaque envoi.

Intégration de la campagne

Nous vous demandons de limiter dans un premier temps à 50.000 le nombre de messages par lot, de nous consulter avant d'augmenter cette limite et de prendre en compte la valeur de retour en cas d'erreur due à un dépassement de taille pour le lot - cela se manifeste par une erreur HTTP 413 Request Entity Too Large.

POST https://api-public-2.mtarget.fr/api-campaignsms HEADERS

Content-Typeapplication/json

BODY

  "username": "USERNAME",

Votre username, transmis à l'inscription

  "password": "PASSWORD",

Votre password, transmis à l'inscription

  "sender": "APICampaign",

Personnalisation de l'émetteur : 11 caractères alphanumériques, par exemple "Magasin" (la valeur par défaut diffère selon les pays et opérateurs). Certains opérateurs refuseront la personnalisation de l'émetteur (par exemple en France NRJ Mobile ou Transatel)

Facultatif : par défaut, un de nos numéros court sera utilisé.

  "msg": "Ceci est un message de test simple avec un parametre : [param1]",

Contenu du message.

Vous pouvez utiliser des [paramètres] placés entre crochets, qui seront à renseigner par numéro pour personnaliser le message.

Le contenu du message est limité à 160 caractères pour un SMS standard (qui utilise l'alphabet GSM – attention aux caractères comptant double, comme €). Nous autorisons avec l'option "messages longs" un envoi de 5 SMS de 153 caractères (la concaténation des SMS utilise 7 caractères par message). Si vos besoins impliquent une taille de message supérieure à 5 x 153 caractères, merci de contacter le support pour demander une analyse du besoin et un paramétrage spécifique. Des limitations imposées par l'opérateur peuvent s'imposer.

  "timetosend": "2019-01-01 10:15:00",

Date et heure de l'émission du message (format : yyyy-MM-dd HH:mm:ss ex : 2038-01-19 04:14:08). Le timetosend ne peut pas être utilisé pour un envoi différé de plus de 24h dans le futur, des délais plus grands doivent être gérés de votre côté. Même programmé en avance, il n'est pas possible d'annuler un message. Le fuseau horaire est celui de la France.

Facultatif : par défaut, le message sera envoyé sans délai.

  "serviceid": 11111,

Permets de gérer plusieurs offres différentes sur un compte unique (par exemple : une offre pour des messages Alerting et une offre pour des messages Marketing en France).

Facultatif : dans la majorité des cas, vous n'aurez besoin que d'une seule offre.

  "msisdns": [
    {
        "msisdn": "+336xxxxxxxxx",
        "param1": "parametre #1",
        "remoteid": "remoteid1"
    },
    {
        "msisdn": "+337yyyyyyyyy",
        "param1": "parametre #2",
        "remoteid": "remoteid2"
    }
  ],

Tableau contenant tout les msisdns (numéro du destinataire avec indicatif (+33...) ou au format international (0033...)) auxquels envoyer le message. Si vous avez utilisé des [paramètres] dans le message, c'est aussi dans ce tableau qu'il faut donner pour chaque numéro la valeur à envoyer pour les paramètres en question. Le champ remoteid est un champ libre limité à 250 caractères alphanumériques, vous permet de nous donner un identifiant métier que nous vous renverrons dans le rapport.

  "validationrequired": true,

Cette variable mise à true signifie qu’il vous faudra valider la campagne avant son envoi avec un appel à une méthode décrite ci-dessous (dans le cas contraire, la campagne est envoyée dès réception de l’appel). Nous vous conseillons de toujours laisser ce paramètre ; il permettra de valider le nombre de SMS, qui peut différer du nombre de messages en cas de SMS longs.

Attention : ceci n'est pas un mécanisme conçu pour différer un envoi. Nous nous réservons le droit de supprimer les campagnes qui resteraient trop longtemps en attente de validation.

  "packetsize": 50,

Champ optionnel : va de pair avec le champ interval. Cette option permet de lisser les envois de SMS : X SMS toutes les Y secondes (packetsize correspond à x, interval à Y)

  "interval": 300,

Champ optionnel : va de pair avec le champ packetsize. Valeur en secondes.

Statut de la campagne

Cette requête permet de constater le statut de la campagne et notamment le nombre de SMS qui vont être réellement envoyés. Les chiffres sont figés lorsque le paramètre campaignstate est à 18 (en attente de validation).

GET https://api-public-2.mtarget.fr/api-campaignsms?username=USERNAME&password=PASSWORD&action=getstate&campaignid=12345678 PATH PARAMETERS

usernameUSERNAME

Votre username, transmis à l'inscription

passwordPASSWORD

Votre password, transmis à l'inscription

actiongetstate

campaignid12346578

Identifiant de la campagne obtenu lors de l'intégration du fichier

Validation de la campagne

Si le paramètre validationrequired a été utilisé (et positionné à true), la campagne a été intégrée mais pas lancée. Il faut la lancer en appelant l’URL suivante. Ce processus permet de valider le nombre de SMS qui vont être envoyés.

Attention : ceci n'est pas un mécanisme conçu pour différer un envoi. Nous nous réservons le droit de supprimer les campagnes qui resteraient trop longtemps en attente de validation.

Attention 2 : cette requête nécessite de position l'header content-type à application/x-www-form-urlencoded.

POST https://api-public-2.mtarget.fr/api-campaignsms?username=USERNAME&password=PASSWORD&action=validation&campaignid=12345678 PATH PARAMETERS

usernameUSERNAME

Votre username, transmis à l'inscription

passwordPASSWORD

Votre password, transmis à l'inscription

actionvalidation

campaignid12346578

Identifiant de la campagne obtenu lors de l'intégration du fichier

Générer un rapport

Après l’envoi de la campagne, il est possible d’obtenir un rapport d’envoi (il est préférable d’attendre quelques heures après le déclenchement de la campagne pour obtenir des résultats significatifs). Le rapport est en principe définitif 3 jours après la fin de la campagne.

GET https://api-public-2.mtarget.fr/api-campaignsms?username=USERNAME&password=PASSWORD&action=report&campaignid=12345678 PATH PARAMETERS

usernameUSERNAME

Votre username, transmis à l'inscription

passwordPASSWORD

Votre password, transmis à l'inscription

actionreport

campaignid12346578

Identifiant de la campagne obtenu lors de l'intégration du fichier

Codes d'erreur

Vous pouvez retrouvez ci-dessous une liste exhaustive des codes d'erreur de l'API :

0, "success"
1, "authentification failure"
2, "user not allowed"
3, "validation failure"
4, "report not available"
5, "report not available. service temporary unavailable"
6, "The report not yet available."
7, "setState not allowed"
8, "setState not allowed. The campaign must be validated."
9, "action not implemented"
10, "campaign not found"
11, "Content-Type not found in http header"
12, "Erreur lors traitement. erreur:xxxxxxxx"
13, "Erreur lors de la recuperation des données. "
14, "Erreur lors traitement du JSON. erreur:xxxxx"
15, "Erreur lors traitement. erreur:xxxxx"
16, "Content-Type: xxxxxx not implemented"
17, "Erreur lors traitement des données. "
18, "Erreur lors traitement des données. Msgcount=0"
19, "authentification failed. Account disabled."
19, "Not enough credit. Account disabled."
500, "service temporary unavailable"