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 server-side SDKs 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. Let’s 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
    
    from flask import Flask, request, Response
    from plivo import plivoxml
    
    app=Flask(__name__)
    
    @app.route('/dialstatus/', methods=['GET','POST'])
    def dial_xml():
    
        # Generate Dial XML
        response = plivoxml.ResponseElement()
        response.add(plivoxml.SpeakElement('Connecting your call..'))
        response.add(plivoxml.DialElement(action='http://foo.com/dialstatus/action/', method='POST', redirect=True)
        .add(plivoxml.NumberElement("+15671234567")))
        return Response(response.to_string(), mimetype='application/xml')
    
    @app.route('/dialstatus/action/', 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
    28
    29
    
    require 'rubygems'
    require 'sinatra'
    require 'plivo'
    
    include Plivo
    include Plivo::XML
    
    post '/dialstatus/' do
        r = Response.new()
        params = {
            'action' => "https://example.com/dialstatus/action/", # 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("+15671234567")
    
        xml = PlivoXML.new(r)
        content_type "application/xml"
        return xml.to_s()
    end
    
    post '/dialstatus/action/' 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
    29
    30
    31
    32
    33
    34
    35
    
    var plivo = require('plivo');
    var express = require('express');
    var app = express();
    
    app.set('port', (process.env.PORT || 5000));
    app.use(express.static(__dirname + '/public'));
    
    app.all('/dialstatus/', function(request, response) {
        var r = plivo.Response();
        var params = {
            'action': "https://www.foo.com/dialstatus/action/",
            'method': "POST",
            'redirect': "true"
        };
        var dial = r.addDial(params);
        var first_number = "+15671234567";
        dial.addNumber(first_number);
        console.log (r.toXML());
        response.set({
            'Content-Type': 'text/xml'
        });
        response.end(r.toXML());
    });
    
    app.all('/dialstatus/action/', function(request, response) {
        var status = request.param('Status');
        var aleg = request.param('DialALegUUID');
        var bleg = request.param('DialBLegUUID');
    
        console.log ('Status : ' + status + ' Aleg UUID  : ' + aleg + ' Bleg UUID : ' + bleg);
    });
    
    app.listen(app.get('port'), function() {
        console.log('Node app is running on port', app.get('port'));
    });
    
    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\XML\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 = "+15671234567";
        $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
    
    import static spark.Spark.*;
    import com.plivo.api.xml.Dial;
    import com.plivo.api.xml.Number;
    import com.plivo.api.xml.Response;
    
    public class dialstatus {
        public static void main(String[] args) {
            post("/dialstatus/", (request, response) -> {
                response.type("application/xml");
                Response resp = new Response()
                    .children(
                            new Dial()
                                .action("http://foo.com/dialstatus/action/")
                                .method("POST")
                                .redirect(true)
                                .children(
                                        new Number("+15671234567")
                                )
                    );
                return resp.toXmlString();
            });
            post("/dialstatus/action/", (request, response) -> {
                String status = request.queryParams("Status");
                String aleg = request.queryParams("DialALegUUID");
                String bleg = request.queryParams("DialBLegUUID");
                System.out.println("Status : " + status + " ALeg UUID : " + aleg + " Bleg UUID : " + bleg);
                response.raw().getWriter().print("Status : " + status + " ALeg UUID : " + aleg + " Bleg UUID : " + bleg);
                return "done";
            });
        }
    }
    
    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
    
    package main
    
    import (
    	"github.com/go-martini/martini"
    	"github.com/plivo/plivo-go/xml"
    	"net/http"
    )
    
    func main() {
    	m := martini.Classic()
    	m.Post("/dialstatus/", func(w http.ResponseWriter, r *http.Request) string {
    		w.Header().Set("Content-Type", "application/xml")
    		response := xml.ResponseElement{
    			Contents: []interface{}{
    				new(xml.DialElement).
    					SetAction("http://foo.com/action/").
    					SetMethod("POST").
    					SetRedirect(true).
    					SetContents([]interface{}{
    						new(xml.NumberElement).
    							SetContents("+15671234567"),
    					}),
    			},
    		}
    		return response.String()
    	})
    	m.Post("/dialstatus/action", func(w http.ResponseWriter, r *http.Request) string {
    		status := r.FormValue("DialStatus")
    		aleg := r.FormValue("DialALegUUID")
    		bleg := r.FormValue("DialBLegUUID")
    		result := status + " " + aleg + " " + bleg
    		return result
    	})
    	m.Run()
    }
    
    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
    
    using System;
    using System.Collections.Generic;
    using Plivo.XML;
    using Microsoft.AspNetCore.Mvc;
    
    namespace Dialstatus.Controllers
    {
        public class DialstatusController : Controller
        {
            // GET: /<controller>/
            public IActionResult Index()
            {
                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/action/"}, // Redirect to this URL after leaving Dial.
                    {"method","GET"} // Submit to action URL using GET or POST.
                });
                dial.AddNumber("+15551234567", new Dictionary<string, string>() { });
                resp.Add(dial);
                var output = resp.ToString();
                return this.Content(output, "text/xml");
            }
            //Action URL
            public String Action()
            {
                var status = Request.Query["DialStatus"];
                var aleg = Request.Form["DialALegUUID"];
                var 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. Let’s 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 dialstatus 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.

    assign dialstatus Application

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

    Voice Phone Number Search

    Sample Output

    <Response>
        <Speak>Connecting your call..</Speak>
        <Dial action="https://morning-ocean-4669.herokuapp.com/dial_status/" method="GET">
            <Number>15671234567</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:

    ParameterDescription
    DialRingStatusThis indicates if the <Dial> attempt rang or not. It can be true or false.
    DialHangupCauseThe standard telephony hangup cause.
    DialStatusStatus of the dial.Can be completed, busy, failed, timeout or no-answer.
    DialALegUUIDCallUUID of the A leg.
    DialBLegUUIDCallUUID of the B leg. Empty if nobody answers.