Overview

    Introduction

    Plivo’s Voice API platform gives you the power to integrate voice calling into your applications. This API allows you to make, receive, and control calls across the world. Plivo offers a rich set of programmatic building blocks that can be used to add voice communication to your existing products and workflows. With Plivo’s APIs and SDKs, you can:

    • Make phone calls to any phone number in the world.
    • Receive phone calls on virtual phone numbers purchased through Plivo.
    • Make internet calls to and from IP endpoints connected through Plivo’s Browser, iOS & Android SDKs, or through third-party softphone clients.
    • Control the experience on connected calls in real-time using Plivo XML and APIs to perform actions like playing a prompt or dial and connect the call to another number.

    Types of Calls

    These are the different calls offered on our Voice API platform and how they are set up.

    Outbound API Calls

    Outbound API call

    How does it work?

    1. Your application utilizes Plivo’s Voice API to make an outbound call. The outbound API call requests are queued and processed at two calls per second.
    2. Plivo’s Voice Platform will make a call to the destination number.
    3. Plivo’s Voice Platform will notify your application server as soon as the call is answered.
    4. Plivo will handle the call based on the XML returned by the application server.

    Inbound Calls to Plivo Phone Numbers

    Inbound calls to Plivo number

    How does it work?

    1. The end-user calls your Plivo phone number.
    2. Plivo’s Voice Platform notifies your application server about the call.
    3. Plivo will handle the call based on the XML returned by the application server.

    Forwarded Calls (also known as B-Legs)

    Forwarded calls

    How does it work?

    1. The end-user calls your Plivo phone number.
    2. Plivo’s Voice Platform notifies your application server about the call.
    3. Plivo will handle the call based on the XML returned by the application server. In this case, a Dial XML will forward the call to another number.
    4. A call will be initiated to the phone number user specified in the Dial XML.
    5. Once the call is answered, the two parties will be connected and will be able to talk to each other.
    Note: There are two distinct call legs involved in the above call flow.
    1. A-Leg: The inbound call connection between the caller to Plivo's Voice Platform.
    2. B-Leg: The outbound call from Plivo's Voice Platform to the destination specified in the Dial XML.

    IP Calls from Browsers and iOS/Android Apps

    Outbound calls from Browser App

    How does it work?

    1. An internet call is initiated by a Plivo Endpoint from a Browser/Mobile App to Plivo’s Voice Platform.
    2. Plivo’s Voice Platform notifies your application server about the call.
    3. Plivo will handle the call based on the XML returned by the application server. In this case, a Dial XML will connect the call with the phone number specified in the XML.
    4. A call will be initiated to the phone number specified in the Dial XML.
    5. Once the call is answered, the two parties will be connected and will be able to talk to each other.
    Note: There are two distinct call legs involved in the above call flow.
    1. A-Leg: The internet call between the Browser/Mobile App and Plivo's Voice Platform. These types of calls are categorized as “Client SDK (Browser, Mobile) & SIP calls” on our pricing page.
    2. B-Leg: The outbound call from Plivo's Voice Platform to the destination specified in the Dial XML.

    How to Control Calls Programmatically

    This section covers instructions for using the Plivo XML and an overview of basic call management features through which you can control calls programmatically – i.e., using Plivo’s XML.

    Introduction to Plivo XML

    Plivo’s XML (eXtensible Markup Language) allows you to programmatically provide Plivo’s Voice Platform with instructions to control a call once it is answered. The XML can be used for both outbound and inbound calls. Once a call is answered, Plivo will invoke the answer_url requesting the XML document to process the call. Plivo provides various XML elements that can be used to handle the call flow synchronously and to perform various control actions – actions such as:

    • Playing music while the caller is on hold
    • Reading out a specified text to the caller
    • Accepting numeric inputs and speech inputs
    • Dialing and connecting to another number

    How to Control Outbound API Calls with Plivo XML

    An outbound call is initiated through an API request to Plivo. Once the call is answered, Plivo invokes the application service endpoint given in the answer_url API request parameter. This answer_url must return a valid Plivo XML document that carries instructions to control the outbound call. For example, you can return a Speak XML or Play XML to play a prompt once the call is answered.

    Outbound Call

    How to Control Incoming Calls with Plivo XML

    When an end-user dials a Plivo phone number, the answer_url configured for the Plivo Application associated with the number is triggered. Details about the incoming call, such as the from and to number, will be included in the request to your answer_url. The answer_url must return a valid Plivo XML document to control the call.

    Internet calls initiated by Plivo Endpoints (from browsers and mobile apps) can be controlled in the same way. For such calls, the answer_url of the Plivo Application associated with the Endpoint is invoked.

    Incoming calls

    Asynchronous Call Management with Plivo’s REST APIs

    By using Plivo’s REST APIs, you can asynchronously manage calls by setting API requests to perform various actions on ongoing calls. These actions include playing an audio file, playing a text-to-speech message, recording calls & conferences, transferring calls, and more.

    Call Management Features

    These basic call management features will help you understand more about Plivo’s XML & API capabilities, as well as how to use these features to manage call flows.

    Play a Pre-Recorded Audio or Text-to-Speech Prompt

    • If you’d like to play a pre-recorded audio file on the call, you can use the Play XML. Plivo supports .mp3 & .wav file formats.

      <Response>
        <Play>https://s3.amazonaws.com/plivocloud/Trumpet.mp3</Play>
      </Response>
      
    • Use Speak XML to play a text-to-speech prompt on an ongoing call. This is helpful for instances in which you are dynamically changing the pre-recorded messages for each call.

      <Response> 
      <Speak>Go Green, Go Plivo.</Speak> 
      </Response>
      
    • You can also use SSML to control the pronunciation, pitch, volume, and other aspects of the machine voice generated by Plivo for the specified text. For more information on using SSML, read our Getting Started with SSML guide.

      <Response> 
      <Speak voice="Polly.Amy"> 
      <prosody rate="medium"> 
      Hello and welcome to Plivo Text To Speech Engine. 
      <break/> 
      <break/> We are now testing the 
      <say-as interpret-as="spell-out">SSML</say-as> feature. 
      </prosody> 
      </Speak> 
      </Response>
      
    • Use the Play API to play an audio file (.mp3 or .wav format). Alternately, use the Speak API to play spoken versions of text on an ongoing call asynchronously. These features can play notifications to users waiting on a call.

    Build an Interactive Voice Response by Accepting Digit and Speech Inputs

    • The GetInput XML element can be used to build Interactive Voice Response (IVR) systems that prompt the caller for input, and then respond based on the keys pressed by the caller.

      <Response>
          <GetInput inputType="dtmf" action="<action url>">
              <Speak>Press 1 to schedule an appointment. Press 2 to cancel an existing appointment.</Speak>
          </GetInput>
      </Response>
      
    • You can also use the GetInput element to collect speech inputs from callers in real time. Plivo’s Automatic Speech Recognition (ASR) engine instantly transcribes the caller’s speech into text, so you may build intelligent systems that respond based on the caller’s speech.

      <Response>
          <GetInput inputType="speech" action="<action url>">
              <Speak>say New Appointment to schedule an appointment. say Cancel Appointment to cancel an existing appointment.</Speak>
          </GetInput>
      </Response>
      

    Call-forwarding with Dial XML

    Call forwarding is useful to many businesses. Through this feature, incoming calls can be dynamically routed to available agents, extensions, or departments that cater to the caller’s needs. You can use the Dial element to forward a call to a number or to a Plivo Endpoint on a browser, iOS, or Android app.

    Dial XML can be used for call hunting or to attempt to connect to multiple numbers or endpoints. The call is connected to the first number/endpoint that answers the call.

      <Response>
          <Dial>
            <User>sip:alice1234@phone.plivo.com</User>
            <Number>15671234567</Number>
            <User>sip:john1234@phone.plivo.com</User>
          </Dial>
      </Response>
    

    Conferences and Multiparty Calls

    The Conference XML element will host a conference call in which multiple participants can be added at the same time. Plivo conferences offer a wide array of features and cater to a variety of use cases involving multiple participants. Explore all the features that conferences provide in our Conference API and Member API guides.

    You can also use the conference element to create waiting rooms for callers before connecting the call with the available agent.

      <Response>
        <Conference startConferenceOnEnter="false" waitSound="http://www.foo.com/waitmusic/">My Room</Conference>
      </Response>
    

    Recording Calls

    • You can record an ongoing call asynchronously using Plivo’s Record API and ongoing conference calls using Record Conference API. These APIs also provide an option to record parts of the call.
    • Using the Record XML, you can record the complete call session. Record XML can be also used to implement virtual voicemail boxes.

      <Response>
        <Record action="http://foo.com/get_recording/" startOnDialAnswer="true" redirect="false" maxLength="3600" />
        <Dial>
          <Number>15551234567</Number>
        </Dial>
      </Response>
      
    • Recordings are securely stored on the Plivo platform and can be accessed or deleted at any time by using the get recording API and delete recording API.