Capacity and Messaging Limits

This document covers:

Capacity Rate Limits

Capacity rate limiting is imposed on each available API endpoint and will return the appropriate HTTPS error codes (e.g., 429, 503, etc.) depending on the state of the system.

Two forms of capacity rate limiting are currently supported:

  • Request rate limiting — Request rate limiting is the throttling of incoming requests on an API endpoint. When the number of requests per second limit is reached, the endpoint will start returning a 429 error code.
    • Beginning with v2.25.3, the request rate limit for the messages endpoint is 50 requests per second with bursts allowed up to 150 requests per second.
    • For versions prior to v2.25.3 and all other endpoints, the request rate limit is 20 requests per second with bursts allowed up to 60 requests per second.
  • Concurrent rate limiting — Concurrent rate limiting is the throttling of incoming requests when the Coreapp itself is under heavy load (e.g., job queue size grew too large). At this point, the endpoint will start returning a 503 error.

When you hit either of these capacity rate limiting scenarios, you should halt any further requests and slow the pace of your API requests. If you start seeing many capacity rate limit errors, it would be advisable to build a queue on your end to throttle the requests.

If your expected average send-rates are significantly higher and queuing is not an effective strategy, please look into our High Availability and Scaling options.

Quality Rating and Messaging Limits

The phone number status, quality rating, and messaging limits for your WhatsApp business account are listed in the Phone Numbers tab in WhatsApp Manager.

Phone Numbers Tab

Quality Rating

The quality rating shows how messages have been received by your customers in a rolling window of the past 24 hours. We show it in three different states:

  • High (green)
  • Medium (yellow)
  • Low (red)

Status

There are different statuses for phone numbers that refer to its connectivity:

  • Pending: This is when a business first sets up a phone number that hasn’t yet been on-boarded and approved.
  • Connected: The phone number is online and functioning normally.
  • Offline: The phone number is currently not reachable by WhatsApp servers or is not otherwise online.

Occasionally, a phone number may show one of two particular statuses that are related to quality and messaging limits: Flagged and Restricted.

  • Flagged: This is a warned state. When the quality rating reaches a low (red) state, the phone number is moved to a Flagged status.
    • If the quality rating improves to a high (green) or medium (yellow) state over 7 days, the phone number will return to a Connected status.
    • If the quality rating does not improve within 7 days, the number will still return to a Connected status but with a lower messaging limit imposed on it.
  • Restricted: Phone numbers that reach their messaging limit are moved to a Restricted state. During a Restricted state, the number will be unable to send any notification messages until the 24-hour window for sending messages is reset. They can still respond to any messages initiated by users.

Notifications

You will receive a notification in the Business Manager if a phone number status from your WhatsApp business account(s) changes to Flagged or Restricted or if your messaging limit changes. Emails are sent to the email registered with Business Manager.

Messaging Limits

Messaging limits determine how many unique users your business can send messages to on a daily basis. This includes new conversations as well as existing conversations with users. The messaging limit does NOT limit the number of messages your business can send, just the number of users you are trying to message. It also does NOT apply to messages sent in response to a user-initiated message within a 24-hour period.

  • Tier 1: Allows your business to send messages to 1K unique customers in a rolling 24-hour period.
  • Tier 2: Allows your business to send messages to 10K unique customers in a rolling 24-hour period.
  • Tier 3: Allows your business to send messages to 100K unique customers in a rolling 24-hour period.

Note: A business starts in Tier 1 when it registers its phone number.

A business’s phone number will be upgraded to the next tier if:

  • Its quality rating is not low, and
  • The cumulative amount of users it sends notifications to adds up to twice its current messaging limit within a 7-day period.

Once the business reaches this threshold, it will be moved to the next tier. The minimum amount of time that this upgrade can occur is after 48 hours, when the business is sending messages up to their current limit every day.

See the charts below for examples of how a business might move to the next tier:

Example 1: A business is upgraded from Tier 1 to Tier 2 when it messages a total of 2,000 users within a 7-day period.

Example 1

Example 2: The chart explains the concept of messaging limit in a rolling 24-hour window.

Example 2

Good Practices

To maintain high quality:

  • Make sure messages follow the WhatsApp Business Policy.
  • Only send messages to users who have opted into receiving messages from your business.
  • Make the messages highly personalized and useful to users. Avoid sending open-ended welcome or introductory messages.
  • Be mindful of messaging frequency; avoid sending customers too many messages a day. Be thoughtful of informational messages, optimizing for content and length.