Phone Number ID et WABA ID : Comprendre les Identifiants de l'API WhatsApp

Quand on débute avec l'API WhatsApp Business, on se retrouve rapidement submergé par une avalanche d'identifiants : Phone Number ID, WABA ID, App ID, Business ID... Chacun joue un rôle précis dans l'écosystème Meta. Confondre ces identifiants est l'une des erreurs les plus fréquentes qui génèrent des messages d'erreur cryptiques. Ce guide clarifie tout.

La Hiérarchie des Identifiants Meta

L'écosystème Meta suit une structure hiérarchique stricte. Comprendre cette hiérarchie, c'est comprendre comment chaque identifiant s'articule avec les autres.

Meta Business Portfolio (Business Manager)
└── Meta App (Application Meta for Developers)
    └── WABA (WhatsApp Business Account)
        └── Phone Number (Numéro de téléphone)
            └── Phone Number ID

Chaque niveau possède son propre identifiant unique. Voici ce que chacun représente :

Business Portfolio ID (ou Business ID) Identifiant de votre Meta Business Manager. Visible dans l'URL de business.facebook.com : business.facebook.com/overview?business_id=XXXXXXXXX. Utilisé pour les opérations de gestion de compte au niveau entreprise.

App ID Identifiant de votre application Meta for Developers. Visible dans le tableau de bord de votre app, généralement dans l'URL ou dans Paramètres > Général. Utilisé pour l'authentification OAuth et les appels API de gestion d'application.

WABA ID (WhatsApp Business Account ID) Identifiant du compte WhatsApp Business. Un WABA peut contenir plusieurs numéros de téléphone. C'est l'entité qui regroupe vos numéros, templates, et paramètres business WhatsApp.

Phone Number ID L'identifiant le plus utilisé dans les appels API quotidiens. C'est le {phone-number-id} qui apparaît dans toutes les URLs d'envoi de messages : https://graph.facebook.com/v19.0/{phone-number-id}/messages. Il est différent du numéro de téléphone lui-même.

Comment Trouver Chaque Identifiant

Via le Meta Developer Dashboard :

1. Accédez à developers.facebook.com
2. Sélectionnez votre application
3. Dans le menu gauche : WhatsApp > Configuration API

Sur cette page, vous trouverez :
- App ID : affiché en haut du tableau de bord de l'app
- WABA ID : dans la section "Compte WhatsApp Business sélectionné"
- Phone Number ID : dans la section "De" > numéro sélectionné > (i) icon

Via l'API Meta (méthode programmatique) :

# Lister tous les WABA associés à votre app
curl -X GET \
  "https://graph.facebook.com/v19.0/YOUR_APP_ID/owned_whatsapp_business_accounts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Réponse exemple
{
  "data": [
    {
      "id": "123456789012345",  // <-- C'est votre WABA ID
      "name": "Mon Entreprise",
      "timezone_id": "1",
      "currency": "EUR"
    }
  ]
}

# Lister tous les numéros d'un WABA
curl -X GET \
  "https://graph.facebook.com/v19.0/YOUR_WABA_ID/phone_numbers?fields=display_phone_number,id,quality_rating" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Réponse exemple
{
  "data": [
    {
      "display_phone_number": "+225 07 XX XX XX XX",
      "id": "987654321098765",  // <-- C'est votre Phone Number ID
      "quality_rating": "GREEN"
    }
  ]
}

Via votre BSP (Whakup, Twilio, etc.) : Si vous utilisez un BSP, ces identifiants sont disponibles dans votre tableau de bord BSP. Dans Whakup, ils apparaissent dans Paramètres > Intégration API > Identifiants.

Utilisation Pratique dans les Appels API

Voici comment utiliser correctement chaque identifiant dans les endpoints API les plus courants :

# Envoyer un message (utilise Phone Number ID)
POST https://graph.facebook.com/v19.0/{PHONE_NUMBER_ID}/messages

# Lister les templates d'un WABA (utilise WABA ID)
GET https://graph.facebook.com/v19.0/{WABA_ID}/message_templates

# Créer un template (utilise WABA ID)
POST https://graph.facebook.com/v19.0/{WABA_ID}/message_templates

# Vérifier le statut d'un numéro (utilise Phone Number ID)
GET https://graph.facebook.com/v19.0/{PHONE_NUMBER_ID}

# Lister les numéros d'un WABA (utilise WABA ID)
GET https://graph.facebook.com/v19.0/{WABA_ID}/phone_numbers

Erreur classique des débutants : Utiliser le numéro de téléphone brut (+225XXXXXXXXX) à la place du Phone Number ID. L'API retournera une erreur Invalid parameter si vous faites cette confusion.

Gérer plusieurs WABA et Numéros

Pour les entreprises avec plusieurs marchés ou plusieurs marques, la gestion de multiples WABA et numéros est courante. Voici la structure recommandée :

# Exemple d'organisation multi-marchés
Meta Business Manager
├── App Meta "Production"
│   ├── WABA "Côte d'Ivoire" (WABA ID: 111...)
│   │   ├── Numéro CI commercial (+225...) [Phone ID: 222...]
│   │   └── Numéro CI support (+225...) [Phone ID: 333...]
│   └── WABA "Sénégal" (WABA ID: 444...)
│       └── Numéro SN (+221...) [Phone ID: 555...]
└── App Meta "Development"
    └── WABA "Test" (WABA ID: 666...)
        └── Numéro test sandbox [Phone ID: 777...]

Cette architecture claire facilite la gestion des tokens (un token par app), des templates (gérés par WABA), et du monitoring (par numéro).

Pour comprendre comment créer et configurer votre application Meta, consultez notre guide Créer son App Meta pour WhatsApp API. Pour la configuration des webhooks qui utilisent ces identifiants, lisez notre article Webhooks WhatsApp API. Le guide complet WhatsApp Business API couvre le contexte global.

Sécurité et Gestion des Accès

Ces identifiants doivent être traités avec précaution :

Ce qui est public (peut être exposé côté client si nécessaire) :

• Phone Number ID : identifiant technique, pas sensible
• WABA ID : identifiant de compte, pas sensible seul

Ce qui est strictement confidentiel :

• App Secret : ne doit jamais apparaître dans du code client ou un repository public
• System User Token : donne un accès complet à l'API — à stocker en variable d'environnement

Bonne pratique : Utilisez toujours des variables d'environnement pour les secrets. Exemple en Node.js :

const config = {
  phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID,
  wabaId: process.env.WHATSAPP_WABA_ID,
  accessToken: process.env.WHATSAPP_ACCESS_TOKEN, // JAMAIS en dur dans le code
};

FAQ — Phone Number ID et WABA ID

Le Phone Number ID change-t-il si je change d'opérateur pour mon numéro ? Non. Le Phone Number ID est attribué par Meta lors de l'enregistrement du numéro dans l'API. Il reste stable tant que le numéro est actif dans votre WABA, indépendamment de l'opérateur téléphonique sous-jacent.

Peut-on avoir plusieurs WABA dans le même Business Manager ? Oui, un Meta Business Manager peut contenir plusieurs WABA. C'est courant pour les groupes multi-marques ou les agences gérant plusieurs clients. Chaque WABA a son propre ensemble de numéros et de templates.

Le WABA ID est-il le même que le "WhatsApp Business Account ID" dans le Business Manager ? Oui, ce sont deux noms pour le même identifiant. La documentation Meta utilise parfois "WABA ID" et parfois "WhatsApp Business Account ID" de façon interchangeable.

Comment savoir si mon Phone Number ID est correct ? Testez avec un appel GET simple : GET https://graph.facebook.com/v19.0/{PHONE_NUMBER_ID}. Si l'ID est valide, vous obtenez les informations du numéro. Si vous recevez une erreur Invalid parameter ou Object with ID does not exist, votre ID est incorrect.

---

Vous cherchez une façon simple d'accéder à l'API WhatsApp Business sans gérer manuellement ces identifiants ? Créez votre compte Whakup — notre interface centralise tous vos identifiants et vous permet d'envoyer vos premières campagnes sans configuration API complexe.