Logs et monitoring WhatsApp API : tracer les échanges et détecter les anomalies

Imaginez que votre système de notifications WhatsApp cesse silencieusement de fonctionner un vendredi soir, pendant une promotion cruciale au Cameroun. Aucune alerte, aucun log exploitable, des milliers de messages perdus. Le lundi matin, des clients en colère inondent votre service client. Ce scénario n'est pas hypothétique — c'est ce qui arrive quand une intégration API est déployée sans stratégie de logs et monitoring. En Afrique, où la confiance client se construit difficilement et se perd rapidement, la fiabilité de vos communications WhatsApp est un actif business critique.

Ce qu'il faut logger absolument

Un bon système de logs pour une intégration WhatsApp doit capturer trois catégories d'informations : les requêtes sortantes (messages envoyés), les événements entrants (webhooks reçus) et les erreurs (avec contexte complet).

Pour chaque message envoyé, loggez au minimum :

• L'identifiant unique du message retourné par l'API (wamid)
• Le numéro destinataire (hashé ou tronqué pour la conformité RGPD/lois locales)
• Le type de message (text, template, image, etc.)
• Le nom du template si applicable
• Le statut de l'envoi (succès/erreur)
• Le code d'erreur si erreur
• L'horodatage précis (UTC)
• L'identifiant de la campagne ou de la session si applicable

// Logger structuré pour les messages sortants
const winston = require('winston');

const logger = winston.createLogger({
    level: 'info',
    format: winston.format.combine(
        winston.format.timestamp(),
        winston.format.json()
    ),
    transports: [
        new winston.transports.File({ filename: 'whatsapp-error.log', level: 'error' }),
        new winston.transports.File({ filename: 'whatsapp-combined.log' }),
        new winston.transports.Console({ format: winston.format.simple() })
    ]
});

async function sendMessageWithLogging(to, payload, metadata = {}) {
    const startTime = Date.now();
    const phoneHash = hashPhone(to); // Ne pas logger le numéro en clair
    
    logger.info('message_send_attempt', {
        phone_hash: phoneHash,
        type: payload.type,
        template: payload.template?.name || null,
        campaign_id: metadata.campaignId,
        session_id: metadata.sessionId
    });
    
    try {
        const response = await axios.post(API_URL, payload, { headers: HEADERS });
        const duration = Date.now() - startTime;
        
        logger.info('message_sent_success', {
            phone_hash: phoneHash,
            message_id: response.data.messages?.[0]?.id,
            type: payload.type,
            duration_ms: duration,
            campaign_id: metadata.campaignId
        });
        
        return response.data;
        
    } catch (error) {
        const duration = Date.now() - startTime;
        const apiError = error.response?.data?.error || {};
        
        logger.error('message_send_failed', {
            phone_hash: phoneHash,
            error_code: apiError.code,
            error_message: apiError.message,
            error_subcode: apiError.error_subcode,
            fbtrace_id: apiError.fbtrace_id,
            http_status: error.response?.status,
            duration_ms: duration,
            campaign_id: metadata.campaignId
        });
        
        throw error;
    }
}

function hashPhone(phone) {
    const crypto = require('crypto');
    return crypto.createHash('sha256').update(phone).digest('hex').substring(0, 12);
}

Tracking des statuts de livraison

Les webhooks de statut (sent, delivered, read, failed) fournissent des données précieuses pour analyser la qualité de vos communications. Stocker ces événements en base de données vous permet de calculer des KPIs en temps réel :

// Schema de base de données pour le tracking
/*
CREATE TABLE message_events (
    id BIGSERIAL PRIMARY KEY,
    message_id VARCHAR(255) NOT NULL,
    event_type VARCHAR(50) NOT NULL, -- sent, delivered, read, failed
    phone_hash VARCHAR(50),
    campaign_id VARCHAR(100),
    template_name VARCHAR(100),
    error_code INTEGER,
    error_message TEXT,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    INDEX idx_message_id (message_id),
    INDEX idx_campaign_id (campaign_id),
    INDEX idx_created_at (created_at)
);
*/

async function trackDeliveryStatus(statusEvent) {
    const { id, status, timestamp, recipient_id, errors } = statusEvent;
    
    await db.query(
        `INSERT INTO message_events 
         (message_id, event_type, phone_hash, error_code, error_message, created_at)
         VALUES ($1, $2, $3, $4, $5, to_timestamp($6))
         ON CONFLICT (message_id, event_type) DO NOTHING`,
        [
            id,
            status,
            hashPhone(recipient_id),
            errors?.[0]?.code || null,
            errors?.[0]?.title || null,
            parseInt(timestamp)
        ]
    );
}

// Calculer les KPIs d'une campagne
async function getCampaignStats(campaignId) {
    const stats = await db.query(`
        SELECT 
            COUNT(*) FILTER (WHERE event_type = 'sent') as sent,
            COUNT(*) FILTER (WHERE event_type = 'delivered') as delivered,
            COUNT(*) FILTER (WHERE event_type = 'read') as read,
            COUNT(*) FILTER (WHERE event_type = 'failed') as failed,
            ROUND(
                COUNT(*) FILTER (WHERE event_type = 'delivered')::numeric / 
                NULLIF(COUNT(*) FILTER (WHERE event_type = 'sent'), 0) * 100, 2
            ) as delivery_rate,
            ROUND(
                COUNT(*) FILTER (WHERE event_type = 'read')::numeric / 
                NULLIF(COUNT(*) FILTER (WHERE event_type = 'delivered'), 0) * 100, 2
            ) as read_rate
        FROM message_events
        WHERE campaign_id = $1
    `, [campaignId]);
    
    return stats.rows[0];
}

Alertes et détection d'anomalies

Monitorer en temps réel permet de détecter les problèmes avant qu'ils ne deviennent critiques. Voici les anomalies les plus importantes à détecter :

Taux d'erreur élevé : si plus de 5% de vos messages échouent sur une fenêtre de 5 minutes, déclenchez une alerte immédiate.

Augmentation des blocages : un pic d'erreurs 131031 (client a bloqué) indique que votre quality rating risque de baisser.

Latence API anormale : si le temps de réponse de l'API dépasse 5 secondes de manière répétée, Meta rencontre peut-être des problèmes.

class WhatsAppHealthMonitor {
    constructor() {
        this.windows = {
            '5min': { errors: 0, total: 0, start: Date.now() },
            '1hour': { errors: 0, total: 0, start: Date.now() }
        };
        this.thresholds = {
            errorRate5min: 0.05,   // 5% d'erreurs sur 5 min
            errorRate1hour: 0.02,  // 2% d'erreurs sur 1h
            blockRate: 0.01        // 1% de blocages = alerte urgente
        };
    }
    
    record(success, errorCode = null) {
        const now = Date.now();
        
        // Réinitialiser les fenêtres si expirées
        if (now - this.windows['5min'].start > 5 * 60 * 1000) {
            this.windows['5min'] = { errors: 0, total: 0, start: now };
        }
        if (now - this.windows['1hour'].start > 60 * 60 * 1000) {
            this.windows['1hour'] = { errors: 0, total: 0, start: now };
        }
        
        for (const window of Object.values(this.windows)) {
            window.total++;
            if (!success) window.errors++;
        }
        
        this.checkThresholds(errorCode);
    }
    
    checkThresholds(errorCode) {
        const rate5min = this.windows['5min'].errors / this.windows['5min'].total;
        const rate1hour = this.windows['1hour'].errors / this.windows['1hour'].total;
        
        if (rate5min > this.thresholds.errorRate5min && this.windows['5min'].total > 10) {
            this.alert('HIGH_ERROR_RATE_5MIN', `${(rate5min * 100).toFixed(1)}% d'erreurs sur 5 min`);
        }
        
        if (errorCode === 131031) {
            this.alert('USER_BLOCK_DETECTED', 'Un utilisateur a bloqué votre numéro');
        }
        
        if (errorCode === 131048) {
            this.alert('SPAM_RATE_LIMIT', 'Limite anti-spam atteinte — risque de restriction');
        }
    }
    
    alert(type, message) {
        logger.error('HEALTH_ALERT', { type, message, timestamp: new Date().toISOString() });
        // Envoyer une alerte email/Slack/SMS à l'équipe tech
        sendAlertToTeam(type, message);
    }
}

const healthMonitor = new WhatsAppHealthMonitor();

Outils de monitoring recommandés

Pour une stack de monitoring complète en production, plusieurs options s'adaptent à différents budgets :

Datadog ou New Relic : solutions enterprise avec dashboards prêts à l'emploi, alertes intelligentes et intégration avec les principaux cloud providers. Coût élevé mais ROI rapide pour les équipes avec des volumes importants.

Grafana + Prometheus : stack open-source puissante, hébergeable localement ou sur un VPS. Idéale pour les équipes techniques africaines qui préfèrent maîtriser leur infrastructure.

Sentry : excellent pour le tracking d'erreurs avec contexte complet. Version gratuite généreuse, s'intègre facilement à Node.js, Python et PHP.

Simple logging vers une base de données + cron de vérification : pour les petites équipes avec budget limité, stocker les logs en MySQL/PostgreSQL et avoir un script cron qui envoie un rapport quotidien par email reste une solution viable.

Combinez ces outils de monitoring avec les métriques business disponibles dans le tableau de bord WhatsApp Business API et votre propre calcul de ROI WhatsApp marketing.

FAQ

Q: Doit-on logger les contenus des messages WhatsApp pour les audits ?

R: C'est une question de conformité qui dépend de votre secteur et de la législation locale. En général, loggez les métadonnées (qui, quand, quel type) mais pas le contenu des messages texte, surtout s'il s'agit de communications personnelles. Pour les messages transactionnels (confirmations, reçus), conserver le contenu peut être nécessaire pour les audits. Consultez un juriste local sur les lois de protection des données applicables dans votre pays.

Q: Comment monitorer la qualité du numéro WhatsApp (quality rating) ?

R: Meta expose le quality rating via l'API Graph. Faites un appel GET à https://graph.facebook.com/v18.0/{phone-number-id}?fields=quality_rating pour récupérer le statut (GREEN, YELLOW, RED). Créez un cron job qui vérifie ce statut toutes les heures et alerte votre équipe si le rating passe en YELLOW ou RED.

Q: Quelle est la durée de rétention recommandée pour les logs WhatsApp ?

R: Pour les logs d'erreurs et les métadonnées de messages, 90 jours est un bon compromis entre l'utilité pour le débogage et le coût de stockage. Pour les données de performance des campagnes (taux de livraison, taux de lecture), une rétention de 2 ans permet des analyses de tendances pertinentes.

Q: Mon serveur webhook génère des logs volumineux. Comment les gérer efficacement ?

R: Utilisez une rotation des logs (logrotate sur Linux, ou la configuration de rotation intégrée de Winston/Monolog). Pour les gros volumes, envoyez les logs vers un service centralisé comme Elasticsearch (stack ELK) ou CloudWatch (AWS). Pensez à échantillonner les logs de succès (garder 1 sur 10) tout en loggant 100% des erreurs.

Q: Comment créer un tableau de bord de monitoring WhatsApp sans développement complexe ?

R: Grafana avec une source de données PostgreSQL ou MySQL permet de créer des tableaux de bord visuels en quelques heures. Alternativement, si vous utilisez Whakup, les analytics sont disponibles nativement dans l'interface sans aucune configuration de monitoring de votre côté.

---

Centralisez le monitoring de vos communications WhatsApp avec Whakup. Analytics en temps réel, taux de livraison, performances des campagnes : tout ce dont vous avez besoin pour piloter votre communication client.