Diagnostiquer Dolibarr : WhatsApp Étude de cas avec des exemples concrets

L’intégration de WhatsApp dans Dolibarr ERP/CRM est un levier puissant pour améliorer la relation client, automatiser les prospections et centraliser les communications. Cependant, comme toute intégration technique, elle peut rencontrer des dysfonctionnements. Cet article propose une méthodologie de diagnostic structurée, illustrée par des études de cas réels, pour résoudre les problèmes courants.

Méthodologie de diagnostic en 5 étapes

  1. Vérifier l’environnement technique : Version de Dolibarr (≥ 15.0 recommandée), module WhatsApp (module externe ou développé sur mesure) correctement installé et activé.

  2. Examiner les journaux (logs) : Fichiers de log Dolibarr (/documents/dolibarr.log), logs du serveur web (Apache/Nginx) et logs spécifiques du module.

  3. Tester l’API WhatsApp Business : Utiliser les outils de test de l’API Meta (Graph API Explorer) pour valider le jeton d’accès (access token) et les permissions.

  4. Analyser le flux de données : Vérifier les webhooks, la synchronisation des contacts et l’envoi des modèles de message (templates).

  5. Simuler le scénario utilisateur : Reproduire l’action qui échoue (ex: envoi d’un devis par WhatsApp) en mode debug.

Étude de cas n°1 : « Erreur d’authentification à l’API WhatsApp »

Contexte : Une PME de services utilise le module "Dolibarr WhatsApp Connector" pour notifier automatiquement ses clients lors de la création d’une facture. Depuis 48h, aucune notification n’est envoyée.

Symptômes :

  • Dans l’interface Dolibarr, le statut du module WhatsApp affiche "Non connecté".

  • Le journal Dolibarr contient l’erreur récurrente : [WhatsAppModule] API Error #190: Invalid OAuth access token.

  • Les clients reçoivent leurs factures par email, mais pas par WhatsApp.

Diagnostic et résolution :

  1. Vérification du jeton : L’administrateur se connecte au Meta Business Suite et constate que le jeton d’accès (Access Token) de l’application WhatsApp Business a expiré (durée de vie par défaut : 24h pour les jetons temporaires).

  2. Action corrective :

    • Générer un nouveau jeton à longue durée ( Long-Lived Access Token ) via le Graph API Explorer.

    • Mettre à jour la configuration du module Dolibarr avec ce nouveau jeton.

    • Vérification supplémentaire : S’assurer que l’application possède bien les permissions whatsapp_business_management, whatsapp_business_messaging et que le numéro de téléphone WhatsApp est bien associé au Business Manager.

  3. Résultat : La recharge des pages Dolibarr fait passer le statut à "Connecté". Les notifications par WhatsApp reprennent immédiatement.

Enseignement : La gestion cyclique des jetons (renouvellement automatique via un script cron si possible) est critique. Un monitoring simple (alerte email si le statut du module devient "Non connecté") peut éviter des jours de rupture.

Étude de cas n°2 : « Échec d’envoi d’un message template »

Contexte : Une boutique e-commerce utilise Dolibarr pour gérer ses commandes. Elle a créé un template WhatsApp approuvé par Meta : "Bonjour {1}, votre commande #{2} est prête pour retrait." Lorsque le statut d’une commande passe à "Prêt", Dolibarr doit envoyer ce message.

Symptômes :

  • La commande est marquée "Prêt" dans Dolibarr.

  • Aucune notification WhatsApp n’est reçue par le client.

  • Le log Dolibarr indique : [WhatsAppModule] Failed to send template message. Error Code: 100 - Missing required parameter: components.

Diagnostic et résolution :

  1. Examen du code d’erreur : L’erreur Meta "100" est générique. Elle indique souvent un problème de format dans le corps de la requête JSON envoyée à l’API.

  2. Analyse du payload : En activant le mode debug du module, on capture la requête JSON sortante. On y découvre : 
    {
    
  "messaging_product": "whatsapp",
    
  "to": "33123456789",
    
  "type": "template",
    
  "template": {
    
    "name": "order_ready_fr",
    
    "language": { "code": "fr_FR" }
    
    // Composants manquants !
    
  }
    
}

  3. Action corrective : La structure de l’API exige un objet components pour passer les paramètres {1} et {2}. Le module Dolibarr utilisé (version 1.2) avait un bug connu dans sa fonction de formattage des variables.

    • Solution temporaire : Mettre à jour le module vers la version 1.3 (correctif inclus).

    • Solution de contournement : Si la mise à jour n’est pas immédiate, modifier manuellement le code du module (fichier whatsapp.class.php) pour s’assurer que le tableau $components est bien construit et inclus dans l’objet template.

  4. Résultat : Après correctif, le message est envoyé avec succès : "Bonjour Marie Dupont, votre commande #COMM-2023-456 est prête pour retrait."

Enseignement : Les templates WhatsApp sont très structurés. Toute modification de leur nom, de leur langue ou de leur nombre de paramètres dans l’interface Meta doit être synchronisée avec les paramètres de variables dans la logique métier de Dolibarr.

Étude de cas n°3 : « Décalage des contacts etmessages non liés aux fiches clients »

Contexte : Un cabinet de conseil utilise Dolibarr pour gérer ses prospects (table llx_societe). Les commerciaux envoient des WhatsApp manuels depuis l’interface Dolibarr. Le problème : les messages envoyés depuis Dolibarr n’apparaissent pas dans l’historique decommunication du bon prospect.

Symptômes :

  • Un commercial clique sur "Envoyer un WhatsApp" sur la fiche de la société "TechSolutions SAS".

  • Le message est bien envoyé depuis le numéro de l’entreprise.

  • Mais dans l’onglet "Communications" de la société "TechSolutions SAS", le message n’est pas enregistré. Il apparaît parfois dans une autre fiche société.

Diagnostic et résolution :

  1. Logique de liaison : Le module cherche-t-il à lier le message WhatsApp à un contact (llx_contact) ou à une société (llx_societe) ? Ici, l’utilisation est faite au niveau société.

  2. Investigation des données : Le numéro de WhatsApp du client (+33 6 12 34 56 78) est-il présent et unique dans le système ?

    • Requête SQL : SELECT rowid, nom, telephone FROM llx_societe WHERE telephone LIKE '%612345678%';

    • Résultat : Le numéro existe dans DEUX fiches sociétés : "TechSolutions SAS" (téléphone: 0612345678) et "TechSolutions SARL" (téléphone: +33612345678). Le module a fait une correspondance partielle et a lié le message à la première entrée trouvée.

  3. Action corrective :

    • Nettoyage des données : Vérifier et uniformiser les numéros de téléphone (format international recommandé : +33612345678). Supprimer ou fusionner les doublons.

    • Amélioration de l’algorithme de matching : Configurer le module pour qu’il effectue une recherche exacte (après normalisation : suppression des espaces, +, 0 initial) et qu’il priorise la correspondance sur le contact principal de la société plutôt que sur tous les champs téléphone.

  4. Résultat : Après nettoyage et paramétrage, chaque message est correctement archivé dans l’historique de la société concernée.

Enseignement : La qualité des données (propreté, unicité, format) dans Dolibarr est le facteur #1 de succès ou d’échec d’une intégration de communication. Un script de déduplication des numéros de téléphone est un investissement précieux.

Bonnes pratiques pour prévenir les diagnostics

  1. Journalisation détaillée : Activer les logs niveau DEBUG pour le module WhatsApp lors des phases de test.

  2. Environnement de test : Toujours tester avec un numéro de téléphone de test WhatsApp Meta et un jeu de données Dolibarr clones avant toute mise en production.

  3. Documentation des paramètres : Tenir un registre (document ou tableaux) de tous les paramètres de configuration : Token, ID de numéro WhatsApp, noms des templates, variables associées.

  4. Surveillance proactive : Mettre en place un监控 (monitoring) simple qui alerte par email si :

    • Le statut de santé de l’API WhatsApp (via un appel GET /v13.0/<PHONE_NUMBER_ID>) échoue.

    • Aucun message WhatsApp n’a été envoyé depuis Dolibarr depuis plus de 48h alors que l’activité commerciale est normale.

  5. Mise à jour prudente : Avant de mettre à jour le module WhatsApp ou Dolibarr, vérifier la compatibilité et sauvegarder la base de données et le répertoire des documents.

Conclusion

Diagnostiquer une intégration Dolibarr-WhatsApp est un exercice qui demande une approche méthodique, combinant compréhension du schéma API de Meta, connaissance de la logique métier de Dolibarr et rigueur dans l’analyse des données. Les trois études de cas ci-dessus illustrent que les racines des problèmes se trouvent souvent dans :

  1. La gestion des authentifiants (jetons expirés).

  2. Le formatage des données (structures JSON, paramètres de templates).

  3. La qualité et l’unicité des données sources dans Dolibarr (numéros de téléphone).

En formalisant ce processus de diagnostic et en appliquant les bonnes pratiques, les entreprises peuvent transformercette intégration puissante en un canal de communication fiable et performant, au service de leur expérience client.

Note : Les noms de modules, numéros de version et exemples de code sont donnés à titre indicatif. Les implementations peuvent varier selon le module Dolibarr-WhatsConnect utilisé (module communautaire, développement spécifique). Consultez toujours la documentation de votre module et les API officielles de Meta.

Publications similaires