Forward an Incoming Call

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 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 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. Lets 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
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
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
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
<?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
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
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<string, string>()
                {
                    // 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<string, string>() { });

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

                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 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.

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 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.

SMS Phone Number Search

Test it out

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

Sample XML

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

Next Step

Learn how to record a call using the API.

  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