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 (
templateetvariables), 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."}'
Http::withToken(env('FLARE_KEY'))->post('https://flare.zola-labs.com/v1/messages', [
'to' => '+237699001122',
'text' => 'Votre colis vous attend au point relais de Bonapriso.',
]);
await fetch('https://flare.zola-labs.com/v1/messages', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.FLARE_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ to: '+237699001122', text: 'Votre colis vous attend au point relais de Bonapriso.' }),
});
requests.post(
"https://flare.zola-labs.com/v1/messages",
headers={"Authorization": f"Bearer {os.environ['FLARE_KEY']}"},
json={"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 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.
{ "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 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
{
"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 à
sentsi 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 "https://flare.zola-labs.com/v1/messages?status=failed&limit=50" \
-H "Authorization: Bearer flr_live_VOTRE_CLE"
{
"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.