API WhatsApp pour les agences push notifications : tutoriel 2026

Votre plateforme push notifications envoie déjà des messages déclenchés par des événements (inscription, achat, inactivité). Ajouter WhatsApp comme canal de sortie supplémentaire demande trois choses : un accès à l'API WhatsApp Business, la gestion des templates et l'ingestion des webhooks de statut. Ce tutoriel détaille chaque étape.

Étape 1 — Mettre en place l'accès API pour vos clients

Chaque client de votre agence doit disposer de son propre WhatsApp Business Account (WABA). Deux approches pour gérer cet onboarding.

Approche A — Embedded Signup (recommandée pour les plateformes)

Vous intégrez le flux OAuth Meta dans votre interface. Le client connecte son compte Meta Business depuis votre dashboard, sans jamais quitter votre produit. Vous récupérez automatiquement :

• waba_id : l'identifiant du compte WhatsApp Business.
• phone_number_id : l'identifiant du numéro WhatsApp.
• access_token : le jeton d'accès à l'API (vous devez le convertir en System User token pour la production).

Passez par un Meta Tech Provider certifié comme Whakup pour accéder à l'Embedded Signup sans dev Meta direct.

Approche B — Création manuelle dans Meta Business Manager

Le client crée son WABA manuellement, vous partage les identifiants. Moins fluide pour le client, mais utilisable en phase de test ou pour des déploiements ponctuels.

Pour comprendre les identifiants Meta et leur rôle, voir le guide complet API WhatsApp Business.

Étape 2 — Structurer votre moteur de templates

Sur votre plateforme push, un template push se compose d'un titre, d'un corps et d'une URL. Sur WhatsApp, un template HSM a une structure différente et doit être pré-approuvé par Meta.

Structure d'un template WhatsApp (JSON soumis à l'API Meta) :

{
  "name": "promo_flash",
  "language": "fr",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "format": "IMAGE"
    },
    {
      "type": "BODY",
      "text": "Bonjour {{1}}, votre code promo {{2}} est valable jusqu'à ce soir minuit. -{{3}}% sur toute la boutique."
    },
    {
      "type": "FOOTER",
      "text": "Répondez STOP pour ne plus recevoir ces messages."
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "URL",
          "text": "Voir les offres",
          "url": "https://boutique.example.com/promo?ref={{4}}"
        }
      ]
    }
  ]
}

Votre plateforme doit stocker les templates approuvés par WABA client et exposer une interface de gestion (création, statut, désactivation).

La catégorisation correcte des templates (MARKETING, UTILITY, AUTHENTICATION) est critique pour la facturation. Consultez le guide sur les templates WhatsApp et leurs catégories.

Étape 3 — Connecter votre moteur de déclenchement à l'API WhatsApp

Sur votre plateforme push, un événement (ex : user.inactive_30d) déclenche l'envoi d'une notification. L'adaptation pour WhatsApp consiste à ajouter un connecteur qui :

1. Vérifie si le contact a un numéro WhatsApp opt-in.
2. Sélectionne le template WhatsApp approprié à l'événement.
3. Appelle l'API WhatsApp avec les variables dynamiques du template.

Exemple de code Python pour l'envoi :

import httpx

def send_whatsapp_template(phone_number_id, access_token, to, template_name, variables):
    url = f"https://graph.facebook.com/v19.0/{phone_number_id}/messages"
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    }
    body_params = [{"type": "text", "text": v} for v in variables]
    payload = {
        "messaging_product": "whatsapp",
        "to": to,
        "type": "template",
        "template": {
            "name": template_name,
            "language": {"code": "fr"},
            "components": [
                {
                    "type": "body",
                    "parameters": body_params
                }
            ]
        }
    }
    response = httpx.post(url, headers=headers, json=payload)
    response.raise_for_status()
    return response.json()

Les identifiants phone_number_id et access_token sont ceux du WABA du client concerné, stockés dans votre base de données multi-tenant.

Étape 4 — Ingérer les webhooks de statut pour vos analytics

Contrairement aux push notifications (dont le statut de livraison est souvent opaque), WhatsApp vous envoie des événements précis :

Événement	Signification
sent	Message accepté par les serveurs Meta
delivered	Message reçu sur l'appareil du destinataire
read	Message lu par le destinataire
failed	Erreur de livraison (numéro invalide, blocage, etc.)

Ces statuts permettent de calculer des métriques réelles de performance : taux de livraison, taux de lecture, taux de conversion (si vous posez un paramètre UTM dans l'URL du bouton).

Configuration webhook dans votre application :

from flask import Flask, request
import hmac, hashlib

app = Flask(__name__)

@app.route('/webhooks/whatsapp', methods=['POST'])
def handle_webhook():
    # Vérification signature
    signature = request.headers.get('X-Hub-Signature-256', '')
    expected = 'sha256=' + hmac.new(
        APP_SECRET.encode(), request.data, hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(signature, expected):
        return 'Unauthorized', 403
    
    payload = request.json
    # Routage par phone_number_id vers le bon compte client
    for entry in payload.get('entry', []):
        for change in entry.get('changes', []):
            phone_number_id = change['value']['metadata']['phone_number_id']
            process_whatsapp_event(phone_number_id, change['value'])
    
    return 'OK', 200

Retournez systématiquement un 200 OK avant de traiter le message de manière asynchrone. Meta re-tentera l'envoi du webhook en cas de timeout.

Pour démarrer l'intégration avec l'infrastructure Whakup (API REST + webhooks unifiés, multi-tenant, marque blanche), accédez à l'API WhatsApp pour agences push.

Pour une analyse complète des coûts, consultez prix API WhatsApp Business 2026.

FAQ

Comment savoir si un numéro de téléphone est actif sur WhatsApp avant d'envoyer ?

Il n'existe pas d'API publique Meta pour vérifier l'existence d'un numéro WhatsApp sans envoyer de message. En pratique, vous le découvrez au premier envoi : si le statut revient failed avec le code 131026 (numéro non enregistré sur WhatsApp), le contact n'est pas joignable par ce canal. Certains providers tiers proposent des services de vérification, mais ils ne sont pas officiellement supportés par Meta.

Peut-on envoyer des images ou des vidéos dans les notifications WhatsApp ?

Oui. Les templates WhatsApp supportent une en-tête de type IMAGE, VIDEO ou DOCUMENT. L'URL du média est fournie au moment de l'envoi (pas lors de la création du template). Le fichier doit être accessible publiquement via HTTPS. Taille max : 5 MB pour les images, 16 MB pour les vidéos.

Comment gérer les opt-outs WhatsApp dans ma plateforme ?

Quand un utilisateur envoie "STOP" ou bloque votre numéro, vous recevez un événement webhook. Votre plateforme doit immédiatement marquer le contact comme opt-out et cesser tout envoi. Ne pas respecter les opt-outs expose le numéro WhatsApp à une dégradation de qualité et à une suspension.

L'API WhatsApp supporte-t-elle les envois en masse (bulk) pour les agences ?

Oui, avec des limites par tier de messagerie (1 000 à 100 000+ conversations uniques/24h selon le tier du numéro). Pour des campagnes de grande ampleur, il faut anticiper la montée en tier du numéro client (progressive, basée sur la qualité) et potentiellement utiliser plusieurs numéros. Votre plateforme peut gérer plusieurs numéros par WABA pour augmenter le débit total.