Campagnes SMS

SMS Designer (smsdesigner.inklura.fr) compose et envoie des campagnes SMS. Les campagnes sont enregistrées dans l'espace de votre organisation, et l'envoi passe par l'opérateur SMS de la plateforme. Les identifiants de l'opérateur restent côté serveur et n'atteignent jamais le navigateur.

L'API d'action des campagnes

Les campagnes se gèrent via un unique endpoint, protégé par la session et limité à votre organisation :

GET  /api/campaigns            lister vos campagnes (les plus récemment modifiées d'abord)
GET  /api/campaigns?id=<id>    une campagne, avec la répartition de ses destinataires
POST /api/campaigns            exécuter une action

GET /api/campaigns?id=<id> renvoie { ok, campaign, recipientCount, breakdown, brands } : breakdown détaille, liste par liste, le nombre de contacts retenus, et brands donne les marques acceptées par l'action setbrand.

L'opération est choisie par le champ action du corps JSON. Les actions sur une campagne existante prennent aussi son id :

action Effet
create Créer une campagne (en brouillon). Renvoie { ok, id, campaign }.
update Mettre à jour une campagne. Modifier une campagne envoyée ou programmée la repasse en brouillon.
delete Supprimer une campagne.
preview Répartition des destinataires en direct pour targets, listId et extraTo. Rien n'est modifié ni envoyé.
send Résoudre et dédupliquer les destinataires, puis envoyer immédiatement.
schedule Résoudre et dédupliquer les destinataires, puis programmer l'envoi à when.
share Créer (ou renvoyer) le lien de rapport public. Renvoie { ok, token, url }.
unshare Révoquer le lien de rapport public.
setdelivery Enregistrer le taux de livraison réel relevé auprès de l'opérateur.
setbrand Définir la marque affichée sur le rapport de la campagne (brand).

Champs d'une campagne

create et update acceptent les champs suivants (tous facultatifs) :

Champ Type Règle
name string 100 caractères au plus. Par défaut « Nouvelle campagne ».
body string Le texte du SMS, 4 000 caractères au plus.
sender string Nom d'expéditeur. Seuls les 11 premiers caractères sont transmis à l'opérateur.
route "N" ou "M" Classe de trafic (voir plus bas). Par défaut N.
targets { listId, cap }[] Listes de contacts visées (50 au plus). cap limite le nombre de contacts tirés de cette liste ; 0 = pas de limite.
listId string Ancienne forme à une seule liste, sans limite. Ignorée si targets est renseigné.
extraTo string Numéros ajoutés à la main, séparés par des virgules, des points-virgules ou des retours à la ligne.

Les listes sont parcourues dans l'ordre. Un numéro déjà retenu par une liste précédente n'est pas compté dans le cap de la suivante, puis les numéros de extraTo s'ajoutent s'ils ne figurent pas déjà dans l'envoi.

POST /api/campaigns
{
  "action": "create",
  "name": "Soldes d'été",
  "body": "Les soldes commencent demain.",
  "sender": "MABOUTIQUE",
  "route": "M",
  "targets": [{ "listId": "<id de liste>", "cap": 500 }]
}

Envoi et mode test

send et schedule acceptent "test": true : la requête part vers l'endpoint de test de l'opérateur, rien n'est envoyé et le statut de la campagne ne change pas. La réponse est { ok, mode: "test", recipients }, où recipients est le nombre de destinataires résolus.

Un envoi réel renvoie { ok: true, campaign, recipients, balance } (balance : solde de crédits indiqué par l'opérateur, s'il le fournit). En cas de refus de l'opérateur, la campagne passe au statut failed et la réponse est un 502 avec le motif dans error.

Statuts d'une campagne : draft, scheduled, sent, failed.

Message hors campagne

Pour un message unique ou un envoi de test hors campagne, utilisez :

POST /api/sms/send
{ "text": "…", "to": "06 12 34 56 78, 07 …", "listId": "<liste facultative>", "sender": "MABOUTIQUE", "route": "N", "test": true }

to accepte un tableau de numéros, ou une chaîne de numéros séparés par des virgules, des points-virgules ou des retours à la ligne (les espaces à l'intérieur d'un numéro sont admis). Les numéros de listId s'ajoutent à ceux de to, sans doublon. La réponse renvoie la liste des numéros retenus dans recipients.

Format des numéros

Les numéros sont normalisés au format international sans + : espaces, points, tirets et parenthèses sont retirés, un préfixe + ou 00 est enlevé, et un numéro français à 10 chiffres (06…) devient 336….

Classe de trafic

Chaque envoi appartient à une classe de trafic, fixée par le champ route :

route Classe Usage
N Notification Messages transactionnels (par défaut).
M Marketing Messages promotionnels.

Erreurs

Les réponses d'erreur ont la forme { "ok": false, "error": "…" } :

Statut Cas
400 Corps JSON invalide, action inconnue, message vide, aucun destinataire, when invalide.
401 Pas de session.
404 Campagne introuvable pour cet id.
500 Envoi SMS non configuré pour la plateforme.
502 L'opérateur a refusé ou n'a pas pu traiter l'envoi (crédits insuffisants, numéro invalide ou sur liste STOP, etc.).

Planification

Une action schedule prend une valeur when (yyyy-mm-dd hh:mm ou yyyy-mm-ddThh:mm, secondes facultatives) et remet la campagne à l'opérateur avec cette heure d'envoi. L'opérateur retient le lot et l'envoie à l'heure prévue. Une fois la campagne programmée, Inklura ne la relance pas de lui-même.

Attention

Modifier une campagne programmée la repasse en brouillon dans SMS Designer, mais n'annule pas le lot déjà remis à l'opérateur : l'envoi programmé partira quand même.

Rapports et taux de livraison

Chaque campagne peut exposer une page de rapport publique, sans connexion :

/rapport/<token>

Le token fait office de contrôle d'accès : l'action share le crée et rend le rapport accessible (un nouvel appel renvoie le même lien), unshare le révoque et l'URL cesse aussitôt de fonctionner.

Attention

Le taux de livraison est une estimation tant que personne ne saisit le chiffre réel. L'opérateur ne renvoie pas d'accusés de réception, donc :

  • Délivrés affiche par défaut une estimation de référence (95 %). Le chiffre devient réel quand quelqu'un relève le taux de la campagne auprès de l'opérateur et le saisit avec l'action setdelivery (champ rate), qui accepte une fraction (0..1) ou un pourcentage (0..100). Un taux nul ou négatif l'efface. Les champs facultatifs source (40 caractères) et period (16 caractères, par exemple 06/2026) s'affichent à côté du chiffre.
  • Lus reste toujours une estimation de référence (95 %).
  • Les clics sont mesurés, à partir du lien court suivi dans le message.

Considérez le taux de livraison d'un rapport comme une donnée saisie, pas comme une mesure.

POST /api/campaigns
{ "action": "setdelivery", "id": "<id>", "rate": 97.4, "period": "06/2026" }

Voir aussi