SMS transactionnels
Envoyer des SMS à vos propres destinataires par l'API (activation, expéditeurs, suivi, plafond mensuel, facturation).
L'API SMS envoie un message d'un seul segment (code de retrait, rappel, notification) à un destinataire de votre choix, refacturé au SMS. Le détail des champs et des erreurs est dans la référence.
Activation
Le service est activé à la demande, pour les organisations Pro et Entreprise. Depuis l'espace client, un administrateur de l'organisation clique sur « Demander l'activation » ; l'équipe Signlift active ensuite le service.
Tant que le service n'est pas activé, POST /api/v1/sms_messages répond
403 sms_service_disabled, sandbox comprise. Il répond de même si
l'organisation revient sur un plan qui n'inclut pas le service. La lecture d'un
message déjà créé reste possible après une désactivation.
En production, l'API exige en plus un accès payant, comme pour toutes les
routes : sans lui, 402 payment_required.
Expéditeurs
Le champ sender doit être l'un des expéditeurs déclarés par Signlift pour
votre organisation (3 à 11 lettres et chiffres, au moins une lettre). Signlift
ne le remplace jamais : un expéditeur inconnu est refusé en 422 unknown_sender.
Certains opérateurs étrangers réécrivent ou refusent un expéditeur
alphanumérique, et Signlift ne peut pas l'empêcher. Si aucun opérateur du pays
ne peut utiliser votre expéditeur, l'appel répond 422 sender_unavailable.
Le message
Un message tient dans un seul segment : alphabet GSM-7, 160 septets au plus.
Les caractères € [ ] { } \ ^ ~ | comptent pour deux septets. Un texte plus long,
ou contenant un caractère hors GSM-7, est refusé en 422 invalid_body : il n'est
ni découpé ni tronqué. Le message d'erreur liste les caractères en cause.
Envoi et suivi
POST /api/v1/sms_messages répond 202 avant l'envoi. Il n'y a pas de
webhook pour ce service : le suivi se fait en interrogeant
GET /api/v1/sms_messages/{id} avec l'id renvoyé.
Un message passe par queued, sending, puis sent, et enfin delivered ou
undelivered quand l'accusé de réception arrive. Deux délais le font passer en
failed : expired s'il n'est pas pris en charge au bout d'environ 15 minutes,
outcome_unknown si l'issue reste inconnue environ 1 heure après la prise en
charge. La liste complète est dans la référence.
- Bornez votre suivi. Un message peut rester
sentindéfiniment si aucun accusé n'arrive : arrêtez d'interroger à un statut final (delivered,undelivered,failed,simulated) ou après un délai que vous fixez. - Espacez les lectures. Chaque
GETconsomme le budget d'appels de l'organisation, comme un envoi : voir Limites et rate-limits. - Signlift ne renvoie jamais automatiquement un message. Pour un message
faileddont l'issue est inconnue, renvoyer avec une nouvellereferenceest votre décision : vous seul savez si un doublon est acceptable. - Renvoi à la demande du destinataire. Pour un bouton « Renvoyer », ou après
un
undelivered, passezresend: trueavec une nouvellereference: Signlift retrouve le SMS précédent et envoie d'abord par l'autre opérateur, pour éviter le chemin qui a échoué. Voir Renvoi.
Idempotence
Passez une reference unique par message métier (order-1042). Rejouer l'appel
avec la même reference et le même contenu renvoie le message existant en
200, sans nouvel envoi ; avec un autre contenu, 409 reference_conflict.
Après un timeout réseau, rejouez donc le même appel : il n'y a jamais de second
envoi, et le status renvoyé dit où en est le message. La reference est unique
pour toute la vie de l'application, 100 caractères au plus.
Plafond mensuel
Le nombre de messages créés en production dans le mois civil (heure de
Paris) est plafonné, hors messages failed. Le plafond par défaut est de 10 000
messages, et Signlift peut le régler pour votre organisation.
Une fois atteint, POST répond 403 sms_quota_exceeded, sans Retry-After :
attendre quelques minutes ne le lève pas, il se lève au mois suivant ou quand
Signlift relève le plafond. Un rejeu idempotent d'un message existant passe
malgré tout. Le bac à sable n'est pas compté.
Sandbox
Mêmes validations qu'en production, mais aucun appel à un opérateur : le message
passe directement en simulated, n'est pas facturé et ne compte pas dans le
plafond. Aucun SMS n'est reçu.
Facturation et pays
- Chaque SMS est facturé à son prix pour le pays du destinataire, remise éventuelle
de l'organisation comprise, figé à la création, sur la facture mensuelle du mois
où il a été envoyé. Un SMS offert reste compté dans le plafond mensuel, à
0. Seuls les messages de production aux statutssent,deliveredetundeliveredsont facturés. - La grille de prix n'est pas publiée ici. Les organisations Pro la consultent dans
leur espace client ; les prix des organisations Entreprise sont fixés par contrat,
et
unit_priceetcurrencyvalent alorsnulldans les réponses. - Certains pays sont exclus : les États-Unis, le Canada et leurs territoires
(Porto Rico, Guam, îles Vierges américaines, Samoa américaines, Mariannes du
Nord, îles mineures éloignées des États-Unis). Un numéro de ces pays répond
422 unsupported_destination. Un pays sans prix ou non desservi répond de même.
Conservation des données
Le texte d'un message est effacé 7 jours après son envoi, le numéro 30
jours après sa création ; to vaut alors null. L'API ne renvoie jamais le
texte : conservez-le de votre côté si vous en avez besoin. Voir
la référence.
Aller plus loin
- Référence SMS transactionnels : champs, statuts, erreurs.
- Limites et rate-limits : budget d'appels et plafond mensuel.
- Bac à sable : développer sans envoyer de SMS réel.