Signlift

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 sent indé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 GET consomme 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 failed dont l'issue est inconnue, renvoyer avec une nouvelle reference est 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, passez resend: true avec une nouvelle reference : 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 statuts sent, delivered et undelivered sont 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_price et currency valent alors null dans 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

On this page