WhatsApp pour la qualification de leads via l'API : tutoriel pour les éditeurs

Ce tutoriel explique comment implémenter un flow de qualification de leads sur WhatsApp via l'API Business. Il s'adresse aux développeurs d'éditeurs SaaS qui veulent ajouter ce cas d'usage à leur plateforme. On couvre l'envoi du premier message, la gestion des réponses interactives, le maintien de l'état et la synchronisation avec un CRM.

Étape 1 : Déclencher le flow avec un template HSM

La qualification démarre souvent par un message sortant vers un nouveau lead (opt-in requis). Ce premier message doit être un template HSM approuvé par Meta, de catégorie marketing ou utility selon le contexte.

Exemple de template de déclenchement :

Bonjour {{1}}, merci pour votre intérêt pour {{2}}.
Pour vous proposer la solution la mieux adaptée, j'ai 3 questions rapides (2 min).
Prêt(e) ?

Ce template a un en-tête texte, un corps avec deux variables, et deux boutons de réponse rapide : "Oui, je suis prêt" / "Pas maintenant".

Appel API pour envoyer ce template :

POST /v19.0/{phone-number-id}/messages
{
  "messaging_product": "whatsapp",
  "to": "+33612345678",
  "type": "template",
  "template": {
    "name": "qualification_intro",
    "language": { "code": "fr" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Sophie" },
          { "type": "text", "text": "votre plateforme CRM" }
        ]
      }
    ]
  }
}

Pour la soumission et l'approbation du template, si vous passez par Whakup (Meta Tech Provider certifié), vous n'avez pas à gérer le processus Meta directement. Voir le guide sur le choix d'un BSP WhatsApp.

Étape 2 : Recevoir et analyser la réponse via webhook

Quand le lead clique sur "Oui, je suis prêt", votre endpoint webhook reçoit un événement de type messages avec un objet interactive ou button.

Structure du webhook reçu (clic sur bouton) :

{
  "object": "whatsapp_business_account",
  "entry": [{
    "changes": [{
      "value": {
        "messages": [{
          "from": "33612345678",
          "type": "interactive",
          "interactive": {
            "type": "button_reply",
            "button_reply": {
              "id": "btn_yes",
              "title": "Oui, je suis prêt"
            }
          }
        }]
      }
    }]
  }]
}

Votre serveur extrait button_reply.id, identifie l'utilisateur via from, récupère son état courant en base et décide de la prochaine étape.

Étape 3 : Envoyer une question interactive (list message)

La deuxième question utilise un list_message pour proposer plusieurs options sans encombrer le chat.

Payload pour un list message :

{
  "messaging_product": "whatsapp",
  "to": "33612345678",
  "type": "interactive",
  "interactive": {
    "type": "list",
    "header": { "type": "text", "text": "Question 1/3" },
    "body": { "text": "Combien de commerciaux compte votre équipe ?" },
    "footer": { "text": "Sélectionnez votre situation" },
    "action": {
      "button": "Voir les options",
      "sections": [{
        "title": "Taille d'équipe",
        "rows": [
          { "id": "team_1_5", "title": "1 à 5" },
          { "id": "team_6_20", "title": "6 à 20" },
          { "id": "team_20plus", "title": "Plus de 20" }
        ]
      }]
    }
  }
}

Les list_messages ne nécessitent pas de template car la conversation est maintenant dans la fenêtre de 24h (le lead a répondu à l'étape 1).

Étape 4 : Maintenir l'état du flow en base

L'API WhatsApp est stateless. C'est votre backend qui maintient l'état de chaque lead dans le flow.

Structure recommandée en base :

Champ	Type	Description
phone_number	string	Identifiant du contact
flow_step	integer	Étape courante (1, 2, 3…)
answers	JSON	Réponses collectées
started_at	datetime	Démarrage du flow
last_activity	datetime	Dernière réponse
status	string	in_progress, completed, abandoned

À chaque webhook entrant, votre handler :

1. Identifie le contact par from
2. Lit son étape courante en base
3. Enregistre la réponse reçue
4. Incrémente l'étape
5. Envoie le prochain message

Gestion des timeouts :

Un job planifié (cron) vérifie toutes les heures les leads dont last_activity date de plus de 2h et status = in_progress. Il les passe en abandoned et peut envoyer un message de relance si vous le souhaitez.

Étape 5 : Conclure et synchroniser avec le CRM

Quand toutes les questions ont obtenu une réponse, envoyez un message de confirmation et déclenchez la synchronisation CRM.

Message de conclusion :

{
  "type": "text",
  "text": {
    "body": "Merci Sophie ! Voici ce que j'ai noté :\n\n• Équipe : 6 à 20 commerciaux\n• CRM actuel : aucun\n• Secteur : retail\n\nUn conseiller vous contacte sous 24h. À bientôt !"
  }
}

Synchronisation CRM via webhook sortant :

Votre backend envoie immédiatement les données collectées vers l'API du CRM ou de votre plateforme. La fiche lead est créée avec toutes les informations, le canal d'acquisition (whatsapp) et le timestamp.

Pour une intégration approfondie, consultez le guide complet de qualification lead WhatsApp et la page de l'API WhatsApp Whakup.

FAQ

Peut-on relancer un lead qui n'a pas répondu au premier template ?

Oui, mais avec précaution. Meta surveille le taux de réponse et le score de qualité de votre numéro. Si vous envoyez des templates à des leads qui n'interagissent jamais, votre score baisse. Limitez les relances à 1 ou 2 tentatives espacées de 48h minimum.

Comment gérer un lead qui écrit un message libre au lieu de cliquer sur un bouton ?

Prévoyez un handler pour les messages de type text. Si le contenu correspond à une réponse attendue (ex : "Oui", "Non", "1-5"), mappez-la manuellement. Sinon, renvoyez la question avec les boutons en rappelant la question précédente.

Est-ce que la qualification fonctionne si le lead répond plusieurs heures après ?

Oui, tant que le lead répond dans la fenêtre de 24h suivant son dernier message. Si la fenêtre est fermée, vous ne pouvez plus envoyer de messages libres ou interactifs — seulement un nouveau template HSM.

Quels outils peut-on utiliser pour tester le flow avant la mise en production ?

Meta propose un environnement sandbox pour l'API Cloud. Vous pouvez envoyer des messages de test vers des numéros autorisés sans coût. Voir l'article sur le sandbox WhatsApp API pour la configuration. Whakup propose aussi un environnement de test dans son dashboard partenaire.

---

Ce tutoriel couvre les bases d'un flow de qualification WhatsApp. Pour aller plus loin en architecture multi-tenant ou pour accéder à l'API sans gérer la certification Meta, Whakup fournit l'infrastructure complète : REST API, webhooks, embedded signup et hébergement EU conforme RGPD.