Skip to main content

General

  • Does Plivo cache audio files specified in the <Play> XML and Play API?

    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.

  • How do I cancel a queued outbound API call?

    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. 

  • How do I determine the cause for a call hangup?

    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.

  • What is PreAnswer? How accurate is it?

    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.

  • Can I make an outbound call to the SIP URI of a Plivo application?

    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.

  • How do I know if my application is having an issue?

    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
  • Why am I getting calls from numbers listed as “unknown”?

    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. 

  • Can I set up CNAM for all my Plivo phone numbers?

    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.

  • Can I use my company name or a custom name as my caller ID?

    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.

  • How do I use a non-Plivo number as the caller ID for outbound calls?

    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

  • What is CLI?

    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/ 

  • How do I implement simultaneous dialing?

    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.

    Screenshot__10_.png

  • How do I implement sequential dialing?

    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.

    Screenshot__9_.png

  • How do I check which XML was executed during my call?

    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.

    Screenshot__6_.png

    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:

    Screenshot__7_.png

    Screenshot__8_.png

    Check the XML document used on the call to handle the call flow, as well as to debug the call from your end. 

  • If Plivo encounters an error during a call, will I be charged?

    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
  • Do you support speech recognition?

    No, Plivo doesn’t support speech or voice recognition as of now.

  • How do I debug a call from dashboard logs?

    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. 

    Screenshot__7_.png

    Screenshot__8_.png

    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. 

  • What is a call UUID?

    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

    Screenshot__6_.png

    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.

  • What type of DTMF does Plivo support?

    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.

  • What audio file formats can I play on a call?

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

    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.

    1. 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. 

    1. 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.

  • How do I set up a call-forwarding application?

    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

  • How can I reject an incoming call?

    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>

  • Can I disconnect a specific outbound call and keep others active?

    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/ 

  • How can I learn the status of 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 

  • What do the different call statuses mean?

    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.

  • How do I change the call flow of an ongoing call?

    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}/

  • Can I make outbound calls without buying a Plivo number?

    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”. 

  • How to make a bulk call using a single API

    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 

  • How do I make calls using the outbound call API?

    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 

  • How to calculate the cost of a call?

    To calculate the cost of a call, you will need to factor in the following elements: 

    1. The usage (the length and direction of the call)
    2. The phone number
    3. The prefix
    4. The duration of a call

    Example: Outbound call with regular number

    Here’s an example illustrating how to calculate charges for an outbound call to a UK number.

    • The prefix is ‘4420’
    • The call duration is 70 seconds.
    • The outbound pricing for UK numbers with prefix “4420” is $0.0031/min.
    • The cost for call would be: $0.0031+ $0.0031= $0.0062.
    • The cost of a phone number in the UK is $.80 per month
    • Total cost = $0.8062

    Note: the phone number is charged on a monthly basis. The above charges are just an example.

    It is not obligatory to purchase a phone number from Plivo to make an outbound call.

    Detailed pricing information is available on the Plivo pricing page.

    Example: Toll-free number

    Plivo supports outbound calls using a toll-free number only in the USA and Canada. Here’s an example of making an outbound call using a toll-free number in the US.

    • The prefix is “1907”
    • The call duration is 70 seconds.
    • The outbound pricing for US numbers with prefix “1907”: $0.1790/min.
    • The cost for call: $0.1790+ $0.1790= $0.358.
    • The cost of a phone number in US: $1.00 per month
    • Total cost = $1.358.

    Note: The phone number is charged on a monthly basis. The above charges are just an example. It is not obligatory to purchase a phone number from Plivo to make an outbound call if you already have an existing toll-free number.

    Detailed pricing information is available at the Plivo pricing page.

    Example: Inbound call with a regular number

    Let us consider an example of an inbound call in the United Kingdom.

    • The call duration is 70 seconds.
    • The inbound pricing for a UK regular number: $0.0050/min
    • The cost for an inbound call is $0.0050+ $0.0050= $0.01
    • The cost of a regular phone number in the UK is $0.80 per month
    • Total cost = $0.81.

    Note: the phone number is charged on a monthly basis. The above charges are just an example.

    It is mandatory to purchase a phone number from Plivo for an inbound call.

    Detailed pricing information for inbound calls is available on the Plivo pricing page.

    Additional features at no extra cost

    At Plivo we provide loads of add-on features at no additional cost:

    1. Call recording and storage
    2. Multilingual text to speech
    3. Automatic machine detection
    4. Dynamic caller ID

    However, there is an additional cost for call transcription: 

    • Auto transcription is $0.05/Min.
    • Hybrid transcription is $0.35/Min.