Guides
Envoyer des messages
Comment un lot se compose, comment les numéros sont normalisés, et ce qui détermine le nombre de segments qui vous sont facturés.
Tout est un lot
Il n’existe pas de point de terminaison pour un message unique. Envoyer à un seul destinataire, c’est un lot de un : même chemin de code, même garantie d’idempotence et même suivi, que vous envoyiez à une personne ou à cent mille.
Un lot accepte entre 1 et 100 000 destinataires, et le corps du message peut aller jusqu’à 4 000 caractères. Au-delà de 10 000 destinataires, la soumission est traitée de façon asynchrone et les compteurs de la réponse arrivent à zéro — voyez la référence des lots pour savoir quoi en faire.
Numéros de téléphone
Les numéros sont acceptés en forme internationale ou locale, puis normalisés au format E.164, avec le Burkina Faso comme région par défaut. Les numéros locaux d’autres pays doivent être envoyés en forme internationale, puisqu’il n’existe aucun moyen de deviner à quel pays ils appartiennent.
Un numéro impossible à analyser n’est pas une erreur. Il devient une ligne de rejet à l’intérieur d’un 202 par ailleurs réussi, avec le reason_code INVALID_MSISDN et un msisdn nul — un mauvais numéro dans une liste de mille ne vous coûte pas les 999 autres.
Choisir un expéditeur
L’expéditeur est ce qui apparaît sur le téléphone — un nom de marque comme PRESTIGE, ou un numéro. Son type est déduit de la valeur plutôt que déclaré : tout ce qui n’est pas numérique est alphanumérique, un numéro long est numérique, et un numéro court est un code court.
Vérifiez is_sendable avant d’envoyer. Un expéditeur peut être approuvé par SMSend sans être enregistré auprès du moindre opérateur ; il affiche alors APPROVED et chaque message envoyé avec lui échoue après avoir consommé la totalité de son budget de tentatives.
Classe de message
La classe est obligatoire, et ce n’est pas une étiquette. Elle décide de la priorité dans la file d’attente, de l’application ou non des heures de silence, des plafonds de fréquence appliqués et de la liste de suppression consultée.
| Valeur | Signification |
|---|---|
TRANSACTIONAL | Déclenché par une action du destinataire — une confirmation de commande, un reçu, un avis de livraison. Non soumis aux heures de silence ni aux plafonds de fréquence. |
MARKETING | Promotionnel. Soumis aux heures de silence, aux plafonds de fréquence quotidiens et hebdomadaires, et aux désinscriptions marketing. |
OTP | Codes à usage unique. Priorité maximale ; jamais retenus par les heures de silence ni par les plafonds. |
Balises de fusion
Placez une balise entre accolades dans le corps et fournissez sa valeur pour chaque destinataire. Une seule requête envoie alors un message différent à chaque personne.
Une balise sans attribut correspondant est remplacée par une chaîne vide, jamais par le texte littéral de la balise. Le destinataire est quand même servi, et l’avertissement n’apparaît pas dans rejections — vérifiez donc vos noms d’attributs, car une faute de frappe produit un message silencieusement tronqué plutôt qu’une erreur.
Encodage et segments
Vous êtes facturé par segment et par destinataire. L’encodage et la segmentation sont calculés sur le corps rendu, après substitution des balises de fusion — deux destinataires d’un même lot peuvent donc être facturés différemment.
| Encodage | Segment unique | Par segment en cas de concaténation |
|---|---|---|
GSM7 | 160 septets | 153 septets |
UCS2 | 70 UTF-16 code units | 67 UTF-16 code units |
Un seul caractère accentué double votre facture
Un unique caractère hors de l’alphabet GSM-7 convertit tout le message en UCS-2, ce qui réduit de plus de moitié la capacité de chaque segment. Dans un texte français, cela arrive en permanence : coût, août, ou un prénom comme Aïssata suffisent chacun à faire basculer le message de ce destinataire.
Quelques caractères existent en GSM-7 mais coûtent deux septets chacun, parce qu’ils sont envoyés sous forme de séquence d’échappement :
Un corps vide compte pour un segment et est facturé. Un caractère à deux unités n’est jamais coupé à la frontière d’un segment : le découpage peut donc laisser un segment incomplet d’une unité et ajouter un segment auquel vous ne vous attendiez pas.
Planification
Renseignez scheduled_at pour envoyer plus tard. La date doit être dans le futur, et le fuseau horaire est un nom IANA — il reprend par défaut celui de votre compte, alors définissez-le explicitement si la campagne relève d’un autre.
Un lot en retard de plus de 30 minutes ne part pas. Il est annulé et intégralement remboursé plutôt qu’envoyé à une heure imprévisible, en partant du principe qu’un message marketing retardé qui arrive à 3 h du matin est pire que pas de message du tout.
Les heures de silence et les plafonds de fréquence du marketing sont évalués au déclenchement du lot, pas à sa soumission. Une campagne composée à 22 h 30 pour un envoi à 9 h n’est pas écartée.
Envois de test
Mettez is_test à true pour exclure un lot des statistiques de campagne. Il est facturé normalement et réellement livré — c’est un indicateur de reporting, pas un bac à sable, et il n’existe aucun mode où SMSend accepte un message sans l’envoyer.