# Connecter un compte WhatsApp

> Faites connecter à vos clients leur compte WhatsApp Business par l'inscription intégrée de Meta, puis finalisez la connexion par l'API.

Chacun de vos clients possède son propre compte WhatsApp Business. Vous le connectez à votre application en deux temps : le client **autorise la connexion chez Meta** (dans le navigateur), puis **votre serveur finalise** par l'API.

<Callout type="warning" title="Statut du service">
La finalisation par l'API décrite ci-dessous est en place. Elle a été vérifiée sur des réponses simulées de Meta ; sa **validation contre la plateforme Meta réelle est en cours**. Le bouton d'inscription prêt à l'emploi (qui lance l'inscription intégrée avec l'application Meta de Bref Point) est en cours d'intégration dans la console.
</Callout>

## Le parcours

```text
1. Votre serveur       POST /connected-businesses        → crée l'entreprise de votre client
2. Le navigateur       Inscription intégrée de Meta       → le client autorise, Meta renvoie un code,
                                                            l'identifiant du compte WhatsApp et celui du numéro
3. Votre serveur       POST …/waba-connections            → échange le code, abonne les événements, lit le numéro
4. Votre serveur       GET …/phone-numbers                → vérifie : numéro, nom vérifié, qualité
```

<Steps>

### Créez l'entreprise de votre client

<ApiExample method="POST" path="/connected-businesses" />

`externalRef` est votre propre identifiant de ce client : il doit être unique dans l'environnement et vous permet de retrouver l'entreprise plus tard.

### Le client termine l'inscription chez Meta

Dans le navigateur, votre client se connecte à Meta, choisit ou crée son compte WhatsApp Business et son numéro. À la fin, Meta fournit à votre page trois valeurs :

| Valeur | À quoi elle sert |
|---|---|
| `code` | Échangé par nos serveurs contre le jeton d'accès du client. **À usage unique et de courte durée** : transmettez-le immédiatement. |
| `wabaId` | Identifiant du compte WhatsApp Business (chiffres uniquement). |
| `phoneNumberId` | Identifiant Meta du numéro (chiffres uniquement). |

### Finalisez par l'API

<ApiExample method="POST" path="/connected-businesses/{businessId}/waba-connections" />

Nous échangeons le code contre un jeton, abonnons l'application aux événements du compte, lisons les informations du numéro et enregistrons le tout. La réponse donne l'`id` de la connexion et celui du **numéro** (`phoneNumber.id`) : c'est cet identifiant que vous utiliserez pour envoyer des messages.

### Vérifiez

<ApiExample method="GET" path="/connected-businesses/{businessId}/phone-numbers" />

`qualityRating` est la note de qualité du numéro chez Meta (`GREEN`, `YELLOW`, `RED`) : surveillez-la, une mauvaise qualité réduit vos capacités d'envoi.

</Steps>

## Le mode coexistence

Avec `"mode": "coexistence"`, votre client **continue d'utiliser l'application WhatsApp Business sur son téléphone** pendant que votre logiciel utilise l'API sur le même numéro. Les messages qu'il envoie depuis son téléphone arrivent chez vous comme les autres. Sans ce mode (`cloud_api`, par défaut), le numéro n'est utilisable que par l'API.

## Plusieurs numéros pour une même entreprise

Une entreprise peut avoir plusieurs comptes WhatsApp, et un compte plusieurs numéros. Pour **ajouter un numéro**, refaites l'inscription et appelez de nouveau `POST …/waba-connections` avec le même `wabaId` et le nouveau `phoneNumberId` : le compte est reconnu, son jeton rafraîchi et le numéro ajouté, sans doublon. Reconnecter un numéro **déjà connecté** n'en ajoute pas et ne compte pas dans la limite.

En production, votre plan limite les numéros **par entreprise** (1 en Gratuit, 2 en Starter, 3 en Growth, 5 en Scale). Le sandbox n'a pas de limite.

## Ce qui est garanti

- **Le jeton Meta de votre client n'est jamais renvoyé** par l'API, même chiffré. Il est stocké chiffré, lié à votre compte et à cette connexion.
- **Un compte WhatsApp ne peut être connecté qu'une fois sur toute la plateforme.** S'il l'est déjà ailleurs, vous obtenez `409 conflict`. Cela empêche qu'un tiers détourne les messages d'un autre.
- **Reconnecter le même compte** (jeton expiré, nouvelle autorisation) est possible : le jeton est remplacé, sans doublon de numéro.
- Une entreprise ne voit que **son** environnement : un compte connecté en sandbox n'existe pas en production.

## Erreurs fréquentes

| Erreur | Cause probable |
|---|---|
| `400 validation_error` | `wabaId` ou `phoneNumberId` contient autre chose que des chiffres |
| `404 not_found` | L'entreprise n'existe pas, ou appartient à un autre environnement que celui de la clé |
| `409 conflict` | Ce compte WhatsApp est déjà connecté (à une autre entreprise ou à un autre compte) |
| `402 plan_limit_reached` | Le plan de votre compte n'autorise pas plus d'entreprises connectées en production, **ou plus de numéros pour cette entreprise**. Le refus intervient **avant** l'échange du code d'inscription : le code n'est pas consommé |
| `502 meta_error` | Meta a refusé la requête : le plus souvent, le `code` a expiré ou a déjà servi. Faites refaire l'inscription au client |