Envoyer des SMS et les MMS pris en charge

Avant l’envoi

Envoyez un SMS ou un MMS pris en charge à l’aide d’un numéro d’envoi configuré pour votre compte. Il s’agit d’une opération en production qui peut contacter des destinataires et entraîner des frais. Limitez-vous aux destinataires autorisés et au trafic approuvé ; les numéros et la référence de l’exemple ci-dessous sont fictifs.

Votre compte doit disposer d’une approbation pour la messagerie sortante et des autorisations applicables à l’expéditeur, au pays et au trafic. Les identifiants directs des utilisateurs de comptes personnels ou grand public ne sont pas admissibles pour cette API. Les identifiants dédiés à l’API et approuvés relèvent d’une procédure d’admissibilité distincte ; les expéditeurs mobiles P2P peuvent nécessiter des autorisations supplémentaires pour le P2P et les États-Unis/le Canada. Confirmez auprès de MultiTEL la configuration requise pour votre compte, plutôt que de considérer un identifiant d’API comme une autorisation automatique d’envoyer tout type de trafic.

Requête d’envoi

Authentifiez-vous via HTTPS avec un compte API activé, depuis son adresse IP source autorisée. Conservez les identifiants dans un stockage de secrets côté serveur. Utilisez POST avec des champs encodés au format formulaire, ou un objet JSON lorsqu’aucun champ de formulaire ni paramètre de requête n’est fourni. Ne placez ni les identifiants ni le texte du message dans une URL.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'from=12025550123' \
  --data-urlencode 'to=12025550124' \
  --data-urlencode 'text=Your requested update is ready.' \
  --data-urlencode 'reference=order-update-example' \
  https://api.multitel.net/v3/sendsms

Pour un tableau JSON, utilisez un véritable tableau dans to ; ne placez pas une chaîne représentant un tableau JSON dans un champ de formulaire. Effectuez le premier test d’intégration avec un envoi à un seul destinataire. La prise en charge des envois groupés et des MMS varie selon la route ; confirmez donc la combinaison prise en charge avant de les utiliser.

Lire le résultat complet

Seuls certains champs sont présentés à titre d’exemple ; le coût affiché ne constitue pas un devis.

{
  "status": {
    "code": "200",
    "msg": ""
  },
  "response": {
    "sms_log_id_ori": 42,
    "to": "12025550124",
    "from": "12025550123",
    "status": "Success",
    "message": "Message queued",
    "causecode": 0,
    "uniqueid": "fixture-message",
    "cost": "$0.0120",
    "carrier_fee_usd": "0.0020000000",
    "chars": 31,
    "parts": 1,
    "encoding": "GSM-7",
    "permsg": "$0.0120",
    "pid": "fixture-reference"
  }
}

Vérifiez conjointement le statut HTTP, le champ JSON status.code et les champs status/message de la réponse. Les codes de résultat peuvent être des chaînes de caractères. Conservez sms_log_id_ori ainsi que les valeurs de message et de référence renvoyées pour permettre au support d’établir les correspondances. Les valeurs historiques uniqueid et pid varient selon la route ; n’en déduisez pas le format et ne supposez pas qu’il s’agit de jetons d’idempotence client.

Success ou Message queued indique normalement l’acceptation par la route sélectionnée, et non la réception sur le téléphone d’une personne. Un statut de notification de rappel initiale tel que sent ne suffit pas à lui seul à établir la livraison finale.

Segments et frais

Utilisez l’outil Analyse de la longueur des SMS sur l’intégralité du texte final avant l’envoi. Les tarifs des SMS dépendent de la destination et du service associé au compte ; les frais d’opérateur applicables sont ajoutés par segment. Le traitement d’envoi additionne les tarifs des destinataires et les frais applicables, puis multiplie le résultat par le nombre calculé de segments SMS. Pour ce calcul, il considère une requête MMS comme un seul message.

cost et permsg sont des chaînes de caractères représentant des montants monétaires formatés dans la réponse historique. carrier_fee_usd indique la part des frais d’opérateur en USD, déjà incluse dans le total calculé de l’envoi ; ne l’ajoutez pas une seconde fois. Les tarifs réels et la disponibilité des routes doivent être vérifiés pour votre compte. Cette requête ne se limite pas à une consultation de tarif.

Le code examiné débite le compte après la réussite de son parcours d’envoi à l’opérateur, mais l’acceptation par l’opérateur, l’enregistrement local et la facturation ne constituent pas une transaction unique. Une erreur ou un dépassement de délai peut survenir après l’acceptation d’une requête en amont. Aucune clé d’idempotence client n’est exposée : réutiliser la même référence peut entraîner un nouvel envoi et une nouvelle facturation.

Livraison locale et résultats mixtes

Les numéros hébergés localement peuvent être admis (accepted) dans le flux de messagerie entrante de MultiTEL sans envoi à un opérateur externe. Pour une requête entièrement locale, la réponse peut inclure accepted, message_id, provider et delivery_status. L’acceptation locale ne garantit pas que le transfert vers la destination configurée par le destinataire a fonctionné.

Examinez local_delivery_results et partial lorsqu’ils sont présents. Un destinataire peut afficher accepted à true alors que son transfert a échoué. Une requête mixte peut comporter des destinataires acceptés par l’opérateur (accepted) et une partie locale en échec. Ne relancez pas automatiquement l’ensemble du lot : rapprochez d’abord les résultats pour chaque destinataire.

Dans ce parcours, une acceptation entièrement locale indique un coût sortant nul, mais les destinataires peuvent toujours supporter leurs frais habituels de messagerie entrante. N’interprétez pas un coût sortant nul comme la garantie qu’aucun compte n’est facturé.

Notifications de rappel et corrélation

Lorsque notifyurl est fourni, la notification de rappel initiale comporte une enveloppe status et des champs de réponse comprenant message_id, reference, from, to, status, status_text, error_code, timestamp et accepted. Des résultats locaux peuvent également être présents. Conservez les informations de corrélation sans consigner les identifiants d’API ni le contenu des messages qui n’est pas nécessaire.

Ce gestionnaire n’ajoute pas de champ de signature à cette notification de rappel initiale. N’utilisez pas une notification de rappel non vérifiée comme seule autorisation pour une autre action. Consultez la configuration d’intégration et de webhook prise en charge pour votre compte et rapprochez les résultats incertains des enregistrements du portail ou faites appel au support. Ne supposez pas que les notifications de rappel arrivent une seule fois ni dans l’ordre des livraisons finales.

Échecs et reprise en toute sécurité

Les échecs de validation peuvent utiliser le code API 403. Les refus liés à l’approbation du compte, au P2P et aux règles applicables au pays peuvent également définir le statut HTTP 403 et inclure un champ response.code exploitable automatiquement. Les limites de débit peuvent utiliser le code 429 avec des informations sur la nouvelle tentative. Une règle indisponible ou un échec d’envoi ou d’enregistrement local peut utiliser le code 503 ou 500 ; le traitement historique d’un solde insuffisant peut également renvoyer 500.

Pour le code 429, respectez Retry-After et toute valeur response.retry_after fournie. En cas de rejet lié au compte, à l’expéditeur, au pays ou au destinataire, corrigez la cause avant de réessayer. En cas de dépassement de délai ou de résultat d’envoi incertain, conservez l’heure de la requête, la référence et les identifiants renvoyés, consultez le portail et contactez le support avant de renvoyer le message. L’absence d’une entrée de journal ne prouve pas à elle seule qu’aucun opérateur n’a accepté la requête.