Getting Started with Calls

This guide helps you implement your first outgoing call with Plivo. This example shows you how to make an outgoing call to a phone number of your choice and greet the user once they answer the call.

Voice call flow

Making an outbound call consists of the following 6 steps.

  1. User’s application initiates a call to the desired phone number (PSTN number)
  2. Plivo then calls the destination number
  3. The end user answers the phone call
  4. When the user answers the call, Plivo invokes the answer_url that was set during call initiation in step 1
  5. The answer_url returns a valid Plivo XML to control the call
  6. Using the contents of the XML, further call flow is controlled

Let us look at these steps in detail.

Initiating a call to a desired number

Your application can initiate a call to a desired number by send an API request to Plivo using one of the 7 server-side SDKs or a custom client written by you that can communicate with our API. Remember to authenticate your request using your Plivo authentication credentials (AUTH_ID and AUTH_TOKEN). A sample code snippet that can initiate a call in Python is as follows. Check the API reference for Calls to see how to initiate a call using the server-side SDK of your choice.

1
2
3
4
5
import plivo
with plivo.Client() as client:
    response = client.calls.create(
        from_='<caller_id>', to_='<destination_number>', answer_url='http://answer.url')
print(response)

The above snippet will initiate a call to <destination_number> using the <caller_id>. Once the call gets answered the answer_url will get invoked with a POST method.

Controlling the call flow using Plivo XML

The answer_url is expected to return a valid Plivo XML that will be used by Plivo to control the ongoing call. You can refer to this tutorial on setting up HTTP servers to return valid Plivo XML.

The following code snippet will help you generate an XML that speaks the text “Good Morning” to the user once they pick up the call.

1
2
3
4
response = (plivoxml.ResponseElement().add(
    plivoxml.SpeakElement('Good Morning'))
)
print(response.to_string())

The above code would generate the following XML.

1
2
3
<Response>
    <Speak>Good Morning</Speak>
</Response>

Once this XML is successfully fetched from the answer_url, it will be executed. The Speak element instructs to speak the text “Good Morning” to the receiver of the call. Since there are no further instructions the call will be hung up after speaking the mentioned text.

Instead of just hanging up the call, if you want to join the call and directly speak to the end user, you could use a Dial element to dial your number and bridge the call. In this case, the following XML could be used

1
2
3
4
5
6
<Response>
    <Speak>Good Morning</Speak>
    <Dial>
        <Number>1415000000</Number>
    </Dial>
</Response>

The Dial element along with the Number element instructs Plivo to dial the number given in the XML and bridge the call with the end user.

Enhancing your call flow further

The above XML is a very simple example to basically get you started with how calls can be controlled using Plivo XML. You can refer to the Plivo XML documentation to know more about what is possible with Plivo XML.

Next Steps