General

VoIP (Voice over Internet Protocol) technology has become increasingly popular in recent years as a way to conduct voice communication over the internet. A VoIP number is any number that doesn’t terminate on a physical handset.

In contrast with comparable technology on the public switched telephone network (PSTN), messaging on VoIP lines is not commonly supported. Unlike phone calls, which use standard protocols such as SIP (Session Initiation Protocol), VoIP messaging has no agreed-upon protocol that allows different VoIP systems to communicate with each other via text.

Carriers in the US require that businesses that send application-to-person (A2P) messages register (in the case of local long code numbers) or verify (for toll-free numbers) their source numbers. 

You can check what numbers are registered or verified via the Filter box on the Plivo console. Go to Phone Numbers > Active and click on Filter. 

Filtering long codes

In the drop-down menu, tick “10DLC Status” to filter long code numbers.

Long code numbers may have one of three possible statuses.

• Completed: These numbers are linked to a 10DLC campaign and require no next steps.
• Processing: These numbers are in the process of being linked to a 10DLC campaign.
• Unregistered: These numbers have yet to be linked to a 10DLC campaign.

You can also filter long codes via the AccountPhoneNumbers API using the filter tendlc_registration_status.

Read our 10DLC documentation to learn more about the process.

Filtering toll-free numbers

To filter toll-free numbers, tick “Toll-free SMS verification.”

Toll-free numbers may have one of three possible statuses.

• Verified: These numbers are verified and require no next steps.
• Pending Verification: These numbers are being reviewed by carriers. 
• Unverified: These numbers require verification. 

You can also filter toll-free numbers via the AccountPhoneNumbers API using the filter toll_free_sms_verification.

Read our toll-free documentation to learn about sending limits and the process for verification.

Exporting a list of filtered numbers

You can export the list of numbers that match your filtering criteria. Tick the box at the top of the rightmost column to select all (or tick individual numbers if you prefer), then from the Choose Action drop-down select Export CSV.

If you have unregistered long codes or unverified toll-free numbers and you intend to use them for messaging, Plivo recommends you to register and verify these numbers.

For long codes:

• Register brands and campaigns for yourself and your end customers. 
• Identify the source numbers that you use to send messages and ensure that those numbers are linked to campaigns.
• You can also automate the registration process using the Plivo 10DLC API.

• • Get started with the Quickstart Guide.
  • Check out the documentation for more information.

For toll-free numbers, follow this process to complete verification.

Plivo is responsible for ensuring that its platform not be used for illegitimate activities. To stay compliant with local laws and regulations, Plivo checks the traffic on its phone numbers to detect and block illegitimate activities.

We may take action against a virtual number or a customer account if we discover a violation of Plivo’s Terms of Service and Acceptable Use Policy (AUP). Plivo’s carriers and local operators alert us to AUP violations based on the local laws and regulations in the destination countries for any of the numbers as well. We also monitor for specific traffic signatures — for example, numbers predominantly used for unapproved traffic patterns such as inbound messaging-only usage with receipts of large-scale verification codes or one-time passwords from online platforms. 

Plivo reserves the right to disconnect numbers or block accounts, depending on the severity of the violation, if we find evidence to suspect that a customer is using Plivo’s numbers for illegitimate activities.

Local phone numbers in the US and Canada follow a specific format. Let’s look at an example phone number: 1415906XXXX. This number can be broken down into four parts: 

• 1: Represents the country dialing code 
• 415: Numbering plan area code of the phone number (NPA)
• 906: Exchange code (NXX)
• XXXX: Line number or subscriber number

All local phone numbers in the US and Canada follow this notation: (1) NPA NXX <Line>.

Each of these NPANXX combinations is assigned to a rate center that defines the boundaries of local calling and subsequent billing. Calls between phone numbers belonging to the same rate center are considered local calls and are subject to local calling rates, whereas calls between different rate centers might be subject to long distance calling rates.

Some important points to note here: 

• Each rate center has multiple NPANXX combinations associated with it. 
• Each NPANXX is uniquely associated with one rate center.
• A single NPA might be mapped to multiple rate centers, so using numbers with the same NPA does not guarantee local calling rates.

We at Plivo try to provide a variety of phone numbers to our customers, but we cannot guarantee the availability of all NPANXXs. A local_calling_area filter in our phone number search API lets users search for phone numbers that match the local calling requirement for a particular NPANXX prefix. 

The Unrented phone numbers screen allows customers to view and, if available, reclaim unrented phone numbers from the last five days. 

If you wish to reclaim phone numbers that were unrented past the five-day timeframe, please reach out to Plivo support. Availability of unrented numbers is not guaranteed.

Phone numbers that are reclaimed using the Unrented phone numbers screen are subject to the same charges as a new phone number purchase.

If you mistakenly unrented or released a phone number in the last five days, you can reclaim that number by clicking on the Unrented phone numbers section in the console and selecting Buy Number for the phone number of choice.

Any phone numbers you reclaim using the console are subject to the standard charges and prerequisites that are applied when you purchase a new phone number.

Availability of unrented phone numbers is on a best-effort basis and is not guaranteed.

High-quality, well-formatted content is more likely to be opened and less likely to be mistaken as spam by consumers, operators, and carriers. Follow these guidelines to make sure your SMS content meets basic standards for great messaging in the US. 

As a general rule, carriers don't preapprove or whitelist messaging content. A carrier may review any message content as part of an account review. Message content flagged by automatic spam detection algorithms will be reviewed by a human operator. If the human operator decides the message is promotional, the sending number may be blocked by the operator platform. To prevent this, use the following guidelines for creating messages. 

Content creation

These best practices make messages more valuable to consumers and less likely to trigger real-time content analysis from messages flagged incorrectly as spam.

If the message is reviewed by a third party, out of context, it should appear to be a transactional, application-to-person message, originating from a specific request by the end user. 

In general, message content should include:

• Your company name
• A reference to the reason the message is being sent
• A STOP message

While a STOP message does not need to be included in every message sent, consider sending it with every fourth or fifth message. 

Message content should avoid:

• Generic URL shortener links 
• The words “Free,” “Now,” “Offer,” “Winner,” or any other promotional-sounding language.
• Requests for action without specifying context.

Sample messages

Example: Good content

Plivo — your one-time passcode is 12345.

DeliveryFoodsInc — your food order has been completed and is on its way. Look for it in 15 minutes. Track your order via our app: https://realurl.com/?id=12345. Reply STOP to opt out of future notifications.

Hi, {Name}, and thank you for requesting more information from {CompanyName}. The content you requested is available at https://realurl.com/?id=12345. Reply STOP to opt-out.

Example: Bad content

Click here to get a FREE quote about your home! Lowest APR! https://urlshortener.com/?id=12345

Bad credit? Still get approved for a home! Click here for free finance options. https://urlshortener.com/?id=12345

Download our app {appname} now to get $20 in free credits. https://appstoreurl.com/myapp

Click now to accept your special offer before it expires. https://urlshortener.com/?id=12345

Use one recognizable number

Each campaign should use one primary phone number. We recommend using a single number for both text and voice calls.

Use one recognizable domain name  

Each campaign should be associated with a single web domain. Although a full domain is preferred, a URL shortener may be used to deliver custom links.

Use natural language

You should use natural language in your messages, which means that you should avoid nonstandard spellings (“H! h0w ar3__you do1ng?”).

Direct consent 

You should collect the consumer consent yourself. Don't use consent acquired from a third party. Consumers expect a relationship with the businesses with which they interact.

Set expectations for message frequency 

You should set the proper expectation with the consumer for message frequency. If you plan to send five texts a month, then disclosing “5 messages a month” on the first interaction leads to a better user experience.

Disallowed content

If a message sender is observed sending any of the kinds of disallowed content listed below, Plivo will perform an account review. This review can result in the suspension of sending rights for a provisioned phone number; restriction of high-throughput access, suspension of provisioning rights for new phone numbers, and/or suspension of all network services.

Message senders are expected to enforce restrictions on their own networks to prevent these types of content at the intake source.

Promotional messages

Promotional messaging is not allowed on toll-free numbers and is subject to blocking.

Phishing

Phishing is the practice of sending messages that appear to come from reputable companies but in fact trick consumers into revealing personal information, such as passwords and credit card numbers.

Fraud or scam 

Any messages that constitute fraud or scam and involve wrongful or criminal deception intended to result in financial or personal gain are prohibited. These messages generally involve money and/or some sort of business transaction.

Deceptive marketing 

Marketing messages must be truthful, not misleading, and, when appropriate, backed by scientific evidence in order to meet the standards set by the Federal Trade Commission’s (FTC) Truth In Advertising rules. The FTC prohibits unfair or deceptive advertising in any medium, including text messages.

Sensitive content

Messages that contain terms related to the following sensitive topics are inspected closely and are more susceptible to carrier blocking:

• Debt restructuring/refinancing offers
• Debt relief offers
• Payday loan offers
• Home loan offers
• Education loan offers
• Insurance quotes (unsolicited) 
• “Earn money from home” job offers

Carrier monitoring

Our carriers continuously monitor text messages sent over their networks. To ensure uninterrupted service, please avoid incurring a high number of consumer complaints and a high opt-out rate.

Consumer complaints 

Major operators in North America support consumer-driven spam controls. Their mobile subscribers can forward unwanted or unconsented text messages to the short code 7726 (it spells “SPAM” on a standard keypad).

Carriers actively monitor consumer complaints sent to this service. If multiple complaints are received for a sender, then a notification is sent to the message sender that includes the source phone number, destination phone number, timestamp, and original message ID. Upon receipt, the service provider must provide proof of a TCPA-compliant opt-in for those specific messages. They must also provide an overview of the messaging campaign and its opt-in process that the unwanted message was a part of.

If a large number of unwanted or unconsented messages are reported on a source phone number, that number may have its sending rights immediately suspended while opt-in is being confirmed.

Opt-out rate

Opt-out rates are tracked. The daily opt-out rate on a phone number is defined as the total number of unique consumer phone numbers divided by the unique opted-out consumers that were sent messages within a 24-hour period.

If the daily opt-out rate on a sending phone number is 5% or greater, the account is flagged for monitoring. An opt-out rate of 10% or greater on a sending phone number may result in immediate suspension of services.

Toll-free, long code, short code, mobile, and national numbers each have different activation requirements and restrictions. These restrictions depend on carrier and country regulations; Plivo has no control over what you must submit to activate a number.

 You can find activation requirements and restrictions for each country on our global coverage page.

 Verification documents fall broadly into two categories:

1. Address documents: Regulations in some countries require people to provide a valid address when purchasing a phone number. The address should be the residential or business address of the user. Always keep this address updated.
2. Identity documents: Local regulations in some countries require people to provide proof of identity to purchase a phone number. The ID must be that of the user.

Address documents may require a local, national, or international address.

1. A local address requirement requires an address in the same geographic zone where the number is being purchased. For example, if you're purchasing a German local number for Berlin, regulatory authorities will consider only a Berlin address valid.
2. A national address requirement requires an address anywhere in the country where the number is being purchased.
3. An international or global address requirement requires proof of address anywhere in the world.

What kind of documents are preferred for address and identity verification?

• Passport
• Business registration document
• For corporate user: an extract of the company register
• For subscribers: ID plus utility bill (phone, electricity, or gas)

Any account that has a rented phone number, whether it's active or disabled, incurs a monthly fee. This rule applies even if the number isn't being used. If the number isn't being used, you won't pay usage fees. If you close your account, all the numbers associated with that account will be released and the account will be deleted. You can close your account from the profile settings page of the Plivo console.

Accounts that are inactive due to pending verification, or suspended due to detection of fraudulent activity, incur phone number rental fees.

In some countries, telecommunications regulators or national regulatory authorities (NRA) impose restrictions and conditions on the use of telephone numbers. These are legal requirements that should be respected at all times to avoid the risk of having your phone number blocked.

These regulatory bodies may require you to activate your number depending on the type of number and the country. Check if activation applies to you by visiting our coverage page. 

If a number requires activation, a pop-up will notify you of the activation requirements before you purchase the number.

Refer to our coverage page to find activation requirements for a particular number. Gather the documents you need for activation. Activate the number by submitting the required documents on the console's verification tab. You can also upload verification documents using the Plivo API.

If you no longer require a number, you can remove it from your Plivo account through the console or via our API.

To unrent a number through the Plivo console, navigate to Phone Numbers > Your Numbers > Active. Select the numbers that you'd like to remove, then click on the Choose Action drop-down, select Unrent Numbers, and confirm.

Once a number is canceled or removed, the number is reserved for 10 days. After that the number is returned to the carrier and is not retrievable. 

If a number was accidentally canceled, please contact us for help. Our number procurement team can try to get the number back to your account, subject to availability.

You can also delete or remove a rented number using our API.

You can rent or purchase a number through the Plivo console or by using Plivo’s API.

To rent a number from the console, navigate to Phone Numbers > Buy Numbers. Here you can search for numbers by country, prefix, and/or location, and filter numbers based on functionality — such as voice, SMS, and MMS — and type of number, such as local, mobile, or toll-free. Click Search to bring up a list of available numbers. The list shows the number type, capabilities, and fees for every number. In the list of numbers returned, click on Buy Number to add a number to your account.

Note: The activation requirement for a number, if any, will be populated at the time of purchase. 

There's no limit to the number of Plivo phone numbers you can rent, as long as you have sufficient credits in your account. 

Once you've rented a number, it will appear under Phone Numbers > Your Numbers > Active on the Plivo dashboard. 

Numbers are subject to availability. If you're unable to find a number for a specific prefix or location, please create a ticket with our support team.

You can also search for and rent a number through Plivo's PhoneNumber API.

We're constantly expanding our phone number coverage to new countries and phone number types. We have a multistep phone number onboarding process that includes several rounds of internal and real-world testing to ensure that all Plivo numbers meet our high-quality standards. The status of a phone number indicates where the phone number is in this onboarding process.

Each phone number may have one of the following statuses indicated during their onboarding:

1. Preview
2. Beta
3. General availability

Preview

During the first step of onboarding, a new phone number goes through rigorous internal testing. In this phase, the quality of the number is measured across several quality metrics. During this phase a phone number is not available to customers for purchase. If the phone number meets Plivo’s quality standards, the number is marked as “preview.”

Phone numbers with preview status are available to only a limited number of customers on demand. We constantly monitor these phone numbers, as they might experience connectivity and quality issues. 

When these phone numbers have satisfactorily met our quality standards for a limited number of customers, they're moved to beta status.

Beta

Phone numbers with beta status are available to the majority of our customers through the Plivo console, APIs, or on demand. These numbers are relatively new on our platform and have passed all internal testing, but have yet to be tested in the real world.

General availability

Once we receive a significant amount of traffic to a phone number that's in beta status, we move it to general availability. We maintain an inventory of such phone numbers so our customers can buy them at any time via the Plivo console and APIs.

You can check the status of a phone number on our coverage page.

When you rent a phone number from Plivo, you'll notice two charges attached to it: a setup fee and monthly rental fees.

Setup fee

The setup fee is a one-time fee charged at the time of purchase. This fee covers setting up, configuring, and provisioning numbers with our carriers. You can see the setup fee, if applicable, before you procure the number.

Monthly rental fees

Monthly rental fee is charged on a recurring basis, regardless of whether the number is used or not. Plivo uses a monthly billing cycle for phone numbers that starts on the day the number is rented and is renewed on the same date in subsequent months. 

Here are some examples to demonstrate the phone numbers billing cycle in various scenarios. Assume a monthly rental fee of $1 with no setup fee.

Pilvo phone numbers are priced according to their country and type. Visit our pricing page for details.

An application is a set of answering, hangup, and messaging URLs that help you manage and control your incoming calls and messages. You can create an application either from the Plivo console or through the Plivo API.

To create an application from the console, follow these steps:

1. Navigate to Voice > XML > Add New Application.
2. Give a name to the application and fill in the URLs according to the actions you wish to take. Learn more about our application options in our Application reference guide documentation.
3. Click on Create Application.

Assigning a Plivo number to your application

To assign a Plivo number to your application:

1. Navigate to Phone Numbers > Your Numbers > Active.
2. Click on the phone number you want to use.
3. Select XML Application for the Application Type.
4. Select the name of your application from the Plivo Application drop-down.
5. Click on Update Number to save.

Us

Using the API

To create an application through the Plivo API, use the URL https://api.plivo.com/v1/Account/{auth_id}/Application/

For a list of parameters and more details, see our application reference guide documentation.

Plivo offers three types of numbers for you to choose from. This table shows the key differences between them.

What is DID?

DID (Direct Inward Dialing) allows businesses to set up virtual numbers that can go directly to a desk extension or group of extensions. Carriers provide DID for use with their customers' PBX systems, allowing businesses to allocate a personal number to each employee without the need for a physical phone line to connect to the PBX. Callers who have a direct number can bypass an auto attendant and reach their contact via a direct extension.

Setting up DID with Plivo

To set up DID with Plivo, create an application by visiting the XML Applications page and click on Add New Application. You can also set up your DID programmatically by using Plivo’s Application method. See our documentation for more information.