Understanding Messaging Rate Limits

About

This guide will walk through the recommended approach to managing queues and rate limits for use with the Messaging API. Over the past years mobile telecom operators have begun to block what is deemed automated traffic (A2P) sent over standard local telephone numbers IE: (919)-430-5555. The amount of messages sent in this way have increased due to spreading automated traffic (A2P) across multiple local telephone numbers to bypass volumetric filters. This process is called "snowshoeing" and as a result, the mobile operators are not only blocking volumetrically, but are also finger-printing content and preemptively blocking messages even from a "fresh" phone number.

Assumptions

Overview

Default Messaging Rate Limits and Queues

All Bandwidth messaging products are rate limited in some fashion. The default rate limit is the same for SMS and MMS. There are various different rate limits within the system:

Scope Rate Limit Description Default
Account Outbound dequeue rate The rate that Bandwidth will send your messages to the downstream carriers across your entire account. 1 MPS
Per-Number Outbound dequeue rate The rate that Bandwidth will send your messages from a single phone number to the downstream carriers P2P - 1 MPS
A2P - ∞, up to account limit
Account Inbound API rate The rate that Bandwidth's API will accept new messages requests. 1 MPS
Per-Number Inbound API rate The rate that Bandwidth's API will accept new messages requests from the same phone number P2P - 1 MPS
A2P - ∞, up to account limit
Account Burst API rate The burst rate that Bandwidth's API will accept new messages. Essentially how quickly can the queue be filled.

⚠️ If queuing is not enabled, this will be same as the Inbound API rate
1 MPS
-or-
Account Outbound dequeue rate + 10

Example: Account Outbound dequeue rate is 5 MPS, the Burst rate will be 15 MPS

400 - BAD_REQUEST

Code Message
message-delay-limit Message tried to be delayed over the maximum limit.

403 – LIMIT

Code Message
message-rate-limit-overall You can send ${0} messages per ${1} seconds calculated as the average over ${2} seconds. Your rate is: ${3}
message-rate-limit-per-tn You can send ${0} messages per ${1} seconds per telephone number, calculated as the average over ${2} seconds. Your rate is: ${3} for telephone number ${4}
multi-message-limit The number of messages [${0}] in the multi message request is greater than the limit [${1}].

Sample Message Rate Limit Response

You will receive this error response if:

  • Your burst rate is exceeded.
  • Your per number messages per second (MPS) is exceeded (only with queueing disabled).
Status: 403 Forbidden
Content-Type: application/json

{
  "category": "limit",
  "code": "message-rate-limit",
  "message": "You can send 1 messages per 1 seconds, calculated as the average over 10 seconds. Your rate is: 1.1",
  "details": [
    {
      "name": "requestMethod",
      "value": "POST"
    },
    {
      "name": "remoteAddress",
      "value": "x.x.x.x"
    },
    {
      "name": "requestPath",
      "value": "users/u-asdf/messages"
    }
  ]
}

Sample Delay Queue full Response

You will receive this error response if:

  • Your queue is full.
Status: 400 Bad Request
Content-Type: application/json

{
  "category": "bad-request",
  "code": "message-delay-limit",
  "message": "Message tried to be delayed over the maximum limit.",
  "details": [
    {
      "name": "requestMethod",
      "value": "POST"
    },
    {
      "name": "remoteAddress",
      "value": "x.x.x.x"
    },
    {
      "name": "requestPath",
      "value": "users/u-asdf/messages"
    }
  ]
}

How Bandwidth Helps

In response to the ever changing (& unregulated) landscape of telecommunications and text messaging, Bandwidth has implemented a new rate-limit process and look-ahead Spam filtering service to help our customers ensure deliver-ability of their messages.

We have broken up our messaging classifications into two categories:

Category About Attributes Common Use-cases
P2P - Conversational Person to Person Person-to-Person (P2P) generally describes the low-volume exchange of wireless messages between end users... the concept of consistent with typical human operation defines P2P traffic to distinguish P2P from A2P traffic Per Number
- 15-60 messages/minute
- 1,000-2,000 messages/day
- ~200 unique recipients
- Close to 1:1 inbound messages to outbound messages
- Support over SMS
- Chat Bots
- Over-the-top (OTT) tel-co application
- Private Phone Numbers
A2P - Automated message to Person A2P traffic is all messaging that falls outside the definition of P2P (i.e., traffic that is not consistent with typical human operation) Per Number
- Bounded only by account permissions
- Sent with a toll-free phone number
- Typically much higher ratio of outbound messages vs inbound
- Appointment Reminders
- Shipping & Order Alerts
- Outbound Mass Communications

Look-ahead Spam filtering

Bandwidth uses the same Adaptive network protection technology as the mobile telco operators. This allows us to screen messages before they're sent to the downstream carrier. By checking before Bandwidth passes the message along, we're able to work with you to understand and fix any potential issues with the message. This maintains your telephone number deliverability reputation and helps build predictable traffic patterns. If the message is marked as Spam we will send a notification to the callbackUrl specified in the create message request.

Toll-Free A2P Best Practices

Principle Description
Consent
The consumer must give appropriate consent
The single most important practice is ensuring you have accurate, reliable consumer opt-in specific to the type of messages you are sending consumers. It is expected that opt-out rates are consistently low when you have obtained reliable and clear consumer opt-in consent. At anytime, Bandwidth or wireless carriers may request from you evidence of written opt-in consent for a particular message.
Single Number Use
Utilize single number for identity
Each campaign should use one primary phone number. Using a single number for both text and voice calls is recommended. Avoid using spreading messages across many source phone numbers, specifically to dilute reputation metrics and evade filters. This is referred to as “snowshoeing” and can result in your content being blocked. If your messaging use case requires the use of multiple numbers to distribute “similar” or “like” content, please discuss with your onboarding team.
Identify Brand
Identify the brand or business in the body of the message
Your application, service or business name should be included in the content of the body.

For example: “Your Business Name: You have an appointment for Tuesday 3:00PM, reply YES to confirm, NO to reschedule. Reply STOP to unsubscribe”
Opt-In Confirmation Upon successful opt-in by a mobile subscriber, an opt-in confirmation message will immediately be sent to the mobile subscriber number. Per CTIA guidelines - a single opt-in confirmation message displaying information verifying the customer’s enrollment in the identified program and describing how to opt out.
Support for STOP
Use of Opt-Out language
The best practice is notifying the consumer of their ability to opt-out from future messages from the message sender. This is especially important when sending informational or promotional messages.

An example would be to include the sentence, “Reply STOP to unsubscribe” to the end of the initial message sent to the consumer, or “reply STOP to cancel”
Processing STOP Keywords
Ensuring proper functioning of Opt-Out behavior - STOP keywords
Consumer opt-in and opt-out functionality is enforced at the network level via the STOP and UNSTOP keywords. This functionality cannot be disabled for service providers or message senders.

Message senders have obligations to process the opted-out consumer phone number so it is removed from all distribution lists and be logged as “opted out” from SMS communications. This ensures that future messages are not attempted and consumer consent is honored.

Examples of valid opt-out messages: “STOP” “Stop” “stop” “STop”

For Toll Free SMS, there is no need to send an acknowledgement to the consumer. The opt-out confirmation message returned to a consumer is generic and gives instructions on how to opt back into service again with the message sender’s phone number. Opt-out confirmation message:

NETWORK MSG: You replied with the word "STOP" which blocks all texts sent from this number. Text back "UNSTOP" to receive messages again.
UNSTOP
[Only for Toll Free A2P]
Processing Opt-In Keywords specific to Toll Free Texting
A consumer can opt back in at any time to receive messages by texting the keyword “UNSTOP” to a message sender’s phone number. The keyword is not case sensitive and triggers an opt-in only when sent as a single word, with no punctuation or leading spaces (any trailing spaces are trimmed). If the consumer uses the opt-in keyword within a sentence an opt-in is not triggered.

Examples of valid opt-ins: “UNSTOP” “Unstop” “unstop” “UNStop”

The message returned to a consumer is generic and informs the consumer they can start two-way texting with the message sender’s phone number again.

NETWORK MSG: You have replied "unstop" and will begin receiving messages again from this number.
Single Domain - Associate URL Each campaign should be associated with a single web domain owned by customer. Although a full domain is preferred, a URL shortener may be used to deliver custom links. Avoid public / shared domain shorteners:
- bit.ly
- goo.gl
- tinyurl.com
- Tiny.cc
- lc.chat
- is.gd
- soo.gd
- s2r.co
- Clicky.me
- budurl.com
- bc.vc

Enabling Queuing

By default Bandwidth does not queue messages internally to be sent out. Once contracted, Bandwidth can enable a 15 minute queue across the entire account. The number of messages in the queue will depend on your account wide dequeue rate. It's important to note that the 15 minute queue is across the entire account, and not per phone number.

Example: Calculating Queue Depth

An account has an Outbound dequeue rate of 5MPS and has enabled the 15 minute queue (900 second).

Example: Calculating Queue Fill Time

An account has an Outbound dequeue rate of 5 MPS, a Burst API rate of 15 MPS and has enabled the 15 minute queue (900 second).

Managing Messages

Method Description Use-cases
Back-off and Retry Try to send messages as quickly as possible to Bandwidth. When you hit the rate limit, add a small delay and try again. If it fails, then add some more delay and try again Works best for use-cases that need to send lots of messages with no priority:
- Day before appointment reminders
- Receipts
- Opted-in Promotions
Throttle Only send messages to Bandwidth as quickly as your dequeue rates Works best with any use case, but favors pure P2P
Queue Management Utilizing a queue system such as RabbitMQ or Mosquitto Works best for use-cases that intermingle massive campaigns with realtime traffic. Enables full control over message priority and time-to-live

Back-off and Retry

Back-off and Retry adaptively increases delay to attempt to find the quickest possible call pacing without hitting rate limits. The pseudocode below shows a simple example using a linear coefficient to adjust delay. Introducing randomness or "jitter" into the delay can help reduce successive collisions.

retries = 0
coefficient = 2 // coefficient to increase delay
delay = some milliseconds (small amount)
DO
status = Get the result of the asynchronous operation.
IF status = SUCCESS
    retry = false
ELSE IF status = TIMEOUT
    retry = true
    retries = retries + 1
    WAIT delay
    delay = coefficient * delay
END IF
WHILE (retry AND (retries < MAX_RETRIES))

Throttling

Throttling paces the asyncronous operations based on a specified time duration. Using a duration just longer than the rate limit will help ensure calls are completed as they are sent without having to resend due to rate limiting.

retries = 0
DO
status = Get the result of the asynchronous operation.
IF status = SUCCESS
    retry = false
ELSE IF status = TIMEOUT
    retry = true
    retries = retries + 1
    WAIT some milliseconds
END IF
WHILE (retry AND (retries < MAX_RETRIES))

Queue Management

Queue Management requires configuring and maintaining a queue of async operations, http API calls for example, facilitating linear control over when the operation is executed. The pseudocode below shows a simple queueing solution. For complex queueing tasks, consider using a queue system such as RabbitMQ or Mosquitto.

1. CONFIGURE_QUEUE size, storage, etc
2. PUSH_TO_QUEUE add async operation data to queue
3. SUBSCRIBE_TO_QUEUE get async operation from queue

 BEGIN_HANDLER
 DO
   message = extracted from queue of async operations
   status = execute async operation with message
   IF status = SUCCESS
      retry = false
   ELSE IF status = TIMEOUT
      retry = true
      retries = retries + 1
      WAIT delay
   END IF
 WHILE (retry AND (retries < MAX_RETRIES))
 END_HANDLER

results matching ""

    No results matching ""