Envoyer
Notifications
Prévenir automatiquement votre client, votre équipe ou un partenaire à chaque événement de votre application.
Une notification est un message construit à partir d'un modèle : un texte type avec des variables, comme « Bonjour {{ prenom }}, votre commande {{ numero }} est confirmée ». Vous pouvez l'envoyer de deux façons :
- directement, en précisant le destinataire et le modèle :
POST /v1/messages; - par événement : votre application signale « une commande vient d'être créée » (
POST /v1/events) et Flare applique vos règles pour prévenir les bonnes personnes.
Les modèles
Créez vos modèles dans l'espace client, rubrique Configurer › Modèles. Chaque modèle a :
- un nom, pour vous ;
- un identifiant, utilisé dans l'API (lettres minuscules, chiffres et
_), par exemplecommande_confirmee; - un texte, avec des variables entre doubles accolades.
Bonjour {{ prenom }}, votre commande {{ commande.numero }} d'un montant de {{ commande.total }} est confirmée. Merci de votre confiance !
Une variable peut désigner un champ imbriqué avec un point : {{ commande.numero }} lit numero dans l'objet commande.
Validation des modèles
Les numéros Flare sont partagés entre tous nos clients. Pour les protéger, un modèle doit être validé par notre équipe avant de pouvoir en partir. Son état est visible dans la liste des modèles : En attente de validation, Validé ou Refusé (avec la raison).
- Depuis votre propre numéro, un modèle est utilisable tout de suite, validé ou non.
- Modifier le texte d'un modèle validé le renvoie en validation.
Envoyer un modèle à un destinataire
POST /v1/messages
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
to |
texte | oui | Numéro du destinataire, au format international. |
template |
texte | oui | Identifiant du modèle. |
variables |
objet | selon le modèle | Valeurs des variables du modèle. |
reference |
texte | non | Votre identifiant, renvoyé tel quel. |
sender |
texte | non | auto (par défaut), shared ou dedicated. |
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",
"commande": { "numero": "CMD-2048", "total": "18 500 FCFA" }
},
"reference": "CMD-2048"
}'
Http::withToken(env('FLARE_KEY'))
->withHeaders(['Idempotency-Key' => "commande-{$order->id}-confirmation"])
->post('https://flare.zola-labs.com/v1/messages', [
'to' => $order->customer_phone,
'template' => 'commande_confirmee',
'variables' => [
'prenom' => $order->customer_first_name,
'commande' => ['numero' => $order->number, 'total' => $order->total_label],
],
'reference' => $order->number,
]);
await fetch('https://flare.zola-labs.com/v1/messages', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.FLARE_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': `commande-${order.id}-confirmation`,
},
body: JSON.stringify({
to: order.customerPhone,
template: 'commande_confirmee',
variables: {
prenom: order.customerFirstName,
commande: { numero: order.number, total: order.totalLabel },
},
reference: order.number,
}),
});
requests.post(
"https://flare.zola-labs.com/v1/messages",
headers={
"Authorization": f"Bearer {os.environ['FLARE_KEY']}",
"Idempotency-Key": f"commande-{order.id}-confirmation",
},
json={
"to": order.customer_phone,
"template": "commande_confirmee",
"variables": {
"prenom": order.customer_first_name,
"commande": {"numero": order.number, "total": order.total_label},
},
"reference": order.number,
},
)
La réponse 202 contient le message créé, avec le texte final dans text. Si une variable manque, rien n'est envoyé :
{
"error": {
"code": "missing_variables",
"message": "Des variables du modèle ne sont pas renseignées.",
"details": { "missing": ["commande.total"] }
}
}
Notifier par événement
Plutôt que de décider dans votre code qui prévenir, décrivez-le une fois pour toutes dans l'espace client, rubrique Configurer › Notifications. Une règle dit : quand l'événement X arrive, envoyer le modèle Y à Z. Z peut être :
| Destinataires | Qui reçoit le message |
|---|---|
| Le client final | Le numéro transmis dans le champ customer de l'appel. |
| Moi et mon équipe | Un ou plusieurs numéros fixes, enregistrés dans la règle. |
| Un numéro tiers | Un partenaire : livreur, fournisseur, agence… également enregistré dans la règle. |
Plusieurs règles peuvent écouter le même événement. Par exemple, pour order.created : une règle « Confirmation au client » et une règle « Alerte à l'équipe ».
Votre application n'a ensuite qu'un appel à faire :
POST /v1/events
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
event |
texte | oui | Nom de l'événement : lettres, chiffres, ., - et _. Par exemple order.created. |
customer |
texte | si une règle vise le client | Numéro du client final. |
data |
objet | selon les modèles | Variables utilisées par les modèles des règles. |
reference |
texte | non | Votre identifiant, recopié sur chaque message. |
curl https://flare.zola-labs.com/v1/events \
-H "Authorization: Bearer flr_live_VOTRE_CLE" \
-H "Content-Type: application/json" \
-d '{
"event": "order.created",
"customer": "+237699001122",
"data": { "prenom": "Awa", "numero": "CMD-2048", "montant": "18 500 FCFA" },
"reference": "CMD-2048"
}'
Http::withToken(env('FLARE_KEY'))->post('https://flare.zola-labs.com/v1/events', [
'event' => 'order.created',
'customer' => $order->customer_phone,
'data' => [
'prenom' => $order->customer_first_name,
'numero' => $order->number,
'montant' => $order->total_label,
],
'reference' => $order->number,
]);
await fetch('https://flare.zola-labs.com/v1/events', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.FLARE_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
event: 'order.created',
customer: order.customerPhone,
data: { prenom: order.customerFirstName, numero: order.number, montant: order.totalLabel },
reference: order.number,
}),
});
requests.post(
"https://flare.zola-labs.com/v1/events",
headers={"Authorization": f"Bearer {os.environ['FLARE_KEY']}"},
json={
"event": "order.created",
"customer": order.customer_phone,
"data": {"prenom": order.customer_first_name, "numero": order.number, "montant": order.total_label},
"reference": order.number,
},
)
Réponse 202 : la liste des messages créés, et celle des envois écartés avec leur raison.
{
"event": "order.created",
"messages": [
{ "id": "01JD40A1…", "to": "+237699001122", "audience": "customer", "rule": "Confirmation au client", "status": "queued" },
{ "id": "01JD40A2…", "to": "+237677000001", "audience": "merchant", "rule": "Alerte à l'équipe", "status": "queued" }
],
"skipped": []
}
Un envoi est écarté, sans faire échouer les autres, quand :
- une règle vise le client final mais la requête ne contient pas de
customer(missing_customer) ; - un envoi est refusé pour une autre raison, par exemple un modèle non validé alors que vous n'avez pas de numéro dédié (
template_required) ou un solde insuffisant (insufficient_balance).
{
"rule": "Confirmation au client",
"audience": "customer",
"code": "missing_customer",
"reason": "Cette règle vise le client final, mais la requête ne contient pas de numéro « customer »."
}
Si aucune règle active n'écoute l'événement, l'API répond 404 avec le code unknown_event.
Note : chaque règle a un bouton Tester dans l'espace client, qui envoie son modèle à votre propre numéro avec des valeurs d'exemple.
Idées d'événements
| Événement | Client final | Équipe ou tiers |
|---|---|---|
order.created |
Confirmation de commande | Alerte « nouvelle commande » |
order.shipped |
Colis en route, date prévue | Détails au livreur |
payment.received |
Reçu de paiement | Alerte comptabilité |
appointment.reminder |
Rappel la veille | — |
ticket.updated |
Réponse du support | — |