General

Messages per second (MPS) refers to limits on your account for sending messages. By default, we assign an outbound MPS limit of 5 for SMS and 0.25 for MMS at signup time. Plivo offers MMS services in the US and Canada only and the messages are dispatched as per the allocated MPS. You can find your allocated outbound MPS by visiting the SMS Overview page of the Plivo console and looking in the Account section.

Outbound MPS

For outbound messaging, MPS represents a limit on the rate at which messages are initiated for a specific account. If you exceed your allotted outbound MPS, your messages will not be dropped; instead, they will be queued and dispatched once the MPS rate falls below the limit.

You can send as many messages as required, but the rate at which messages are dispatched adheres to the allocation in your account. Here are a couple of examples.

Scenario 1: If a user has an allocated outbound limit of 5 MPS and sends 5 API messages in a second, all 5 messages will be dispatched simultaneously.

Scenario 2: If a user has an allocated outbound limit of 5 MPS and places 10 API messages in a second, the first 5 messages will be dispatched simultaneously, and the remaining 5 messages will be queued and executed during the next available MPS interval.

Can I increase my allocated MPS?

If you have a use case that requires a higher MPS limit, contact the Plivo support team.

A2P messaging throughput in Canada depends on the type of service (SMS or MMS) and the type of number that you use.

Throughput for long code, toll-free, and short code numbers is set at a per-number level. 

You must verify your toll-free numbers to avoid running into sending limits.

A2P messaging throughput in the US depends on the type of service (SMS or MMS) and type of number that you use.

Throughput for toll-free numbers and short codes

Toll-free and short code number throughput is set at a per-number level. You must verify your toll-free numbers to avoid running into sending limits.

SMS

SMS throughout is defined at a campaign level and depends on your vetting score, as shown in this table. If your brand receives a score of 80, for example, then each campaign under that brand can send up to 4,500 messages per minute towards AT&T, T-Mobile, and Verizon numbers.

*Including T-Mobile, Sprint, and Metro by T-Mobile

Smaller carriers (<5% of US messaging volume) have not explicitly declared their throughput assignment details but we expect them to be in similar ranges for a given vetting score.

MMS

Unlike SMS throughput, which depends on vetting score and campaign type, MMS throughput has been defined at a per number level by the operators. Each number linked to a campaign can send up to 50 messages per minute per operator. For a higher throughput, you can link multiple numbers in the same campaign.

T-Mobile TPD restrictions

T-Mobile (including Sprint) also has a limit on the total daily number of SMS and MMS messages (TPD) a brand can send toward its subscribers. Like TPM, this limit varies with the vetting score assigned to a brand. T-Mobile’s TPD limit takes into account both SMS and MMS messages; in other words, the daily limit is shared across SMS and MMS services. This means that even if you are vetted for throughput of 4,500 TPM towards T-Mobile, any messages sent after the 200,000 limit will fail.

What happens if I reach the daily T-Mobile quota for my brand?

You can check your T-Mobile TPD cap on the console. After you reach the limit T-Mobile allots to your brand, any more messages sent to T-Mobile by the same brand will fail for the rest of the day (days are defined as begin in the Pacific (PT) time zone). Once a day is over, you can again send messages towards T-Mobile.

Traffic toward AT&T, Verizon, and other operators is not affected by the T-Mobile quota.

What if the throughput I’m assigned is not sufficient for my messaging volume? Can I increase my throughput?

Plivo recommends opting for vetting during the brand registration process to unlock higher throughputs. If, even after your business is vetted, your allocated throughput (TPM) isn’t high enough, you can appeal your vetting score by working with our support team. If your appeal is rejected and your daily messaging volume toward T-Mobile is higher than the TPD you’ve been allocated, you can request T-Mobile conduct a Special Business Review (SBR) to gain access to higher daily volumes. 

If your campaign requires linking more than 49 numbers, T-Mobile requires you to submit a Number Pool Request (NPR).

T-Mobile charges a fee for each SBR or NPR. Plivo passes on carrier fees to its customers without any markup. Before submitting an SBR or NPR request, you must have a brand and campaign registered with TCR.

To submit an SBR or NPR, please contact your customer success manager or our support team.

What is message expiry?

Some text messages have a limited useful lifetime. If they’re not delivered within a certain period, they become useless. By default, Plivo expires messages that remain in the messaging queues after three hours. These messages are marked “failed” with error code 420 and are not charged to customers.

Why might a message expire?

When customers send a message through Plivo, it spends a short time in Plivo’s messaging queue before we forward it to a carrier. Typically this time is on the order of seconds, but it might be longer, typically due to messaging rate limits or an outage.

Each Plivo account and sender (the source number in the API) has an upper cap of how many messages it can handle, because we need to comply with carrier-level guidelines in each country. For instance, a short code in the US supports throughput of 100 messages per second. Sending messages at a higher rate results in queuing delays.

Another common cause of message expiry is an outage, either on Plivo’s side or on carriers’, that causes messages to be delayed.

In such cases your users might be getting messages at a time later than you expected — sometimes too late to be useful. A one-time password (OTP) that gets delayed by 15 minutes is no good when your application expects the OTP to be entered within one minute.

How can I customize the expiry of my messages with Plivo?

You can set the expiry time for each message with our send message API by passing the parameter message_expiry. Its default value is 10,800 seconds (three hours); you can set the expiry time to be 5 to 10,799 seconds. 

When Plivo dequeues each message to send it to the carrier, we evaluate the time it has spent in Plivo’s messaging queue and compare that value with the expiry interval. If the elapsed time is more than the expiry period of the message, we mark the messages as failed and don’t charge for it.

What does Plivo recommend for message expiry values?

If your use case revolves around authentication, set message expiry to a value of between 60 and 600 seconds, depending on the time your application allows for a value to be input. For less time-sensitive use cases, such as promotional messaging, you can keep the default value of three hours or lower it to one hour (3,600 seconds).

Setting a too aggressive message expiry period might mean your messages don’t reach your customers, so choose your expiry period based on the upper limit of when the message will be useful.

You can check for message expiry by filtering your message log for an error code of 420.

If you see messages expiring frequently, you might be sending too many messages in too short a period, beyond the allowed limit for your account or number type. Your customer success manager or our support team can help you resolve the issue.

Sign up for a free Plivo account, and register for or log in to a Bitrix24 account. Then search for Plivo in the Bitrix24 Marketplace, and install Plivo by clicking on the Install button.

• . 

You'll then be redirected to the Plivo Application page. Enter your Plivo Auth ID, Auth Token, and sender ID details. Save the details, then click on the Test SMS button to validate the integration. 

Please note that sender ID refers to the source number. You can rent a Plivo US/Canada number if the destination number is a US/Canada number.   

Test and validate

Once you're done with the implementation, you can test the setup from the Test SMS page. You can trigger a test SMS message by entering a destination number and message content. 

Note: 

• You can trigger bulk SMS messages to multiple recipients by providing a list of destination numbers separated with the delimiter "<" (e.g. 14156667777<14157778888<14158889999).
• Bitrix24/Plivo integration supports only outbound SMS.

All messages, regardless of whether they were successfully delivered, count toward these limits. If, for example, a customer attempts to send 25,000 messages on the first of the month, the first 500 messages will be sent and the remaining 24,500 will be blocked because of the daily limit. However, all 25,000 messages will count toward the weekly and monthly limits. Any attempt to send more messages the following day will fail with error code 960 because of the weekly limit.

The day resets at 12:00 midnight PST, while the week resets on Sunday at 12:00 midnight PST. A month refers specifically to a calendar month.

These limits apply only to US destinations. All messages toward Canada have been required to be sent from verified numbers since October 1, 2022.

How can I submit a verification request for a toll-free number?

To submit a verification request, fill out the Plivo Toll-Free Verification form. If you can’t access the form, or you need to submit verification requests for multiple numbers, download this spreadsheet, fill out the necessary information, and create a ticket with our support team.

• The details you enter in the form should apply to the business that will be sending out the messages. This means that if you’re submitting a toll-free verification request on behalf of a customer, the form information for fields such as use case and opt-in flow should apply to the customer.
• You don’t need to provide message samples for every message you plan to send, but we recommend that you provide enough samples to be representative of most of your messaging traffic.
• Snowshoeing is strictly prohibited on toll-free numbers. If your business has a legitimate requirement for using multiple numbers for the same use case, provide a clear and detailed justification in the Use Case field.
• Any images you uploaded (for opt-in workflow, for instance) should be clear and in JPG or PNG format.

The verification process may take up to six weeks; the process is outlined in our documentation. We’re working on reducing this time. 

What if I want to change the content of a message on a verified toll-free number?

If you change the content of a message on a verified toll-free number, you must submit a new verification request to update the content; this ensures that messages with the revised content will not be not filtered by the network.

Can I port a verified toll-free number to another carrier?

You can obtain a toll-free number from any vendor and have it verified. If you port the number to a different vendor, you must submit a new request for verification.

To include line breaks in messages sent from Plivo, you may need to encode the newline escape sequence "\n" in your code. Here’s an example of how this works:

curl -X POST https://api.plivo.com/v1/Account/<auth_id>/Message/ \
  -u <auth_id>:<auth_token> -H 'Content-Type: application/json' \
  -d '{  "src" : "14845355114", 
  "dst" : "14845355111"  , 
  "text": "Here is my first line\nHere is my second line" 
}'

This example sends an outbound message from the sender (484) 535-5114 (+14845355114) to the recipient at (484) 535-5111 (+14845355111), and includes the message:

Here is my first line
Here is my second line

In your own applications, you can use similar syntax, updating several <variables> and strings:

• Line 1 — your Auth ID
• Line 2 — your Auth ID and Auth Token
• Line 3 — a valid sender/from number
• Line 4 — a valid destination number
• Line 5 — the desired message text

We support inbound SMS in the following countries:

Australia
Austria
Belgium
Canada
France
Netherlands
Sweden
United Kingdom
United States

We support outbound SMS in more than 200 countries.

A promotional SMS message is sent with the objective of promoting a product or service. These are sales and marketing messages which may or may not be solicited by the recipient.

A transactional SMS message is sent to customers with the purpose of passing on information necessary for using your product or service. For example: 

• Messages sent for two-factor authentication or one-time passwords
  
• Notifications regarding a product or service used by a customer, such as an appointment reminder

Customers can generate Message Detail Record (MDR) reports directly from the Plivo console. 

 To find your MDRs, log in to your account. Navigate to SMS, then Logs. Filter the logs by clicking on Filter Logs. From the drop-down list select either "Select MDRs on this page" or "Select all MDRs," then click Export.

If the logs are of downloadable size, the file will automatically be downloaded to your device. If the logs are too large, exported logs will be emailed to your registered email address.

The information included in your MDR export includes: 

For a downloaded file:

Message UUID

From

To    

To Country ISO2

Direction    

Message Time    

Status    

Error Code    

Error Reason    

Units    

Rate Per Unit (USD)    

Carrier Surcharge Per Unit (USD)    

Total Charge Per Unit (USD)    

Total Charge (USD)

For an emailed file:

Message UUID

From    

To    

Direction    

Time    

Status    

Units    

Amount    

Message Rate    

Message Charge

We retain MDRs in our transactional databases for 90 days.