Skip to main content
Your application must use Plivo XML to control SMS messages synchronously. You can use the Message XML element to send an SMS message in different scenarios — for example, to reply to or forward an incoming message.

​
How It Works

Let’s look at an example to see how Plivo XML works. Consider a use case where you want to reply to an incoming SMS message. This diagram outlines the message flow for a typical case where XML is used:
An incoming SMS message is received on a Plivo number and is connected through the Plivo SMS Platform. Plivo then looks up the message_url configured for the Application that’s linked to the Plivo number and makes a request to that URL. Your web application at that URL should return an XML document that provides instructions to the Plivo API on how the SMS message should be handled. In this case, it should return a message XML document to reply to the incoming SMS message. In this example, Plivo works like an HTTP client that receives a message and and makes a request to your web application for instructions on how to handle the message. By default, XML requests to your application are made via POST, but you can configure Plivo to make XML requests to your application via HTTP GET or POST methods by changing the related configuration parameter. You can set configuration parameters when sending out a message. To deal with incoming messages, Plivo uses the configuration attached to the application that’s linked to the phone number on which your incoming message is received.

​
XML Request

When Plivo makes a synchronous HTTP request to your application, the API expects an XML document in response. Plivo also sends a few parameters with the HTTP request that your application can act upon before responding.

​
Incoming Message Parameters

To receive a message, your Plivo Application must have a message_url. Plivo expects an XML response from this URL after it sends the parameters below. Only a Message XML element can be sent as a response from the message URL.
ParameterDescription
FromThe source number of the message.
ToThe number to which the message was sent.
TypeThe type of the message. Allowed value: sms
TextThe message content.
MessageUUIDA unique ID for the message.

​
Signature Validation

All requests made by Plivo to your server URLs consist of X-Plivo-Signature-V2 and X-Plivo-Signature-V2-Nonce HTTP headers. To validate a request and to verify that the request to your server originated from Plivo, you must generate a signature at your end and compare it with X-Plivo-Signature-V2 parameter in the HTTP header to check whether they match. Read more about signature validation. Methods to compute and verify X-Plivo-Signature-V2 are available in the latest server SDKs. Choose the SDK for the programming language of your choice to see how to use these methods.

​
Signature Validation Arguments

NameTypeDescription
uristringThe callback that you want to validate. Allowed values: answer_url, message_url, callback_url, action_url, hangup_url
X-Plivo-Signature-V2-NoncestringRandom numeric digits posted to the callback_url, used for validation purposes.
X-Plivo-Signature-V2 or X-Plivo-Signature-Ma-V2stringRandom alphanumeric characters used for validation. You can get this from the relevant event details posted to your callback.
auth_tokenstringYour account Auth Token, which you can find on the Overview page of the Plivo console.
Note: You can either use X-Plivo-Signature-V2 or X-Plivo-Signature-Ma-V2 to validate the signature.
  • X-Plivo-Signature-V2 is generated using the Auth Token of the associated account or subaccount. To validate using the X-Plivo-Signature-V2 request header, generate the signature at your end using the same account or subaccount.
  • X-Plivo-Signature-Ma-V2 is always generated using the Auth Token of the account. To validate using the X-Plivo-Signature-Ma-V2 request header, generate the signature using the main account.
from flask import Flask, request, make_response, url_for
import plivo

app = Flask(__name__)

@app.route('/receive_sms/', methods =['GET','POST'])
def signature():
    signature = request.headers.get('X-Plivo-Signature-V2')
    nonce = request.headers.get('X-Plivo-Signature-V2-Nonce')
    uri = url_for('signature', _external=True)
    auth_token = "<auth_token>"

    output = plivo.utils.validate_signature(uri,nonce,signature,auth_token)
    print(output)

    from_number = request.values.get('From')
    to_number = request.values.get('To')
    text = request.values.get('Text')

    print('Message received - From: %s, To: %s, Text: %s' %(from_number, to_number, text))
    return "Text received"

if __name__ == "__main__":
    app.run(host='0.0.0.0', debug=True)

​
XML Response

When your application gets initiated to send a message, Plivo makes an HTTP request to the message_url, which is one of the mandatory parameters when sending a message.

​
Requirements

  • The message_url should respond with an XML document that provides instructions to control the SMS.
  • The Content Type of the response header, returned by the message_url, must be set to text/xml or application/xml.
  • The XML document returned should contain a valid Plivo Message XML element as described below.

​
Structuring the XML Document

​
The Parent Element

The <Response> element is the parent element of Plivo’s XML. All child elements must be nested within this element. Any other structure is considered invalid.

​
Child Elements

Child elements are proprietary Plivo elements and are case-sensitive. This means that using <message> instead of <Message>, for example, will result in an error. Attributes for the child elements are also case-sensitive and “camelCased.” When Plivo receives an XML response, it executes the elements from top to bottom.
Example XML Response
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Message src="12023222222" dst="15671234567" type="sms" callbackUrl="http://foo.com/sms_status/" callbackMethod="POST">
    Hi, Message from Plivo
  </Message>
</Response>

​
Message Element

Use the Message element to send a message during your call flow. For instance, if you want to send out an SMS notification when you receive an incoming call on your Plivo number, you can use the <Message> element in your application. To receive a message, you must set a message URL in your Plivo application via the API or in the Plivo console at Messaging > Applications.

​
Message Attributes

NameTypeDescription
srcstringSource number — for example, 12025550000. Must be a purchased, valid number.
dststringDestination number. Must be a valid number. To use bulk numbers, specify them separated by < — for example, 12025551111<12025552222.
typestringType of the message. Allowed values: sms
callbackUrlstringA valid, reachable URL that Plivo notifies when a response is available and to which the response is sent (Delivery reports).
callbackMethodstringThe method used to notify the callbackUrl. Allowed values: GET, POST. Defaults to POST.

​
Message Example

This example XML document is used to send out an SMS message. Plivo sends a delivery report to the callback URL using the HTTP POST method. 
from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(
    plivoxml.MessageElement(
        'Hi, this is a sample text',
        src='+12025550000',
        dst='+12025551111',
        type='sms',
        callback_url='https://<yourdomain>.com/sms_status/',
        callback_method='POST'))
print(response.to_string())

​
Response

<Response>
  <Message src="12022220000" dst="12025551111" type="sms" callbackUrl="https://<yourdomain>.com/sms_status/" callbackMethod="POST">
    Hi, this is a text message
  </Message>
</Response>