Screen an Incoming Call

When you receive a call on your Plivo number, you can screen it using Plivo XML. In this example, when an incoming call is received, we will check if that number has been blacklisted. And if it has, then we will hangup immediately using the Hangup XML. If the phone number hasn’t been blacklisted, then we will return a Speak XML that will say “Hello, how are you today!”.

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. 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.
  4. Use a web hosting service to host your web application. There are many inexpensive cloud hosting providers that you can use for just a few dollars a month. Follow the instructions of your hosting provider to host your web application.

Set up a Web Server

Let’s assume your web server is located at myvoiceapp.com. Below is a snippet to set up a route on your webserver. Lets call it, screen_call. Now when we send an HTTP request to myvoiceapp.com/screen_call this route will be invoked. You will now have to configure this URL in your Plivo application.

Note: For PHP, the route will be myvoiceapp.com/screen_call.php
  1. Copy the relevant code below into a text file and save it. Lets call it, screen_call.
    Note: Make sure to use the appropriate file extention for your code (e.g., screen_call.py for Python).
  2. Add phone numbers to your black list that you want to reject.
  3. Now that you have the code, you will need to expose your server to the public Internet. This way, Plivo will know where to find your app when a particular phone number is dialed. Moving forward, we will assume that your app is available at myvoiceapp.com.

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
from flask import Flask, Response
import plivo, plivoxml

app = Flask(__name__)

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

    blacklist = ['1111111111','2222222222','3333333333']
    from_number = request.values.get('From')

    response = plivoxml.Response()

    if from_number in blacklist:
        # Specify the reason for hangup
        params = {'reason': 'rejected'}
        response.addHangup(**params)
    else:
        response.addSpeak('Hello, how are you today')

    return Response(str(response), mimetype='text/xml')

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
require 'rubygems'
require 'sinatra'
require 'plivo'
include Plivo

get '/screen_call/' do
    blacklist = ['1111111111','2222222222','3333333333']

    from_number = params[:From]
    r = Response.new()

    if blacklist.include? from_number
        # Specify the reason for hangup
        params = {'reason' =>'rejected'}
        r.addHangup(params)
    else
        r.addSpeak('Hello, how are you today')
    end

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

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
var plivo = require('plivo');
var express = require('express');
var bodyParser = require('body-parser');
var app = express();

app.use(bodyParser.urlencoded({extended: true}));
app.set('port', (process.env.PORT || 5000));

app.all('/screen_call/', function(request, response) {
    var blacklist = ['1111111111','2222222222'];
    // Get the caller's phone number from the 'From' parameter
    var from_number = request.query.From || request.body.From;
    var r = plivo.Response();

    if (blacklist.indexOf(from_number) === -1){
        var body = "Hello, how are you today";
        r.addSpeak(body);
    } else {
        //Specify the reason for hangup
        var params = {'reason': "rejected"};
        r.addHangup(params);
    }

    console.log (r.toXML());
    response.set({'Content-Type': 'text/xml'});
    response.send(r.toXML());
});

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
<?php
    require 'vendor/autoload.php';
    use Plivo\Response;
    $from_number = $_REQUEST['From'];
    $blacklist = array('1111111111', '2222222222', '3333333333');
    $r = new Response();
    if (in_array($from_number, $blacklist)) {
        $params = array('reason' => 'rejected');
        $r->addHangup($params);
    } else {
        $body = "Hello, how are you today!";
        $r->addSpeak($body);
    }
    Header('Content-type: text/xml');
    echo($r->toXML());
?>
 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
package plivoexample;

import java.io.IOException;
import java.util.Arrays;
import com.plivo.helper.exception.PlivoException;
import com.plivo.helper.xml.elements.Hangup;
import com.plivo.helper.xml.elements.PlivoResponse;
import com.plivo.helper.xml.elements.Speak;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

public class blackList extends HttpServlet {
    private static final long serialVersionUID = 1L;
    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp)
            throws ServletException, IOException {
        String[] blacklist = { "1111111111","2222222222","3333333333"};
        String fromNumber = req.getParameter("From");
        PlivoResponse response = new PlivoResponse();
        if (Arrays.asList(blacklist).contains(fromNumber)) {
            Hangup hang = new Hangup();
            hang.setReason("rejected");
            try {
                response.append(hang);
            } catch (PlivoException e) {
                e.printStackTrace();
            }
        } else {
            Speak speak = new Speak("Hello, how are you today!");
            try {
                response.append(speak);
            } catch (PlivoException e) {
                e.printStackTrace();
            }
        }

        System.out.println(response.toXML());
        resp.addHeader("Content-Type", "text/xml");
        resp.getWriter().print(response.toXML());
    }

    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 blackList()),"/screen_call/");
        server.start();
        server.join();
    }
}
 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 System.Diagnostics;
using RestSharp;
using Plivo.XML;
using Nancy;

namespace blacklist
{
    public class Program : NancyModule
    {
        public Program()
        {
            Get["/screen_call/"] = x =>
            {
                string[] blacklist = {"1111111111","2222222222","3333333333"};
                String fromNumber = Request.Query["From"];
                Plivo.XML.Response resp = new Plivo.XML.Response();

                if (blacklist.Equals(fromNumber)) {
                    resp.AddHangup(new Dictionary<string, string>()
                    {
                        {"reason", "rejected"}
                    });
                } else {
                    resp.AddSpeak("Hello, how are you today!", new Dictionary<string, string>() { });
                }
                var output = resp.ToString();
                var res = (Nancy.Response)output;
                res.ContentType = "text/xml";
                return res;
            };
        }
    }
}

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 “Screen Call”. Enter your server URL (e.g., http://myvoiceapp.com/screen_caller) 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 “Screen Call” (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

Test it out

Call the Plivo phone number assigned to your app. If your phone number is on the blacklist, then your call will be rejected. If your phone number is not blacklisted, then the call will go through and you will be greated with “Hello, how are you today!”.

Sample XML

Sample output when From number is in blacklist
<Response>
    <Hangup reason="rejected"/>
</Response>

Sample Output when From number is not in blacklist
<Response>
    <Speak>Hello, how are you today!</Speak>
</Response>

Next Step

Learn how to Reject an Incoming Call.

  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