Envoyer un premier SMS par API
Ce guide montre l’envoi d’un SMS avec l’API de démonstration, la lecture des segments et de l’encodage, puis le suivi des statuts. Le SMS est simulé tant qu’aucun fournisseur n’est configuré.
Mis à jour le
Avant de commencer
- Une clé de test fictive : tq_test_EXEMPLE.
- Un numéro expéditeur et un destinataire au format E.164 sans espace. Ici : +33199001234 et +33199005678, plage fictive.
- Une idée claire de la nature du message : transactionnel (lié à une action de la personne) ou marketing (communication commerciale).
Envoyer le message
- Rédigez le texte. Un SMS long est découpé en plusieurs segments, chacun étant facturable selon votre contrat.
- Choisissez la nature : transactional ou marketing. Un message marketing relève de règles propres à chaque pays, notamment sur le consentement et les listes d’opposition.
- Envoyez POST /messages avec une clé Idempotency-Key. Ajoutez scheduled_at et timezone pour programmer l’envoi.
curl -X POST https://api.example.test/v1/messages \
-H "Authorization: Bearer tq_test_EXEMPLE" \
-H "Idempotency-Key: 8d4e6b10-2c9a-47f3-b5e1-0a7c3d9f2e64" \
-H "Content-Type: application/json" \
-d '{"from":"+33199001234","to":"+33199005678","text":"Votre code de test est 4821.","nature":"transactional"}'Lire la réponse
La réponse indique le statut queued : le message est pris en charge, pas encore remis. Les champs segments et encoding vous montrent comment le texte a été découpé. L’encodage est GSM-7 ou UCS-2.
Un seul caractère hors de l’alphabet GSM-7 peut faire basculer tout le message en UCS-2, ce qui réduit la taille d’un segment et peut augmenter leur nombre. Vérifiez le champ segments avant d’envoyer à grande échelle.
{
"id": "msg_EXEMPLE_001",
"status": "queued",
"segments": 1,
"encoding": "GSM-7",
"simulated": true
}Programmer un envoi
Ajoutez scheduled_at (date et heure) et timezone (fuseau horaire) au corps de la requête. Précisez toujours le fuseau : une même heure n’a pas le même sens à Paris et à Mexico.
{
"from": "+33199001234",
"to": "+33199005678",
"text": "Rappel : rendez-vous demain.",
"nature": "transactional",
"scheduled_at": "2026-11-09T09:00:00",
"timezone": "Europe/Paris"
}Comprendre les statuts
Vous recevez ces statuts par les événements message.sent, message.delivered et message.undelivered, via un webhook signé.
| Statut | Signification |
|---|---|
| queued | Pris en charge par la plateforme, pas encore transmis. |
| sent | Transmis vers le réseau. Ce n’est pas une remise. |
| delivered | Remis au terminal du destinataire. Cela ne veut pas dire lu. |
| undelivered | Non remis. La cause n’est pas toujours disponible. |
| unknown | Statut final non connu. Il peut ne jamais évoluer : ne le traitez pas comme un échec ni comme une réussite. |
Erreurs fréquentes
| Symptôme | Cause probable | Que faire |
|---|---|---|
| 400 invalid_request | Numéro mal formé, nature absente ou différente de transactional et marketing, texte vide. | Corrigez le champ signalé dans le message d’erreur. |
| 409 idempotency_conflict | Même Idempotency-Key avec un texte différent. | Nouvelle clé pour un nouveau message. |
| 429 rate_limited | Débit trop élevé. | Respectez Retry-After puis réessayez. |
| Plus de segments que prévu | Un caractère spécial a fait passer le message en UCS-2. | Lisez encoding et segments, puis simplifiez le texte si besoin. |
Ce que ce guide ne fait pas
- Il n’envoie aucun SMS réel tant qu’aucun fournisseur n’est configuré.
- Il ne promet aucune remise : un statut delivered n’est pas garanti, et delivered ne signifie pas que le message a été lu.
- Il ne traite pas la réception de SMS. Les réponses entrantes exigent un numéro et un pays compatibles.
- Il ne remplace pas la vérification de vos obligations (consentement, listes d’opposition, identité de l’expéditeur), qui se déterminent selon le service, le pays et votre rôle réel.
Questions fréquentes
Pourquoi mon SMS compte-t-il plusieurs segments ?
Parce que le texte dépasse la taille d’un segment, ou parce qu’un caractère spécial a imposé l’encodage UCS-2. Le champ segments de la réponse vous donne le nombre exact avant l’envoi réel.
Puis-je envoyer vers n’importe quel pays ?
Non. Les capacités SMS dépendent du pays, du fournisseur retenu et du contrat. Consultez le catalogue des pays et demandez un devis pour votre périmètre.