Onboarding de numéro WhatsApp (Meta Cloud API)

Que fait Onboarding de numéro WhatsApp (Meta Cloud API) ?

Connecter un numéro ressemble à 10 clics. En pratique, cela échoue à cause de l'ordre des étapes, de la propriété des portfolios, et des écrans Meta qui indiquent "connecté" alors que rien n'arrive. Cette compétence fournit l'ordre sûr ainsi que les blocages qui se sont réellement produits, avec leurs solutions.

Étiquettes de confiance utilisées ci-dessous : [official] = indiqué sur developers.facebook.com (URL dans le tableau) ; [field] = s'est produit lors d'onboardings réels et la solution a été confirmée en conditions réelles ; [unconfirmed] = observé, cause ou solution jamais prouvée. Ne jamais présenter [field] ou [unconfirmed] comme une politique Meta.

Mots : ne jamais mélanger ces quatre

• Business portfolio (Business Manager) : l'entreprise dans Meta.
• WhatsApp Business Account (WABA) : vit à l'intérieur d'un portfolio. Dans l'interface, utiliser l'ID Compte de messagerie, pas l'ID "Compte WhatsApp/présence" (ce dernier renvoie "This API is not supported") [field].
• Numéro de téléphone : vit à l'intérieur d'une WABA. Son ID de numéro de téléphone n'est pas le numéro de téléphone.
• Application Meta : vit dans un compte développeur et est liée à un portfolio ; elle possède le jeton, le secret de l'application et le webhook.

Lorsque vous énoncez une limite, précisez de lequel des quatre il s'agit.

Limites qui déterminent le plan [official]

• Un nouveau portfolio peut enregistrer 2 numéros de téléphone ; le plafond passe à 20 lorsque l'entreprise est vérifiée ou atteint la limite de 2 000 messages.
• Les limites de messagerie sont par portfolio, partagées par tous ses numéros : 250 → 2 000 → 10 000 → 100 000 → illimité. Un seul numéro très actif peut épuiser l'allocation de tous.
• Enregistrement et désenregistrement : 10 requêtes par numéro par période de 72 h chacune ; au-delà, erreur 133016 et le numéro est bloqué pendant 72 h. Ne pas marteler "Activer" pendant le débogage.
• Ajouter un numéro dans WhatsApp Manager ou le tableau de bord de l'application ne l'enregistre pas pour Cloud API ; l'appel d'enregistrement est toujours nécessaire.
• Un numéro déjà utilisé avec WhatsApp (application téléphonique) ne peut pas être enregistré tant que ce compte n'est pas supprimé.
• Supprimer un numéro : uniquement les administrateurs du portfolio, pas via l'API, nécessite le code PIN à 2 étapes s'il est connecté, et est impossible s'il a envoyé des messages payants au cours des 30 derniers jours. Considérez la suppression comme irréversible.

Avant de commencer (collecter une fois)

Nom de l'entreprise exactement tel que les clients le verront, nom légal, pays, adresse complète, téléphone, site web ou page Facebook, email, logo, et le numéro à connecter. Le numéro ne doit pas avoir WhatsApp installé (si c'est le cas, supprimer d'abord le compte WhatsApp sur ce téléphone). Décider qui invente et conserve le code PIN à 6 chiffres.

Ordre sûr (chaque étape se termine par une vérification de retour)

1. Portfolio (business.facebook.com) : remplir Informations sur l'entreprise complètement (nom légal, adresse, téléphone, site web) avant d'ajouter un numéro. Sinon, l'onboarding échoue avec "your business doesn't meet WhatsApp policy" (#2494070) [field].
2. Compte WhatsApp + numéro (Paramètres du portfolio → Comptes → Comptes WhatsApp → Ajouter → nouveau numéro). Nom d'affichage = le nom de l'entreprise du client, jamais celui de l'agence. Vérifier par SMS, ou VOICE pour les lignes fixes [official]. Vérification de retour : le numéro apparaît sous la WABA.
3. Application Meta (developers.facebook.com → Créer une application → Cas d'utilisation WhatsApp), liée au même portfolio qui possède la WABA. Application dans un portfolio et WABA dans un autre : tout affichait en vert et aucun message n'était délivré ; déplacer l'application dans le portfolio de la WABA a résolu le problème [field]. Paramètres → Général : URLs de confidentialité/conditions/suppression de données qui renvoient 200, catégorie, icône.
4. Utilisateur système dans ce portfolio avec l'application et la WABA comme actifs ; jeton avec whatsapp_business_messaging + whatsapp_business_management, sans expiration. Un humain colle le jeton là où il est stocké ; ne jamais l'afficher.
5. IDs, lues par vous, pas tapées par une personne : GET /{waba-id}/phone_numbers → ID du numéro de téléphone. Stocker le numéro de téléphone dans la variable ID-du-numéro-de-téléphone a cassé un bot [field].
6. Variables d'environnement dans le projet d'hébergement exact. Plusieurs projets clients avec les mêmes noms de variables : indiquer le nom du projet et vérifier le titre avant de sauvegarder. Les IDs d'un client se sont retrouvés dans le projet d'un autre et son bot en production pointait vers le mauvais numéro [field].
7. Webhook (Application → WhatsApp → Configuration) : https://<domaine>/webhook plus jeton de vérification ; s'abonner au champ messages (il n'est pas toujours activé). Ensuite abonner la WABA à l'application : POST /{waba-id}/subscribed_apps.
8. Enregistrer le numéro : POST /{phone-number-id}/register avec le code PIN à 6 chiffres. Si le numéro a déjà une vérification en 2 étapes, utiliser le code PIN existant [official]. Vérification de retour : GET /{phone-number-id}?fields=status,platform_type,name_status → CONNECTED et CLOUD_API. Avant cela, il affiche PENDING / NOT_APPLICABLE [field].
9. Publier l'application, puis envoyer "Bonjour" depuis un téléphone personnel et voir le bot répondre.
10. Facturation : mode de paiement, fuseau horaire et devise définis sur le compte WhatsApp avant d'envoyer des modèles (131042 sinon) [official].
11. Vérification finale : statut du numéro, GET /{waba-id}/subscribed_apps affiche uniquement cette application, URL et champs du webhook, debug_token affiche la bonne application et un jeton d'utilisateur système.

Le nom d'affichage peut rester "en cours d'examen" pendant des jours alors que le numéro fonctionne déjà [field] ; ne pas cliquer sur Modifier, car la modification relance l'examen.

Règles d'or

• Même portfolio pour l'application et la WABA. Si le portfolio du client est bloqué en cours d'examen, une solution éprouvée sur le terrain consiste à placer le numéro dans une WABA d'un portfolio qui fonctionne (le vôtre), avec l'application dans ce même portfolio, dans la limite des 2 numéros [field]. Le chemin officiel à long terme est de devenir un fournisseur technologique avec Embedded Signup.
• Une application par client, par défaut. L'URL de callback de l'application est la destination par défaut. Meta prend en charge les remplacements de webhook par WABA et par numéro [official], mais si vous ne les avez pas testés, gardez une application par client.
• Lorsque le domaine d'hébergement change, mettre à jour le webhook dans Meta immédiatement et le vérifier. Un changement de domaine a silencieusement arrêté un bot [field].
• Ne jamais utiliser le chemin "Continuer" qui installe l'application WhatsApp Business sur le téléphone pour un numéro qui doit rester sur Cloud API : cela retire le numéro de l'API [field].
• Essayer d'abord ce qui ne casse rien. Désenregistrer, supprimer ou déplacer un numéro viennent en dernier, uniquement si Meta l'exige (voir les limites ci-dessus).
• Un contrôle de santé est vert uniquement lorsque Meta le dit : lire le statut du téléphone depuis Meta. Un jeton valide ne prouve rien sur le numéro [field].
• Une redirection vers l'URL d'un portfolio ne prouve pas qui possède un actif. Confirmer le nom du portfolio à l'écran [field].

Dépannage

Symptôme	Cause	Solution	Étiquette / Source
Tout vert, rien n'arrive	Application et WABA dans des portfolios différents	Nouvelle application dans le portfolio de la WABA ; supprimer le webhook de l'ancienne application	[field]
Messages arrivent en double / avertissements "app secret mismatch"	Deux applications abonnées à la même WABA	Supprimer le webhook et l'abonnement de l'ancienne application	[field]
Bot arrêté après un déploiement	Webhook toujours sur l'ancien domaine	Mettre à jour le webhook et le vérifier	[field]
"No se pudo asignar el socio" (assigner un partenaire) lorsque le client partage sa WABA	Jamais prouvé (portefeuille nouveau ou non vérifié, compte en cours d'examen)	Éviter le partage : construire dans un seul portfolio (voir les règles d'or)	[unconfirmed] cause, [field] contournement
"Business doesn't meet WhatsApp policy" (#2494070) lors de l'onboarding développeur	Informations d'entreprise incomplètes / nouveau portfolio	Compléter les informations d'entreprise ; ajouter le numéro depuis WhatsApp Manager à la place	[field]
"This API is not supported" avec l'ID WABA	Utilisé l'ID "Compte WhatsApp"	Utiliser l'ID Compte de messagerie	[field]
Statut PENDING, plateforme NOT_APPLICABLE	Ajouté mais pas enregistré	POST /register avec le code PIN	[official] + [field]
133005	Mauvais code PIN à 2 étapes	Utiliser le code PIN existant du numéro	codes d'erreur
133006	Numéro non vérifié	Vérifier par SMS/VOICE, puis enregistrer	codes d'erreur
133008 / 133009	Trop de tentatives de code PIN ou trop rapides	Attendre le temps indiqué dans details	codes d'erreur
133010	Numéro non enregistré sur la plateforme	L'enregistrer	codes d'erreur
133015	Numéro récemment supprimé, encore en cours de suppression	Attendre 5 minutes	codes d'erreur
133016	Plus de 10 requêtes d'enregistrement/désenregistrement en 72 h	Arrêter ; attendre la fin du blocage	enregistrement
133000	Un précédent désenregistrement a échoué	Désenregistrer à nouveau, puis enregistrer	codes d'erreur
"Number already has WhatsApp"	Numéro toujours sur l'application téléphonique ou un autre compte	Supprimer d'abord ce compte WhatsApp	numéros de téléphone
131042 sur les modèles	Mode de paiement : ligne de crédit, fuseau horaire ou devise non définis, compte suspendu	Corriger la facturation dans WhatsApp Manager ; montrer à l'utilisateur le texte de error_data.details de Meta, pas une supposition	codes d'erreur
131042 sur seulement quelques destinataires	À l'échelle du compte selon le texte de Meta, mais dans un contrôle en direct, 16 des 18 modèles ont été délivrés	Compter les délivrés et les échoués sur la même période avant de qualifier de compte entier ou de mettre en pause quoi que ce soit	[field] heuristique
131049	Non délivré "pour maintenir un engagement sain de l'écosystème"	Attendre au moins 24 h avant de renvoyer	codes d'erreur
131026	Le destinataire ne peut pas recevoir (pas de WhatsApp, version obsolète, conditions)	Le contacter autrement	codes d'erreur
131031	WABA restreint pour violation de politique	Consulter Policy Enforcement et l'API Health Status	codes d'erreur
Impossible de lier le numéro à la page Facebook pour les publicités click-to-WhatsApp	Nom d'affichage toujours en cours d'examen (probable)	Attendre l'approbation, puis Page → Comptes liés → WhatsApp	[unconfirmed]

Autres pages officielles : démarrer · limites de messagerie · remplacements de webhook.

Non vérifié (le dire si cela se présente)

• Ce que "No se pudo asignar el socio" nécessite réellement.
• Si un portfolio nouveau et non vérifié peut créer une WABA.
• Déplacer un numéro entre WABAs : le guide de Meta dit que ce n'est pas pris en charge pour les comptes sur le nouveau modèle de compte ; cela n'a jamais été réalisé sur le terrain.
• Délais officiels d'examen du nom d'affichage. Les deux URL officielles retournaient 404 en novembre 2026.

Qui fait quoi

L'agent effectue chaque vérification d'écran et d'API qu'il peut. La personne fournit uniquement ce qu'une machine ne peut pas : le code SMS/voix du téléphone, le code PIN, le collage des secrets, les contrôles d'identité, les paiements.