Architecture multi-tenant pour une API WhatsApp en marque blanche

Une architecture multi-tenant WhatsApp permet à un éditeur de plateforme ou à une agence de gérer plusieurs clients (tenants) depuis une seule intégration API, chaque client disposant de son propre numéro WhatsApp Business, de ses propres templates et de ses propres conversations — sans que les données ne se croisent. C'est le modèle qui s'impose dès qu'on veut opérer WhatsApp en marque blanche à grande échelle.

Les deux modèles d'architecture : WABA partagée vs WABA par client

Le premier choix architectural est de décider où se situe le périmètre de chaque tenant dans le graphe d'objets Meta.

Modèle 1 — WABA partagée, numéros séparés

Tous les clients partagent un même WhatsApp Business Account (WABA), mais chacun dispose d'un ou plusieurs numéros de téléphone distincts. C'est l'approche la plus simple à opérer : une seule app Meta, un seul token d'accès système, un seul endpoint webhook à maintenir.

Limites : les templates sont partagés au niveau WABA (un template approuvé est visible par tous les numéros), la limite de messagerie s'applique par numéro, et un incident de conformité sur un tenant peut rejaillir sur le WABA entier.

Modèle 2 — WABA dédiée par client

Chaque client possède son propre WABA, rattaché à votre Business Manager via l'embedded signup. Cette isolation est plus forte : templates, limites de messagerie et score qualité sont totalement indépendants par client. En contrepartie, la complexité opérationnelle est plus élevée (gestion de N tokens, N webhooks ou un fan-out centralisé, N audits de conformité).

Pour la majorité des éditeurs SaaS B2B, le modèle 2 est recommandé dès lors qu'on dépasse une dizaine de clients actifs ou que les clients ont des exigences de conformité strictes.

Conception du routage des webhooks

Quelle que soit l'approche WABA choisie, votre infrastructure doit recevoir les événements Meta (messages entrants, statuts de livraison, mises à jour de templates) et les acheminer vers le bon tenant.

Architecture recommandée :

1. Un endpoint webhook unique exposé publiquement, qui reçoit tous les événements Meta.
2. Un service de fan-out qui identifie le tenant à partir du phone_number_id contenu dans le payload, puis publie l'événement dans une queue dédiée (RabbitMQ, SQS, Pub/Sub).
3. Des workers par tenant (ou un worker multi-tenant avec isolation logique) qui consomment la queue et exécutent la logique métier.

Ce pattern découple la réception des événements de leur traitement. Il permet d'absorber des pics de volume sur un tenant sans affecter les autres, et de rejouer des événements en cas d'erreur de traitement sans risquer de perdre des messages.

Composant	Rôle	Point d'attention
Endpoint webhook	Réception et validation de la signature HMAC Meta	Répondre 200 OK en < 5 s
Fan-out router	Mapping phone_number_id → tenant_id	Table de routage à tenir à jour
Message queue	Découplage et persistance	Idempotence via message_id
Worker tenant	Traitement métier	Isolation des credentials par tenant

Gestion des credentials et des tokens par tenant

Chaque WABA client génère son propre System User Token. Stocker ces tokens en clair dans une base de données est une erreur de sécurité courante. Les bonnes pratiques :

• Vault ou KMS : chiffrez chaque token avec une clé dérivée de l'identifiant tenant. AWS KMS, HashiCorp Vault ou GCP Secret Manager sont des options éprouvées.
• Rotation automatique : implémentez un job périodique qui renouvelle les tokens avant leur expiration et notifie l'équipe en cas d'échec.
• Scope minimal : un System User dédié par WABA avec uniquement les permissions nécessaires (envoi de messages, gestion de templates) réduit la surface d'attaque.

Pour les aspects de sécurité liés à l'intégration API elle-même (validation des webhooks, rate limiting), l'article Sécuriser son intégration API WhatsApp détaille les contrôles à implémenter.

Isolation des données et conformité RGPD

En architecture multi-tenant, la séparation des données clients est une obligation légale en Europe. Les données de conversation WhatsApp (numéros de téléphone, contenus, métadonnées) sont des données personnelles au sens du RGPD.

Trois niveaux d'isolation possibles :

• Isolation logique : tous les tenants dans la même base de données, séparés par un tenant_id. Simple à opérer, acceptable si le contrôle d'accès applicatif est rigoureux.
• Isolation par schéma (PostgreSQL) : un schéma par tenant dans la même instance. Bon compromis entre isolation et coût d'infrastructure.
• Isolation par base de données : une instance dédiée par tenant. Maximum d'isolation, coût élevé, réservé aux grands comptes avec SLA de conformité très strict.

Whakup héberge son infrastructure en Europe, ce qui simplifie la conformité RGPD pour les éditeurs qui choisissent de s'appuyer sur la solution API WhatsApp Whakup en marque blanche plutôt que de construire cette couche eux-mêmes.

FAQ

Peut-on avoir plusieurs numéros WhatsApp pour un même tenant ?

Oui. Un WABA peut contenir plusieurs numéros de téléphone. C'est utile pour segmenter par marque, par pays ou par cas d'usage (support vs marketing). Chaque numéro a son propre phone_number_id, son propre quota de messagerie et son propre score qualité.

Comment gérer l'embedded signup pour onboarder automatiquement un nouveau tenant ?

L'embedded signup permet à un client de connecter son compte Meta Business directement depuis votre interface, sans quitter votre plateforme. Meta retourne un code d'autorisation que vous échangez contre un token WABA. Ce token est ensuite stocké dans votre vault. Le processus complet prend moins de 5 minutes côté client. Référez-vous au guide complet de l'API WhatsApp Business pour le détail du flux OAuth.

Quelle est la limite de numéros par WABA ?

Meta impose une limite par défaut de 20 numéros de téléphone par WABA. Cette limite peut être augmentée sur demande auprès de Meta, généralement via votre BSP ou Meta Tech Provider, en justifiant le volume et le cas d'usage.

Un tenant peut-il voir les messages des autres tenants en cas de bug ?

Si l'architecture est correctement conçue (routage par phone_number_id, isolation des credentials, contrôle d'accès applicatif), non. Le risque de fuite inter-tenant existe uniquement si le routage est mal implémenté ou si les tokens sont partagés entre tenants. C'est pourquoi l'isolation des credentials par tenant est non négociable.

---

Construire une architecture multi-tenant WhatsApp robuste demande de prendre les bons choix dès le départ : modèle WABA, routage des webhooks, isolation des credentials, conformité RGPD. Ces décisions structurelles sont difficiles à réviser une fois la plateforme en production. Pour éviter de repartir de zéro, des éditeurs choisissent de s'appuyer sur l'infrastructure Whakup — Multi-tenant natif, hébergement EU, marque blanche — via la solution API WhatsApp pour éditeurs et agences.