Les composants techniques de l'API WhatsApp Business

L'API WhatsApp Business s'articule autour d'un ensemble d'objets et de concepts qu'il faut maîtriser avant d'écrire la première ligne d'intégration. Sans cette cartographie, les erreurs de conception arrivent tôt et coûtent cher à corriger. Ce guide décortique chaque composant technique : ce qu'il est, à quoi il sert, et comment il interagit avec les autres.

La hiérarchie des objets Meta

L'architecture de l'API WhatsApp Business repose sur une hiérarchie d'objets imbriqués :

Meta Business Account
└── WhatsApp Business Account (WABA)
    ├── Phone Number 1
    │   ├── Templates
    │   └── Conversations
    └── Phone Number 2
        ├── Templates
        └── Conversations

Meta Business Account : le compte racine. C'est le compte Meta Business Manager de l'entreprise. Il peut contenir plusieurs WABA.

WhatsApp Business Account (WABA) : l'entité WhatsApp centrale. Elle a un identifiant unique (WABA ID) et regroupe les numéros, les templates et les paramètres de l'entreprise. C'est l'objet auquel s'appliquent les règles Meta (score de qualité, niveaux d'envoi).

Phone Number : chaque numéro de téléphone activé dans l'API. Il a son propre identifiant (Phone Number ID) qui est l'identifiant utilisé dans tous les appels API d'envoi de messages.

Les identifiants clés à connaître

Identifiant	Rôle	Où le trouver
`WABA ID`	Identifie le compte WhatsApp Business	Meta Business Manager ou tableau de bord du partenaire
`Phone Number ID`	Identifie le numéro pour les envois	Tableau de bord du partenaire, API de listing
`Access Token`	Authentifie les appels API	Généré par le partenaire ou Meta
`App ID`	Identifie l'application Meta	Console développeurs Meta
`Template Name`	Identifie un template approuvé	Tableau de bord Meta ou API

Ces identifiants sont distincts du numéro de téléphone lui-même. Vos appels API utilisent toujours le Phone Number ID, jamais le numéro en clair.

L'API REST : structure des endpoints

La Cloud API de Meta est une API REST standard. Les endpoints principaux :

Envoi d'un message

POST /v17.0/{phone-number-id}/messages
Authorization: Bearer {access-token}

Récupération des templates

GET /v17.0/{waba-id}/message_templates

Création d'un template

POST /v17.0/{waba-id}/message_templates

Récupération des numéros d'un WABA

GET /v17.0/{waba-id}/phone_numbers

Les versions d'API (v17.0, v18.0, etc.) sont mises à jour régulièrement par Meta. Une bonne pratique est de ne pas coder en dur la version, mais de la rendre configurable pour faciliter les mises à jour.

Les tokens d'accès : types et durée de vie

L'authentification sur l'API se fait via des tokens Bearer. Meta distingue :

Token temporaire (User Access Token) : valide quelques heures, généré lors du flux OAuth. Utilisé uniquement pendant la phase de développement ou de tests.
Token système permanent (System User Token) : la solution recommandée pour la production. Il ne expire pas et est associé à un utilisateur système (System User) créé dans le Meta Business Manager.

Pour une intégration en production, utilisez toujours un System User Token. Un token temporaire qui expire en production est une source classique d'incidents.

Les templates (HSM) : structure et variables

Un template WhatsApp est un modèle de message structuré, composé de plusieurs composants optionnels :

Header : texte, image, document ou vidéo.
Body : texte principal avec des variables ({{1}}, {{2}}, etc.).
Footer : texte statique en bas du message.
Buttons : jusqu'à 3 boutons par message (appel téléphonique, URL, réponse rapide).

Exemple de corps de template avec variables :

Bonjour {{1}}, votre commande {{2}} a été expédiée.
Suivez votre livraison ici : {{3}}

Lors de l'envoi, vous remplacez les variables par les valeurs dynamiques de chaque destinataire. La catégorie du template (marketing, utility, authentification) détermine les frais Meta applicables et les règles de contenu. Pour un détail complet des règles par catégorie, consultez notre article sur les catégories de templates WhatsApp.

Les webhooks : le système d'événements temps réel

Les webhooks sont la mécanique par laquelle Meta notifie votre système des événements de conversation. Sans webhooks, votre intégration est borgne : vous envoyez des messages mais ne recevez pas les réponses ni les statuts.

Les événements principaux :

Événement	Description
`messages`	Un utilisateur vous a envoyé un message
`message_status`	Statut d'un message (sent, delivered, read, failed)
`template_status`	Changement de statut d'un template (approuvé, rejeté)
`account_alerts`	Alertes sur le compte (qualité, limite d'envoi)

Structure d'un payload webhook (simplifié) :

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "{WABA_ID}",
    "changes": [{
      "value": {
        "messaging_product": "whatsapp",
        "messages": [{
          "from": "33612345678",
          "type": "text",
          "text": { "body": "Bonjour" }
        }]
      }
    }]
  }]
}

Votre endpoint webhook doit répondre en moins de 20 secondes avec un statut HTTP 200, sinon Meta considère la livraison comme échouée et retente.

Les types de messages supportés

L'API prend en charge plusieurs types de messages, chacun avec sa propre structure JSON :

text : message texte simple.
image / audio / video / document : médias avec URL hébergée.
template : message template avec remplacement de variables.
interactive : boutons, listes déroulantes, réponses rapides.
location : partage de coordonnées GPS.
contacts : partage d'une fiche contact.
sticker : stickers WhatsApp natifs.

Pour les messages interactifs (boutons, listes), il y a des restrictions sur l'utilisation dans les templates vs les messages de service. Les messages interactifs proactifs (hors fenêtre de 24h) sont soumis aux mêmes règles d'approbation que les templates.

La gestion des erreurs

Meta renvoie des codes d'erreur structurés. Les plus fréquents à gérer :

130429 : limite de débit dépassée (rate limiting). Retentez avec un backoff exponentiel.
131047 : le message n'a pas pu être livré (numéro invalide, utilisateur inexistant sur WhatsApp).
132000 : le template n'existe pas ou n'est pas approuvé.
133010 : le numéro est en dehors de la fenêtre de 24 heures et vous n'avez pas envoyé de template.

Une gestion robuste des erreurs est indispensable pour toute intégration en production. Pour aller plus loin sur la structure complète de l'API, notre guide de l'API WhatsApp Business est le point de départ.

FAQ

Peut-on utiliser la même application Meta pour plusieurs WABA ?

Oui. Une application Meta peut être associée à plusieurs WABA. C'est la configuration recommandée pour les agences et plateformes multi-clients. Chaque WABA reste isolé avec ses propres numéros et templates.

Quelle est la différence entre un Phone Number ID et le numéro de téléphone ?

Le numéro de téléphone est le numéro humain (ex: +33612345678). Le Phone Number ID est l'identifiant interne Meta de ce numéro dans l'API. C'est toujours le Phone Number ID qui est utilisé dans les appels API, jamais le numéro en clair.

Comment savoir si mon webhook est correctement configuré ?

Meta propose un outil de vérification dans la console développeurs. Il envoie un challenge GET à votre endpoint. Si votre serveur répond correctement avec le hub.challenge, la configuration est validée. Vous pouvez aussi utiliser des outils comme ngrok en développement pour exposer un endpoint local.

Les tokens d'accès permanent expirent-ils ?

Les System User Tokens ne sont pas soumis à expiration automatique, mais ils peuvent être révoqués manuellement. Stockez-les de façon sécurisée (variable d'environnement, secret manager) et ne les incluez jamais dans votre code source.

Vous construisez une intégration WhatsApp et vous voulez éviter les erreurs d'architecture classiques ? Découvrez l'API WhatsApp pour agences et éditeurs de Whakup, Meta Tech Provider certifié, avec documentation technique complète, webhooks, embedded signup et hébergement EU.