Campagnes SMS

SMS Designer (smsdesigner.inklura.fr) compose et envoie des campagnes SMS. Les enregistrements de campagne vivent dans le store bext KV par application ; la livraison réelle passe, elle, par la passerelle Capitole Mobile.

La passerelle Capitole Mobile

Les envois sont des POST application/x-www-form-urlencoded avec un unique champ de formulaire XML=<payload> vers :

https://sms.capitolemobile.com/api/sendsms/xml_v2

Un endpoint de test/écho renvoie la requête sans envoyer (aucun envoi, aucun coût), utile pour valider un payload :

https://sms.capitolemobile.com/api/sendsms/xml_test

Le payload XML porte trois parties :

Partie Champs
Auth username, password
Message text, sender, route, prog
Destinataires la liste des destinataires résolue et dédupliquée

route sélectionne la classe de trafic :

route Signification
"N" Notification (par défaut)
"M" Marketing

prog est une planification côté serveur optionnelle au format yyyy-mm-dd hh:mm:ss — voir Planification ci-dessous.

Un envoi est considéré comme réussi lorsque le corps de la réponse contient :

SENDING_OK;<balance>

Les identifiants sont des variables d'environnement par site, CAPITOLE_SMS_USERNAME et CAPITOLE_SMS_PASSWORD — ils n'atteignent jamais le navigateur.

L'API d'action des campagnes

Les campagnes sont gérées via un unique endpoint protégé par session et cloisonné par tenant :

POST /api/campaigns

L'opération est choisie par un champ { action } dans le corps JSON :

action Effet
create Créer un enregistrement de campagne.
update Mettre à jour un enregistrement de campagne.
delete Supprimer un enregistrement de campagne.
preview Répartition des destinataires en direct — aucune mutation, rien n'est envoyé.
send Résoudre + dédupliquer les destinataires, puis appeler Capitole immédiatement.
schedule Résoudre + dédupliquer les destinataires, puis appeler Capitole avec une heure prog.
share Générer un token de rapport public.
unshare Révoquer un token de rapport public.
setdelivery Stocker le taux de livraison réel lu manuellement depuis le portail Capitole.
setbrand Définir la marque de la campagne / de son rapport.

send comme schedule résolvent et dédupliquent l'ensemble des destinataires avant de le remettre à Capitole. Pour un message unique ou un envoi de test, utilisez :

POST /api/sms/send

Stockage KV

Les enregistrements de campagne sont stockés dans l'espace de noms bext KV de l'application sous une clé cloisonnée par tenant :

smscampaign/<tenant>/<id>

Les tokens de rapport public (générés par share) sont stockés sous :

smsreport/<token>

Planification

Note

Il n'y a ni cron ni queue local pour les envois SMS. La planification est entièrement déléguée à la passerelle : une action schedule appelle Capitole avec le champ prog positionné à yyyy-mm-dd hh:mm:ss, et Capitole retient puis dispatch le lot à ce moment. Inklura ne re-sonde ni ne re-déclenche l'envoi lui-même.

Rapports et le flag d'honnêteté sur le % de livraison

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

/rapport/<token>

Le token constitue le contrôle d'accès — en générer un avec l'action share rend le rapport accessible ; unshare le révoque.

Attention

Les taux de livraison et de lecture sont des estimations à moins qu'un opérateur ne saisisse le chiffre réel. Il n'y a aucun callback d'accusé de réception (DLR) de la part de Capitole, donc :

  • Délivrés / Lus valent par défaut une estimation de référence (~95 %). Ils ne deviennent réels que lorsqu'un opérateur lit le chiffre par campagne depuis le portail Capitole et le saisit via l'action setdelivery (qui accepte soit une fraction 0..1, soit un pourcentage 0..100).
  • Les métriques de clic sont réelles — elles proviennent du journal de clics des liens courts.

Traitez le pourcentage de livraison d'un rapport comme une donnée saisie par un humain, pas comme une métrique récupérée.

Voir aussi

  • KV — le store par application qui sous-tend les enregistrements de campagne
  • Vue d'ensemble des intégrations — comment le SMS s'inscrit dans le modèle des deux mondes
  • Journeys marketing — notez que l'étape SMS d'un journey est un stub v1 distinct et non fonctionnel