What is Plivo XML?

Plivo communicates with remote applications built by businesses through a series of API calls. These back and forth calls between Plivo and other applications are communicated through XML (Extensible Markup Language). XML is a dynamic self-describing language that is both machine and human readible. Plivo recognizes XMLs as a set of instructions that tells Plivo how to handle incoming and outgoing calls or SMS text messages. Essentially, developers write code that generate the right XML messages. These messages tell Plivo to execute behaviors during communication flows.

For Example, below is that the ‹Speak› XML element looks like when it tells Plivo to read a pre-written message:

<Response>
    <Speak language="en-US" loop="1" voice="WOMAN">
        Congratulations! You just made a text to speech app on Plivo cloud!
    </Speak>
</Response>
Advanced Hack: Changing XML attributes will affects your call. For example, changing the voice from WOMAN to MAN or the language from en-US to en-GB will change the voice output. Visit the Speak XML docs for more details on the ‹Speak› XML attributes.


How does Plivo's XML work?

Plivo's XML can be considered as the set of instructions that Plivo uses to control calls and text messages. The workflow can be split into incoming and outgoing traffic.

Incoming calls and text messages to a Plivo phone number:

  1. A call or SMS text message is received on a Plivo phone number
  2. Plivo will look up the application Uniform Resource Identifier (URI) linked to that phone number and make a request to that URL via HTTP. For calls, this URL is called the Answer URL. For SMS text messages, it's called the Message URL.
  3. Note: Uniform Resource Identifier (URI) is a string of characters used to identify a name of a resource. In Plivo's case, the URI is in the form of a uniform resource locator (URL).
  4. The web application at that URL will return an XML document that provides instructions to the Plivo on what to do with the call or text message.

Outgoing calls made from a Plivo phone number:

If the call is initiated from a Plivo number, the same logic remains true. The only difference is that the call is initiated through a Plivo REST API request. Upon initiating the call, Plivo will execute the XML instructions it receives from the application URL.

  1. A call or text message to a pre-specified phone number is initiated through a Plivo API request from a Plivo phone number.
  2. The call or SMS text message is received on the destination phone number.
  3. If an application URI is provided, Plivo will make a HTTP request to that URI. For calls, this URL is called the Answer URL. For SMS text messages, it's called the Message URL.
  4. The web application at that URL will return an XML document that provides instructions to the Plivo on what to do with the call or text message.


How Plivo Communicates With Your Web Application

As mentioned above, Plivo makes requests to the application URI via HTTP GET or POST. By default, XML requests to your application are made via POST. However, you can configure Plivo to make its XML requests to your application via HTTP GET or POST by changing the related config parameter.

HTTP POST Requests

POST stores the transferred information (i.e., metadata) in a packet that is sent along with the URI in the body of the POST – you don’t see the information attached to the URI in the address bar. This also means that POST requests are never cached, do not remain in the browser history, cannot be bookmarked, and does not have restrictions on data length. Post values can be altered by the receiving page and returned. In almost any situation where you’re making a call, creating an endpoint or application, purchasing a phone number, POST is used.

HTTP GET Requests

GET exchanges data strictly through the parameters to the URL. GET requests should only be used to retrieve data (e.g., searching for phone numbers, getting call details, etc.). Think of GET as a one-way communication method - once the information is sent to the receiving page, the web server doesn’t retain the parameter data or do anything else with it. However, since GET data exchanges are done through the URL, the data length is also restricted by the maximum URL length of 2048 characters. As well, GET requests can be cached and can remain in the browser history and be bookmarked. Therefore, GET requests should never be used when dealing with sensitive data.


What can Plivo's XML do?

Plivo's APIs are designed to accept XMLs in the following formats and can be used as building blocks that control simple to complex communication flows.

XML Element Description
‹Conference› The Conference element is used for starting a conference and callers can then join in to talk to others connected to that room. Maximum number of participants in a single conference room is 100 callers.
‹Dial› Makes a call to a single or multiple phone numbers.
‹DTMF› Sends digits in the background of a call. For example, after a call is connected, Plivo can send the DTMF tones that connects the call to an extention.
‹GetDigits› Used to collect the digits entered by a caller. Once the caller has finished entering the digits, the API submits the data to the provided action URL using a HTTP GET or POST request.
‹Hangup› Ends a call when certain attributes are satisfied. For example, schedule a hangup after a certain amount of time, or if the call is rejected or busy.
‹Message› Sends a SMS text message during your communication flow. For example, send an SMS notification when you receive a call on your Plivo phone number.
‹Play› Plays an audio file to the caller. The audio file is retrieved from an URL and can be in mp3 or wav formats.
‹Record› Records a call and returns the URL of the recording when the call is complete.
‹Redirect› Transfers the control of a call to a different URL, which then starts processing a new set of XML instructions from the new URL.
‹Speak› Reads out static or dynamic text as speech to the caller. For example, it can be helpful to read back the digits that the caller just entered.
‹Wait› Waits in silence for a specified number of seconds. This can be used as the first element of an XML to delay picking up incoming calls for a specified amount of time.