WhatsApp Throughput, Rate Limits & 100% Delivery Architecture

This document details WhatsApp Cloud API message throughput tiers (Messages Per Second — MPS), rate limiting mechanisms, and SMSPort's defensive architecture to guarantee 100% message delivery with zero data loss and zero server crashes.

1. Meta Throughput Tiers (MPS)

Every registered WhatsApp Cloud API business phone number operates under an assigned throughput capacity:

[!NOTE]
Throughput is inclusive of both inbound and outbound messages across all payload types (Text, Media, Interactive, Templates).

2. Key Rate Limits & Error Codes

A. Account Throughput Ceiling (`130429`)

• Trigger: Attempting to dispatch messages faster than your assigned MPS tier (e.g. > 80 MPS).
• Meta Response: (#130429) Cloud API message throughput has been reached.
• SMSPort Defense: Outbound campaign queues automatically throttle concurrency. If 130429 is encountered, the job enters an exponential backoff retry queue without dropping the message.

B. Single-User Pair Rate Limit

• Even with 1,000 MPS enabled, Meta enforces a per-recipient rate limit to protect end-users from spam. You cannot dispatch multiple messages per second to the exact same phone number.
• High throughput is intended for bulk campaigns distributed across unique phone numbers.

C. Automatic Upgrade Downtime (`131057`)

• When an eligible number upgrades from 80 MPS to 1,000 MPS, Meta performs a seamless migration taking up to 1 minute.
• During this window, Meta returns error 131057 (Phone number is being upgraded). SMSPort pauses sending on this sender and resumes automatically once the migration completes.

3. High-Velocity Webhook Sizing

When sending outbound broadcasts at high velocity, Meta concurrently pushes real-time delivery status updates (sent, delivered, read):

$$\text{Incoming Status Callbacks} \approx 3 \times \text{Outbound MPS}$$

• At 80 MPS, your webhook handles up to 240 requests/sec.
• At 1,000 MPS, your webhook handles up to 3,000 requests/sec.

SMSPort Webhook Ingestion Design:

1. Ultra-Fast 200 OK (< 50ms): Incoming webhooks are immediately acknowledged with 200 OK upon signature verification, preventing Meta from triggering aggressive exponential retries.
2. Asynchronous Worker Offloading: Webhook payloads are pushed to internal worker queues to process database status updates and trigger bot execution loops without blocking HTTP listener threads.

4. Querying Phone Number Throughput via API

SMSPort integrates live throughput inspection into phone number health checks:

GET https://graph.facebook.com/v23.0/{PHONE_NUMBER_ID}?fields=throughput,health_status,quality_rating

Meta returns:

{
  "id": "106540352242922",
  "throughput": {
    "level": "STANDARD",
    "mps": 80
  }
}

SMSPort displays this signal directly in the WhatsApp Operations Console alongside Quality Rating and Messaging Limit Tiers.