Embedded signup WhatsApp : guide pas à pas pour les éditeurs

L'embedded signup WhatsApp est le mécanisme officiel de Meta qui permet à un utilisateur de connecter son compte WhatsApp Business directement depuis l'interface de votre plateforme, sans jamais quitter votre site. En tant qu'éditeur, vous intégrez ce flux une fois ; tous vos clients bénéficient ensuite d'un onboarding WhatsApp fluide en quelques minutes. C'est le point d'entrée incontournable pour toute plateforme SaaS qui veut proposer WhatsApp en marque blanche.

Ce que fait concrètement l'embedded signup

L'embedded signup repose sur le SDK JavaScript de Meta (anciennement SDK Facebook) et un flux OAuth. Voici ce que voit votre client lors de l'onboarding :

1. Il clique sur "Connecter WhatsApp" dans votre interface.
2. Une popup Meta s'ouvre (elle reste dans le domaine de Meta, pas le vôtre).
3. Il se connecte à son compte Facebook personnel (nécessaire pour accéder au Business Manager).
4. Il sélectionne ou crée son compte Meta Business Manager.
5. Il sélectionne ou crée son compte WhatsApp Business Account (WABA).
6. Il ajoute ou sélectionne un numéro de téléphone et le vérifie (par appel ou SMS).
7. Il autorise votre application à accéder à son WABA.
8. La popup se ferme et retourne un code d'autorisation à votre callback JavaScript.

De votre côté, vous échangez ce code contre un token d'accès WABA, que vous stockez pour les appels API futurs.

Prérequis avant d'implémenter

Avant d'écrire la moindre ligne de code, vérifiez que vous avez :

• Une app Meta approuvée pour WhatsApp Business (type "Business" dans Meta for Developers).
• Un Meta Tech Provider certifié comme partenaire — c'est lui qui vous donne accès au produit "WhatsApp" dans votre app Meta. Whakup fournit cet accès clé en main.
• Les permissions app requises : whatsapp_business_management, whatsapp_business_messaging, business_management.
• Un domaine HTTPS vérifié dans les paramètres de votre app Meta.
• Un endpoint backend capable de recevoir le code d'autorisation et d'appeler l'API Graph pour l'échanger contre un token.

Implémentation côté frontend

Chargement du SDK

<script async defer crossorigin="anonymous"
  src="https://connect.facebook.net/fr_FR/sdk.js">
</script>

Initialisation

window.fbAsyncInit = function() {
  FB.init({
    appId: 'VOTRE_APP_ID',
    autoLogAppEvents: true,
    xfbml: true,
    version: 'v20.0'
  });
};

Déclenchement du flux

function lancerEmbeddedSignup() {
  FB.login(function(response) {
    if (response.authResponse) {
      const code = response.authResponse.code;
      // Envoyer ce code à votre backend
      envoyerCodeAuBackend(code);
    }
  }, {
    config_id: 'VOTRE_CONFIG_ID', // Configuré dans Meta for Developers
    response_type: 'code',
    override_default_response_type: true,
    extras: {
      sessionInfoVersion: 2
    }
  });
}

Le config_id est un identifiant de configuration que vous créez dans l'interface Meta for Developers, sous "Configuration de l'intégration WhatsApp". Il définit les étapes du flux que votre client verra.

Implémentation côté backend : échange du code contre un token

Une fois le code reçu, votre backend effectue un appel POST à l'API Graph :

POST https://graph.facebook.com/v20.0/oauth/access_token
  ?client_id={APP_ID}
  &client_secret={APP_SECRET}
  &code={CODE_RECU}

Meta retourne un token d'accès utilisateur. Vous l'échangez ensuite contre un token système (System User Token) rattaché à votre app, qui sera le token utilisé pour tous les appels API au nom de ce WABA client.

Ce qu'il faut stocker après le flux :

Donnée	Usage
waba_id	Identifiant du WABA client — nécessaire pour la gestion des templates
phone_number_id	Identifiant du numéro — nécessaire pour l'envoi de messages
System User Token	Token d'authentification pour tous les appels API
business_id	Identifiant du Business Manager client

Stockez ces données dans votre vault de secrets, associées à l'identifiant du tenant. Ne les exposez jamais dans des réponses API côté client.

Gestion des erreurs et cas particuliers de l'embedded signup

L'embedded signup peut échouer ou être abandonné pour plusieurs raisons :

• L'utilisateur ferme la popup sans terminer : le callback JS ne reçoit pas de code. Gérez ce cas en affichant un message d'aide et en permettant de relancer le flux.
• Le numéro est déjà utilisé sur WhatsApp : Meta demandera à l'utilisateur de le libérer depuis l'app WhatsApp avant de pouvoir l'utiliser via l'API. Informez votre utilisateur de cette étape en amont.
• Le Business Manager est restreint : certains comptes Meta Business ont des restrictions d'accès aux produits WhatsApp, souvent suite à des violations passées. Dans ce cas, le client doit contacter le support Meta directement.
• L'exchange du code échoue : les codes d'autorisation ont une durée de vie courte (quelques minutes). Si l'échange échoue pour cause d'expiration, relancez le flux depuis le début.

Pour aller plus loin sur les étapes qui suivent l'embedded signup (activation du numéro, configuration des webhooks, premiers templates), consultez le guide complet de l'API WhatsApp Business. La question du choix entre construire cette intégration soi-même ou s'appuyer sur un partenaire est traitée dans Build vs Buy pour l'API WhatsApp.

FAQ

L'embedded signup fonctionne-t-il sur mobile ?

Oui. La popup Meta s'adapte au format mobile. Cependant, l'expérience est plus fluide sur desktop. Si votre audience est majoritairement mobile, testez spécifiquement le flux sur iOS et Android pour vérifier que la popup s'ouvre correctement et que le retour vers votre interface se fait sans erreur.

Combien de temps dure l'onboarding via embedded signup pour un client ?

Entre 3 et 10 minutes, selon que le client a déjà un Business Manager et un numéro disponible ou qu'il doit en créer un. La vérification du numéro (SMS ou appel) représente généralement l'étape la plus longue.

Faut-il que le client soit administrateur de son Business Manager ?

Oui. Seul un administrateur du Business Manager peut autoriser une app tierce à accéder au WABA. Si votre interlocuteur chez le client n'a pas ce rôle, il doit en obtenir un de la part de l'administrateur existant avant de lancer le flux d'onboarding.

Le token récupéré via embedded signup expire-t-il ?

Le token utilisateur récupéré lors de l'embedded signup expire (généralement au bout de 60 jours d'inactivité). C'est pourquoi l'étape d'échange contre un System User Token à longue durée de vie est essentielle. Ce token système, correctement configuré, n'expire pas automatiquement mais doit faire l'objet d'une politique de rotation régulière.

---

L'embedded signup est la brique qui rend l'onboarding WhatsApp scalable pour un éditeur SaaS : un seul flux, des dizaines ou des centaines de clients connectés sans intervention manuelle. Pour accéder à l'embedded signup et à l'ensemble de l'infrastructure API WhatsApp — hébergée en Europe, conforme RGPD, avec support technique dédié — découvrez la solution Whakup pour les éditeurs de plateformes.