General

Your call was disconnected because you attempted to use a caller ID that is part of the US Telecom 'Do Not Originate' list. These numbers typically belong to government agencies or financial institutions and are designated for inbound calls only. They can only be used by authorized personnel.

Calls per Second (CPS) refers to the limit on the number of calls your account can send or receive within one second. These limits are categorized into outbound and inbound calling, each with its own threshold. By default, upon signing up, we assign an outbound CPS limit of 2 and an inbound CPS limit of 10. To view your current inbound and outbound CPS allocations, visit the Voice Overview page in the Plivo console and check the Account section.

Outbound CPS

For outbound calling, CPS represents the maximum rate at which calls can be initiated using APIs for your specific account. It's important to note that outbound CPS limits apply solely to calls made via APIs and do not affect calls made using the Dial XML element.

When you exceed your allocated outbound CPS, your additional calls won't be dropped. Instead, they will be queued and dispatched once the CPS rate drops below your set limit. While you can maintain as many concurrent calls as your servers allow, the initiation rate of these calls is governed by your account's CPS allocation.

Examples:

• Scenario 1: If your outbound CPS limit is set to 10 and you initiate 10 API calls within one second, all 10 calls will be executed simultaneously without any delay.

• Scenario 2: If your outbound CPS limit is 10 and you attempt to place 12 API calls in one second, the first 10 calls will be executed immediately. The remaining 2 calls will be queued and executed in 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.

How does CPS differ from Concurrent Calls?

Understanding the distinction between CPS and concurrent calls is essential for effective call management.

CPS refers to the rate at which calls are initiated or received per second. It controls how many new calls can start each second, focusing on the speed of call initiation or reception. For example, if your outbound CPS limit is 10, you can initiate up to 10 new calls every second.

On the other hand, concurrent calls refer to the total number of active calls happening simultaneously at any given moment. This number depends on your server capacity and system resources rather than being directly controlled by CPS limits. For instance, if each call lasts five minutes, having a high number of concurrent calls means your system is handling many ongoing calls at the same time, regardless of the CPS rate at which they were initiated.

Example to Illustrate the Difference:

Imagine you have an outbound CPS limit of 10 and you initiate 10 API calls in one second:

• From a CPS perspective, all 10 calls are initiated simultaneously within that second.
• From a concurrent calls perspective, if each call lasts five minutes, you now have 10 active concurrent calls ongoing.

If you initiate another 10 API calls in the next second:

• The CPS allows these new 10 calls to be initiated immediately, adhering to the CPS limit.
• The total number of concurrent calls increases to 20, assuming none of the previous calls have ended.

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. If a non-Plivo IN number is used as the Caller ID, the calls will be processed on a best-effort basis, and Plivo cannot provide support for any issues. To ensure reliable service, Plivo strongly recommends using a Plivo IN number for outbound calls.

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. 

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.

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.

China has strict regulations on calling traffic to ensure all communications are legal and safe. Below are the traffic types that are not allowed:

• Gambling or any other form of betting and funded games of chance.
• Financial services, including money transfer, payment, investment, or any financial-related activities.
• Bitcoin and other cryptocurrency trading systems, as well as non-approved investment schemes.
• Promotion and marketing calls (spam).
• Fraudulent calls, such as "fake police," fake bank, or fake shipping company calls.
• Any calls involving politically sensitive topics.

Customers who need to make outbound calls to China should submit their use case and business requirements to Plivo Support or Sales for evaluation.

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 your application encounters 4xx or 5xx status codes while making an API request for an outbound call or SMS, or during an inbound call or message execution, it may indicate an issue. Refer to our documentation for a detailed list of common HTTP status codes, Plivo error codes, and their explanations.

To proactively monitor such issues, you can set up Voice Alerts on Plivo. Voice Alerts actively track voice traffic anomalies in real time and can detect configuration errors that may lead to call failures. These errors can include invalid XML responses or other misconfigurations.

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 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 Update 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 support the CNAM feature.

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

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.

Each long code number has a Destination Point Code, which informs the receiving phone carrier which national CNAM database to use for retrieving the CNAM.

Toll-free numbers do not have Destination Point Codes. The receiving phone carrier can only retrieve a CNAM for a toll-free number from its own internal database. Even if Plivo registers your CNAM, it will only be effective if the receiving phone carriers update their databases accordingly. In other words, you can register a CNAM for a toll-free number, but there is no guarantee that the CNAM will display. This is a limitation across the entire industry.

You can map your organization's CNAM to one or all of your Plivo phone numbers from the Plivo console. Use the API or console to update your CNAM. 

To update from the Plivo console, go to the Phone Numbers page and select the phone numbers you want to provide a name. Click on the Choose Action dropdown and select Add CNAM. Enter a name (up to 15 characters; allowed characters are A-Z, a-z, 0-9, and spaces) and click Submit CNAM. The numbers’ CNAM registration status on the console will change to “In Progress.” Check back to see whether your registration request was a success, partial success, or a failure.

To update using Plivo’s API, use the Update A Number API and provide a name in the ‘cnam’ argument.

After a CNAM is registered, the name will be displayed on the recipient’s handset if the end operator and the handset supports the CNAM feature.

In case you have any questions, reach out to our support team.

Yes, you can make outbound calls without purchasing a Plivo number by using Plivo’s Bring Your Own Carrier (BYOC) feature or Verified Caller ID.

1. Bring Your Own Carrier (BYOC):
   • If you have an existing telecom carrier, Plivo’s BYOC feature allows you to use your own carrier for outbound calling while leveraging Plivo’s platform for call control and routing.
   • This ensures flexibility and seamless integration with your current telecom setup.

2. Verified Caller ID:
   • Register your number through the Plivo Console or using Plivo’s REST APIs or SDKs.
   • Receive a one-time password (OTP) via SMS or voice for verification.
   • Enter the OTP to complete the verification process.
   • Once verified, your number will be added to the Verified Caller ID list.
   • Use the verified number as the outbound caller ID without renting a Plivo number.

Calls using a non-Plivo number without Verification/BYOC will fail with an "Unknown caller ID" error. 

Refer to our Verified Caller ID guide for more information.

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. 

Billing for outbound calls in Plivo depends on whether the call was successfully connected.

If Plivo returns an HTTP response error, the request cannot be processed, and the call is not dialed. No charges will be applied. 

Codes that indicate an HTTP response error include: 

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

If Plivo successfully processes the request and initiates the call, You will be charged for the duration of the call, since a connection was established.

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. 

1. What is a call UUID?

A call UUID is a universally unique identifier assigned to each call you make using Plivo. This identifier helps you track and troubleshoot specific calls.

2. Where can I find the UUID for a specific call?

You can find the UUID for a call using one of the following methods:

a. Use the Plivo Dashboard:

• Log in to your Plivo dashboard.
• Navigate to Voice > Logs > Calls.
• Click on the timestamp of any call to view the call’s insights, including the UUID.

b. Use Plivo’s Voice API:

•  Use Plivo’s Voice API to retrieve call details.
• Create a GET HTTP request to the Call Detail Records (CDR) endpoint.
• This request will return information about each call, including the UUID. 

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.