Forward Incoming Calls

    Call forwading can be very useful in any business work flow. For example, incoming calls can be dynamically routed to available agents, extensions, or departments that cater to the caller’s needs. In this tutorial, you will learn how to forward a received call to another phone number.

    Warning:  This tutorial requires understanding of  receiving an incoming 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. 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. Let’s call it forward. Now when we send an HTTP request to myvoiceapp.com/forward 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/forward.php`
    1. Copy the relevant code below into a text file and save it. Let’s call it, forward.
      Note: Make sure to use the appropriate file extention for your code (e.g., forward.py for Python).
    2. 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
    25
    26
    27
    28
    29
    30
    
    from flask import Flask, request, Response
    import plivo, plivoxml
    
    app = Flask(__name__)
    
    @app.route("/forward/", methods=['GET','POST'])
    def forward():
        # Generate a Dial XML to forward an incoming call.
    
        # The phone number of the person calling your Plivo number,
        # we'll use this as the Caller ID when we forward the call.
        from_number = request.args.get('From')
    
        # The number you would like to forward the call to.
        forwarding_number = "2222222222"
    
        # The phone number to be used as the caller id.
        # It can be set to the from_number or any custom number.
        params = {'callerId': from_number }
    
        response = plivoxml.Response()
        d = response.addDial(**params)
        d.addNumber(forwarding_number)
    
        print response.to_xml()
        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
    25
    26
    27
    28
    
    require 'rubygems'
    require 'sinatra'
    require 'plivo'
    include Plivo
    
    get '/forward/' do
        # Generate a Dial XML to forward an incoming call.
    
        # The phone number of the person calling your Plivo number,
        # we'll use this as the Caller ID when we forward the call.
        from_number = params[:From]
    
        # The number you would like to forward the call to.
        forwarding_number = "2222222222"
    
        # The phone number to be used as the caller id.
        # It can be set to the from_number or any custom number.
        params = {'callerId' => from_number}
    
        r = Response.new()
        d = r.addDial(params)
        d.addNumber(forwarding_number)
    
        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
    32
    33
    34
    35
    36
    37
    38
    
    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));
    
    // Generate a Dial XML to forward an incoming call.
    
    // we'll use the phone number of the person calling your
    // Plivo number as the Caller ID when we forward the call.
    
    app.all('/forward/', function(request, response) {
        var r = plivo.Response();
    
        var from_number = request.body.From || request.query.From;
        // The number you would like to forward the call to.
        var forwarding_number = "2222222222";
        var params = {
            // The phone number to be used as the caller id.
            // It can be set to the from_number or any custom number.
            'callerId' : from_number
        };
    
        var d = r.addDial(params);
        d.addNumber(forwarding_number);
        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
    17
    
    <?php
        require 'vendor/autoload.php';
        use Plivo\Response;
        // Fetch the from_number from the URL
        $from_number = $_REQUEST['From'];
        $r = new Response();
        // Add Dial tag
        $params = array(
            'callerId' => $from_number # Caller ID
        );
        $d = $r->addDial($params);
        $number = "2222222222";
        $d->addNumber($number);
        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
    
    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 javax.servlet.ServletException;
    import javax.servlet.http.HttpServlet;
    import javax.servlet.http.HttpServletRequest;
    import javax.servlet.http.HttpServletResponse;
    import org.eclipse.jetty.server.Server;
    import org.eclipse.jetty.servlet.ServletContextHandler;
    import org.eclipse.jetty.servlet.ServletHolder;
    
    public class connectCall extends HttpServlet {
        private static final long serialVersionUID = 1L;
        @Override
        protected void doGet(HttpServletRequest req, HttpServletResponse resp)
                throws ServletException, IOException {
    
            PlivoResponse response = new PlivoResponse();
            String fromNumber = req.getParameter("From");
    
            Dial dial = new Dial();
            dial.setCallerId(fromNumber);
            Number num = new Number("2222222222");
    
            try {
                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 connectCall()),"/forward/");
            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
    36
    37
    38
    39
    40
    41
    42
    43
    
    using System;
    using System.Collections.Generic;
    using System.Diagnostics;
    using RestSharp;
    using Plivo.XML;
    using Nancy;
    
    namespace connect_call
    {
        public class Program : NancyModule
        {
            public Program()
            {
                Get["/forward/"] = x =>
                {
                    // The phone number of the person calling your Plivo number,
                    // we'll use this as the Caller ID when we forward the call.
                    String from_number = Request.Query["From"];
    
                    // The number you would like to forward the call to.
                    String forwarding_number = "2222222222";
    
                    Plivo.XML.Response resp = new Plivo.XML.Response();
                    Plivo.XML.Dial dial = new Plivo.XML.Dial(new Dictionary&lt;string, string&gt;()
                    {
                        // The phone number to be used as the caller id.
                        // It can be set to the from_number or any custom number.
                        {"callerId", from_number}
                    });
                    dial.AddNumber(forwarding_number, new Dictionary&lt;string, string&gt;() { });
    
                    resp.Add(dial);
                    Debug.WriteLine(resp.ToString());
    
                    var output = resp.ToString();
                    var res = (Nancy.Response)output;
                    res.ContentType = "text/xml";
                    return res;
                };
            }
        }
    }
            
    

    Sample XML

    <Response>
        <Dial callerId="1111111111">
            <Number>2222222222</Number>
        </Dial>
    </Response>

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

    Plivo Create 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 Forward 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.

    Voice Phone Number Search

    Test and validate

    When you make a call to your Plivo number, the call will be forwarded to the number specified in your code.

    Forward incoming calls to a Plivo SIP Endpoint

    In this section, We’ll walk you through setting up a call forwarding app to forward the incoming call to a Plivo number to a Plivo SIP Endpoint. If you are new to Plivo SIP Endpoints, you should read more about it here.

    To get started, below are the prequisities:

    Create an endpoint

    • Create an endpoint on Plivo with a username and a password. Create Endpoint
    • Make sure you attach the built-in direct_dial application.
    • Plivo will append random numbers to your endpoint username. Make a note of your endpoint username.

    Host your XML

    You need to host a static URL which returns a Dial XML when Plivo requests the URL.

    • Create a file with the following contents. Append phone.plivo.com to your endpoint username and change the SIP URI “sip:yoda12312312@phone.plivo.com” in the below example to your endpoint’s SIP URI. Make sure your URI starts with “sip:”
    <Response>
    <Dial callerId="18004321321">
        <User>sip:yoda12312312@phone.plivo.com</User>
    </Dial>
    </Response>
    • Host your file on github or Dropbox
    • Create a Plivo Application and set the Answer URL as the URL of your static file. Create Application
    • Open the numbers page and click on the number to link the application you created in the above step
    • Choose the application from the dropdown and click on Update Number Edit
    • If you don’t have a number, go to the Buy Number page to purchase a Plivo phone number. Voice Phone Number Search

    Register your endpoint

    Register your endpoint using a softphone, hardware phone, web SDK or mobile SDK.

    Test and validate

    When you make a call to your Plivo number, the call will be forwarded to the Plivo endpoint specified in your code.