API WhatsApp pour les outils de marketing automation : tutoriel 2026

Ajouter WhatsApp à un outil de marketing automation demande de résoudre trois défis techniques : déclencher des envois depuis un moteur de workflow, recevoir des statuts en temps réel via webhooks, et gérer la fenêtre de conversation de 24 heures. Ce tutoriel couvre chaque étape avec les détails d'implémentation nécessaires à un lead dev ou un architecte qui conçoit ce canal pour la première fois.

Étape 1 — Provisionner l'accès API via Whakup

Avant d'écrire une ligne de code, il faut un accès à l'API Cloud Meta. En passant par Whakup (Meta Tech Provider certifié), vous évitez la démarche de certification Meta et accédez à l'API REST directement.

Ce que vous recevez à l'issue de l'onboarding :

• Un access_token (Bearer token) pour authentifier les appels API
• Le phone_number_id de chaque numéro provisionné
• L'URL de base de l'API : https://graph.facebook.com/v19.0/
• Un URL de webhook à configurer côté Meta pour recevoir les événements

Si votre outil est multi-tenant (un numéro par client), Whakup fournit un accès unifié : vous gérez tous les numéros depuis un seul access_token de niveau système, en passant le phone_number_id approprié dans chaque requête.

Pour comprendre les différences entre les modèles d'hébergement et choisir la bonne architecture, lisez notre analyse build vs buy pour l'API WhatsApp.

Étape 2 — Implémenter le nœud d'envoi WhatsApp dans votre workflow engine

Dans votre moteur d'automation, un nœud d'action WhatsApp doit exposer :

• Le choix du template (liste des templates approuvés du client)
• Le mapping des variables du template vers les attributs du contact
• La condition de déclenchement (immédiat, différé, ou conditionnel)

Appel API pour un envoi depuis un nœud workflow :

POST https://graph.facebook.com/v19.0/{phone_number_id}/messages
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "messaging_product": "whatsapp",
  "to": "33XXXXXXXXX",
  "type": "template",
  "template": {
    "name": "relance_panier_j1",
    "language": { "code": "fr" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "{{contact.first_name}}" },
          { "type": "text", "text": "{{cart.total_amount}}" },
          { "type": "text", "text": "{{cart.recovery_url}}" }
        ]
      },
      {
        "type": "button",
        "sub_type": "url",
        "index": "0",
        "parameters": [
          { "type": "text", "text": "{{cart.recovery_url}}" }
        ]
      }
    ]
  }
}

La réponse contient un messages[0].id qui sert à corréler les événements de statut reçus via webhook.

Gestion de la fenêtre de conversation :

Votre nœud doit vérifier si le contact a envoyé un message dans les dernières 24 heures. Si oui, vous pouvez envoyer un message libre (type text). Si non, vous devez utiliser un template. Stockez le timestamp de la dernière interaction entrante dans votre base de contacts.

def send_whatsapp_message(contact, template_name, variables):
    last_inbound = contact.get_last_whatsapp_inbound()
    if last_inbound and (datetime.now() - last_inbound).seconds < 86400:
        # Fenêtre active : message libre possible
        payload = build_free_message_payload(contact, variables)
    else:
        # Hors fenêtre : template obligatoire
        payload = build_template_payload(contact, template_name, variables)
    return whakup_api.send(payload)

Étape 3 — Recevoir les statuts et réponses via webhook

Configurez votre endpoint de webhook dans la console Meta (ou via l'API Whakup). Il recevra des payloads POST pour chaque événement.

Structure d'un événement de statut :

{
  "object": "whatsapp_business_account",
  "entry": [{
    "changes": [{
      "value": {
        "statuses": [{
          "id": "wamid.XXX",
          "status": "delivered",
          "timestamp": "1720000000",
          "recipient_id": "33XXXXXXXXX"
        }]
      }
    }]
  }]
}

Structure d'un message entrant :

{
  "messages": [{
    "from": "33XXXXXXXXX",
    "id": "wamid.YYY",
    "timestamp": "1720000001",
    "text": { "body": "Oui, je suis intéressé" },
    "type": "text"
  }]
}

Dans votre moteur d'automation, le traitement du webhook doit :

1. Valider la signature HMAC du payload (header X-Hub-Signature-256)
2. Extraire le type d'événement (statut ou message entrant)
3. Mettre à jour le statut du contact dans le workflow
4. Déclencher les branches conditionnelles si applicable (ex : branche "a répondu")

Étape 4 — Gérer les erreurs et la résilience

Les erreurs les plus fréquentes dans un contexte d'automation :

Code erreur	Signification	Stratégie
131026	Numéro non sur WhatsApp	Fallback SMS/email
131056	Limite de messagerie dépassée	Retry après 1 heure
132001	Template non approuvé	Alerte éditeur, arrêt du nœud
130429	Rate limit (trop de requêtes)	Backoff exponentiel

Implémentez une file de retry avec backoff exponentiel pour les erreurs 131056 et 130429. Pour les erreurs définitives (131026, 132001), loguez et routez vers le canal alternatif.

Pour approfondir la gestion des templates et leur cycle de vie, notre guide sur les templates WhatsApp et leurs catégories couvre les scénarios d'approbation et de révocation.

FAQ

Comment lister les templates disponibles pour un client depuis l'API ?

Appelez GET https://graph.facebook.com/v19.0/{waba_id}/message_templates avec le Bearer token. La réponse liste tous les templates avec leur statut (APPROVED, PENDING, REJECTED). Intégrez cet endpoint dans votre interface pour permettre à l'utilisateur de sélectionner le bon template dans l'éditeur de workflow.

Comment vérifier que le webhook fonctionne avant la mise en production ?

Meta impose une vérification du webhook lors de la configuration : il envoie une requête GET avec un hub.challenge que votre endpoint doit retourner tel quel. Une fois vérifié, testez l'envoi d'un message vers un numéro de test et vérifiez que les événements sent, delivered et read arrivent correctement dans vos logs.

Peut-on envoyer des images ou des fichiers PDF dans les workflows WhatsApp ?

Oui. Les templates peuvent inclure un composant header de type image, video ou document. L'image ou le fichier doit être hébergé sur une URL publique accessible par Meta. Vous passez l'URL dans le composant header.parameters lors de l'appel API.

Comment gérer les opt-outs WhatsApp dans le moteur d'automation ?

Le webhook reçoit les messages de désinscription (réponse « STOP » ou équivalent). Votre moteur doit traiter ces messages pour mettre à jour le flag whatsapp_opt_in du contact et l'exclure automatiquement des nœuds WhatsApp dans tous les workflows actifs.

---

Une fois ces quatre étapes implémentées, votre outil de marketing automation peut orchestrer WhatsApp avec la même flexibilité que l'email ou le SMS. Whakup fournit l'API WhatsApp Business avec l'infrastructure adaptée aux éditeurs : REST, webhooks temps réel, multi-tenant et hébergement EU. Contactez notre équipe pour accéder à la documentation complète et à l'environnement sandbox.