Programmer un lot de SMS

Un texte et une date pour plusieurs destinataires

POST /api/sms/v2/message-batches/ demande la permission sms.schedule et un en-tête Idempotency-Key. Tous les destinataires partagent text, send_at et, si fourni, sender_name. send_at est obligatoire et doit être futur, avec un fuseau explicite.

recipients contient de 1 à 1000 numéros distincts au format mobile malgache E.164. Un doublon est refusé ; il n’est pas retiré automatiquement. Ce contrat ne fournit pas de lot immédiat ni de texte différent par destinataire.

Créer le lot

Définissez BEFIANA_SMS_API_KEY comme dans le quickstart. Remplacez la date et les numéros de démonstration.

curl --include --request POST 'https://api.befiana.cloud/api/sms/v2/message-batches/' \
  --header "Authorization: Bearer $BEFIANA_SMS_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: event-0001-reminder-batch' \
  --data '{"recipients":["+261340000000","+261320000000"],"text":"Your event starts tomorrow.","send_at":"2030-01-15T09:00:00+03:00"}'

Exemple de réponse HTTP 202 avec identifiant et dates illustratifs :

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /api/sms/v2/message-batches/363e02d3-04ce-434b-951f-c9d034f86d5e/

{
  "id": "363e02d3-04ce-434b-951f-c9d034f86d5e",
  "recipient_count": 2,
  "credits_reserved": 2,
  "send_at": "2030-01-15T06:00:00Z",
  "created_at": "2030-01-14T12:00:00Z",
  "counts": {
    "scheduled": 2,
    "processing": 0,
    "accepted": 0,
    "delivered": 0,
    "undeliverable": 0,
    "blocked": 0,
    "failed": 0,
    "unknown": 0
  }
}

Deux destinataires recevant chacun un texte d’un segment nécessitent deux crédits. credits_reserved conserve cette réservation initiale ; il ne représente pas les réservations restantes après traitement. Consultez le solde pour connaître les valeurs courantes.

Comprendre l’admission atomique

La validation, la création des messages et la réservation des crédits forment une seule admission. Un numéro invalide, un doublon ou des crédits insuffisants ne produisent pas une acceptation partielle du lot. Une réponse 202 signifie que l’ensemble est admis, pas que l’ensemble sera livré.

Après admission, chaque message a son propre résultat. Les compteurs de GET /message-batches/{batch_id}/ reflètent les états courants. Une reprise idempotente du POST restitue au contraire la réponse initiale.

Consulter et paginer

La permission delivery.read permet de consulter le lot et ses messages.

export BATCH_ID='REPLACE_WITH_RETURNED_UUID'
curl "https://api.befiana.cloud/api/sms/v2/message-batches/$BATCH_ID/" \
  --header "Authorization: Bearer $BEFIANA_SMS_API_KEY"
curl "https://api.befiana.cloud/api/sms/v2/message-batches/$BATCH_ID/messages/" \
  --header "Authorization: Bearer $BEFIANA_SMS_API_KEY"

La liste répond avec results et next_cursor. Elle contient au plus 100 messages, dans l’ordre des destinataires fournis. Chaque message possède un id public indépendant.

Si next_cursor n’est pas null, transmettez sa valeur inchangée au paramètre cursor du même lot :

export NEXT_CURSOR='REPLACE_WITH_RETURNED_NEXT_CURSOR'
curl --get "https://api.befiana.cloud/api/sms/v2/message-batches/$BATCH_ID/messages/" \
  --header "Authorization: Bearer $BEFIANA_SMS_API_KEY" \
  --data-urlencode "cursor=$NEXT_CURSOR"

Le curseur est opaque et n’est pas une URL. Ne le décodez pas, ne l’incrémentez pas et ne le réutilisez pas pour un autre lot. null marque la fin. Les statuts peuvent évoluer entre deux pages ; le parcours n’est pas une photographie figée des livraisons.

Gérer une reprise

Conservez la même clé, le même ordre de destinataires et le même corps lors d’une reprise réseau. Ne recréez pas le lot pour obtenir un suivi actualisé. Utilisez la recette de pagination, l’idempotence et les statuts pour distinguer reprise technique et nouvelle opération métier.