API WhatsApp et l'embedded signup : guide pour les intégrateurs

L'embedded signup WhatsApp est le mécanisme officiel par lequel un intégrateur — agence, éditeur SaaS, plateforme martech — connecte les comptes WhatsApp Business de ses clients à sa propre infrastructure sans que ces clients aient besoin d'un accès direct au Business Manager Meta. C'est le point d'entrée obligatoire pour toute intégration multitenante sérieuse, et comprendre son fonctionnement précis est la condition sine qua non d'un onboarding fluide.

Ce qu'est vraiment l'embedded signup

L'embedded signup est un flux OAuth étendu fourni par Meta. Il permet à l'utilisateur final (votre client) de passer par une fenêtre modale Meta, directement intégrée dans votre interface, pour :

• créer ou connecter son compte WhatsApp Business Account (WABA),
• vérifier son numéro de téléphone professionnel,
• accepter les conditions d'utilisation Meta,
• déléguer les permissions nécessaires à votre application Meta (votre "Business App").

À la sortie du flux, vous recevez un code d'autorisation que vous échangez côté serveur contre un token système lié à ce WABA. Ce token est ce qui vous permet ensuite d'envoyer des messages, de créer des templates et de gérer le numéro pour le compte de votre client.

Ce qui distingue l'embedded signup d'une intégration manuelle :

Critère	Embedded signup	Intégration manuelle
Besoin d'accès BM pour le client	Non	Oui
Temps moyen d'onboarding	3-5 minutes	1-3 jours
Automatisable	Oui (webhooks)	Partiellement
Adapté au multi-tenant	Oui	Non

Prérequis techniques avant de démarrer

Avant d'implémenter l'embedded signup, plusieurs conditions doivent être réunies du côté de votre application Meta.

Côté Meta :

• Une Business App (type : Business) validée dans le Meta Developer Dashboard.
• Les produits WhatsApp et Facebook Login for Business activés sur cette app.
• La configuration du flux de signup (scopes, permissions, redirect URI) validée par Meta.
• Un accès Business Portfolio Meta (anciennement Business Manager) pour héberger les WABA de vos clients.

Côté votre infrastructure :

• Un endpoint HTTPS capable de recevoir le code d'autorisation post-flux.
• Une logique d'échange de code contre un System User Token (appel Graph API POST /{waba-id}/subscribed_apps).
• Un stockage sécurisé des tokens par WABA/client (les tokens n'expirent pas mais peuvent être révoqués).
• Un abonnement aux webhooks WhatsApp pour détecter les changements d'état du numéro.

Si vous passez par un Meta Tech Provider certifié comme Whakup, une partie de cette infrastructure est mutualisée : la Business App, le Business Portfolio et la gestion des System User Tokens sont déjà en place. Vous n'avez qu'à intégrer le widget front-end et brancher vos webhooks.

Le flux technique étape par étape

Voici le déroulé d'un embedded signup correctement implémenté :

1. Votre front-end charge le SDK Facebook JS et initialise FB.init() avec votre App ID.
2. L'utilisateur clique sur "Connecter WhatsApp" dans votre interface.
3. La fenêtre modale Meta s'ouvre : création ou connexion du WABA, vérification du numéro OTP.
4. Callback JavaScript : vous recevez un objet avec authResponse.code.
5. Échange côté serveur : POST https://graph.facebook.com/v19.0/oauth/access_token avec le code.
6. Souscription au WABA : POST /{phone-number-id}/subscribed_apps pour activer les webhooks.
7. Confirmation : le numéro apparaît en statut "Connected" dans le Graph API.

Points d'attention critiques :

• Le code d'autorisation a une durée de vie courte (quelques minutes). L'échange doit être immédiat.
• Ne stockez jamais le code côté client ; l'échange doit se faire serveur-à-serveur.
• En cas d'échec du flux (utilisateur ferme la modale), prévoyez un état "en attente" avec reprise possible.
• Testez les scénarios de numéro déjà enregistré sur un autre WABA — Meta retourne une erreur spécifique.

Gestion multi-tenant et isolation des données

Pour un éditeur SaaS ou une agence gérant des dizaines de clients, l'embedded signup doit s'inscrire dans une architecture multi-tenant rigoureuse.

Chaque client doit avoir :

• Son propre WABA (WhatsApp Business Account) — jamais de WABA partagé entre clients.
• Son propre numéro de téléphone enregistré (ou plusieurs si besoin).
• Des tokens isolés dans votre base de données, associés à son identifiant client.

Côté webhooks, Meta envoie tous les événements vers une seule URL de webhook configurée sur votre Business App. C'est à vous de router les événements entrants vers le bon client en vous basant sur le phone_number_id ou le waba_id présent dans chaque payload.

Une architecture propre inclut une table de correspondance {client_id, waba_id, phone_number_id, system_user_token} avec chiffrement des tokens au repos. Si vous gérez 50+ clients, automatisez également la détection des tokens révoqués via le webhook account_update (événement ACCOUNT_DELETED ou changement de statut).

Pour aller plus loin sur l'architecture multi-tenant et les bonnes pratiques de l'API WhatsApp Business, consultez notre documentation technique.

FAQ

L'embedded signup fonctionne-t-il pour les numéros déjà utilisés sur WhatsApp personnel ?

Non directement. Un numéro enregistré sur l'application WhatsApp grand public doit d'abord être supprimé du compte personnel avant d'être enregistré via l'API. Meta impose ce prérequis pour éviter les conflits de compte. Informez vos clients en amont pour éviter les blocages en cours de flux.

Faut-il que le client ait un Business Manager Meta existant ?

Non. L'embedded signup crée automatiquement un WABA (et si nécessaire un Business Portfolio associé) pendant le flux. Le client n'a pas besoin d'avoir configuré quoi que ce soit sur Meta au préalable. C'est précisément l'avantage de ce mécanisme pour les intégrateurs.

Comment gérer la révocation d'un token par un client ?

Quand un client supprime votre application de son Business Manager ou révoque les permissions, vous recevez un webhook account_update avec le type ACCOUNT_DELETED. À réception, marquez le WABA comme déconnecté dans votre base et envoyez une notification au client pour relancer le flux d'embedded signup.

Est-il possible de tester l'embedded signup en sandbox ?

Oui. Meta propose un environnement de test via le Meta Developer Dashboard (mode "test"). Vous pouvez simuler le flux complet avec un numéro de test fourni par Meta sans engager de compte réel. Utilisez cet environnement pour valider votre implémentation avant toute mise en production.

---

L'embedded signup est la pierre angulaire de tout onboarding WhatsApp scalable. Une implémentation correcte réduit le temps d'activation d'un client de plusieurs jours à quelques minutes. Si vous cherchez un partenaire technique pour déployer ce flux sans repartir de zéro, découvrez comment Whakup structure son embedded signup pour ses partenaires intégrateurs — infrastructure EU, multi-tenant natif, et support technique dédié.