General

Calls per second (CPS) refers to limits on your account for sending and receiving calls. The limits differ for outbound and inbound calling. By default, we assign an outbound CPS limit of 2 and an inbound limit of 10 at signup time. You can find your allocated inbound and outbound CPS by visiting the Voice Overview page of Plivo console and looking in the Account section.

Outbound CPS

For outbound calling, CPS represents a limit on the rate at which calls are initiated for a specific account. Outbound CPS applies only to calls made using APIs; it does not apply to calls made using the Dial XML element. 

If you exceed your allotted outbound CPS, your calls will not be dropped; instead, they will be queued and dispatched once the CPS rate falls below the limit.

You can maintain as many concurrent calls as your servers permit, but the rate at which calls are placed adheres to the allocation in your account. Here are a couple of examples.

Scenario 1: If a user has an allocated outbound limit of 10 CPS and places 10 API calls in a second, all 10 calls will be executed simultaneously.

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

Inbound CPS

For inbound calling, CPS represents a limit on the rate of inbound calls to Plivo numbers, and also to the rate of outbound calls originating from SIP and browser clients. (The term "inbound CPS" is used because outgoing call requests from SIP and browser clients are essentially inbound requests to Plivo.) Calls that surpass the specified inbound CPS limit based on the above criteria are rejected with SIP code 486.

Can I increase my allocated CPS?

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

Domestic calling is a better choice than international calling if your calls originate and terminate in India. It provides several advantages.

• The call media path is shorter, which means lower latency and better audio quality.
• Outbound callers can get better recognition with assured local caller ID.
• Pricing is attractive, and INR billing is available.

Requirements

Businesses should be aware of several requirements for domestic calling in India.

Caller ID — Outbound calls must originate from the caller ID of an India Plivo phone number.

Media anchoring — Media anchoring requires the media of the call to reside in the same country as the phone call. Simply put, the media cannot leave the country; your calls should originate from and terminate to users in India. If a domestic call leg is bridged with an international call leg, the call will fail with hangup cause “Violates Media Anchoring.”

Business KYC — You must submit know-your-customer (KYC) documentation before you can rent India phone numbers and make and receive calls from your Plivo account. Submit a support ticket and attach the following documents as image files in PNG or JPG format.

For all new Plivo accounts, only US and Canada are geo-enabled for calling. Calls made to other destination countries will fail with hangup - Destination Country Barred.  

You can modify the country permissions under Voice > Geo Permissions on the Plivo console. This is a security feature. Carefully enable the countries where you intend to make calls and keep the rest of the countries disabled. 

For more information on voice geo-permissions, please visit the dedicated FAQ section. 

KYC — Know Your Customer — is a set of guidelines intended to verify a customer’s identity. Plivo requires customers to provide KYC information so that we can comply with STIR/SHAKEN call authentication requirements.

The US Federal Communications Commission (FCC) began requiring carriers to implement call authentication by adopting the new STIR/SHAKEN standards in June 2021. STIR (Secure Telephone Identity Revisited) and SHAKEN (Signature-based Handling of Asserted Information Using toKENs) are technical frameworks that measure trust in the displayed caller name and number by authenticating the calling number. 

To comply with STIR/SHAKEN and authenticate a call, Plivo needs to know some facts about a customer’s business, such as:

• Company name
• Company website
• Business registration number and documents that provide proof of registration
• Nature of the business
• Use case for Plivo

Because STIR/SHAKEN applies only to US businesses, we do not require KYC information for businesses in countries other than the US.

Customers can generate Call Detail Record (CDR) reports directly from the Plivo console.

To export CDRs generated in the last 90 days

1. On the Plivo console, navigate to Voice > Logs > Calls.
2. Filter the CDRs by ticking the filters you wish to use and clicking on Apply.
   
   
3. Select the logs you want to export by ticking the checkbox for individual CDRs, or choose from the checkbox drop-down options “Select CDRs on this page” or “Select all CDRs.”
   
4. To export the selected CDRs, click on Export, select Export Filtered Results, and click on Export Logs.
   
   

If the logs are of downloadable size, they will be downloaded to your device automatically. If the logs are too large, Plivo will email them to your registered email address.

To export historical CDRs — those generated in last 12 months

1. Log in to your Plivo account and navigate to Voice > Logs > Calls.
2. Click on Export and select Export Historical Data. Select the account or subaccount and the date range for which you want to export CDRs, then click on Export Logs.
   
   

Plivo will email exported logs to your registered email address. 

The following information is included in exported CDRs:

• Call UUID
• Parent call UUID
• From number
• To number
• Call direction
• End time
• Initiation time
• Answer time
• Call duration
• Billed duration
• Call rate
• Billed amount
• Hangup cause
• Hangup cause code
• Hangup source
• Call leg
• Subaccount Auth ID
• Call type
• To country ISO
• From country ISO
• Billing prefix

Note that CDRs older than 90 days have their from and to numbers redacted.

Scam calling is detrimental to the industry, service providers, and end-users. Scammers often use spoof calling line identification (CLI, also known as caller ID) to make it seem as if they’re calling from a legitimate line.

Due to the large volume of spoofed traffic, Australian operator Telstra plans to apply filters for calls terminating toward the Telstra network in Australia and block them if the calling number is also a Telstra number, in accordance with Australian Communications Alliance rules to track, block, and reduce spam calls.

This blocking was expected to commence by the end of November 2021 but Telstra has pushed back the implementation date until 1 March 2022. 

Similar changes are expected to be adopted by other Australian operators; Telstra is the first. 

How will Telstra’s implementation impact Plivo customers?

• Outbound calls originating out of the Plivo’s network that have a source number that’s a valid Telstra number terminating to another Telstra phone number will get blocked. 
• Calls will be rejected if the calling number (CLI) prefixes include +6113, +611300, +611800, or +611900. 
• Calls from international calling numbers that have a missing or invalid format will be blocked. 
• CLIs that are too short or too long, unallocated country codes and regions, and unallocated Australian CLIs will also be blocked. 
• “Wangiri” calls (identified in real-time) will also be blocked. In the Wangiri scam (also known as the one-ring scam), a scammer typically places a call and causes it to disconnect after a short ring time, usually less than 10 seconds. 
• Calls using anonymous as the calling number will be blocked. 

What can you do to ensure your services are not disrupted?

1. If you have a Telstra number and want to continue to use it as the caller ID for making outbound calls to Telstra users, you can port your number to Plivo or a different provider of your choice. Please note that a port request might take up to three weeks. 
2. You can rent new Australia numbers from the Plivo console or by using our Numbers API. See our pricing page for monthly rates. 

You can read more about Plivo phone number features and capabilities in Australia on our coverage page.

What are the restrictions on outbound calling toward China?

• Chinese numbers cannot be used as “from” numbers for outbound calling purposes.
• Plivo recommends ensuring an average call duration of three minutes or more. Strict spam monitoring and general restrictions on VoIP in China mean that numbers involved in calls of less than three minutes have a high probability of being blocked.
• If you have a high volume of unanswered outbound calls, it’s likely that calls will be blocked.
• Don’t make calls from modified, spoofed, or restricted origination numbers.
• Avoid high volumes of repeated calls from the same origin number within one hour.
• Don’t use a toll-free number, as your calls will be blocked.

What are the restrictions on inbound calling toward China?

Chinese numbers can be called only from international, non-Chinese numbers. Any inbound calls with a Chinese caller ID will fail.

A caller ID or calling line identity (CLI) is assigned when you make a call, and it's transmitted to the caller’s phone. In the case of a domestic CLI, it applies to in-country calls.

When a country or region is supported for domestic caller IDs, the caller ID is the "From" number displayed on the receiver’s device. 

Plivo guarantees domestic caller IDs in these countries:

1. United States
2. Canada
3. United Kingdom
4. Australia
5. Peru

We're working toward supporting domestic caller IDs across more geographical regions.

Dual-tone multi-frequency (DTMF) tones are audio call signals that are usually transmitted over voice frequencies. They're the tones that are generated when you push a regular phone’s keys. They’re commonly used in interactive voice response systems (IVR) and audio conferencing.

Plivo does not provide DTMF support in China.

Plivo caches audio files specified in a <Play> XML element and Play API method based on standard client-side caching directives for RESTful communication over HTTP.

You can control whether an audio file should be cached on Plivo servers and for how long using the cache-control and e-tag response headers.

The cache-control response header

Responding with Cache-Control:no-store ensures Plivo won't maintain a local copy of the file in its cache and will always make a request to your web server for the resource. Responding with Cache-Control:no-cache will ensure that Plivo always checks to see whether the file has changed. 

Responding with Cache-Control: max-age=<new max-age value in seconds> tells Plivo to use a locally cached copy of a returned audio file for a defined period of time. Plivo will consider its cached copy outdated only after the specified number of seconds (max-age value). For example: responding with Cache-Control: max-age=14400 will ensure Plivo uses the cached copy for the next four hours.

The e-tag response header

The e-tag value of a resource is typically an MD5 hash or some other fingerprint of the contents of the file. 

Plivo sets the If-None-Match request header to the e-tag value of the resource in its cache, allowing your web server to respond with a new version or with a 304 Not Modified message to instruct Plivo to use its cached version. This enables a more efficient resource update check, as no data is transferred if the resource has not changed.

Every Plivo media server maintains its own local cache. Therefore, the first call landing on any Plivo media server will always result in a cache miss.

You can cancel queued outbound calls using the Hangup A Call API method by triggering the Hangup API with the request UUID that was generated for the queued call. 

The cause for a call hangup and the hangup source information is available in the Call Detail Record (CDR) of a call. CDRs can be accessed via our API and through the Plivo console. Hangup information is also included in callback requests sent on call hangup.

• For outbound API calls, the hangup information is included in the payload sent to the hangup_url specified in the Make Call API request.
• For incoming calls, the information is included in the payload sent to the hangup_url specified for the associated Plivo Application.
• For calls initiated using the <Dial> XML element, the information is included in the payload of DialHangup events sent to the Dial callbackUrl.

For a comprehensive list of possible hangup causes and hangup sources, see our documentation.

The PreAnswer element answers an incoming call in early media mode — that is, at a time when the calling and answering SIP user agents communicate before the SIP call is actually established. This is useful when you want to play custom tunes or use specified text dynamically while the call is still in an unanswered state.

You can nest Speak, Play, and Wait elements within the PreAnswer element.

PreAnswer is not guaranteed to work for every destination. It’s not supported by every carrier due to regulations and abuse-prevention protocols. Therefore, there aren’t many steps you can take to increase the accuracy of the PreAnswer. Please note that the WebRTC SDK does not support PreAnswer because early media is not a part of the WebRTC specifications.

You can make an outbound call to the SIP URI of a Plivo application you've created. For example, you can make an HTTP POST request to originate an outbound call to "sip:example@app.plivo.com," which is the SIP URI used to identify the Plivo application.

If you’re expecting to receive calls to your SIP URI, you must create a SIP endpoint that’s attached to your Plivo application by visiting Voice > Endpoints in the Plivo console. Share this endpoint, not the SIP URL of your application.

If you face any 4xx error or 5xx status codes while triggering an API request for an outbound call or SMS message, or when an application is executed during an inbound call or message, then your application could be having an issue. Check our documentation for a list of common HTTP status codes and Plivo error codes and descriptions of what they mean.

If you get an inbound call from a number listed as UNKNOWN, ANONYMOUS, or UNAVAILABLE, the originating carrier is passing through that label instead of showing the real number. Calls from such numbers are common if the caller is using a VoIP service. 

A caller ID name (CNAM) can only be set up for US Plivo numbers. The CNAM database is available only in the United States. 

CNAM registration works differently for long codes and toll-free numbers.

Long codes: Each long code number has a Destination Point Code that lets the receiving phone carrier know which national CNAM database to pull the CNAM from. 

Toll-Free: Toll-free numbers do not have Destination Point Codes, so the receiving phone carrier can only pull a CNAM for a toll-free number from its own internal database. Even if Plivo registers your CNAM, it will not work if the receiving phone carriers don't update their databases. In other words, while you can register a CNAM for a toll-free number, there's no guarantee that the CNAM will work after registration. This is an industry-wide issue.

You can map your organization's CNAM to one or all of your Plivo phone numbers from the Plivo console. Go to the Phone Numbers page, tick the phone numbers you’re interested in providing a name for, then click on the Choose Action dropdown and choose Add CNAM. Enter a name (up to 15 characters) and click Submit CNAM. The numbers’ CNAM status on the console will change to “In Progress.” Within a short time the numbers’ status will change to show whether your submission was a success, partial success, or a failure.

After a CNAM is registered, the CNAM will be displayed on the destination handset if the end operator and the handset supports the CNAM feature.

To check if your Plivo number has a CNAM feature, reach out to our support team.

Some hardphones, softphones, and phone numbers are capable of displaying a caller’s name on the screen during an incoming call. You can set up a caller name (your company name, business name, or a custom name) for calls to such phone numbers or endpoints.

Calls to endpoints

For outbound calls to endpoints that are registered with softphones or hardphones and have caller ID name support, you can set up the caller name using the caller_name attribute in the HTTP API. Refer to our API reference guide on making a call for details.

For inbound calls that are redirected from your Plivo DID to an endpoint registered to a softphone or hard phone with caller ID name support, you can make use of the “callerName” attribute available in the dial XML element.

Calls to phone numbers

We support the CNAM feature only for calls made to US phone numbers. A phone number (Plivo DID) must be registered in the CNAM database for such calls to display a custom name.

You must use Plivo phone numbers as the caller ID for your outbound calls. We no longer support using a non-Plivo number as the caller ID. We’ve implemented this restriction to prevent fraud and ensure compliance with the guidelines set by our operators.

If you attempt to use a non-Plivo number as the caller ID for outbound calls, your calls may fail with a hangup cause of “Unknown caller ID.” Our documentation provides more information on Voice API hangup causes.

You have two options to obtain Plivo numbers: You can rent numbers through the Plivo console or use our Buy a Phone Number API to acquire new numbers. If you have existing numbers, you can port them to Plivo, ensuring seamless connectivity for your outbound calls.

If you have a use case that requires the use of a non-Plivo number as the caller ID, please contact our support team for assistance. We’ll help you find a solution that meets your requirements.

CLI stands for calling line identification. CLI identifies and displays the telephone numbers of incoming calls made to a particular line. CLI also transmits a caller's number to the receiver’s telephone equipment.

You can dial out to a list of phone numbers, endpoints, or a combination of numbers and endpoints at the same time using simultaneous dialing. 

The following example shows how to simultaneously call a  list containing two endpoints and one phone number. This will dial out to all the numbers and endpoints mentioned in the XML element. The first of these calls to answer is connected to the current caller, while the rest of the connection attempts are canceled. You can combine endpoints and phone numbers in one XML element.

 <Response>

    <Dial>

      <User>sip:alice1234@phone.plivo.com</User>

      <Number>12025551111</Number>

      <User>sip:john1234@phone.plivo.com</User>

    </Dial>

</Response>

 The same result can be achieved through PHLO by using call forwarding with parallel dialing.

You can integrate sequential dialing using a Dial XML element. Add a list of phone numbers, endpoints, or a combination of numbers and endpoints so that the calls are sequential for each recipient one after the other. 

The following example shows sequential calls to a list with two numbers. The first call goes to the number 12025551111 with a timeout value of 30 seconds. That means if the call is not answered by 12025551111 within that time, then the call will be redirected to the second number, 12025552222. You can combine endpoints and phone numbers in the same XML element.

Example 1

<Response>

    <Dial timeout="30" action="https://yourdomain.com/dial_action/">

        <Number>12025551111</Number>

     </Dial>

     <Dial>

         <Number>12025552222</Number>

      </Dial>

</Response>

The second example shows sequential calling to a list containing one number and one endpoint. The first call goes to the number 12025551111 with a timeout value of 30 seconds. If the call is not answered by 12025551111 within that time, then the call will be redirected to the endpoint sip:john1234@phone.plivo.com.

Example 2

<Response>

    <Dial timeout="30" action="https://yourdomain.com/dial_action/">

       <Number>12025551111</Number>

    </Dial>

    <Dial>

       <User>sip:john1234@phone.plivo.com</User>

    </Dial>

</Response>

You can also use PHLO to set up sequential calling.

You can use a call UUID to check what XML code was executed during a call. You can find the call_UUID in two ways. One way is by checking your account dashboard logs:

1. Log in to your Plivo dashboard.
2. Go to Voice > Logs > Calls.
3. Click on the timestamp of the call you want to debug. A new window will pop up with the UUID.

Another way to get a UUID is by using the Voice API to retrieve all call details. It delivers a GET HTTP request to the Call Detail Records (CDR) to retrieve details about each call. Get the call UUID, then navigate to the log debug page and enter it in the search field. This will bring up details of the call in the following format:

Check the XML document used on the call to handle the call flow to debug the call. 

During an outbound call made using Plivo, an HTTP API error means that your request is unable to be processed and Plivo is unable to execute the call. In these instances, calls will not be queued and you will not be charged.

These are the error responses that you may receive during an outbound call:

• 400 — A parameter is missing or is invalid
• 401 — Authentication failed
• 404 — Resource cannot be found
• 405 — HTTP method not allowed
• 500 — Server error

Yes. Plivo supports automatic speech recognition through the Plivo GetInput XML element. GetInput enables real-time capture and transcription of a speaker's voice.

Follow these steps: 

1. Get the call_UUID from your dashboard logs or by using the API.
2. Navigate to the log debug page.
3. Key in the call_UUID in the search field. This will give you details of the call, as shown below. 

Check the XML document that's used to handle the call flow to help you debug the call. 

When you make a call using Plivo, a universally unique identifier (UUID) will be assigned to the call to identify the call and help you troubleshoot.

Where do I find the UUID for a particular call?

There are two ways to find the UUID for a particular call. The first is by checking your account dashboard logs:

1.     Log in to your Plivo dashboard.
2.     Go to Voice > Logs > Calls.
3.     Click on the timestamp of the call you want to debug. A new window will pop up with the UUID.

The second way to get a call UUID is by using the Voice API to retrieve all call details.

To find the call UUID for a specific call, use this method to make a GET HTTP request to the Call Detail Records (CDR). This will deliver details about each call.

DTMF stands for dual-tone multi-frequency. DTMF is a signaling system that recognizes the keys or numbers dialed on a telephone keypad. The first telephone systems used pulse dialing signaling. Later, the system was updated to multi-frequency (MF) dialing. 

DTMF is a multi-frequency tone dialing system used by the keypads in landline and mobile phones to deliver the number or key dialed by the caller. DTMF has allowed long-distance signaling of called numbers in voice frequency ranges over telephone lines. This has removed the need for telecom operators to switch between a person calling and the person receiving a call

At Plivo we support only out-of-band DTMF.

The incoming stream delivers DTMF signals out-of-audio using the RFC-2833 mechanism, independently of codecs. In other words, the DTMF signals are sent separately from the actual audio stream.

Plivo supports .mp3 and .wav file formats. We recommend that an .mp3 file should be formatted with the settings: MPEG ADTS, layer III, v1, 128 Kbps, 44.1 kHz, JntStereo. A .wav file should be formatted with the settings: WAVE PCM, 8,000 Hz 16 bit or 11,025 Hz 16 bit PCM.

If your audio file specs don't match these recommendations, Plivo will still process the file, but the quality may not be as clear as you'd like.

Plivo doesn't process or modify an audio file before playing it.

You can play an audio file to a participant by using either the play API or the play XML. 

• XML: https://www.plivo.com/docs/xml/play/ 
• API: https://www.plivo.com/docs/api/call/play/

Read more about how to pay audio on calls in our Voice API Reference documentation.

To set up a call forwarding application, you need to set up an XML response using the <Dial> element.

The logic of call forwarding is simple. First, you receive an incoming call to your Plivo number. Plivo looks for the answer_url from the call forwarding application with which the number is associated. The answer_url should respond to Plivo’s request with an XML document that states which number or endpoint to forward the call to.

You can find a demo call forwarding app in the dashboard under Voice > Applications > Call Forward. The Primary Answer URL on that page is

http://callforward.herokuapp.com/forward/?Numbers=NUMBER_1_HERE,NUMBER_2_HERE, where Number_1 is the primary forwarding destination and Number_2 is a failover destination.

You can forward calls to a SIP endpoint using the same URL with the Users argument:

http://callforward.herokuapp.com/forward/?Users=SIP URI

Example: 

http://callforward.herokuapp.com/forward/?Users=sip:Yoda180329161554@phone.plivo.com

Read more in our Getting Started with Call Forwarding guide, which also talks about how to set up call forwarding using PHLO.

You can hang up an incoming call using the <Hangup> XML element. The application attached to the Plivo number must return a <Hangup> element, along with an applicable reason attribute to end the call.

<Response>

    <Hangup reason="rejected" />

</Response>