Aller au contenu

Envoyer

Messages

Texte libre, médias, groupes, idempotence, suivi et historique des messages.

POST /v1/messages envoie un message unique. Il accepte trois formes :

  • un modèle (template et variables), décrit dans Notifications ;
  • un texte libre (text) ;
  • un média (media) : image, vidéo, audio ou document.

Attention : le texte libre et les médias partent uniquement de votre propre numéro. Les numéros Flare, partagés entre tous nos clients, n'envoient que des codes OTP et des modèles validés. Voir Numéros.

Texte libre

curl https://flare.zola-labs.com/v1/messages \
  -H "Authorization: Bearer flr_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{"to": "+237699001122", "text": "Votre colis vous attend au point relais de Bonapriso."}'

Le texte peut faire jusqu'à 4 096 caractères.

Médias

Champ Type Obligatoire Description
media.type texte oui image, video, audio ou document.
media.url texte oui Adresse publique du fichier (http ou https). Flare le télécharge au moment de l'envoi.
media.caption texte non Légende affichée sous le média.
media.filename texte non Nom du fichier, pour un document.
cURL
curl https://flare.zola-labs.com/v1/messages \
  -H "Authorization: Bearer flr_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+237699001122",
    "media": {
      "type": "document",
      "url": "https://exemple.com/factures/F-2026-118.pdf",
      "filename": "Facture F-2026-118.pdf",
      "caption": "Votre facture de novembre"
    }
  }'

Groupes et chaînes

Depuis votre numéro, vous pouvez écrire à un groupe dont il fait partie : passez l'identifiant de conversation du groupe (il se termine par @g.us) dans to. Pour retrouver ces identifiants, listez vos groupes avec l'API avancée.

JSON
{ "to": "120363041234567890@g.us", "text": "Réunion d'équipe à 15 h." }

Choisir l'expéditeur

Le champ sender précise d'où part le message :

Valeur Comportement
auto (par défaut) Suit le réglage Expéditeur par défaut de votre compte.
shared Les numéros Flare, en relais. Codes OTP et modèles validés uniquement.
dedicated Votre numéro relié, et lui seul.

Un texte libre, un média ou un identifiant de groupe partent toujours de votre numéro, quelle que soit la valeur choisie.

Éviter les doublons

Un réseau qui coupe au mauvais moment, et votre application ne sait plus si sa requête est passée. Ajoutez l'en-tête Idempotency-Key avec une valeur unique pour chaque message (par exemple commande-2048-confirmation) : si la même clé revient, Flare renvoie le message déjà créé (200) au lieu d'en envoyer un second.

cURL
curl https://flare.zola-labs.com/v1/messages \
  -H "Authorization: Bearer flr_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: commande-2048-confirmation" \
  -d '{"to": "+237699001122", "template": "commande_confirmee", "variables": {"prenom": "Awa"}}'

L'objet message

JSON
{
  "id": "01JD40A1B3D5F7H9K1M3P5R7T9",
  "kind": "notification",
  "type": "text",
  "to": "+237699001122",
  "status": "delivered",
  "text": "Bonjour Awa, votre commande CMD-2048 est confirmée. Merci de votre confiance !",
  "otp_id": null,
  "event": "order.created",
  "reference": "CMD-2048",
  "cost": 0,
  "attempts": 1,
  "rerouted": false,
  "error": null,
  "created_at": "2026-11-17T09:43:02+00:00",
  "sent_at": "2026-11-17T09:43:03+00:00",
  "delivered_at": "2026-11-17T09:43:05+00:00",
  "read_at": null
}
Champ Description
kind otp, notification (modèle) ou message (texte libre ou média).
type text, image, video, audio ou document.
status État de livraison, voir ci-dessous.
text Texte envoyé. Pour un OTP, le code est masqué.
cost Montant débité de votre solde, en francs CFA ; 0 si le message est inclus dans votre forfait.
attempts Nombre de numéros essayés.
rerouted true si un autre numéro a pris le relais.
error { "code", "message" } en cas d'échec, sinon null.

Cycle de vie des messages

Statut Signification
queued Accepté par Flare, en attente d'envoi.
sending En cours d'envoi.
sent Parti du numéro expéditeur.
delivered Arrivé sur le téléphone du destinataire.
read Lu par le destinataire (s'il n'a pas désactivé les confirmations de lecture).
failed Abandonné ; la raison est dans error.

Un statut n'avance que dans ce sens : un message lu ne redevient jamais « livré ». Un message failed n'est pas facturé.

Note : un message peut rester à sent si le téléphone du destinataire est éteint, ou si le numéro n'a pas WhatsApp. Pour un code OTP, Flare tente alors un renvoi par un autre numéro.

Retrouver ses messages

GET /v1/messages/{id} renvoie un message. GET /v1/messages liste vos messages, du plus récent au plus ancien :

Paramètre Description
status Filtre sur un statut.
kind otp, notification ou message.
to Numéro du destinataire.
reference Votre référence.
limit Nombre de messages par page, de 1 à 100. Par défaut : 25.
cursor Valeur next_cursor de la page précédente.
cURL
curl "https://flare.zola-labs.com/v1/messages?status=failed&limit=50" \
  -H "Authorization: Bearer flr_live_VOTRE_CLE"
JSON
{
  "data": [ { "id": "01JD40A1…", "status": "failed", "…": "…" } ],
  "next_cursor": "eyJpZCI6IjAxSkQzWlE3…"
}

Quand next_cursor vaut null, vous êtes sur la dernière page. Pour suivre vos messages sans interroger l'API en boucle, préférez les webhooks.