Rate limiting WhatsApp API : comprendre les limites et optimiser l'envoi

Vous venez de lancer une campagne promotionnelle pour votre boutique en Côte d'Ivoire et vous obtenez des centaines d'erreurs 130429. Votre solde fidélité expire dans 48h et vous devez notifier 10 000 clients au Sénégal. Votre système d'envoi de confirmations de commandes WooCommerce plante lors des pics de trafic. Dans tous ces scénarios, le rate limiting de WhatsApp API est en cause. Comprendre ces limites et adapter votre architecture en conséquence est indispensable pour tout développeur ou marketer qui utilise WhatsApp à grande échelle en Afrique.

Les différents niveaux de rate limiting WhatsApp

WhatsApp Business API applique plusieurs couches de limitations indépendantes. Les confondre est une erreur fréquente.

Les tiers de messagerie (Message Tiers) : c'est la limite la plus connue. Elle détermine combien de contacts uniques vous pouvez contacter en 24 heures avec des messages initiés par l'entreprise (templates HSM). Les paliers sont :

• Tier 1 : 1 000 contacts uniques/24h
• Tier 2 : 10 000 contacts uniques/24h
• Tier 3 : 100 000 contacts uniques/24h
• Tier 4 : illimité

Le passage d'un tier à l'autre est automatique si vous maintenez une qualité de messagerie élevée (peu de blocages, peu de signalements spam) et que vous atteignez 80% de la limite du tier actuel sur deux jours consécutifs.

La limite par second (throughput) : indépendamment du tier, l'API limite le nombre de requêtes API par seconde par numéro de téléphone. Cette limite est généralement de 80 messages par seconde pour les comptes en bonne santé, mais peut être plus basse pour les nouveaux comptes.

La fenêtre de conversation (24h) : les messages en réponse à un client (session messages) ne comptent pas dans le quota du tier, mais la fenêtre de 24h impose d'utiliser des templates pour les nouvelles conversations.

Consultez le guide WhatsApp Business API pour comprendre le système de tiers en détail.

Calculer votre débit réel

Pour planifier une campagne, vous devez connaître votre débit effectif. Voici un calcul pratique :

function calculateCampaignTime(contactCount, tierLimit, messagesPerSecond = 50) {
    // Vérifier si le tier permet l'envoi
    const tierNames = { 1000: 'Tier 1', 10000: 'Tier 2', 100000: 'Tier 3' };
    
    if (contactCount > tierLimit) {
        const days = Math.ceil(contactCount / tierLimit);
        return {
            feasible: false,
            message: `Impossible en une journée. Nécessite ${days} jours avec votre tier actuel.`,
            recommendation: 'Augmentez votre tier ou étalez la campagne.'
        };
    }
    
    // Temps minimum basé sur le throughput
    const secondsNeeded = Math.ceil(contactCount / messagesPerSecond);
    const minutesNeeded = Math.ceil(secondsNeeded / 60);
    
    return {
        feasible: true,
        estimatedMinutes: minutesNeeded,
        message: `Envoi possible en environ ${minutesNeeded} minutes à ${messagesPerSecond} msg/sec`,
        recommendation: minutesNeeded > 60 ? 
            'Planifiez l\'envoi pendant les heures creuses' : 
            'Durée raisonnable, procédez à l\'envoi'
    };
}

// Exemple : 5000 clients pour une boutique de Dakar, tier 2
const result = calculateCampaignTime(5000, 10000, 50);
console.log(result.message); // "Envoi possible en environ 2 minutes"

Implémenter un token bucket pour le throttling

La stratégie la plus efficace pour respecter les limites de débit est le token bucket. Voici une implémentation en Node.js avec Bull (file de messages) :

const Queue = require('bull');
const messageQueue = new Queue('whatsapp-messages', {
    redis: { host: 'localhost', port: 6379 }
});

// Configuration du rate limiting dans Bull
messageQueue.process(
    // Traiter au maximum 50 jobs par seconde
    { concurrency: 5 },
    async (job) => {
        const { to, message, templateName, params } = job.data;
        
        try {
            if (templateName) {
                return await sendTemplateMessage(to, templateName, 'fr', params);
            } else {
                return await sendTextMessage(to, message);
            }
        } catch (error) {
            if (error.code === 130429) {
                // Rate limit : délai avant retry
                throw new Error('RATE_LIMIT'); // Bull va retenter automatiquement
            }
            throw error;
        }
    }
);

// Limiter le débit à 50 messages/seconde
const limiter = {
    max: 50,
    duration: 1000 // 1 seconde
};

// Ajouter des messages à la queue
async function queueCampaign(contacts, templateName, params) {
    const jobs = contacts.map(contact => ({
        data: { to: contact.phone, templateName, params },
        opts: {
            attempts: 3,
            backoff: { type: 'exponential', delay: 5000 },
            limiter
        }
    }));
    
    await messageQueue.addBulk(jobs);
    console.log(`${jobs.length} messages ajoutés à la queue`);
}

// Lancer une campagne pour 3000 clients ivoiriens
queueCampaign(
    clients,
    'promo_flash',
    ['{prenom}', '30%', '24 heures']
);

Stratégies pour optimiser l'utilisation des limites

Prioriser les messages : toutes les notifications n'ont pas la même urgence. Donnez la priorité aux messages transactionnels (confirmations de commande, alertes de sécurité) sur les messages marketing. Utilisez des queues séparées avec des priorités différentes.

// Queue haute priorité pour messages transactionnels
await messageQueue.add(
    { to: phone, message: 'Votre paiement a été confirmé' },
    { priority: 1 } // Plus la valeur est basse, plus la priorité est haute
);

// Queue basse priorité pour marketing
await messageQueue.add(
    { to: phone, templateName: 'newsletter_hebdo' },
    { priority: 10 }
);

Étaler les campagnes dans le temps : plutôt qu'envoyer 50 000 messages en un bloc, échelonnez sur 8-10 heures en évitant les heures de pointe réseau (midi et 18-20h). Cela réduit le risque d'atteindre les limites et améliore l'engagement (les messages reçus pendant les heures actives ont de meilleurs taux de lecture).

Monitorer le quality rating : Meta attribue un score de qualité à votre numéro basé sur les signalements et blocages. Un score "Low" réduit vos limites d'envoi. Surveillez ce score dans le tableau de bord Meta Developer et réagissez rapidement si des clients commencent à signaler vos messages comme spam.

Préférer les sessions messages quand possible : si un client vous a écrit dans les dernières 24h, répondez-lui plutôt que d'initier une nouvelle conversation avec un template. Les messages de session ne consomment pas votre quota journalier.

Pour une vision globale de la performance de vos campagnes et du ROI de votre présence WhatsApp, l'article sur le calcul du ROI WhatsApp marketing est une lecture complémentaire indispensable.

FAQ

Q: Comment passer rapidement du Tier 1 (1000/jour) au Tier 2 (10 000/jour) ?

R: Le passage est automatique selon les critères de Meta : atteindre 80% de votre limite actuelle pendant 2 jours consécutifs, avec un bon quality rating (Green). Évitez les signalements en ne contactant que des clients opt-in, en soignant la qualité de vos messages et en proposant facilement la désinscription.

Q: Le rate limiting s'applique-t-il aussi aux messages de réponse (session) ?

R: Les messages de session (envoyés dans la fenêtre de 24h après qu'un client vous a écrit) ne sont pas soumis aux limites de tier journalier. En revanche, la limite de throughput (messages/seconde) s'applique à tous les types de messages. Un chatbot répondant à des milliers de clients simultanément doit également gérer ce throughput.

Q: Peut-on utiliser plusieurs numéros pour multiplier les limites d'envoi ?

R: Techniquement oui, mais Meta surveille les comportements suspects. L'utilisation de plusieurs numéros pour contourner les limites peut entraîner des restrictions. La solution légitime est de monter en tier via une qualité de messagerie excellente ou d'utiliser des numéros officiellement répartis par marché ou business unit.

Q: Que se passe-t-il si je dépasse ma limite de tier ?

R: Les messages dépassant la limite du tier sont simplement rejetés avec le code d'erreur 130429 ou un message d'erreur de limite quotidienne. Votre numéro n'est pas suspendu pour ça, mais les messages perdus ne sont pas réenvoyés automatiquement. C'est pourquoi avoir une queue avec retry logic est essentiel.

Q: Y a-t-il des limites sur les messages reçus (webhooks entrants) ?

R: Non, il n'y a pas de limite sur les messages que vos clients peuvent vous envoyer. En revanche, votre infrastructure de webhook doit pouvoir absorber les pics. Si Meta n'arrive pas à livrer les événements webhook (serveur hors ligne ou trop lent), ils sont retentés mais peuvent être perdus après plusieurs jours.

---

Gérez vos campagnes WhatsApp à grande échelle sans vous soucier du rate limiting. Whakup optimise automatiquement l'envoi de vos messages pour maximiser la délivrabilité tout en respectant les limites Meta.