Aller au contenu

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 exemple commande_confirmee ;
  • un texte, avec des variables entre doubles accolades.
Texte
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"
  }'

La réponse 202 contient le message créé, avec le texte final dans text. Si une variable manque, rien n'est envoyé :

JSON
{
  "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"
  }'

Réponse 202 : la liste des messages créés, et celle des envois écartés avec leur raison.

JSON
{
  "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).
JSON
{
  "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 —