Programmer un SMS

Préparer la programmation

Utilisez POST /api/sms/v2/messages/ avec send_at. La clé doit posséder sms.schedule ; delivery.read permet ensuite de consulter le message. La présence de send_at détermine la permission demandée, même si la clé possède déjà sms.send.

Préparez une clé d’idempotence stable pour l’opération et les crédits correspondant aux segments du texte. Remplacer une lecture préalable du solde par une réservation dans votre application ne suffit pas : seule l’admission par l’API réserve les crédits.

Donner une date sans ambiguïté

send_at doit être une date future RFC 3339 avec secondes et fuseau explicite : Z ou un décalage comme +03:00. Les dates locales sans fuseau, null et les dates passées sont refusées.

L’exemple suppose que BEFIANA_SMS_API_KEY est défini comme dans le quickstart. Remplacez la date par une date future adaptée à votre besoin et le numéro par un destinataire autorisé.

curl --include --request POST 'https://api.befiana.cloud/api/sms/v2/messages/' \
  --header "Authorization: Bearer $BEFIANA_SMS_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: appointment-0001-reminder' \
  --data '{"to":"+261340000000","text":"Your appointment is tomorrow.","send_at":"2030-01-15T09:00:00+03:00"}'

Une admission réussie renvoie HTTP 202. Exemple illustratif :

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /api/sms/v2/messages/8607cac9-cfda-437f-99f3-ec88824e49f8/

{
  "id": "8607cac9-cfda-437f-99f3-ec88824e49f8",
  "to": "+261340000000",
  "sender_name": "BEFIANA",
  "segments": 1,
  "status": "scheduled",
  "send_at": "2030-01-15T06:00:00Z",
  "delivery_time": null
}

La réponse exprime ici en UTC le même instant que 09:00:00+03:00. Comparez les instants, pas les chaînes de dates. send_at conserve la date demandée après le traitement. Le nom BEFIANA suppose la sélection d’expéditeur correspondante.

Ce que confirme la réponse

L’identifiant id est consultable dès la création. Les crédits sont réservés et scheduled signifie que le message attend sa date d’envoi. L’heure demandée indique le début souhaité du traitement ; elle ne garantit pas une réception à la seconde près.

Consultez GET /api/sms/v2/messages/{message_id}/ avec une clé delivery.read. Le traitement peut ensuite être processing, accepted ou un autre statut. Un résultat inconnu ne justifie pas une nouvelle soumission.

Reprendre ou changer de besoin

En cas de réponse perdue, reprenez exactement la requête avec la même clé d’idempotence. Une reprise d’une programmation déjà admise restitue la réponse initiale, même si son traitement a progressé. Si les données du message terminé ont ensuite fait l’objet d’un effacement ciblé, le rejeu renvoie 410 personal_data_erased : arrêtez les reprises et conservez la clé sans nouvel envoi. Voir l’idempotence.

Le contrat v2 ne fournit pas d’opération publique de modification ou d’annulation d’un message programmé. Ne créez pas un second message pour « remplacer » le premier sans avoir traité le risque de double envoi.

Pour plusieurs destinataires partageant la même date et le même texte, utilisez un lot. Sans programmation, utilisez l’envoi immédiat.