SMS - Envoyer avec l'API

Cette page détaille la requête d'envoi de SMS (POST /sms), avec des exemples JSON complets et la liste des codes retour et payloads d'erreur possibles.

Pour l'authentification, l'URL de base et le format général des requêtes, voir SMS - Didacticiels.

Envoyer une requête avec succès ne garantit pas la livraison du SMS. La requête est acceptée de manière synchrone, mais le SMS est délivré de manière asynchrone au terminal du destinataire. Utilisez la requête de consultation du statut d'un SMS pour vérifier sa livraison.

Requête

POST /sms
Content-Type: application/json
Authorization: Basic <vos identifiants encodés en base64>

Corps de la requête

Champ	Type	Requis	Description
phoneNumber	string	Oui	Numéro du destinataire : soit un numéro local français (10 chiffres), soit un numéro international au format +<indicatif><numéro>.
message	string	Oui	Contenu du message, 600 caractères maximum. Un SMS est facturé tous les 160 caractères.
allowUnicode	boolean	Non	true par défaut. Si false, force l'encodage GSM 03.38 au lieu d'unicode.
metadata	object	Non	Objet JSON libre pour associer des données personnalisées au message (voir exemple ci-dessous).

Exemple simple

{
  "phoneNumber": "[phone]",
  "message": "Please call me back"
}

Exemple avec métadonnées personnalisées

Le tag metadata ajouté est renvoyé lors de la consultation des détails du SMS.

{
  "phoneNumber": "[phone]",
  "message": "Please call me back",
  "metadata": {
    "myCustomerId": "123de32",
    "caller": "MyApp 2.2"
  }
}

Réponse en cas de succès

Un envoi accepté renvoie 200 avec l'identifiant du message, à utiliser pour consulter son statut de livraison par la suite.

{
  "messageId": "77a76363bd882992893",
  "smsCount": 1
}

Codes retour et erreurs possibles

Le format du corps d'erreur dépend du contrôle qui a rejeté la requête - il n'y a pas de format unifié entre les différents codes retour.

Code	Signification
200	SMS accepté pour envoi.
400	Requête invalide (champ manquant/trop long, numéro non reconnu, ou rejet du fournisseur SMS).
422	Destinataire non autorisé pour ce compte (voir ci-dessous).
429	Seuil de débit (SMS/minute ou SMS/heure) atteint pour ce compte.
503	Aucun fournisseur SMS disponible actuellement - à retenter plus tard.

400 Bad Request

Trois situations distinctes renvoient 400, avec trois formats de corps différents :

• Un champ manquant/vide, ou un message de plus de 600 caractères, échoue à la validation de champ. Le corps est une correspondance clé/valeur, une entrée par champ invalide :

  {
    "message": "length must be between 1 and 600"
  }

• Un phoneNumber qui ne peut pas être analysé comme un numéro valide (format incorrect, indicatif de pays inconnu, caractères non numériques...) échoue à un contrôle ultérieur, une fois la validation de champ passée. Le corps n'a qu'une clé error, dont la valeur est le phoneNumber envoyé, tel quel :

  {
    "error": "+33 6 not-a-number"
  }

• Si la configuration du fournisseur SMS de votre compte rejette elle-même la requête (par exemple un fromName invalide), le corps est un tableau de causes :

  [
    {
      "code": "INVALID_MESSAGE_LENGTH",
      "on": "message",
      "message": "Message length cannot exceed 600 characters"
    }
  ]

422 Unprocessable Entity

Le destinataire n'est pas autorisé pour votre compte. Ceci couvre trois politiques indépendantes configurables par compte : une liste blanche de pays de destination, une liste noire de pays de destination, et une liste blanche de numéros de téléphone. Les trois produisent le même corps - la réponse n'indique pas laquelle s'est déclenchée. C'est un 422, pas un 403 : vos identifiants et votre rôle sont valides, c'est spécifiquement le destinataire de cette requête que la politique de votre compte rejette.

{
  "error": "RECIPIENT_NOT_ALLOWED"
}

Aucun SMS n'est envoyé et aucune tentative de livraison n'a lieu dans ce cas.

Si une liste blanche de pays contient au moins une entrée, elle prend systématiquement le pas sur la liste noire de pays, qui est alors ignorée pour ce compte.

429 Too Many Requests

Renvoyé lorsque le seuil de débit (SMS/minute ou SMS/heure) de votre compte est atteint. Le format du corps correspond au cas de rejet par le fournisseur SMS ci-dessus (un tableau de causes) - notez que message est un template générique non interpolé ici (le %s littéral n'est pas une erreur), le détail réel (quel seuil, combien de SMS) se trouve dans args :

[
  {
    "code": "LIMIT_REACHED",
    "message": "Request cannot be completed because of limit [%s]",
    "args": ["Threshold of 10 SMS within a minute has been reached."]
  }
]

503 Service Unavailable

Aucun fournisseur SMS n'est actuellement disponible pour envoyer votre message - à retenter plus tard, en suivant le pattern décrit ci-dessous.

{
  "error": "No providers are currently available to send SMS, retry later"
}

Pattern client recommandé

Vortext peut avoir jusqu'à 5 secondes d'indisponibilité en cas de défaillance d'un nœud de notre infrastructure clusterisée. Dans ce cas, vous obtiendrez une erreur 502 ou 503. Pour garantir la délivrance du message, envisagez d'appeler le service avec ce pattern :

sendSms();
if (échec) {
  attendre(5 secondes);
  sendSms();
  if (échec) {
    ceciEstUnVraiEchec();
  }
}