Skip to main content

WhatsApp Health System Configuration

This document outlines the WhatsApp messaging health system that manages rate limiting, account warm-up, and adaptive delays to keep accounts safe from WhatsApp's spam detection.

Overview​

The health system dynamically adjusts message sending behavior based on:

  • Account Age: How long the WhatsApp profile has been connected
  • Account Tier: Classification based on age and behavior
  • Health Score: Real-time score (0-100) based on delivery success, responses, and errors
  • Time of Day: Slower sending during off-hours
  • Response Rate: Higher engagement allows faster sending
  • Error Patterns: Consecutive errors trigger slowdowns

Account Tiers​

TierEmojiDaily LimitMin DelayMax DelayBatch SizeBatch Break
New Account🔴5002s5s501 min
Warming Up🟠1,5001s3s1001 min
Established🟡4,0001s2s2001 min
Trusted🟢10,0000s1s5000 min

Tier Progression​

  • New Account: Days 0-13 (first 2 weeks)
  • Warming Up: Days 14-27 (weeks 2-4)
  • Established: Days 28-89 (months 1-3)
  • Trusted: Day 90+ (after 3 months)

Warm-Up Schedule​

The system enforces a gradual warm-up for new accounts over 90 days:

DayDaily LimitDelay RangeBatch SizeBreakNotes
01003-6s102 minVery conservative start
12003-5s202 minSlow ramp
23002-5s301 minBuilding trust
34002-4s401 minContinued
55002-4s501 minNew Account tier cap
75002-4s501 minWeek 1 complete
101,0002-3s751 minEntering Warming Up
141,5001-3s1001 minWarming Up tier cap
172,5001-2s1501 minApproaching Established
213,5001-2s1751 minWeek 3
284,0001-2s2001 minEstablished tier cap
426,0001-2s3001 minBuilding to Trusted
608,0000-1s4001 minMonth 2
9010,0000-1s5000 minTrusted tier cap

Health Score Multipliers​

The health score (0-100) affects message delays:

Health ScoreLevelMultiplierEffect
90-100Excellent0.8x20% faster
70-89Good1.0xNormal speed
50-69Warning1.5x50% slower
25-49Critical2.5x150% slower
0-24Danger4.0x300% slower

Health Score Calculation​

The health score is composed of:

  • Delivery Rate (40%): Percentage of messages successfully delivered
  • Engagement Rate (30%): Reply rate and read receipts
  • Stability (30%): Connection stability, no errors

Messages Per Minute by Health Score​

New Account Tier (Base: 3.5s average delay)​

Health ScoreMultiplierActual DelayMsgs/Min
90-1000.8x2.8s~21
70-891.0x3.5s~17
50-691.5x5.25s~11
25-492.5x8.75s~7
0-244.0x14.0s~4

Warming Up Tier (Base: 2.0s average delay)​

Health ScoreMultiplierActual DelayMsgs/Min
90-1000.8x1.6s~37
70-891.0x2.0s~30
50-691.5x3.0s~20
25-492.5x5.0s~12
0-244.0x8.0s~7

Established Tier (Base: 1.5s average delay)​

Health ScoreMultiplierActual DelayMsgs/Min
90-1000.8x1.2s~50
70-891.0x1.5s~40
50-691.5x2.25s~27
25-492.5x3.75s~16
0-244.0x6.0s~10

Trusted Tier (Base: 0.5s average delay)​

Health ScoreMultiplierActual DelayMsgs/Min
90-1000.8x0.4s~120
70-891.0x0.5s~100
50-691.5x0.75s~75
25-492.5x1.25s~46
0-244.0x2.0s~30

Time of Day Multipliers​

Sending is automatically slowed during off-peak hours:

TimeMultiplierEffect
9-11 AM0.85x15% faster (peak)
12-3 PM0.85-0.9x10-15% faster
4-5 PM1.0-1.1xNormal
6-8 PM1.2-1.5x20-50% slower
9-11 PM1.7-1.9x70-90% slower
12-4 AM2.0x100% slower (avoid)

Recommendation: Schedule bulk campaigns for 9 AM - 5 PM for best results.

Response Rate Multipliers​

Higher engagement rates reward faster sending:

Response RateMultiplierEffect
>30%0.85x15% faster
20-30%0.95x5% faster
10-20%1.0xNormal
5-10%1.2x20% slower
<5%1.5x50% slower

Error Handling​

Consecutive Error Multipliers​

Consecutive ErrorsMultiplierEffect
0-11.0xNormal
2-31.5x50% slower
4-52.5x150% slower
6+4.0x300% slower

Circuit Breaker​

The system includes a circuit breaker that stops sending when too many errors occur:

  • Failure Threshold: 5 consecutive errors → Circuit opens
  • Open Duration: 5 minutes pause
  • Recovery: After pause, sends 1 test message
  • Close Threshold: 3 successful messages → Resume normal

Batch Configuration​

Messages are sent in batches with breaks between:

TierMessages Per BatchBreak DurationExtended Break Threshold
New Account252 minutesAfter 300 messages
Warming Up1001 minuteAfter 500 messages
Established2001 minuteAfter 1,000 messages
Trusted5000 minutesAfter 2,000 messages

Extended Break: After threshold, a 5-minute break is enforced.

Delay Bounds (Safety Limits)​

The system enforces absolute bounds regardless of multipliers:

LimitValuePurpose
Absolute Minimum100msPrevent flooding
Absolute Maximum5 minutesPrevent stalling
Cooldown Delay10 minutesRate limit recovery

Typing Simulation (Human Emulation)​

Before each message is sent, the system simulates realistic "typing..." indicator to appear more human-like. This is crucial for avoiding spam detection.

Typing Speed Calculation​

Based on mobile typing research (average: 38 WPM on smartphones):

ComponentValuePurpose
Base speed35-55ms per char~40 WPM average
Initial delay200-500ms"Preparing to type"
Word pauses50-150ms every ~35 charsNatural breathing
Sentence pauses200-400ms at .!?Natural breaks
Emoji time100-200ms per emojiSelection time
Variance±15%Random natural variation

Typing Duration by Message Length​

Message LengthTyping DurationSimulated WPM
10 chars (2 words)0.5-0.8s~30-40 WPM
50 chars (10 words)2.0-3.0s~35-45 WPM
100 chars (20 words)4.0-5.5s~35-45 WPM
200 chars (40 words)8.0-11.0s~35-45 WPM
300 chars (60 words)12.0-15.0s~40 WPM
400+ chars15.0s (max)Capped for UX

Typing Duration Bounds​

LimitValueReason
Minimum300msEven short messages show typing
Maximum15 secondsWhatsApp hides indicator after ~25s

Example Calculations​

Short message: "Hi there!" (10 chars)

  • Base: 10 × 45ms = 450ms
  • Initial delay: 350ms
  • Total: ~0.8 seconds

Medium message: "Hey! How are you doing today? I wanted to check in about our meeting tomorrow." (78 chars)

  • Base: 78 × 45ms = 3,510ms
  • Initial delay: 350ms
  • Word pauses: 2 × 100ms = 200ms
  • Sentence pauses: 2 × 300ms = 600ms
  • Total: ~4.7 seconds

Long message: A 250-character paragraph

  • Base: 250 × 45ms = 11,250ms
  • Initial delay: 350ms
  • Word pauses: 7 × 100ms = 700ms
  • Sentence pauses: 3 × 300ms = 900ms
  • Total: ~13.2 seconds

Time to Send Daily Limits​

Estimated time to send all daily messages (with 100% health, during business hours):

TierDaily LimitAvg DelayTime to Complete
New Account5003.5s~30 minutes
Warming Up1,5002.0s~50 minutes
Established4,0001.5s~100 minutes
Trusted10,0000.5s~100 minutes

Best Practices​

For New Accounts (Days 0-14)​

  1. Start Small: Begin with 50-100 messages on day 1
  2. Personalize: Use recipient names and custom fields
  3. Quality Recipients: Only message people who expect to hear from you
  4. Monitor Health: Watch for delivery failures
  5. Business Hours: Only send 9 AM - 5 PM

For Warming Up Accounts (Days 14-28)​

  1. Gradual Increase: Don't jump to max limits immediately
  2. Track Responses: High response rates help your score
  3. Avoid Spam Reports: Quality > Quantity
  4. Consistent Activity: Send daily rather than bursts

For Established/Trusted Accounts (Day 28+)​

  1. Maintain Health: Keep health score above 70
  2. Batch Campaigns: Spread large campaigns over multiple days
  3. Monitor Alerts: Pay attention to health warnings
  4. Regular Activity: Inactive accounts may need re-warming

Alerts & Warnings​

The system generates alerts at these thresholds:

Alert TypeTriggerRecommendation
Low HealthScore < 50Reduce volume, improve personalization
High Error Rate>10% failuresCheck connection, verify numbers
Rate Limit HitCooldown triggeredWait 10 minutes, reduce speed
Low Response<5% response rateImprove message quality
Daily Limit100% usedWait until tomorrow

API Reference​

Get Health Status​

GET /api/whatsapp/:profileId/queue-health

Response includes:

  • healthScore: Current score (0-100)
  • tier: Account tier
  • adaptive.rateLimits: Current rate limits
  • adaptive.delay: Current delay configuration
  • adaptive.dailyLimit: Daily limit status

Health Dashboard​

Navigate to WhatsApp Profile → Health Dashboard to view:

  • Real-time health score
  • Current limits
  • 24-hour metrics
  • Alerts and recommendations

Configuration Files​

  • Constants: server/lib/whatsapp/health/constants.ts
  • Adaptive Engine: server/lib/whatsapp/health/adaptive-engine.ts
  • Calculator: server/lib/whatsapp/health/calculator.ts
  • Queue: server/lib/whatsapp/core/queue.ts

Last Updated: January 2026