WhatsApp Business API Limits

Message Types

WhatsApp distinguishes between two fundamental message types. The type determines when you can send a message, what content is allowed, and how it is billed.

Messaging Tiers

Your WhatsApp Business Account (WABA) is assigned a messaging tier that determines how many unique users you can send business-initiated (template) messages to within a rolling 24-hour period. This limit applies per phone number.

Tier upgrades happen automatically when you meet the volume requirement while maintaining a high or medium quality rating. Downgrades can occur if your quality rating drops to low due to user complaints or blocks.

Template Limits

Message templates must be submitted for approval before use. Meta reviews each template against their commerce and messaging policies.

Each template has an individual quality rating (high, medium, or low) based on recipient feedback. Templates that receive too many blocks or "report spam" actions will be paused automatically by Meta.

APPROVED    -> Template is active and can be sent
PAUSED      -> Too many negative signals; sending is temporarily disabled
DISABLED    -> Permanently rejected; must create a new template
IN_REVIEW   -> Awaiting Meta approval (typically < 24 hours)
REJECTED    -> Did not pass policy review; edit and resubmit

24-Hour Conversation Window

When a user sends your business a message, a 24-hour conversation window opens. During this window you can reply with free-form session messages without needing a pre-approved template. The window resets every time the user sends a new message.

User sends message             -> 24h window OPENS
  |
  |-- Business sends session     (free-form, no approval needed)
  |-- Business sends session     (still within 24h)
  |
  +-- 24 hours elapse            -> Window CLOSES
      |
      +-- Business must use      -> Template message (pre-approved)
          template to re-engage

Rate Limits

The WhatsApp Business API enforces per-second throughput limits on message sending. These limits apply at the phone number level and vary by message type.

Quality-Based Throttling

Your phone number's quality rating directly affects your effective throughput. If the quality rating drops, Meta may reduce your sending rate below the standard limits.

Handling Rate Limit Errors

When you exceed the per-second rate limit, the API returns a 429 status code. Implement exponential backoff with jitter to retry gracefully.

async function sendWithRetry(payload, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const res = await fetch("https://api.intelliportal.io/v1/messages/send", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.INTELLI_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(payload),
    });

    if (res.status !== 429) return res;

    const retryAfter = parseInt(res.headers.get("Retry-After") ?? "1");
    const jitter = Math.random() * 1000;
    const delay = retryAfter * 1000 * Math.pow(2, attempt) + jitter;

    console.log(`Rate limited. Retrying in ${Math.round(delay / 1000)}s`);
    await new Promise((r) => setTimeout(r, delay));
  }

  throw new Error("Max retries exceeded");
}

Best Practices

Follow these guidelines to maintain a healthy quality rating, avoid throttling, and ensure reliable message delivery.

• Honor opt-outs immediately. Remove users from your messaging lists as soon as they request it. Continuing to message opted-out users will damage your quality rating.
• Use correct template categories. Choose the appropriate category (utility, authentication, or marketing) for each template. Miscategorized templates may be rejected or paused.
• Monitor your quality rating. Check the IntelliPortal dashboard regularly for quality alerts. Address issues before your rating drops to low.
• Implement proper rate limiting on your end. Use a queue or token bucket to stay below the per-second API limits rather than relying on 429 retries.
• Warm up new phone numbers gradually. Start with low volumes and increase over several days to build a positive sending reputation before scaling to higher tiers.
• Keep template content relevant and timely. Avoid sending promotional templates to users who have not interacted recently. Stale audiences are more likely to block or report your messages.
• Leverage session messages when possible. Session messages are more flexible and do not require pre-approval. Reply within the 24-hour window to take advantage of free-form messaging.
• Use idempotency keys for retries. When retrying failed API calls, always include an idempotency key to prevent duplicate message delivery.