Monitor WhatsApp Usage and Plan Limits

You're growing. Last month 800 messages. This month 1,200. Next month? If you hit plan limits mid-campaign, you're losing deals. This guide shows you how to track WhatsApp usage in real-time and upgrade at exactly the right moment.

Real-time usage dashboards with API access. No waiting for monthly invoices to find out you overspent. MoltFlow gives you programmatic access to your consumption data so you can forecast growth and scale confidently.

What You'll Need

Before starting, make sure you have:

• A MoltFlow account — Any plan tier works. Usage tracking is available on all plans including the free Starter tier.
• An active WhatsApp session — Usage metrics track activity from connected WhatsApp accounts. If you haven't connected yet, see the "Connect Your WhatsApp Account" guide first.

No API key required for dashboard usage—everything is accessible through the web interface.

Usage API (Growth+) — Programmatic access to your consumption data. Build custom alerts, forecast scaling needs, integrate with your internal analytics.

Step 1: Navigate to the Usage Dashboard

Log in to your MoltFlow dashboard at molt.waiflow.app and look for the Usage link in the left sidebar.

The WhatsApp usage tracking dashboard displays your current billing period metrics at a glance:

• Messages Sent — Total outbound messages this billing period (this is the primary metric for plan limits)
• Active Sessions — Number of connected WhatsApp accounts (counts toward your session limit)
• Monitored Groups — Number of WhatsApp groups being tracked for leads (counts toward your group limit)
• Usage Percentage — How close you are to your monthly message limit (color-coded: green under 70%, yellow 70-90%, red over 90%)

The dashboard updates in real-time—send a message and the counter increments within 1-2 seconds.

Understanding the Usage Bar

The usage bar shows your consumption visually:

• Green bar — You're comfortably within limits (below 70%)
• Yellow bar — You're approaching limits (70-90%)—consider upgrading soon
• Red bar — You're near or at your limit (>90%)—urgent action needed

If you hit 100%, the API returns 429 Too Many Requests for new message sends until your billing period resets.

Step 2: Understand Your Billing Period Metrics

Your billing period determines when usage counters reset. Unlike calendar months, MoltFlow billing periods start from your subscription start date and run for 30 days.

For example:

• If you subscribed on January 15th, your billing period is January 15 - February 14
• If you subscribed on February 3rd, your billing period is February 3 - March 4

The Usage dashboard shows your current period boundaries at the top:

Period: 2026-02 (Feb 1, 2026 - Mar 1, 2026)

Metrics Tracked Per Billing Period

MoltFlow tracks these counters:

1. Messages Sent (Primary Limit) — Every outbound message via POST /messages/send, bulk sends, scheduled messages, and AI auto-replies counts toward this limit. This is the source of truth for plan enforcement.

2. Messages Received — Inbound messages from WhatsApp. These do not count toward plan limits (receiving is always free), but are tracked for analytics.

3. Active Sessions — The number of WhatsApp sessions with status "working". This is a concurrent limit, not a cumulative counter (connecting a 3rd session while on a 2-session plan is blocked).

4. Monitored Groups — The number of WhatsApp groups configured for lead capture. Like sessions, this is a concurrent limit—you can monitor up to N groups at once based on your plan.

5. API Calls — Total API requests (tracked for internal analytics, not enforced as a limit currently).

Where the Counters Live

Usage counters are stored in Redis for performance:

• Real-time counter — Incremented on every message send via an atomic Lua script (prevents race conditions)
• Monthly aggregate — At the end of each billing period, counters are written to the usage_aggregates database table for historical reporting
• Daily breakdowns — Redis stores per-day counters for trend analysis (accessible via /usage/daily endpoint)

The Usage dashboard always shows the Redis counter (most up-to-date), with fallback to the aggregate table if Redis is unavailable.

Step 3: Check Plan Limits and Current Consumption

Each plan tier has different limits for messages, sessions, and groups. Here's the breakdown:

Your current plan is displayed at the top of the Usage page. If you need to check programmatically, use the API:

curl -X GET https://apiv2.waiflow.app/api/v2/usage/current \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Replace YOUR_JWT_TOKEN with your dashboard JWT (obtainable from developer tools → Application → Cookies → moltflow_token).

Response Example

{
  "period": "2026-02",
  "period_start": "2026-02-01T00:00:00Z",
  "period_end": "2026-03-01T00:00:00Z",
  "messages_sent": 7823,
  "messages_received": 1204,
  "total_messages": 7823,
  "leads_detected": 34,
  "api_calls": 9156,
  "limit_messages": 10000,
  "limit_groups": 20,
  "limit_sessions": 3,
  "groups_active": 8,
  "sessions_active": 2,
  "usage_percentage": 78.2
}

This tells you:

• You've sent 7,823 messages out of 10,000 (78.2% used)
• You have 2 active sessions out of 3 allowed
• You're monitoring 8 groups out of 20 allowed

Important: The messages_sent field is the authoritative source for plan enforcement. Even if the aggregate table shows a different number, the Redis counter is what determines whether your next API call succeeds or returns 429.

Step 4: Monitor Usage Trends Over Time

The Usage page includes two views for historical analysis:

Monthly History

Click the "History" tab to see your usage for the past 6-12 months. This shows:

• Message volume trends (are you growing or shrinking?)
• Seasonal patterns (e.g., higher volume during holiday campaigns)
• Plan adequacy (consistently hitting 90%+ means you need to upgrade)

Use this data to forecast future needs. If you're averaging 8,500 messages/month on a 10,000-message plan, you'll likely hit the limit during a peak month. Planning a large campaign? Check our bulk messaging guide to learn how to estimate message counts.

Daily Breakdown

For more granular analysis, fetch the daily usage via API:

curl -X GET "https://apiv2.waiflow.app/api/v2/usage/daily?days=30" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

[
  {
    "date": "2026-02-13",
    "messages_sent": 342,
    "messages_received": 87,
    "leads_detected": 2,
    "api_calls": 456
  },
  {
    "date": "2026-02-12",
    "messages_sent": 298,
    "messages_received": 74,
    "leads_detected": 1,
    "api_calls": 389
  }
  // ... 28 more days
]

Use this to:

• Identify which days have highest volume (e.g., Mondays after weekend lead capture)
• Detect anomalies (sudden spike might indicate a bug or unauthorized usage)
• Plan bulk campaigns around low-usage days to avoid hitting limits
• Schedule recurring messages during off-peak hours to distribute load

Set Up Proactive Alerts

MoltFlow doesn't yet have built-in alerts (coming soon), but you can build your own using the API:

1. Set up a daily cron job to fetch /usage/current
2. Check if usage_percentage > 80
3. Send yourself a notification (email, Slack, SMS) to prompt an upgrade

Example script (pseudo-code):

import requests

response = requests.get(
    "https://apiv2.waiflow.app/api/v2/usage/current",
    headers={"Authorization": f"Bearer {JWT_TOKEN}"}
)
usage = response.json()

if usage["usage_percentage"] > 80:
    send_alert(f"Warning: {usage['usage_percentage']}% of message limit used")

Run this daily at 9 AM to catch approaching limits before they become critical.

Step 5: Upgrade Your Plan When Approaching Limits

If you're consistently hitting 80%+ of your message limit, it's time to upgrade. Here's how:

Upgrade via Dashboard

1. Click Settings in the sidebar
2. Navigate to Billing section
3. Click "Manage Subscription"
4. You'll be redirected to the Stripe Customer Portal
5. Click "Update Plan" and select your new tier (Pro or Business)
6. Confirm the change

Plan changes take effect immediately with prorated billing. If you upgrade mid-month, you'll only pay the difference for the remaining days of your billing period.

For example:

• You're 15 days into a Pro plan ($29/month)
• You upgrade to Business ($99/month)
• Stripe charges you ~$35 (half the $70 difference) to cover the next 15 days
• Your next full billing period is charged at $99

Downgrade Considerations

If you downgrade (Business → Pro or Pro → Starter), the change takes effect at the end of your current billing period. This prevents immediate enforcement of lower limits that could disrupt active campaigns.

For example:

• You're on Business (50K messages) and downgrade to Pro (10K messages) on February 15
• The change applies on March 1 (when your billing period resets)
• You can still send up to 50K messages until March 1

What Happens When You Hit Limits

If you send the maximum allowed messages before upgrading:

• Message sends — API returns HTTP 429 Too Many Requests with header X-RateLimit-Reset indicating when your limit resets
• Scheduled messages — Queued messages wait until your billing period resets or you upgrade (they don't fail permanently)
• Bulk sends — Pause at the limit and resume automatically after upgrade or period reset

No messages are lost—they're just queued until capacity is available.

Contact Sales for Enterprise

If you need more than 50,000 messages/month or 10 sessions, contact our sales team at [email protected]. We offer Enterprise plans with:

• Custom message limits (100K, 500K, 1M+)
• Unlimited sessions and groups
• Dedicated infrastructure (no multi-tenant limits)
• Priority support with SLA

Troubleshooting

Usage Not Updating

Problem: The Usage dashboard shows 0 messages sent even though you've sent messages.

Solution: Wait 1-2 minutes. The Redis counter updates instantly, but the dashboard may cache the value briefly. If it still doesn't update:

1. Check your session status—if the session is "stopped" or "failed", messages aren't being sent
2. Verify the API response—successful sends return HTTP 200 with a message ID
3. Try a hard refresh (Ctrl+Shift+R) to clear browser cache

Wrong Billing Period Displayed

Problem: The Usage dashboard shows the wrong billing period (e.g., shows Feb 1-28 but you subscribed on Jan 15).

Solution: Check your subscription start date in Settings > Billing. The billing period is always anchored to that date, not calendar months. If the date is incorrect, contact support—there may be a billing sync issue with Stripe.

Limits Enforced Mid-Message

Problem: You're sending a bulk campaign and hit the limit halfway through.

Solution: This is expected behavior. MoltFlow enforces limits per message, not per API call. If your bulk send contains 500 messages but you only have 200 remaining in your limit:

• The first 200 send successfully
• The 201st returns 429 Too Many Requests
• The remaining 299 are queued (if using scheduled bulk send) or rejected (if using immediate send)

To avoid this, always check your remaining limit before starting large campaigns:

curl -X GET https://apiv2.waiflow.app/api/v2/usage/current \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  | jq '.limit_messages - .messages_sent'

This returns your remaining message quota. For comprehensive API usage, see our REST API Quick Start guide.

Redis Counter Mismatch

Problem: The API shows different usage than the dashboard.

Solution: The dashboard may be showing cached or aggregate data. The /usage/current API endpoint always returns the Redis counter, which is the source of truth. If you see a discrepancy:

1. Use the API value for accurate enforcement decisions
2. Wait for the next aggregate sync (happens nightly at midnight UTC)
3. Contact support if the discrepancy is large (>5%)

What's Next?

Now that you understand WhatsApp usage tracking, explore related features to optimize your message consumption and scale efficiently:

• Send Bulk WhatsApp Messages — Plan large campaigns around usage forecasts to avoid hitting limits
• Schedule Recurring Messages — Spread bulk campaigns over multiple days to stay under daily limits
• REST API Quick Start — Build custom usage alerts and integrate with your internal dashboards
• Configure Anti-Spam Rules — Avoid wasting messages on rate-limited sends

Upgrade to Scale Your WhatsApp Operations

Hitting your message limits consistently? Time to scale up:

• Pro plan (10K messages/month) — Perfect for growing teams sending 300-500 messages/day
• Business plan (50K messages/month) — High-volume campaigns and multi-session operations
• Enterprise (custom limits) — Unlimited messages, dedicated infrastructure, SLA guarantees

View plans and pricing — Upgrades apply immediately with prorated billing. No downtime, no message loss.

Questions about billing or plan limits? Contact our billing team at [email protected] or use the dashboard chat. We can help you choose the right plan tier and explain prorated charges.