Plivo’s voice API platform lets you integrate voice calling into your applications. With it, you can make, receive, and control calls across the world. Plivo offers a rich set of programmatic building blocks that you can use to add voice communication to your existing products and workflows. With Plivo’s APIs and SDKs, you can:
A voice call involves two-way conversation between two or more users. Plivo acts as the intermediary to connect these users. Devices that may be involved in a voice call include not only mobile, landline, and VoIP phones, but also browser and mobile apps.
For voice calls on the Plivo voice platform, multiple call legs may be involved, depending on the call flow, and each call leg is considered a separate call.
For example, in a call forwarding use case, the inbound connection between the caller and the Plivo voice platform is considered the A leg, and the outbound connection between the Plivo voice platform and the destination is the B leg.
Plivo supports outbound, inbound, and forwarded calls. Here’s a look at how each works.
Plivo XML lets you programmatically provide Plivo with instructions to control outbound and inbound calls. Once a call is answered, Plivo invokes a specified URL to request an XML document to be used to process the call. Plivo provides XML elements to handle call flow synchronously and to perform actions such as
An application can initiate an outbound call through an API request to Plivo. When the call is answered, Plivo invokes the application service endpoint given in the answer_url
API request parameter, which carries instructions to control the call. For example, you could return a Speak XML or Play XML element to play a prompt when the call is answered.
When someone dials a Plivo phone number, the answer_url
parameter configured for the Plivo application associated with the number is triggered. Details about the incoming call, such as the from and to numbers, are included in the request to the answer_url
.
You can control internet calls initiated by Plivo endpoints (from browser and mobile apps) in the same way. These calls invoke the answer_url
of the Plivo application associated with the endpoint.
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 and conferences, and transferring calls.
Here are some basic call management examples to help you learn about Plivo’s XML and API capabilities, and see how to use Plivo to manage call flows.
Use the Play XML element to play a prerecorded MP3 or WAV audio file on the call.
<Response>
<Play>https://s3.amazonaws.com/plivocloud/Trumpet.mp3</Play>
</Response>
Use the Speak XML element to play a text-to-speech prompt on an ongoing call. This is useful for instances in which you dynamically change the prerecorded message for each call.
<Response>
<Speak>Go Green, Go Plivo.</Speak>
</Response>
You can use SSML to control the pronunciation, pitch, volume, and other aspects of the machine voice generated by Plivo.
<Response>
<Speak voice="Polly.Amy">
<prosody rate="medium">
Hello and welcome to the 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), or use the Speak API to play spoken versions of text, on an ongoing call asynchronously — for example, to play notifications to users waiting on a call.
You can use the GetInput XML element to build an interactive voice response (IVR) system that prompts callers for input, then responds based on 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 can build intelligent systems that respond based on what a caller speaks.
<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 lets you dynamically route incoming calls to available agents, extensions, or departments. You can use the Dial XML element to forward a call to a number or to a Plivo endpoint on a browser or iOS or Android app.
You can use the Dial element for call hunting or to attempt to connect to multiple numbers or endpoints. This response, for instance, connects a caller to the first number or endpoint that answers the call.
<Response>
<Dial>
<User>sip:alice1234@phone.plivo.com</User>
<Number>12025551111</Number>
<User>sip:john1234@phone.plivo.com</User>
</Dial>
</Response>
The Conference XML element hosts a conference call to 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 reference pages.
You can also use the Conference element to create waiting rooms for callers before connecting them with an available agent.
<Response>
<Conference startConferenceOnEnter="false" waitSound="https://<yourdomain>.com/waitmusic/">My Room</Conference>
</Response>
You can record a complete call session or implement virtual voice mail boxes using the Record XML element.
<Response>
<Record action="https://<yourdomain>.com/get_recording/" startOnDialAnswer="true" redirect="false" maxLength="3600" />
<Dial>
<Number>12025551111</Number>
</Dial>
</Response>