General

A caller ID (CLI) is assigned when you make a call. The phone number is 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 as-is on the receiver’s device. 

Plivo guarantees domestic caller IDs in the following countries:

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

We are working towards supporting domestic caller IDs across more geographical regions. 

Dual-tone multi-frequency tones are audio call signals that are usually transmitted over voice frequencies. A very common use case is to have DTMF tones for interactive voice responses (IVRs) and during conferencing. These are tones that are generated when you push a regular phone’s keys. 

As of now, Plivo does not provide DTMF support in China. 

Plivo caches audio files specified in <Play> XML and Play API based on standard clientside caching directives for RESTful communication over HTTP.

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

The cache-control response header

Responding with 'Cache-Control:no-store' will ensure Plivo doesn't maintain a local copy of the file in its cache. It will always request your web-server for the resource. Responding with 'Cache-Control:no-cache' will ensure that Plivo will always check to see if the file has changed. 

Responding with 'Cache-Control: max-age=<new max-age value in seconds>' informs Plivo to use a locally cached copy of a returned audio file for a definite 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 directly 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 webserver 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.  Simply trigger 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 the call. CDRs can be accessed via our API and through your 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, this information is included in the payload sent to the hangup_url specified for the associated Plivo Application.
• For calls initiated using <Dial> XML, this information is included in the payload of DialHangup events sent to the Dial callbackUrl.

For the comprehensive list of possible hangup causes and hangup sources, check out our documentation here.

The PreAnswer element answers the incoming call in early media mode. This is useful when you want to play custom tunes or to 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. Learn more in the guide at the link: https://api-reference.plivo.com/latest/python/elements/preanswer

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 early media (PreAnswer) as it's not a part of the WebRTC specifications.

You can make an outbound call to the SIP URI of the Plivo application you have 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 an SIP endpoint that’s attached to your Plivo application in the ‘Endpoint’ tab. Share this endpoint with others, not the SIP URL of your application.

If you face any 4XX error or 5XX error while triggering an API request for an outbound call or SMS, or when the application is executed during an inbound call or SMS, then your application could be having an issue. 

Please find below the typical error logs and their descriptions. 

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

If you get inbound calls from numbers listed as UNKNOWN, ANONYMOUS, or UNAVAILABLE, the originating carrier for a specific call is passing through these labels instead of showing the real number. Calls from such numbers are common if the caller is using a VOIP service. 

CNAM can only be set up for US Plivo numbers. The CNAM database is currently available only in the United States. 

CNAM registration works differently for long codes and toll-free numbers. While the CNAM can be registered for toll-free numbers, there is no guarantee that CNAM will work even after registration.

Long codes: each long code number has a tag (the Destination Point Code) that lets the receiving phone carrier knows which national CNAM database to pull the CNAM from. 

Toll-Free: toll-free numbers do not have a tag (Destination Point Code). As a result, the receiving phone carrier can only pull a CNAM from its own internal database. Even if Plivo does register your CNAM, it will not work if the receiving phone carriers do not update their database. This is an industry-wide restriction.

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, please reach out to our Support Team.

Some hard phones, softphones, and phone numbers are capable of displaying the 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 hard phones and have caller ID name support, you can set up the caller name using the “caller_name” attribute in the HTTP API. Please refer to this guide for details: https://api-reference.plivo.com/latest/python/resources/call/make-a-call

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. Read more in this guide: https://api-reference.plivo.com/latest/python/elements/dial 

Calls to phone numbers

We currently 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. Please create a ticket with Plivo Support for more detail.

A non-Plivo number can be used as the caller ID for outbound calls. Please use the following API:  

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

From attribute

This attribute acts as the caller ID for the outbound call, Please use a valid phone number as the ‘from’ number which will be displayed as the caller’s number to the call recipient. For more information, please refer to this guide: https://www.plivo.com/docs/api/call/#arguments 

You can achieve the results using the PHLO. 

CLI stands for Caller 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. Please read our guide about how to set up caller ID here: https://www.plivo.com/docs/getting-started/dynamic-caller-id/ 

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. The first of these calls to answer will be connected to the current caller, while the rest of the connection attempts are canceled. You can combine endpoints and phone numbers in one XML.

 <Response>

    <Dial>

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

      <Number>15671234567</Number>

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

    </Dial>

</Response>

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

You can integrate sequential dialing using a Dial XML. 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 will be to the number 18217654321 with a timeout value of 30 secs. That means if the call is not answered by 18217654321 within 30 seconds, then the call will be redirected to the second number, 15671234567. You can combine endpoints and phone numbers in the same XML.

Example: 1

<Response>

    <Dial timeout="30" action="http://foo.com/dial_action/">

        <Number>18217654321</Number>

     </Dial>

     <Dial>

         <Number>15671234567</Number>

      </Dial>

</Response>

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

Example: 2

<Response>

    <Dial timeout="30" action="http://foo.com/dial_action/">

       <Number>18217654321</Number>

    </Dial>

    <Dial>

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

    </Dial>

</Response>

Sequential calling can be achieved through the PHLO as well.

A callUUID is required to check which XML was executed during your 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 from here https://console.plivo.com/dashboard/.
2. Click on “Logs”.
3. Click on the timestamp of the relevant call which you want to debug. A new window will pop up with the UUID.

The second way to get your UUID is by using the get all call details API: https://www.plivo.com/docs/api/call/#get-all-call-details 

To find the call_UUID for a certain call, use this API to deliver a GET HTTP request to the call detail records (CDRs). This will find information about your calls along with the details of each call. After getting the call_UUID, navigate to: https://console.plivo.com/voice/logs/debug/?next_id=&page=1&type=all and input the call_UUID 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, as well as to debug the call from your end. 

During an outbound call made using Plivo, an HTTP API error means that your request is unable to be processed and Plivo will be unable to execute the call. During 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 with Plivo GetInput XML. GetInput XML enables the real-time capture and transcription of the speaker's voice. 

To learn more about Automatic Speech Recognition with GetInput XML, check out the detailed reference documentation here.

To debug a call, please follow these steps: 

1. Get the call_UUID from your dashboard logs (https://console.plivo.com/voice/logs/calls/) or by using the API in this guide: (https://www.plivo.com/docs/api/call/#get-all-call-details)
2. Navigate to this page: https://console.plivo.com/voice/logs/debug/?next_id=&page=1&type=all.
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 is used on the call to handle the call flow which will help you debug the call from your end. 

When you make a call using Plivo, a universally unique identifier (UUID) will be assigned to the call to identify and troubleshoot if there is a voice-related or call-related issue.

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.     Login to your Plivo dashboard from: https://console.plivo.com/dashboard/.
2.     Click on “Logs”.
3.     Click on the timestamp of the relevant call which you want to debug. A new window will pop  up with the UUID

The second way to get your UUID is by using the get all call details API: https://www.plivo.com/docs/api/call/#get-all-call-details 

To find the call_UUID for a specific call, use this API to make a GET HTTP request to the call detail records (CDRs). This will deliver information about your calls along with 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 one type of DTMF.

Out-of-band  

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

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/

The audio file can be shared through a remote URL. Plivo supports .mp3 and .wav file formats. The preferences for .mp3 and .wav files are as follows.

MP3:

The .mp3 file should be formatted with the following settings: MPEG ADTS, layer III, v1, 128 kbps, 44.1 kHz, JntStereo

WAV:

The .wav file should be formatted with the following settings: WAVE PCM, 8,000 Hz 16 bit or 11,025 Hz 16 bit PCM

Learn how to set up an audio file in this tutorial: https://www.plivo.com/docs/getting-started/play-mp3-audio-to-caller/ 

Frequently asked questions

1. Does Plivo process or modify a customer's audio file?

No, we don't modify the audio file before playing it.

2. What happens if the .mp3 or .wav specs don't match the preferences mentioned above? Will Plivo still process that file?

Yes, but the quality may not be as clear as expected. 

3. What happens if the .mp3 is set at 193 kbps? Will the audio be of poor quality?

We should be able to play this file as it is, but can't guarantee the audio quality. We advise you to configure the file withing the suggested parameters mentioned above.

To set up the call forwarding application, you need to set up an XML response using the <Dial> element. A demo call forwarding app can be found under the “Application” tab in your Plivo dashboard.

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

You can also use our demo application which is available in your account. Look for the application named “call forward.” 

Answer_URL of the application: 

http://callforward.herokuapp.com/forward/?Numbers=NUMBER_1_HERE,NUMBER_2_HERE 

Number 1: the primary destination

Number 2: the failover destination

Add the priority destination and failover destination so that the inbound calls to the Plivo DID can be forwarded to a set destination. You can also forward calls to an SIP endpoint using the same URL:

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

Example: 

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

You can also refer to the step by step instructions available here. 

The same use case can also be achieved using the PHLO. Please read more at this link. 

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

<Response>

    <Hangup reason="rejected" />

</Response>

Yes, you can disconnect a specific call and keep all other outbound calls active by using the following API: 

DELETE https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/

Note: if the CallUUID is not specified, all live calls for that particular account will be disconnected.

Please refer to the guide at the link for more detail on how to disconnect a specific call. https://www.plivo.com/docs/voice/detailed-reference/api/call/hangup-a-call/ 

Call status details are posted on your web server from the Plivo platform. Here, you can find detailed call information, including: 

• From_number
• To_number
• Start time
• End time

We will post call details to your web server (database) configured in any of the following URLs.

• Answer_URL: Details are posted when the call is answered. 
• Hangup_URL: Details are posted when the call is ended. 
• Action: Details are posted if an action( attribute) is defined in the dial XML element. 
• Callback_URL: Details are posted if the callback_URL is defined in the XML element when the call is answered. 

Based on these parameters, you can identify the call status. For more detail, refer to the following guides: 

https://www.plivo.com/docs/xml/dial/#action-request-parameters

https://www.plivo.com/docs/xml/dial/#callbackurl-request-parameters

https://www.plivo.com/docs/xml/request/#request-parameters

https://www.plivo.com/docs/xml/request/#call-status 

The status of a call on Plivo is sent to the requested URLs under the CallStatus key. Decisions can be made by your app to process a call based on this status.

Plivo will classify a call status as one of the following categories under the CallStatus parameter.

1. In-progress: string

The call has been answered and is currently in progress. Calls under this status can be explicitly terminated using the Hangup API.

2. Completed: string

The call has been completed. It’s either terminated using the Hangup API or ended by one of the parties in the call.

3. Ringing: string

The call is currently ringing. This status is sent to the Ring URL.

4. No-answer: string

The call hasn't been answered by the callee. Your application must have the logic to parse this parameter and take action.

5. Busy: string

The callee is busy on a different call. You should wait and retry the call. 

6. Cancel: string

The call has been canceled by the callee without answering.

7. Timeout: string

There was a timeout while connecting your call. This is either an issue with one of the terminating carriers or network lag in our system.

A call flow can be changed during a live call by using Plivo’s Call Transfer API. This API enables an in-progress or active call to transfer to a different URL and fetch and execute XML from a new URL. Read more here:

https://www.plivo.com/docs/api/call/#transfer-a-call 

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

Yes, calls can be made without buying a number from Plivo. However, there are certain restrictions. 

• Only outbound calls can be made.
• You cannot receive calls as you are not using a Plivo number.

Please click on the link below to use our API to make calls: POST https://api.plivo.com/v1/Account/{auth_id}/Call/

The variable “from” in this field acts as the caller ID for making the outbound call. Please use a valid phone number in “from”. 

Plivo’s API supports bulk calling. Use the following command to make bulk calls:

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

The auth_id can be procured from your dashboard: https://console.plivo.com/dashboard/

There are three mandatory requirements that must be met to make an outbound call. 

The “from” requirement

The “from” requirement refers to the phone number that can be used as the caller ID (with the country code). For example, a US caller ID number could be, 15677654321, where '1' is the country code.

The “to” requirement

Use the regular number(s) or SIP endpoint(s) to place a call. A regular number must be prefixed with country code but without the + sign.

Using the REST API:

Multiple numbers can be sent by using a delimiter. To make bulk calls please use the delimiter “<”

For example: 15677654321<12077657621<12047657621..1

Regular numbers and SIP endpoints can be added together in a bulk call. 

For example: 5677654321<15673464321<sip: john1234@phone.plivo.com 

Using an SDK:

Every language has its own defined syntax to use for bulk calling. Please refer to this page for a guide for each language: https://github.com/plivo 

The “answer_url” requirement

This refers to the URL invoked by Plivo when the outbound call is answered. 

To add additional options on the API, please refer https://www.plivo.com/docs/api/call/#arguments 

You can make an outbound call using the following API with the help of a REST client.

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

The auth_id can be found in your dashboard: https://console.plivo.com/dashboard/

There are three mandatory requirements that must be met to make an outbound call.  

from (mandatory)  

The phone number to be used as the caller ID (with the country code). For example, a USA caller ID number would look like 15677654321, where '1' is the country code.

to (mandatory)

Use the regular number(s) or SIP endpoint(s) to make a call. Regular number must be prefixed with country code but without the + sign. For example, to dial a number in the USA, the number would look like 15677654321, where '1' is the country code. 

SIP endpoints must be prefixed with SIP – for instance,  sip: john1234@phone.plivo.com. 

answer_url (mandatory)

This is the URL invoked by Plivo when the outbound call is answered.

To add additional options on the API, please refer to this guide:  https://www.plivo.com/docs/api/call/#arguments