General

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. Italy
6. 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 knows 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.

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 can use a non-Plivo number as the caller ID for outbound calls by making a POST to the Call object. The From attribute acts as the caller ID for the outbound call and is displayed as the caller’s number to the call recipient.

You can achieve the same results using PHLO. 

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

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 goes to the number 18217654321 with a timeout value of 30 seconds. If the call is not answered by 18217654321 within that time, 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>

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>

Yes, you can disconnect a specific call and keep all other outbound calls active by using the Call object with a DELETE verb and specifying a call_uuid. If you don't specify a call_uuid, all live calls for the account will be disconnected.

Plivo posts call details to the web server configured in any of these 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. 

Call status is among the details posted. For more information, refer to our documentation on Voice XML requests, Using Callback URL, and Call Status.

See our Voice XML Reference documentation for a list of call status values and explanations of each.

You can change a call flow during a live call by using Plivo’s Call object. You can transfer an in-progress or active call to a different URL and fetch and execute XML from a new URL.

Yes, but you can only make outbound calls. You cannot receive calls without a Plivo number. For API syntax, see our Voice API Reference Guide.

See our Bulk Call use-case guide for complete details.

See the Make Outbound Calls guide in our documentation for details about how to make outbound calls using the Voice API in Node.js, Ruby, Python, PHP, .NET, Java, Go, or PHLO, Plivo's visual workflow design studio.