📱 WhatsApp Cloud API

WhatsApp est connecté via l'API Cloud de Meta — l'API officielle, disponible en niveau gratuit, qui vous permet d'envoyer et recevoir des messages WhatsApp depuis votre propre serveur. Aucun BSP (Business Solution Provider) tiers n'est requis.

---

Prérequis

1. Un compte développeur Meta sur developers.facebook.com
2. Un compte Meta Business (alias Business Manager)
3. Un numéro de téléphone pour WhatsApp qui n'est pas déjà enregistré sur WhatsApp personnel (vous pouvez utiliser une SIM, un numéro virtuel ou un fixe)

---

Étapes de Configuration

1. Créer une App Meta

1. Allez sur developers.facebook.com/apps
2. Cliquez sur Create App
3. Choisissez le type Business
4. Remplissez un nom et connectez votre compte Business

2. Ajouter le Produit WhatsApp

1. Dans le tableau de bord de votre app, faites défiler jusqu'à Add Products to Your App
2. Cliquez sur Set Up sur WhatsApp
3. Sélectionnez votre compte Business

3. Obtenir Vos Identifiants

Naviguez vers WhatsApp → API Setup dans le tableau de bord de votre app :

Identifiant	Où le Trouver
Phone Number ID	Listé dans la section « From » — un ID numérique comme 123456789012345
Access Token	Le token temporaire affiché sur cette page. Pour la production, générez un token permanent via System Users.
App Secret	Tableau de bord de l'App → Settings → Basic → App Secret
Verify Token	Une chaîne que vous inventez — n'importe quelle chaîne aléatoire, ex. my_secret_verify_token_2024

4. Ajouter le Canal dans PulseHub

1. Allez dans Canaux → Ajouter un Canal
2. Sélectionnez WhatsApp
3. Remplissez les quatre champs
4. Cliquez sur Enregistrer le Canal
5. Copiez l'URL Webhook affichée sur la carte du canal

5. Configurer le Webhook dans Meta

1. Dans votre app Meta, allez dans WhatsApp → Configuration
2. Cliquez sur Edit à côté de la section Webhook
3. Callback URL : collez votre URL webhook PulseHub
4. Verify Token : entrez la même chaîne que dans PulseHub
5. Cliquez sur Verify and Save

Meta fera une requête GET vers votre URL webhook avec ?hub.mode=subscribe&hub.verify_token=...&hub.challenge=.... PulseHub vérifie le token et renvoie le challenge.

6. Sous Webhook Fields, abonnez-vous à : messages

6. Tester

Envoyez un message WhatsApp à votre numéro professionnel. Il devrait apparaître comme nouvelle conversation dans la boîte PulseHub en quelques secondes.

---

Vérification de Signature

Meta inclut un en-tête X-Hub-Signature-256 sur chaque webhook :

X-Hub-Signature-256: sha256=abc123...

PulseHub le vérifie en utilisant HMAC-SHA256 avec votre App Secret. Si la vérification échoue, le webhook retourne 401 Signature mismatch.

---

Envoi de Messages

Quand un agent envoie une réponse depuis la boîte de réception, PulseHub appelle l'API WhatsApp Cloud :

POST https://graph.facebook.com/v18.0/{phone_number_id}/messages
Authorization: Bearer {access_token}
{
  "messaging_product": "whatsapp",
  "to": "{recipient_phone}",
  "type": "text",
  "text": {"body": "Votre réponse ici"}
}

---

Accès Production

L'app Meta par défaut est en mode Development — elle ne peut envoyer des messages qu'aux numéros ajoutés comme numéros de test. Pour passer en production :

1. Complétez la Vérification Business dans Meta Business Manager
2. Soumettez votre cas d'utilisation WhatsApp pour la revue de Meta
3. Une fois approuvé, votre app obtient l'accès pour envoyer des messages à tous les utilisateurs WhatsApp

---

Problèmes Courants

Symptôme	Cause Probable
La vérification échoue lors de la configuration du webhook	Le verify_token dans PulseHub ne correspond pas à ce que vous avez entré dans Meta
Erreur de signature non correspondante dans les logs	app_secret incorrect — copiez-le depuis App Settings → Basic, pas depuis API Setup
Les messages n'arrivent pas	Le champ webhook messages n'est pas abonné dans le tableau de bord Meta
Invalid phone number lors de l'envoi	Le format du numéro doit être E.164 sans + (ex. 15551234567)
Erreur d'app en mode Development	Seuls les numéros de test vérifiés peuvent recevoir des messages en mode dev