# Implémenter WaaConnect dans un projet (guide générique)

Guide pas-à-pas pour brancher l'API WaaConnect (WhatsApp multi-sessions, basé WhatsApp Web) dans n'importe quel projet backend. Réutilisable tel quel, sans dépendance à un framework particulier.

## Étape 0 — Prérequis

- Compte sur [app.waaconnect.com](https://app.waaconnect.com)
- Une clé API (`x-api-key`), disponible dans le dashboard
- Un numéro WhatsApp dédié (pas ton numéro perso si usage en prod — WhatsApp peut bannir les numéros utilisés pour de l'automatisation non-officielle)

## Étape 1 — Créer une session

Une session = une connexion WhatsApp. Il en faut au moins une avant de pouvoir envoyer quoi que ce soit.

```bash
curl -X POST https://api.waaconnect.com/v1/sessions \
  -H "x-api-key: wac_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Nom de ta session"}'
```

Réponse : un objet avec `id` (le `sessionId` UUID à garder — c'est lui qu'on utilisera dans toutes les routes suivantes) et `status: "DISCONNECTED"`.

## Étape 2 — Connecter la session (scanner le QR)

```bash
# Lancer la connexion
curl -X POST https://api.waaconnect.com/v1/sessions/{sessionId}/connect \
  -H "x-api-key: wac_xxxxxxxxxxxxxxxx"

# Récupérer le QR code (image base64)
curl https://api.waaconnect.com/v1/sessions/{sessionId}/qrcode \
  -H "x-api-key: wac_xxxxxxxxxxxxxxxx"
```

Affiche le `qrCode` (data URI base64) quelque part et scanne-le avec l'appli WhatsApp du numéro dédié (Réglages → Appareils liés). Alternative sans QR : `POST /sessions/{sessionId}/pairing-code` avec `{"phoneNumber": "22997000000"}`, qui génère un code à 8 chiffres à entrer manuellement dans WhatsApp.

Vérifie la connexion :

```bash
curl https://api.waaconnect.com/v1/sessions/{sessionId}/status \
  -H "x-api-key: wac_xxxxxxxxxxxxxxxx"
```

Attendre `"status": "CONNECTED"` avant de passer à l'étape suivante. Le champ `phone` retourné (ex. `22997000000@s.whatsapp.net`) confirme le numéro réellement lié.

## Étape 3 — Stocker les identifiants côté serveur

Ne jamais coder la clé API ou le `sessionId` en dur dans le code source. Les mettre en variables d'environnement (ou équivalent secret manager) :

```
WAACONNECT_API_KEY=wac_xxxxxxxxxxxxxxxx
WAACONNECT_SESSION_ID=<uuid-de-l-etape-1>
```

## Étape 4 — Écrire la fonction d'envoi

Point d'entrée unique à réutiliser partout dans le projet plutôt que de dupliquer des appels HTTP :

```bash
curl -X POST https://api.waaconnect.com/v1/sessions/{sessionId}/send \
  -H "x-api-key: wac_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"to": "22997000000", "message": "Texte du message"}'
```

- `to` : numéro sans `+` (ou JID complet `numero@s.whatsapp.net`)
- Réponse succès : `{ "ok": true, "id": "uuid-message" }`
- En cas d'échec réseau/auth : HTTP 401 (clé invalide), 403 (session pas à toi), 404 (session introuvable), 400 (corps invalide)

Pseudo-code d'un wrapper (à adapter au langage du projet) :

```
fonction envoyerWhatsapp(destinataire, texte):
    reponse = POST https://api.waaconnect.com/v1/sessions/{SESSION_ID}/send
              headers: x-api-key = API_KEY
              body: { to: destinataire, message: texte }
    si reponse.ok == false ou erreur HTTP:
        logger l'erreur, ne pas supposer que le message est parti
    retourner reponse
```

## Étape 5 — Endpoints utiles selon le besoin

| Besoin | Route |
|---|---|
| Envoi simple | `POST /v1/sessions/:sessionId/send` |
| Média (image/vidéo/audio/document) | `POST /v1/sessions/:sessionId/send-media` |
| Message avec boutons / liste | `POST /v1/sessions/:sessionId/send-interactive` |
| Document / contact / localisation | `POST /v1/sessions/:sessionId/messages/rich` |
| Envoi en masse personnalisé (`{name}`) | `POST /v1/sessions/:sessionId/messages/campaign` |
| Programmé (persiste au redémarrage) | `POST /v1/sessions/:sessionId/messages/schedule` |
| Récurrent (⚠️ non persistant, voir plus bas) | `POST /v1/sessions/:sessionId/messages/recurring` |
| Historique des envois | `GET /v1/sessions/:sessionId/messages?status=SENT` |
| Messages reçus | `GET /v1/sessions/:sessionId/incoming?waitMs=5000` |

## Étape 6 — Tester avant de brancher sur un vrai flux applicatif

Avant de connecter WaaConnect à une fonctionnalité réelle (OTP, notifications...), envoyer un message de test manuel vers un numéro que tu contrôles et vérifier :
1. Le message arrive vraiment sur le téléphone (pas juste `ok:true` dans la réponse API).
2. Le statut dans l'historique (`GET .../messages`) passe bien à `SENT`.

## Pièges à connaître avant la mise en prod

**`ok:true` ne veut pas dire livré.** WaaConnect ne vérifie pas que le JID cible existe réellement sur WhatsApp avant d'accepter l'envoi. Un numéro mal formaté peut retourner un succès API et un statut `SENT` en historique sans jamais être livré, sans erreur explicite. Si un utilisateur signale ne rien recevoir :
1. Vérifier `GET /v1/sessions/:sessionId/status` → `CONNECTED` ?
2. Comparer le `phone` de la session avec le numéro ciblé — un décalage de format (indicatif, préfixe local ajouté/retiré selon le pays) est la cause la plus fréquente.
3. Si un autre fournisseur qui valide les JID (ex. API Cloud officielle Meta) rejette le même numéro avec une erreur explicite, c'est le signe fiable d'un problème de format plutôt que de session.

**Récurrence en mémoire.** `messages/recurring` utilise un `setInterval` process — perdu au redémarrage, non annulable via l'API. Préférer un scheduler externe qui appelle `messages/schedule` à intervalles réguliers (celui-ci est backé par une queue persistante).

**Numéro dédié.** Utiliser un numéro d'automatisation dédié, pas un numéro personnel — WhatsApp peut restreindre/bannir un numéro qui envoie beaucoup de messages automatisés hors de l'API Cloud officielle.