WhatsApp pour les notifications transactionnelles via l'API : tutoriel pour les éditeurs

Envoyer une notification transactionnelle WhatsApp via l'API demande de suivre une séquence précise : onboarding du numéro, création et approbation du template, appel API d'envoi, réception des statuts via webhook. Ce tutoriel est destiné aux développeurs et leads tech d'éditeurs SaaS qui veulent intégrer les notifications WhatsApp dans leur plateforme. Chaque étape est détaillée avec les appels API correspondants.

Ce que vous aurez à la fin de ce tutoriel

À l'issue de ces étapes, votre plateforme sera capable de :

• Activer un numéro WhatsApp Business pour un client (embedded signup)
• Créer et faire approuver un template de notification transactionnelle
• Envoyer une notification personnalisée via l'API REST
• Recevoir les accusés de livraison et les réponses via webhook

Ce tutoriel suppose que vous avez un compte Whakup actif et un accès développeur à votre plateforme. Whakup est un Meta Tech Provider certifié : il gère la relation avec Meta, vous n'avez pas à passer par la procédure de certification BSP.

Étape 1 : onboarder un client via l'embedded signup

L'embedded signup permet à votre client (le commerçant, la plateforme, l'entreprise) d'activer son numéro WhatsApp directement depuis votre interface, sans manipulation de la console Meta Business.

Côté développeur, voici ce qu'il faut implémenter :

1. Récupérez votre app_id et votre configuration_id dans le dashboard Whakup.
2. Intégrez le SDK JavaScript Meta dans votre frontend :

<script>
  window.fbAsyncInit = function() {
    FB.init({
      appId: 'VOTRE_APP_ID',
      autoLogAppEvents: true,
      xfbml: true,
      version: 'v19.0'
    });
  };
</script>
<script async defer crossorigin="anonymous"
  src="https://connect.facebook.net/fr_FR/sdk.js">
</script>

3. Déclenchez le flux d'onboarding au clic d'un bouton :

FB.login(function(response) {
  if (response.authResponse) {
    const code = response.authResponse.code;
    // Envoyez ce code à votre backend
    // Votre backend échange ce code contre un token via l'API Whakup
  }
}, {
  config_id: 'VOTRE_CONFIGURATION_ID',
  response_type: 'code',
  override_default_response_type: true,
  extras: {
    setup: {},
    featureType: '',
    sessionInfoVersion: '3'
  }
});

4. Côté backend, échangez le code contre un token via l'API Whakup et récupérez le waba_id et le phone_number_id du client.

Pour en savoir plus sur l'embedded signup, consultez notre article dédié sur l'onboarding simplifié via embedded signup.

Étape 2 : créer un template de notification transactionnelle

Tout message initié par l'entreprise doit utiliser un template pré-approuvé par Meta. Voici comment créer un template de confirmation de commande.

Appel API pour créer un template :

POST https://api.whakup.com/v1/templates
Authorization: Bearer VOTRE_ACCESS_TOKEN
Content-Type: application/json

{
  "phone_number_id": "PHONE_NUMBER_ID_DU_CLIENT",
  "name": "confirmation_commande",
  "language": "fr",
  "category": "UTILITY",
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Confirmation de votre commande"
    },
    {
      "type": "BODY",
      "text": "Bonjour {{1}},\n\nVotre commande n°{{2}} d'un montant de {{3}} € a bien été enregistrée.\n\nLivraison prévue : {{4}}.\nSuivez votre commande : {{5}}"
    },
    {
      "type": "FOOTER",
      "text": "Merci pour votre confiance."
    }
  ]
}

Points importants :

• La catégorie doit être UTILITY (pas MARKETING) pour les notifications transactionnelles. Cela impacte le coût : ~0,0336 €/msg vs ~0,08 €/msg pour les numéros français.
• Les variables sont numérotées {{1}}, {{2}}, etc. dans l'ordre d'apparition.
• Meta approuve ou refuse le template dans les 24-48h. Un template utility refusé est souvent rejeté pour contenu trop promotionnel dans le corps.

Pour comprendre les règles de catégorisation, lisez notre guide sur les catégories et règles des templates WhatsApp.

Étape 3 : envoyer une notification via l'API

Une fois le template approuvé (statut APPROVED), vous pouvez déclencher l'envoi depuis votre système.

Appel API d'envoi :

POST https://api.whakup.com/v1/messages
Authorization: Bearer VOTRE_ACCESS_TOKEN
Content-Type: application/json

{
  "phone_number_id": "PHONE_NUMBER_ID_DU_CLIENT",
  "to": "33612345678",
  "type": "template",
  "template": {
    "name": "confirmation_commande",
    "language": {
      "code": "fr"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Marie" },
          { "type": "text", "text": "CMD-2026-04892" },
          { "type": "text", "text": "89,90" },
          { "type": "text", "text": "15 août 2026" },
          { "type": "text", "text": "https://track.example.com/CMD-2026-04892" }
        ]
      }
    ]
  }
}

Réponse attendue :

{
  "messaging_product": "whatsapp",
  "contacts": [{ "input": "33612345678", "wa_id": "33612345678" }],
  "messages": [{ "id": "wamid.HBgN..." }]
}

Le message_id retourné (wamid.HBgN...) est la référence pour suivre le statut de ce message via webhook.

Étape 4 : recevoir les statuts et réponses via webhook

Configurez un endpoint HTTPS dans votre infrastructure pour recevoir les événements Whakup.

Payload de statut de livraison :

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "WABA_ID",
    "changes": [{
      "value": {
        "statuses": [{
          "id": "wamid.HBgN...",
          "status": "delivered",
          "timestamp": "1755000000",
          "recipient_id": "33612345678"
        }]
      }
    }]
  }]
}

Les statuts possibles : sent → delivered → read. Si vous ne recevez pas delivered dans les 30 minutes, déclenchez un fallback (SMS, email).

Payload de message entrant (réponse du destinataire) :

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "WABA_ID",
    "changes": [{
      "value": {
        "messages": [{
          "from": "33612345678",
          "id": "wamid.XYZ...",
          "timestamp": "1755000060",
          "text": { "body": "Merci, j'ai bien reçu ma commande." },
          "type": "text"
        }]
      }
    }]
  }]
}

Quand un destinataire répond, la fenêtre de conversation de 24h s'ouvre. Pendant cette fenêtre, vous pouvez envoyer des messages libres (sans template) pour répondre à sa question ou gérer sa demande.

Checklist avant la mise en production

Avant de passer en production, vérifiez les points suivants :

• Le WABA du client est bien activé et son numéro vérifié
• Le template est en statut APPROVED (pas PENDING ou REJECTED)
• L'endpoint webhook est accessible en HTTPS depuis les serveurs Whakup
• La validation du token webhook est implémentée (vérification du header X-Hub-Signature)
• La logique de retry est en place pour les erreurs API transitoires
• Le fallback SMS/email est configuré pour les numéros non WhatsApp
• Les statuts de livraison sont loggés dans votre base de données
• Le numéro d'envoi a le bon Display Name validé par Meta

Pour une checklist complète de déploiement, consultez notre checklist des 30 points de déploiement API WhatsApp.

FAQ

Combien de messages puis-je envoyer par heure avec l'API WhatsApp ?

Le débit dépend du niveau de messagerie (Messaging Tier) de votre numéro. Un compte nouveau est en Tier 1 (1 000 conversations par 24h). Ce niveau monte automatiquement avec le volume et la qualité. Les éditeurs SaaS à fort volume peuvent atteindre le Tier 4 (conversations illimitées) en quelques semaines.

Comment tester mon intégration sans envoyer de vrais messages ?

Whakup met à disposition un environnement sandbox où vous pouvez tester vos appels API sans déclencher d'envois réels. Le sandbox simule les réponses de l'API et les webhooks de statut, ce qui permet de valider toute votre chaîne d'intégration avant la mise en production.

Que se passe-t-il si le template est refusé par Meta ?

Vous recevez un statut REJECTED avec un motif. Les causes fréquentes : contenu trop promotionnel pour une catégorie UTILITY, lien URL non reconnu, variable mal formatée. Modifiez le template selon le motif et resoumettez. Whakup peut vous aider à reformuler pour maximiser les chances d'approbation.

L'API Whakup est-elle compatible avec n'importe quel langage de programmation ?

Oui. L'API est une API REST standard : elle accepte des requêtes HTTP avec JSON. Elle est compatible avec Node.js, Python, PHP, Ruby, Java, Go ou tout autre langage capable de faire des requêtes HTTP. Whakup fournit des exemples de code dans les langages les plus courants.

Conclusion

Ce tutoriel couvre la chaîne complète pour envoyer des notifications transactionnelles WhatsApp depuis une plateforme SaaS : embedded signup, création de template utility, appel API d'envoi et réception des statuts via webhook. L'intégration complète prend généralement 2 à 5 jours de développement pour un lead dev expérimenté.

Whakup, Meta Tech Provider certifié, fournit l'infrastructure, la documentation et le support pour que vos équipes soient autonomes rapidement. Démarrez votre intégration avec l'API WhatsApp Business et envoyez vos premières notifications transactionnelles en quelques jours.