WhatsApp pour le programme de fidélité via l'API : tutoriel pour les éditeurs

Intégrer WhatsApp dans un programme de fidélité via l'API Business se fait en trois étapes : configurer l'accès API, créer et valider les templates de messages, puis brancher les webhooks pour gérer les réponses membres. Ce tutoriel suit ce fil de façon séquentielle pour les équipes techniques d'éditeurs SaaS.

---

Étape 1 : Configurer l'accès API via Whakup

Créer un compte et connecter un numéro

Whakup est un Meta Tech Provider certifié. Vous n'avez pas à vous inscrire directement sur la Business Platform Meta ni à passer d'audit de certification.

1. Créez votre compte éditeur sur Whakup
2. Ajoutez un numéro WhatsApp Business via l'interface (ou via l'embedded signup intégrable dans votre propre interface SaaS)
3. Récupérez votre API_KEY et le phone_number_id du numéro créé

Le phone_number_id est l'identifiant Meta du numéro. Il est nécessaire dans toutes les requêtes d'envoi.

Tester l'accès avec un premier appel

curl -X POST https://api.whakup.com/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+336XXXXXXXX",
    "phone_number_id": "YOUR_PHONE_NUMBER_ID",
    "type": "text",
    "text": { "body": "Test de connexion Whakup" }
  }'

Si vous recevez un message_id en retour, la connexion est opérationnelle. Les messages texte libres ne fonctionnent que dans une fenêtre de 24h après un message entrant du client. Pour les envois proactifs (notifications de points), vous devez utiliser des templates.

---

Étape 2 : Créer et soumettre les templates de fidélité

Template de notification de points (Utility)

Ce template est déclenché après chaque achat validé. Il est classé UTILITY car il informe sur une transaction existante.

Soumettez-le via le dashboard Whakup ou l'API :

{
  "name": "notification_points_achat",
  "language": "fr",
  "category": "UTILITY",
  "components": [
    {
      "type": "body",
      "text": "Bonjour {{1}}, vous avez gagné {{2}} points suite à votre achat du {{3}}. Votre solde total est de {{4}} points. Il vous en faut {{5}} de plus pour atteindre le niveau {{6}}.",
      "example": {
        "body_text": [["Sophie", "120", "14 août 2026", "1 340", "160", "Gold"]]
      }
    },
    {
      "type": "footer",
      "text": "Répondez STOP pour ne plus recevoir ces messages."
    }
  ]
}

Points d'attention :

• Renseignez toujours l'objet example : Meta l'utilise pour évaluer le template
• Le footer avec "STOP" est une bonne pratique, pas obligatoire pour Utility mais recommandé

Template d'offre membre (Marketing)

Pour les offres exclusives, la catégorie est MARKETING. Vous pouvez ajouter un bouton URL :

{
  "name": "offre_exclusive_membre",
  "language": "fr",
  "category": "MARKETING",
  "components": [
    {
      "type": "header",
      "format": "IMAGE",
      "example": { "header_handle": ["UPLOADED_IMAGE_HANDLE"] }
    },
    {
      "type": "body",
      "text": "Bonjour {{1}}, en tant que membre {{2}}, profitez de -{{3}}% sur {{4}} jusqu'au {{5}}.",
      "example": {
        "body_text": [["Marie", "Gold", "20", "toute la collection été", "31 août 2026"]]
      }
    },
    {
      "type": "buttons",
      "buttons": [
        {
          "type": "url",
          "text": "Voir l'offre",
          "url": "https://exemple.com/offre/{{1}}",
          "example": ["ete2026"]
        },
        {
          "type": "quick_reply",
          "text": "Ne plus recevoir ces offres"
        }
      ]
    }
  ]
}

Délai de validation

Les templates simples (texte + boutons) sont généralement approuvés en moins d'une heure. Si le template est rejeté, Whakup fournit le motif de refus dans le dashboard.

---

Étape 3 : Envoyer un message de fidélité

Envoi d'une notification de points

import requests

def notifier_points_membre(api_key, phone_number_id, membre):
    payload = {
        "to": membre["telephone"],
        "phone_number_id": phone_number_id,
        "type": "template",
        "template": {
            "name": "notification_points_achat",
            "language": {"code": "fr"},
            "components": [
                {
                    "type": "body",
                    "parameters": [
                        {"type": "text", "text": membre["prenom"]},
                        {"type": "text", "text": str(membre["points_gagnes"])},
                        {"type": "text", "text": membre["date_achat"]},
                        {"type": "text", "text": str(membre["solde_total"])},
                        {"type": "text", "text": str(membre["points_manquants"])},
                        {"type": "text", "text": membre["prochain_niveau"]}
                    ]
                }
            ]
        }
    }
    
    response = requests.post(
        "https://api.whakup.com/v1/messages",
        headers={"Authorization": f"Bearer {api_key}"},
        json=payload
    )
    
    return response.json().get("message_id")

Stockez le message_id retourné dans votre table de notifications pour corréler avec les événements de livraison.

---

Étape 4 : Configurer les webhooks

Déclarer l'URL de webhook

Dans le dashboard Whakup, renseignez l'URL de votre endpoint webhook. Whakup enverra un POST pour chaque événement : livraison, lecture, réponse, opt-out.

Traiter les événements entrants

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/webhook/whatsapp", methods=["POST"])
def webhook():
    data = request.json
    event_type = data.get("type")
    
    if event_type == "message_status":
        # Livraison/lecture d'un message envoyé
        message_id = data["message_id"]
        status = data["status"]  # sent, delivered, read, failed
        mettre_a_jour_statut_notification(message_id, status)
    
    elif event_type == "message":
        # Message entrant (réponse membre ou opt-out)
        sender = data["from"]
        body = data.get("text", {}).get("body", "")
        
        if "STOP" in body.upper():
            enregistrer_optout(sender)
        else:
            # Traiter la question ou réponse libre du membre
            traiter_message_membre(sender, body)
    
    elif event_type == "button":
        # Clic sur un bouton quick_reply
        payload = data["button"]["payload"]
        if payload == "Ne plus recevoir ces offres":
            enregistrer_optout_marketing(data["from"])
    
    return jsonify({"status": "ok"})

Gestion de l'opt-out

Quand un membre se désabonne via le bouton ou le mot STOP, vous devez :

1. Mettre à jour son profil (optout_whatsapp_marketing = True)
2. Ne plus lui envoyer de templates Marketing
3. Conserver l'opt-in Utility si le membre souhaite garder les notifications de points

---

Étape 5 : Gestion des envois en volume (campagnes membres)

Pour une campagne (ex. : offre flash pour tous les membres Gold), vous devez envoyer le template à une liste. Recommandations :

• Batchez les envois : 100 à 500 messages par appel (ou boucle avec délai)
• Respectez les plafonds : un numéro neuf est limité à 1 000 conversations Marketing par 24h
• Filtrez les opt-outs avant l'envoi
• Journalisez chaque message_id pour le reporting

Le coût d'une campagne Marketing vers des numéros français est d'environ 0,08 €/membre (frais Meta 0,0712 € + frais Whakup 0,0088 €). Calculez votre ROI avant l'envoi.

Pour comparer les offres des différents fournisseurs, consultez le comparatif des meilleurs BSP WhatsApp en France.

---

FAQ

Comment uploader une image pour le header d'un template Marketing ?

Via l'API d'upload de médias Whakup (endpoint /v1/media). L'upload retourne un handle que vous utilisez dans le champ header_handle du template. Les images doivent être au format JPEG ou PNG, inférieures à 5 Mo.

Peut-on personnaliser le bouton URL avec l'ID du membre ?

Oui. Les boutons URL peuvent contenir une variable {{1}} dans l'URL. Lors de l'envoi du template, vous passez la valeur de cette variable dans le composant button. Cela permet de générer des URLs de tracking personnalisées par membre.

Que faire si un message échoue (statut "failed") ?

Le webhook retourne un code d'erreur. Les causes fréquentes : numéro invalide, compte WhatsApp désactivé, numéro hors réseau. Pour les échecs, relancez une fois après 24h ou basculez sur SMS comme canal de secours.

Multi-tenant : comment séparer les notifications de deux marques distinctes ?

Chaque marque dispose de son phone_number_id distinct. Dans vos appels API, passez le phone_number_id de la marque concernée. Les webhooks Whakup identifient le numéro source dans chaque payload, ce qui permet un routage propre côté votre back-end.

---

Conclusion

Ce tutoriel couvre l'essentiel pour brancher WhatsApp sur un moteur de fidélité : accès API, création de templates utility et marketing, envoi, webhooks et gestion des opt-outs. L'architecture est reproductible pour chaque nouveau client de votre SaaS via l'embedded signup Whakup.

Pour aller plus loin sur la stratégie et les cas d'usage, consultez le guide complet fidélité WhatsApp. Pour démarrer, rendez-vous sur la page API WhatsApp de Whakup.