Envoyer un SMS transactionnel

Un SMS transactionnel part à l'unité, au moment où votre système le décide : une confirmation de réservation, un rappel de rendez-vous, un code de retrait. Il est facturé au même tarif que vos campagnes et compte dans le même plafond journalier.

Réservez cette API aux messages qui répondent à une action du destinataire. Les messages promotionnels (offres, relances commerciales) passent par les campagnes, qui gèrent la mention STOP et les désinscriptions. Un destinataire désinscrit de vos campagnes reçoit toujours vos messages transactionnels.

Prérequis

Une clé API secrète dotée de la permission send_transactional_messages (et view_transactional_messages pour consulter les envois). Voir Authentification.
Des crédits, ou un forfait SMS inclus dans votre offre.
Facultatif : un expéditeur SMS vérifié (Paramètres › Expéditeurs). Sans lui, le message part depuis le numéro court de la plateforme.

Envoyer

curl https://api.metaventus.com/v1/transactional/sms \
  -H "X-API-Key: VOTRE_CLE_SECRETE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: resa-20481" \
  -d '{
    "to": "+33612345678",
    "from": "LEBISTROT",
    "body": "Votre table pour 4 est confirmée ce soir à 20h. Merci !",
    "reference": "resa-20481"
  }'

Champ	Obligatoire	Description
`to`	oui	Numéro du destinataire, au format international (`+33612345678`). Un numéro national est lu comme français.
`body`	oui	Le texte, envoyé tel quel. 9 SMS au plus (voir Longueur et coût).
`from`	non	Un expéditeur SMS vérifié de votre compte. Sans `from`, votre expéditeur par défaut, sinon celui de la plateforme.
`reference`	non	Votre identifiant (n° de réservation…), 128 caractères au plus. Renvoyé tel quel, filtrable.

Réponse 202 Accepted : le message est accepté, facturé et en route.

{
  "id": "922c2bfd-32ec-4773-b348-63967731e3a7",
  "channel": "sms",
  "to": "+33612345678",
  "from": "LEBISTROT",
  "body": "Votre table pour 4 est confirmée ce soir à 20h. Merci !",
  "segments": 1,
  "encoding": "gsm7",
  "country_code": "33",
  "status": "queued",
  "reference": "resa-20481",
  "created_at": "2026-10-14T09:00:00Z",
  "updated_at": "2026-10-14T09:00:00Z"
}

202 n'est pas une erreur : c'est la réponse normale d'un envoi.

Ne jamais envoyer deux fois

Passez un en-tête Idempotency-Key propre à chaque message (votre numéro de réservation, par exemple). Si votre requête expire et que vous la rejouez avec la même clé, le premier message est renvoyé avec un 200 et l'en-tête Idempotent-Replayed: true : rien n'est renvoyé au destinataire, rien n'est refacturé.

Réutiliser une clé pour un autre message (autre destinataire ou autre texte) est refusé (422 idempotency_key_reused).

Longueur et coût

Un SMS est facturé au nombre de SMS que l'opérateur transporte, au tarif du pays du destinataire — le même que vos campagnes. La réponse indique ce qui a été compté (segments, encoding, country_code).

Alphabet	1 SMS	Au-delà, par SMS
GSM-7 (lettres latines, `é`, `è`, `à`…)	160 caractères	153 caractères
Unicode (dès un seul caractère hors GSM-7 : `ç`, `ê`, `â`, `ô`, `À`, emoji…)	70 caractères	67 caractères

Les caractères € [ ] { } ^ ~ | \ comptent double en GSM-7. Un message est limité à 9 SMS ; au-delà, il est refusé (400 body_too_long) sans rien facturer.

Suivre la livraison

curl https://api.metaventus.com/v1/transactional/messages/922c2bfd-32ec-4773-b348-63967731e3a7 \
  -H "X-API-Key: VOTRE_CLE_SECRETE"

`status`	Signification
`queued`	Accepté et facturé, en cours de remise à l'opérateur.
`sent`	Remis à l'opérateur (`sent_at`).
`delivered`	Reçu par le téléphone (`delivered_at`).
`failed`	Non remis — voir `error_code`.

`error_code`	Cause	Facturé
`rejected`	Refusé par l'opérateur (numéro ou contenu).	Non, recrédité
`not_sent`	Jamais transmis à l'opérateur.	Non, recrédité
`undelivered`	Transporté mais non reçu (téléphone éteint, hors réseau, numéro inactif).	Oui

L'accusé de réception arrive en général en quelques secondes ; l'opérateur retente la livraison jusqu'à 48 heures. Le statut est mis à jour toutes les deux minutes environ : interrogez-le avec parcimonie.

Lister les envois

curl "https://api.metaventus.com/v1/transactional/messages?status=failed&limit=50" \
  -H "X-API-Key: VOTRE_CLE_SECRETE"

Filtres : status, reference, to. Les messages viennent du plus récent au plus ancien, limit de 1 à 100 (50 par défaut). Si has_more vaut true, demandez la page suivante avec starting_after=<id du dernier message reçu>.

Refus

Un envoi refusé n'est ni envoyé ni facturé. Le corps porte un code stable, sur lequel brancher votre logique, et une phrase explicative dans error.

Statut	`code`	Cause	Conduite à tenir
`400`	`invalid_to`, `invalid_body`, `body_too_long`, `invalid_reference`	Requête invalide	Corriger
`402`	`insufficient_credits`	Solde insuffisant (`details.credits_needed`, `details.wallet_balance`)	Recharger, puis réessayer
`403`	`account_suspended`	Abonnement suspendu	Régulariser
`422`	`sender_not_allowed`	`from` n'est pas un expéditeur vérifié du compte	Corriger `from` ou le retirer
`422`	`idempotency_key_reused`	Clé déjà utilisée pour un autre message	Nouvelle clé
`429`	`daily_limit_reached`	Plafond SMS de votre offre atteint pour la période (`details.limit`, `details.used`)	Attendre le lendemain, ou changer d'offre
`503`	`temporarily_unavailable`	Incident passager	Réessayer avec la même `Idempotency-Key`

{
  "error": "Plafond de votre offre atteint : 100 SMS par jour, il en reste 1, ce message en compte 2.",
  "code": "daily_limit_reached",
  "details": { "limit": 100, "used": 99, "period": "daily", "segments": 2 }
}

Le plafond journalier est partagé avec vos campagnes, scénarios et rappels de rendez-vous : c'est un seul forfait SMS, quel que soit le canal d'envoi.

Prérequis​

Envoyer​

Ne jamais envoyer deux fois​

Longueur et coût​

Suivre la livraison​

Lister les envois​

Refus​