> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ouraicalling.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Inscription intégrée WhatsApp (fournisseur technologique Meta)

> Configurez votre application Meta et connectez WhatsApp dans Paramètres → Canaux → WhatsApp

L'intégration WhatsApp dans le produit repose sur **Meta Embedded Signup v4** (fournisseur technologique). Les utilisateurs cliquent sur **Connect with Meta**, complètent la fenêtre Meta (connexion, WABA, vérification du numéro), puis nous finalisons l'intégration côté serveur (échange de jeton, webhooks, enregistrement du numéro).

Le collage manuel des identifiants reste disponible en solution de repli. Le fonctionnement ne change pas : API Cloud pour le texte, connecteur vocal WhatsApp de la plateforme pour les appels.

<Note>
  L'inscription intégrée v2 sera obsolète à compter du **15 octobre 2026**. Utilisez uniquement les configurations v4.
</Note>

## Architecture

| Couche                 | Stack                                                                                   |
| ---------------------- | --------------------------------------------------------------------------------------- |
| Intégration            | Inscription intégrée Meta (Connexion Facebook pour les entreprises)                     |
| Texte                  | API Cloud Meta                                                                          |
| Voix                   | Connecteur vocal WhatsApp de la plateforme                                              |
| Numéros du marketplace | Marketplace E.164 + OTP Meta (assistant de capture SMS)                                 |
| Facturation (Meta)     | Le client ajoute un moyen de paiement dans WhatsApp Manager (fournisseur technologique) |

Les assistants SMS de la plateforme sont **SMS/MMS uniquement** — pas WhatsApp. La voix par Trunk SIP sur un numéro marketplace est indépendante de l'API Cloud WhatsApp et des webhooks SMS.

## Prérequis (plateforme)

1. Portefeuille Meta Business avec **vérification d'entreprise** et **2FA**
2. Nouvelle application Meta de type **Business** (ne réutilisez pas une ancienne application)
3. Produits : **WhatsApp**, **Connexion Facebook pour les entreprises**, **Webhooks**
4. Accès avancé App Review : `whatsapp_business_management`, `whatsapp_business_messaging`
5. Fournisseur technologique / Vérification d'accès (fait passer la limite hebdomadaire d'intégration de 10 à 200)

## Liste de contrôle du tableau de bord de l'application Meta

### 1. Créer l'application

1. Allez sur [developers.facebook.com](https://developers.facebook.com) → **Créer une application** → sélectionnez le type **Business**
2. Ne mettez **pas** « WhatsApp » dans le nom de l'application (règles de marque de Meta)
3. Associez votre portefeuille Business vérifié

### 2. Connexion Facebook pour les entreprises

1. Ouvrez **Connexion Facebook pour les entreprises → Paramètres → Paramètres OAuth du client**
2. Activez : connexion OAuth du client, connexion OAuth Web, HTTPS obligatoire, connexion OAuth via navigateur intégré, mode strict, connexion avec le SDK JavaScript
3. **Domaines autorisés** et **URI de redirection OAuth valides** : votre domaine de production et vos domaines de prévisualisation (HTTPS uniquement), par exemple `https://app.famulor.io`

### 3. Configuration de l'inscription intégrée

1. **Connexion Facebook pour les entreprises → Configurations → Créer à partir d'un modèle**
2. Choisissez **WhatsApp Embedded Signup Configuration With 60 Expiration Token**
3. Copiez l'**ID de configuration** → `META_EMBEDDED_SIGNUP_CONFIG_ID` / `NEXT_PUBLIC_META_EMBEDDED_SIGNUP_CONFIG_ID`

### 4. Webhooks de l'application (callback de la plateforme)

1. **WhatsApp → Configuration → Webhook**
2. URL de callback : `https://app.famulor.io/api/webhooks/meta/whatsapp-platform`
3. Jeton de vérification : même valeur que `META_WEBHOOK_VERIFY_TOKEN`
4. Abonnez-vous au minimum à : `account_update`, `messages`, `calls`, `message_template_status_update`

Après l'inscription intégrée, nous configurons également un **remplacement de webhook par WABA** vers `/api/webhooks/messaging/whatsapp/{connectorId}` afin que le routage multi-tenant corresponde au reste des canaux de messagerie. Les champs qui ne prennent pas en charge ce remplacement (par exemple certains événements de compte ou de modèle) restent sur le callback de la plateforme.

### 5. Variables d'environnement

```bash theme={null}
META_EMBEDDED_SIGNUP_ENABLED=true
META_APP_ID=...
NEXT_PUBLIC_META_APP_ID=...          # identique à META_APP_ID
META_APP_SECRET=...
META_EMBEDDED_SIGNUP_CONFIG_ID=...
NEXT_PUBLIC_META_EMBEDDED_SIGNUP_CONFIG_ID=...
META_GRAPH_API_VERSION=v25.0
META_WEBHOOK_VERIFY_TOKEN=...
```

Également requis pour la messagerie/voix (opérateur) : clé de chiffrement des identifiants, **URL de base de l'application** de la plateforme (origine publique utilisée pour les webhooks), identifiants vocaux de la plateforme, identifiants IA de la plateforme, et authentification cron pour la synchronisation des modèles.

### 6. App Review et mode Live

* Tant que l'application est en mode Development, seuls les admins, développeurs et testeurs peuvent finaliser l'inscription intégrée
* Soumettez l'App Review pour les permissions WhatsApp, puis passez en mode Live
* Abonnez-vous à `account_update` avant d'intégrer de vrais clients

## UX produit (espace de travail)

**Paramètres → Canaux → WhatsApp**

1. Choisissez un assistant
2. Sélectionnez éventuellement un numéro marketplace (de préférence compatible SMS pour l'OTP Meta)
3. Si un numéro marketplace est sélectionné, nous redirigeons temporairement son webhook **SMS** vers notre endpoint de capture OTP (la voix téléphone/SIP reste inchangée) et affichons l'OTP de Meta dans l'interface
4. Cliquez sur **Connect with Meta** → complétez la fenêtre contextuelle
5. Côté serveur : échange du code → jeton business → abonnement WABA → remplacement du webhook → enregistrement du numéro → création du connecteur (`onboarding_source=embedded_signup`)
6. Demandez au client d'ajouter un **moyen de paiement** dans WhatsApp Manager avant tout envoi de messages à fort volume

## Numéros marketplace + OTP

| Type de numéro               | OTP Meta                     | Notre assistant                                                   |
| ---------------------------- | ---------------------------- | ----------------------------------------------------------------- |
| Marketplace avec SMS         | SMS envoyé au numéro         | La session OTP capture le SMS et affiche le code dans l'interface |
| Marketplace vocal uniquement | Appel vocal                  | Privilégiez les numéros compatibles SMS pour le MVP               |
| Carte SIM du client          | SMS/appel vers son téléphone | L'utilisateur saisit l'OTP dans la fenêtre contextuelle Meta      |

Acheter un numéro dans **Paramètres → Numéros** n'active jamais WhatsApp automatiquement.

## API publique

* `GET /api/whatsapp/embedded-signup/config` — IDs publics d'application/configuration + indicateur d'activation
* `POST /api/whatsapp/embedded-signup` — finalise l'intégration (`code`, `waba_id`, `phone_number_id`, `assistant_id`, …)
* `POST/GET/DELETE /api/whatsapp/otp-session` — cycle de vie de la capture OTP marketplace
* MCP : `complete_whatsapp_embedded_signup`

## Voir aussi

* [WhatsApp (Texte + Voix)](/channels/whatsapp)
* [Canaux de messagerie](/channels/messaging)
* [Voix WhatsApp](/telephony/whatsapp-voice)
* Meta : [Inscription intégrée](https://developers.facebook.com/docs/whatsapp/embedded-signup/) · [Intégration en tant que fournisseur technologique](https://developers.facebook.com/docs/whatsapp/embedded-signup/onboarding-customers-as-a-tech-provider)