API Graph Meta : endpoints WhatsApp essentiels pour développeurs 2025

L'API Graph de Meta est l'interface centrale par laquelle transitent toutes les interactions avec WhatsApp Business Cloud. Comprendre la structure de cette API, ses endpoints principaux et leurs paramètres est indispensable pour tout développeur qui construit des intégrations WhatsApp. Ce guide de référence 2025 couvre les endpoints les plus utilisés avec des exemples d'appels réels, les paramètres disponibles et les codes de réponse à connaître.

Structure générale de l'API Graph Meta

L'API Graph Meta suit une architecture RESTful standard. Toutes les requêtes vers les ressources WhatsApp suivent ce pattern :

https://graph.facebook.com/{version}/{resource-id}/{edge}

Pour WhatsApp, la version actuelle recommandée est v18.0 (ou la version stable la plus récente). Le {resource-id} est typiquement votre phone-number-id pour les opérations de messagerie.

Authentification : toutes les requêtes requièrent un token Bearer dans le header :

Authorization: Bearer {ACCESS_TOKEN}

Format : toutes les requêtes et réponses sont en JSON avec le header Content-Type: application/json.

Endpoint 1 : Envoi de messages

POST https://graph.facebook.com/v18.0/{phone-number-id}/messages

C'est l'endpoint central pour tout envoi de message. Il supporte tous les types de messages WhatsApp.

Paramètres obligatoires :

• messaging_product : toujours "whatsapp"
• to : numéro du destinataire (format international sans +)
• type : type de message (text, template, image, document, audio, video, sticker, location, contacts, interactive, reaction)

Exemple — Message texte :

curl -X POST https://graph.facebook.com/v18.0/PHONE_NUMBER_ID/messages \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "221771234567",
    "type": "text",
    "text": { "body": "Bonjour depuis l API WhatsApp !" }
  }'

Réponse succès :

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

Endpoint 2 : Gestion des templates (HSM)

GET https://graph.facebook.com/v18.0/{whatsapp-business-account-id}/message_templates

Récupérer la liste de tous vos templates approuvés :

curl -X GET "https://graph.facebook.com/v18.0/WABA_ID/message_templates?fields=name,status,language,components" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Réponse :

{
  "data": [
    {
      "name": "confirmation_commande",
      "status": "APPROVED",
      "language": "fr",
      "components": [
        { "type": "HEADER", "format": "TEXT", "text": "Confirmation commande #{{1}}" },
        { "type": "BODY", "text": "Bonjour {{1}}, votre commande est confirmée..." },
        { "type": "FOOTER", "text": "Whakup - Messagerie Professionnelle" }
      ]
    }
  ]
}

POST — Créer un nouveau template :

curl -X POST "https://graph.facebook.com/v18.0/WABA_ID/message_templates" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "rappel_rdv",
    "language": "fr",
    "category": "UTILITY",
    "components": [
      {
        "type": "BODY",
        "text": "Bonjour {{1}}, rappel de votre rendez-vous le {{2}} à {{3}}."
      },
      {
        "type": "BUTTONS",
        "buttons": [
          { "type": "QUICK_REPLY", "text": "Confirmer" },
          { "type": "QUICK_REPLY", "text": "Reporter" }
        ]
      }
    ]
  }'

Endpoint 3 : Informations sur les numéros de téléphone

GET https://graph.facebook.com/v18.0/{whatsapp-business-account-id}/phone_numbers

Lister tous les numéros enregistrés sur votre compte :

curl -X GET "https://graph.facebook.com/v18.0/WABA_ID/phone_numbers?fields=id,display_phone_number,verified_name,quality_rating,status" \
  -H "Authorization: Bearer ACCESS_TOKEN"

GET https://graph.facebook.com/v18.0/{phone-number-id}

Détails d'un numéro spécifique avec son quality rating :

curl -X GET "https://graph.facebook.com/v18.0/PHONE_NUMBER_ID?fields=quality_rating,messaging_limit_tier,display_phone_number" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Réponse :

{
  "quality_rating": "GREEN",
  "messaging_limit_tier": "TIER_10K",
  "display_phone_number": "+221 77 123 45 67",
  "id": "PHONE_NUMBER_ID"
}

Endpoint 4 : Upload de médias

POST https://graph.facebook.com/v18.0/{phone-number-id}/media

Uploader un fichier média pour l'utiliser dans un message :

curl -X POST "https://graph.facebook.com/v18.0/PHONE_NUMBER_ID/media" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -F "messaging_product=whatsapp" \
  -F "type=image/jpeg" \
  -F "file=@/path/to/image.jpg"

Réponse :

{ "id": "MEDIA_ID_1234567" }

Utiliser le media_id dans un message :

{
  "messaging_product": "whatsapp",
  "to": "221771234567",
  "type": "image",
  "image": {
    "id": "MEDIA_ID_1234567",
    "caption": "Notre nouveau produit disponible dès maintenant !"
  }
}

Endpoint 5 : Vérification de token et débogage

GET https://graph.facebook.com/debug_token

Vérifier la validité d'un token :

curl -X GET "https://graph.facebook.com/debug_token?input_token=TOKEN_A_VERIFIER&access_token=APP_ID|APP_SECRET" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Réponse :

{
  "data": {
    "is_valid": true,
    "expires_at": 0,
    "scopes": ["whatsapp_business_messaging", "whatsapp_business_management"]
  }
}

Endpoint 6 : Gestion des webhooks

GET/POST https://graph.facebook.com/v18.0/{app-id}/subscriptions

Vérifier et configurer les souscriptions webhook de votre application :

# Lister les souscriptions actives
curl -X GET "https://graph.facebook.com/v18.0/APP_ID/subscriptions" \
  -H "Authorization: Bearer APP_ACCESS_TOKEN"

# Souscrire à des champs webhook
curl -X POST "https://graph.facebook.com/v18.0/APP_ID/subscriptions" \
  -H "Authorization: Bearer APP_ACCESS_TOKEN" \
  -d "object=whatsapp_business_account&callback_url=https://votre-serveur.com/webhook&fields=messages,message_deliveries,message_reads&verify_token=VOTRE_VERIFY_TOKEN"

Pour une compréhension complète de l'architecture API, consultez le guide complet WhatsApp Business API et l'article sur l'utilisation sans développeur pour les équipes non-techniques.

FAQ

Q: Quelle version de l'API Graph Meta utiliser pour WhatsApp en 2025 ?

R: Meta maintient plusieurs versions simultanément pendant 2 ans avant leur dépréciation. En 2025, v18.0 à v21.0 sont actives. La pratique recommandée est d'utiliser la version la plus récente stable (v20.0 ou v21.0) pour bénéficier des dernières fonctionnalités, et de planifier des mises à jour régulières. Abonnez-vous aux release notes Meta pour être notifié des dépréciations.

Q: Comment récupérer l'identifiant WABA_ID (WhatsApp Business Account ID) ?

R: Le WABA_ID est disponible dans votre tableau de bord Meta Business Suite → Accounts → WhatsApp Accounts. Il est également retourné dans la réponse de l'endpoint /phone_numbers. Ne confondez pas le WABA_ID (identifiant du compte business) avec le Phone Number ID (identifiant d'un numéro spécifique) — ils sont tous deux nécessaires pour différents appels API.

Q: L'API Graph Meta supporte-t-elle les appels en batch pour envoyer plusieurs messages en une seule requête ?

R: Meta propose une API Batch (https://graph.facebook.com) qui permet d'inclure jusqu'à 50 requêtes API dans un seul appel HTTP. Chaque requête dans le batch peut envoyer un message différent. Cependant, pour WhatsApp, cette approche n'offre pas d'avantage significatif sur le rate limit par message. Les appels séquentiels avec throttling restent l'approche recommandée.

Q: Peut-on appeler l'API Graph Meta depuis un navigateur (frontend JavaScript) ?

R: Techniquement oui, mais c'est une très mauvaise pratique. Cela exposerait votre token d'accès dans le code source frontend visible par tous. Les appels à l'API WhatsApp doivent toujours se faire côté serveur (backend). Utilisez votre propre API backend comme intermédiaire si vous avez une application web ou mobile.

Q: Y a-t-il un SDK officiel Meta pour l'API Graph WhatsApp ?

R: Meta ne propose pas de SDK officiel spécifique à WhatsApp. Le SDK Graph API Meta (disponible pour Python, PHP, JavaScript, iOS, Android) peut être utilisé pour les appels de base, mais la communauté a développé des wrappers plus spécialisés pour WhatsApp (heyoo pour Python, whatsapp-cloud-api pour Node.js). En pratique, utiliser directement requests/axios/curl avec les endpoints documentés est souvent plus simple.

---

Maîtrisez l'API WhatsApp sans vous perdre dans la documentation Meta. Whakup abstrait la complexité de l'API Graph pour vous offrir une interface intuitive, des templates gérés et des analytics en temps réel.