SMS

1. Getting Started With The Plivo Lookup API

Plivo’s Lookup API allows users to query phone number information including number validation and formatting, carrier information, and the portability information associated with a phone number. Continue reading for an overview of the Lookup API, how it works, and answers to frequently asked questions.

This guide covers the following information:

• Submit A Lookup API Request
• Where Does Lookup Data Come From?
• How Is Phone Number Validity Determined?
• What Are The Carrier Lookup 'type' Values? 
• Are There Geographic Support And Limitations?
• Can I Process Simultaneous Lookup API Requests?
• Does Lookup Cache Response Values?  

Submit A Lookup API Request

To Lookup a phone number, your application needs to make an HTTP GET request to Plivo’s Lookup REST API resource with the phone number you wish to lookup. Here's a simple cURL script example:

curl -i --user auth_id_ID:auth_token \
https://api.plivo.com/v1/LookupNumber/{number}?info=serviceprovider

This example will look up to the phone number (204) 999-9999(2539999999 inline 1 of the code sample). It should return the following response:

{
	"api_id": "ac073f08-xxxx-xxxx-xxxx-c19435b84cd7",
	"country": {
		"name": "Canada",
		"code_iso2": "CA",
		"code_iso3": "CAN"
	},
	"number_format": {
		"e164": "+12049999999",
		"national": "(204) 999-9999",
		"international": "+1 204-999-9999",
		"rfc3966": "tel:+1-204-999-9999"
	},
	"service_provider": {
		"mobile_country_code": "XXX",
		"mobile_network_code": "XXX",
		"name": "Carrier Name",
		"type": "Number_type",
		"ported": "true_or_false"
	}
}

Notice: The Lookup API will return an HTTP 404 status with a response containing "code": 20404 when a phone number is determined invalid. For full details, see the section How is phone number validity determined.

Where Does Lookup Data Come From?

Lookup utilizes a variety of authoritative sources to return the most accurate response for a given Lookup type. See more details on each Lookup type below:

How Is Phone Number Validity Determined?

The lookup will return an HTTP 404 status code if a phone number resource is invalid. Phone number validity is based on international phone numbering plan data administered by the ITU. Though the ITU should in theory have all global numbering plans on file, in practice, not every country will file their numbering plans with the ITU. Additionally, some government authorities may let telecom companies be responsible for administrating numbering plans. As a result of this lack of centralization, maintaining an accurate global numbering plan is a patchwork process. Plivo works with a variety of carrier partners to maintain accurate global numbering plan data but discrepancies can arise as numbering plans change and downstream providers must propagate these changes.

What Are The Carrier Lookup 'type' Values?

In the response for a Carrier Lookup, the type property specifies whether the phone is a landline, mobile, or VOIP phone.

• landline (aka 'fixed' or 'wireline') and mobile (aka 'non-fixed' or 'wireless') are service type designations provided by the carrier who owns the number.
• VOIP is a classification of the carrier.

Please note, since VoIP phone numbers are easier to obtain, they are sometimes used for fraudulent purposes. Customers often use Lookup to screen these numbers in their applications.

Are There Geographic Support Limitations?

While the Lookup API is supported internationally, there are limitations to some request types:

Phone number validation and formatting: Number validation and formatting lookups are supported in all countries worldwide.

Carrier Lookup: This is supported worldwide with the following caveats:

• The VOIP type will only be returned for carriers in the U.S. It is not supported outside of the U.S.

• The mobile and landline types can be returned to all countries worldwide.

• The mobile_country_code and mobile_network_code fields are returned for 90+ countries where mobile number portability is supported. For more information, see Why does the Mobile Country Code (MCC), Mobile Network Code (MNC) not show up for my phone number lookup?

Can I Process Simultaneous Lookup API Requests?

The Lookup API only handles a phone number per request. For more information and recommendations, see Sending multiple requests to Plivo Lookup API.

Does Lookup Cache Response Values?

Lookup does not cache any response values.

2. Sending Multiple Requests To Plivo Lookup API

4. What Numbers Can I Get Lookup API Details For?

Sometimes a Unicode character such as a smart quote ( 〞), a long dash (—), or Unicode whitespace accidentally slips into your carefully crafted 125 character message and now your message is segmented and priced at two messages instead of one.

When Unicode characters are used in an SMS message, they must be encoded as UCS2. UCS2 characters take 16 bits to encode though, so when a message includes a Unicode character, it will be segmented at 70 characters instead of 160 characters per message segment.

The Messaging Service Smart Encoding feature helps detect those easy to miss Unicode characters and replaces them with a similar GSM encoded character. This helps ensure that your message gets segmented at 160 characters and saves you from sending two messages.

Messages that include emoji or language-based characters such as kanji are not transliterated with Smart Encoding. Please reference this list for the Unicode characters Smart Encoding will replace.

1. What’s changing with Verizon Toll-free phone numbers?

Similar to A2P 10DLC (local numbers), Verizon is going to start charging an additional surcharge fee of $0.0025 for every outgoing SMS message segment on Toll-free phone numbers. 

2. How does the pass-through fee on Verizon Toll-free impact me?

This new surcharge means that you will start paying a pass-through fee on Toll-free numbers. As a result, they will no longer be as cost-effective as A2P 10DLC.  

To break it down:

• The outbound charge for local numbers is $0.0050/sms, compared to $0.0058/sms for Toll-free. 

• The Verizon pass-through fee is an additional $0.0025/sms, for both long codes and Toll-free numbers.

• In total, you will pay $0.0083 for Toll-free A2P, vs $0.0075 for A2P 10DLC. That is a 10.7% increase in cost.
  

3. But deliverability on Toll-free A2P is higher, so it makes sense that the cost is higher?

While historically, Toll-free numbers had a higher messaging throughput rate and deliverability, long codes now provide the same benefit. 

Verizon opened up A2P routes on long codes specifically to extend long codes’ usability to commercial A2P messaging (alerts, appt reminders, chatbots, notifications, marketing/customer loyalty purposes). 

A2P 10DLC will have lower monthly costs, are sanctioned by the carrier networks, will be much faster to provision, and are in par with the high deliverability of Toll-free numbers.

4. What do I need to do?

There will be no change to your account or services. As soon as Verizon enables these surcharges, we will pass through this fee at no additional upcharge. To ensure transparency, this fee will appear as a separate line item on invoices. 

5. Does this apply to MMS?

At this time, this new surcharge only applies to Outbound Toll-Free SMS messages. Please note that for A2P 10DLC, Verizon is charging an additional surcharge fee of $0.005 for every outgoing MMS message segment.

6. Are the requirements, routing logic, and rate limits the same for A2P long codes and Toll-free on Verizon?

With the messaging space continuing to change at such a rapid speed, we are doing our best to stay informed and keep you up-to-date as soon as we receive any news. We assume that they work the same way, but haven’t gotten confirmation yet from Verizon. We will update this FAQ as soon as we have that information.

7. Are providers outside of Plivo subject to the same pass-through fee on Verizon Toll-free?

All providers--not just Plivo--are impacted equally by this pass-through fee.  

8. What about other mobile networks? Are they also implementing a surcharge for their Toll-free numbers?

Right now, only Verizon is putting forth a surcharge for its Toll-free phone numbers. AT&T has recently announced that all commercial long code messaging to AT&T’s network will need to be sent via their new 10-digit long code (10DLC) A2P service, starting August 15th, and will incur the same surcharge. We believe that Toll-free numbers on AT&T will follow suit and that similar fees will be added for terminating long code and toll-free traffic on other carrier networks in the coming months (T-mobile/Sprint).

9. What if I have additional questions?

We value your continued business with Plivo. If you have any questions, please feel free to contact your Account Executive or our Support Team.

No, you can only set your Plivo number as the source number for messages going to the US and Canada due to telecom regulations. You can, however, make an outbound voice call using Plivo’s APIs with a non-Plivo caller ID.

Dynamic sender IDs (i.e. non-Plivo numbers) may be used as the source number for messages directed to international destinations. However, we cannot guarantee that the source number displayed to the message recipient will match the number which was originally used. 

Authorizing Plivo to view your SMS content helps our customer success teams debug content-related delivery issues for your account. 

Messages can be marked as “Spam” by network carriers because of many reasons. Content policy violations are among the most common reasons why a carrier will flag your message. Plivo’s customer success team can help avoid being marked as spam by:

1. Suggesting changes to your SMS content to abide by regional content policies. 
2. Helping you find a better-suited SMS product for your SMS traffic (long code, shortcodes, toll-free etc.)
3. Raising issues with our downstream carriers to fix unexpected delivery failures.

You can withdraw your consent at any time by visiting your Plivo Console and reviewing your SMS settings.

Note: Outbound and inbound SMS messages for which log redaction has been requested will not be visible to customer success teams regardless of this preference.

Mobile subscribers who reply with a "STOP" message to your Plivo number are considered opted-out. Any subsequent SMS to these phone numbers are blocked by Plivo. If you attempt to send a message to an opted-out customer, these messages will be marked failed with error code 200. 

However, you may acknowledge the receipt of a "STOP" keywords from the customer to let them know that they have been opted-out. Plivo allows you to send outbound messages to opted-out customers with the following conditions: 

• The acknowledgment SMS should be sent under five mins of receipt of "STOP" keyword from the subscriber.
• At most, one SMS is allowed to be sent to opted-out customers.  

Outbound messages will be labeled as "failed" with Plivo error code 900 and will not be forwarded to our downstream carriers. Following this error code, for the next two mins, all send message API requests will fail with the error "Insufficient Credit". This is to ensure that the customer can take necessary action before queuing any more messages in Plivo.

Note: All messages that are already queued in Plivo's system will continue to be marked "failed" with error code 900 as and when they are dequeued for processing until required credits are added to the account.

Plivo is a pay-as-you-go API platform. Plivo relies on its extensive carrier network to deliver messages successfully. In some cases, messages may be sent by Plivo that are not received by the end-user. Plivo charges for messages that are successfully 'sent' out of the Plivo platform. 

Do I get charged for inbound messages when the message_url or message_method is not specified?

Yes. Inbound messages are free for long codes but are chargeable on toll-free and shortcodes, even without the message_url or message_method configured. In this case, the inbound message state will be set as received.

A unique feature of Plivo’s REST APIs is that you can send bulk SMS messages using a single API request. To send bulk SMS, make an HTTP POST request to the Message API. This request is similar to sending a single outbound SMS, but with the additional step of adding multiple DST destination numbers by separating each phone number with the "<"character.

POST https://api.plivo.com/v1/Account/{auth_id}/Message/

Getting started:

1. Sign up for a free Plivo trial account.
2. Check out our server-side SDKs page and install the right helper based on the programming language you want to use.
3. Buy a Plivo phone number (optional). Note: A phone number is required only for sending SMS to US and Canadian phone numbers. Country-specific carrier conditions may still apply. You can buy a US or Canadian phone number through the Buy Numbers tab in your Plivo account menu.
4. Use a web hosting service to host your web application. There are many inexpensive cloud hosting providers that you can use for just a few dollars a month. Follow the instructions of your hosting provider to host your web application.

Note: If you are using a Plivo Trial account for this scenario, you can only send SMS messages to phone numbers that have been verified with Plivo. Phone numbers can be verified through the Sandbox Numbers page.

Implementation

1. Copy the relevant code below into a text file and save it.
2. Replace “Your AUTH_ID” and “Your AUTH_TOKEN” with the AUTH ID and AUTH TOKEN found on your Plivo dashboard.
3. Add your src (source) phone number. This will show up as your sender ID. Be sure that all phone numbers include the country code, area code, and phone number without spaces or dashes (e.g., 14153336666). Note: You can send SMS text messages to any country using the Message API and set any src number, except for US and Canadian numbers. In order to send text messages to phones in the US or Canada, you will need to purchase a US or Canadian phone number from Plivo and use it as the src number. You can buy a Plivo number from the Buy Numbers tab on your Plivo account dashboard.
4. Add your DST (destination) phone numbers. These are the phone numbers you wish to send SMS text messages to. To send messages in bulk, separate your destination phone numbers with the delimiter "<"(e.g., 14156667777<14157778888<14158889999). Note: If you are using a trial account, your destination number needs to be verified with Plivo. Phone numbers can be verified on the Sandbox Numbers page.
5. Edit the text field with your SMS text message. Note: text messages that are longer than 160 characters are concatenated and billed separately as individual text messages.

After completing these steps, make the HTTP POST request to Plivo. If successful, Plivo will queue your SMS and deliver it to your recipients at a base rate of one message per second. Please note that delivery is handled separately for each message. 

Pro-tip: check out our full Message API guide to see all the parameters and functionalities you can use to bulk send SMS.

Prerequisites

1. Sign up for a free Plivo trial account OR login to your Plivo account. 
2. Check out our Helper Library page for information on how to install the right helper based on the programming language you want to use.
3. Buy a Plivo phone number. A phone number is required to receive and reply to SMS text messages. You can buy a Plivo phone number in over 19 countries through the Buy Numbers tab on your Plivo account menu. Check the SMS API coverage page for all the supported countries.
4. Use a web hosting service to host your web application. There are many inexpensive cloud hosting providers that you can use for just a few dollars a month. Follow the instructions of your hosting provider to host your web application.

Set up a web server

For this example, let’s assume your web server is located at http://example.com. The following snippet will set up a route on your web server. Now, when we send an HTTP request to http://example.com/receive_sms, this route will be triggered.

Create an application

1. Create an application by either visiting the Application Page and clicking on “Add New Application” or by using Plivo’s Application API.
2. Give your application a name. For this example, let’s call it “Receive SMS”. Enter your server URL (e.g. http://example.com/receive_sms) in the message URL field and set the method to POST. See our Application API guide to learn how to modify your application through our APIs.
3. Click on “Create Application” to save your application.

Assign a Plivo number to your app

1. Navigate to the Numbers page and select the phone number you want to use for this app.
2. Select “Receive SMS” (the name of the app) from the Plivo App dropdown list.
3. Click on “Update Number” to save

If you don’t have a number, go to the Buy Number page to purchase a Plivo phone number.

Test it out

Send an SMS to your Plivo number using a regular mobile phone. Plivo will send a request to your Message URL.

An inbound message is categorized in two distinct stages: received and delivered/undelivered.

1. Received

Plivo receives an inbound message from a carrier. The user is charged for the inbound message. If the message_url or message_method is not configured in the user’s application to the number that receives the message, the message remains marked as “received.”

2. Delivered/Undelivered

Once Plivo receives the message, it sends a callback to the message_url. Based on the response Plivo gets, the message gets recategorized as either delivered or undelivered.

• Delivered: the message_url is valid and active. After sending a callback to the message_url, the state of the message is set as ‘delivered’.
• Undelivered: the message_url is invalid, inactive, or not responding. Plivo will retry callbacks for the next 24 hours. Please check this guide for retry interval timings. If all callbacks fail, the status of the message will be set as ‘undelivered’.

Plivo’s APIs support concatenation; however, some carriers and handsets do not support long SMS concatenation. Here’s how SMS concatenation works and what you can expect from carrier restrictions.

When sending a long SMS, Plivo’s Messaging API automatically breaks long SMS text messages into multiple SMS’s and adds a concatenation header to each message so that it can be stitched together (i.e., concatenated) on the recipient’s mobile device.

Plivo supports sending SMS in all text-based languages (e.g., English, French, Chinese, Arabic, etc.). As a result, text messages in any language will be automatically concatenated. Plivo’s Helper Libraries automatically encode messages into Unicode UTF-8 as needed.

How does Plivo charge for concatenated messages?

Long SMS text messages that are over the character limit are concatenated and billed separately as individual text messages.

For example, check out the screenshot linked below. This message was divided into four units, with each unit costing USD 0.00250. The total amount to send this message was USD 0.01000.

How does Plivo handle delivery reports for concatenated SMS text messages?

DLRs for long messages are processed the same way they are for single unit messages. Only one Message Delivery Report (MDR) is generated for long messages. Only one DLR is raised for the message.

Plivo’s APIs support sending SMS in all text-based languages (e.g., English, French, Chinese, Arabic, etc.).

Messages containing only GSM03.38 seven-bit characters have a maximum limit of 1600 characters. Messages that are longer than 160 characters will be split into multiple messages with each message consisting of a maximum of 153 characters.

Messages containing one or more UCS-2 16-bit Unicode characters have a maximum limit of 737 characters. Messages longer than 70 characters will be split into multiple messages, with each message consisting of a maximum of 67 characters. The list of Unicode characters can be found here: https://unicode-table.com/en/#control-character

Multi-unit messages are automatically stitched back together and delivered as a single message in countries where mobile networks support long message concatenation.