Dial Status Reporting

Once the Call API request is successful, your call will be put into a queue to be sent to its destination. By default, each Plivo account can make 1 outgoing call per second. That is, Plivo will send 1 call every second for each ‘src’ source number in the API request. This limit is regulated by carrier policies and can be increased in some regions.

By default, you will not receive an automatic notification regarding the delivery of your calls. To get notified on the status of your call, include the url parameter in your API request. You can also find your call reports in the Call Logs of your Plivo account. This will automatically output a notification when your call reaches its destination, or if it fails to deliver. Your delivery report will update to show “in-progress” for each individual call.

Prerequisites

  1. Sign up for a free Plivo trial account.
  2. Check out our Helper Libraries page and install the right helper based on the programming language you want to use.
  3. Buy a Plivo phone number. A phone number is required to receive calls. You can buy a Plivo phone number in over 20+ countries through the Buy Numbers tab on your Plivo account UI. Check the Voice API coverage page for all the supported countries.

Set up a Web Server

Let’s assume your web server is located at example.com. Below is a snippet to set up a route on your webserver. Lets call it, dial. Now when we send an HTTP request to example.com/dial/ this route will be invoked. We also define a route for reporting the status of the dial which is sent to the action url in the Dial tag. Let’s call this dial_status. Now when the Dial is in progress, the status is reported to this action url - https://example.com/dial_status/

Note: For PHP, the route will be example.com/dial.php.

Code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
from flask import Flask, request, Response
import plivoxml

app=Flask(__name__)

@app.route('/dial/', methods=['GET','POST'])
def dial_xml():

    # Generate Dial XML

    response = plivoxml.Response()
    params = {
        'action' : "https://example.com/dial_status/",
        'method' : 'GET'
    }
    response.addSpeak("Connecting your call..")
    d = response.addDial(**params)
    d.addNumber("1111111111")
    print response.to_xml()
    return Response(str(response), mimetype='text/xml')

@app.route('/dial_status/', methods=['GET','POST'])
def dial_status():

    # After completion of the call, Plivo will report back the status to the action URL in the Dial XML.

    status = request.args.get('DialStatus')
    aleg = request.args.get('DialALegUUID')
    bleg = request.args.get('DialBLegUUID')
    print "Status : %s, ALeg Uuid : %s, BLeg Uuid : %s" % (status,aleg,bleg)
    return "Dial status reported"

if __name__ == '__main__':
    app.run(host='0.0.0.0', debug=True)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
require 'rubygems'
require 'sinatra'
require 'plivo'
include Plivo

get '/dial/' do
    r = Response.new()
    params = {
        'action' => "https://example.com/dial_status/", # Redirect to this URL after leaving Dial.
        'method' => 'GET' # Submit to action URL using GET or POST.
    }

    r.addSpeak("Connecting your call..")
    d = r.addDial(params)
    d.addNumber("1111111111")

    puts r.to_xml()
    content_type 'text/xml'
    return r.to_s()
end

get '/dial_status/' do
    status = params[:DialStatus]
    aleg = params[:DialALegUUID]
    bleg = params[:DialBLegUUID]
    puts "Status : #{status}, ALeg UUID : #{aleg}, BLeg UUID : #{bleg}"
end
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
<?php
    require 'vendor/autoload.php';
    use Plivo\Response;
    $r = new Response();
    // Add Speak tag
    $body = "Connecting your call..";
    $r->addSpeak($body);
    $params = array(
        'action' => 'https://example.com/dial_status.php', # Redirect to this URL after leaving Dial.
        'method' => 'GET' # Submit to action URL using GET or POST.
    );
    // Add Dial tag
    $d = $r->addDial($params);
    $number = "1111111111";
    $d->addNumber($number);
    Header('Content-type: text/xml');
    echo($r->toXML());
?>

<!--dial_status.php-->

<?php
    // Print the Dial Details
    $status = $_REQUEST['DialStatus'];
    $aleg = $_REQUEST['DialALegUUID'];
    $bleg = $_REQUEST['DialBLegUUID'];
    echo "Status = $status , Aleg UUID = $aleg , Bleg UUID = $bleg";
?>
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
package plivoexample;

import java.io.IOException;

import com.plivo.helper.exception.PlivoException;
import com.plivo.helper.xml.elements.Dial;
import com.plivo.helper.xml.elements.Number;
import com.plivo.helper.xml.elements.PlivoResponse;
import com.plivo.helper.xml.elements.Speak;

import org.eclipse.jetty.server.Server;
import org.eclipse.jetty.servlet.ServletContextHandler;
import org.eclipse.jetty.servlet.ServletHolder;

import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

public class dialXml extends HttpServlet {
    private static final long serialVersionUID = 1L;
    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp)
            throws ServletException, IOException {

        PlivoResponse response = new PlivoResponse();
        Speak speak = new Speak("Connecting your call..");
        Dial dial = new Dial();
        dial.setAction("https://example.com/dial_status/");
        dial.setMethod("GET");
        Number num = new Number("1111111111");

        try {
            response.append(speak);
            dial.append(num);
            response.append(dial);
            System.out.println(response.toXML());
            resp.addHeader("Content-Type", "text/xml");
            resp.getWriter().print(response.toXML());;
        } catch (PlivoException e) {
            e.printStackTrace();
        }
    }

    public static void main(String[] args) throws Exception {
        String port = System.getenv("PORT");
        if(port==null)
            port ="8000";
        Server server = new Server(Integer.valueOf(port));
        ServletContextHandler context = new ServletContextHandler(ServletContextHandler.SESSIONS);
        context.setContextPath("/");
        server.setHandler(context);
        context.addServlet(new ServletHolder(new dialXml()),"/dial/");
        context.addServlet(new ServletHolder(new dialStatus()),"/dial_status/");
        server.start();
        server.join();
    }
}

// dialStatus.java
// After completion of the call, Plivo will report back the status to the action URL in the Dial XML.
package plivoexample;

import java.io.IOException;

import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

public class dialStatus extends HttpServlet {
    private static final long serialVersionUID = 1L;

    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp)
            throws ServletException, IOException {
        String status = req.getParameter("Status");
        String aleg = req.getParameter("DialALegUUID");
        String bleg = req.getParameter("DialBLegUUID");
        System.out.println("Status : " + status + " ALeg UUID : " + aleg + " BLeg UUID : " + bleg);
        resp.getWriter().print("Status : " + status + " ALeg UUID : " + aleg + " BLeg UUID : " + bleg);
    }
}
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
using System;
using System.Collections.Generic;
using System.Diagnostics;
using RestSharp;
using Plivo.XML;
using Nancy;

namespace dial_status_reporting
{
    public class Program : NancyModule
    {
        public Program()
        {
            Get["/dial/"] = x =>
            {
                Plivo.XML.Response resp = new Plivo.XML.Response();

                // Generate Dial XML
                Plivo.XML.Dial dial = new Plivo.XML.Dial(new Dictionary<string, string>()
                {
                    {"action","http://example.com/dial_status/"}, // Redirect to this URL after leaving Dial.
                    {"method","GET"} // Submit to action URL using GET or POST.
                });
                dial.AddNumber("1111111111", new Dictionary<string, string>() { });

                resp.Add(dial);
                Debug.WriteLine(resp.ToString());

                var output = resp.ToString();
                var res = (Nancy.Response)output;
                res.ContentType = "text/xml";
                return res;
            };

            Get["/dial_status/"] = x =>
            {
                // After completion of the call, Plivo will report back the status to the action URL in the Dial XML.
                String status = Request.Query["DialStatus"];
                String aleg = Request.Form["DialALegUUID"];
                String bleg = Request.Form["DialBLegUUID"];

                Debug.WriteLine("Status : {0}, ALeg UUID : {1}, BLeg UUID : {2}", status, aleg, bleg);
                return "OK";
            };
        }
    }
}

Create an Application

  1. Create an Application by visiting the Application Page and click on New Application or by using Plivo’s Application API.
  2. Give your application a name. Lets call it Dial Status Report. Enter your server URL (e.g., http://example.com/dial/) in the Answer URL field and set the method as POST. See our Application API docs to learn how to modify your application through our APIs.
  3. Click on Create to save your application.

Create Text to Speech Application

Assign a Plivo number to your app

  1. Navigate to the Numbers page and select the phone number you want to use for this app.
  2. Select Dial Status Report (name of the app) from the Plivo App dropdown list.
  3. Click on ‘Update’ to save.

Create Text to Speech Application

If you don’t have a number, go to the Buy Number page to purchase a Plivo phone number.

SMS Phone Number Search

Sample Output

<Response>
    <Speak>Connecting your call..</Speak>
    <Dial action="https://morning-ocean-4669.herokuapp.com/dial_status/" method="GET">
        <Number>1111111111</Number>
    </Dial>
</Response>

Status : completed, ALeg Uuid : 52bb0058-902d-11e4-9681-2d7d49a323a0, BLeg Uuid : 54f84290-902d-11e4-96df-2d7d49a323a0

Parameters sent to the action_url

The following parameters are then sent to the URL:

Parameter Description
DialRingStatus This indicates if the <Dial> attempt rang or not. It can be true or false.
DialHangupCause The standard telephony hangup cause.
DialStatus Status of the dial.Can be completed, busy, failed, timeout or no-answer.
DialALegUUID CallUUID of the A leg.
DialBLegUUID CallUUID of the B leg. Empty if nobody answers.

Next Step

Learn how to Play Custom Music to a Caller.

  1. Make an Outbound Call
  2. Play a Text-to-speech Message
  3. Connect Call to a Second Person
  4. Greet Caller by Name
  5. Play MP3/WAV Audio to Caller
  6. Hangup Using API
  7. Receive Incoming Call
  8. Forward Incoming Call
  9. Record Using API
  10. Screen Incoming Call
  11. Reject incoming call
  12. Get Details of all Calls
  13. Get Details of a single Call
  14. Get Details of Live Calls
  15. Build an IVR Phone Menu
  16. Conference Call
  17. Call Forward
  18. SIP Endpoint (Direct-Dial)
  19. Inbound Trunk
  20. Outbound Trunk