Receive an Incoming Call

When you receive a call on your Plivo number, you can answer it using Plivo XML. In this example, when an incoming call is received, Plivo’s text-to-speech engine will play a message using the <Speak> XML.

Prerequisites

Sign up for a free Plivo trial account.
Check out our server-side SDKs page and install the right helper based on the programming language you want to use.
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.
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 speak. Now when we send an HTTP request to myvoiceapp.com/speak 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/speak.php.

Copy the relevant code below into a text file and save it. Lets call it speak.
Note: Make sure to use the appropriate file extention for your code (e.g., speak.py for Python).
Next you will now have to configure this URL in your Plivo application.

Code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
from flask import Flask, request, make_response
import plivo, plivoxml

app = Flask(__name__)

@app.route('/speak/', methods=['GET','POST'])
def speak_xml():
    # Generate a Speak XML with the details of the text to play on the call.
    body = "Hello, you just received your first call"
    r = plivoxml.Response()
    r.addSpeak(body)

    print r.to_xml()
    return Response(str(r), 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
require 'rubygems'
require 'sinatra'
require 'plivo'
include Plivo

get '/speak/' do
    r = Response.new()
    r.addSpeak("Hello, you just received your first call")

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

app.set('port', (process.env.PORT || 5000));

app.all('/speak/', function(request, response) {
  // Generate a Speak XML with the details of the text to play on the call.
  var r = plivo.Response();

  r.addSpeak('Hello, you just received your first call');
  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
<?php
    require 'vendor/autoload.php';
    use Plivo\Response;

    // Generate a Speak XML with the details of the text to play on the call.
    $body = 'Hello, you just received your first call';
    $r = new Response();
    // Add speak element
    $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
package plivoexample;

import java.io.IOException;
import com.plivo.helper.exception.PlivoException;
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 receiveCalls extends HttpServlet {
    private static final long serialVersionUID = 1L;
    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp)
            throws ServletException, IOException {

        PlivoResponse response = new PlivoResponse();
        Speak spk = new Speak("Hello, you just received your first call");

        try {
            response.append(spk);
            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  receiveCalls()),"/speak/");
        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
using System;
using System.Collections.Generic;
using System.Diagnostics;
using RestSharp;
using Plivo.XML;
using Nancy;

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

                // Add Speak XML Tag
                resp.AddSpeak("Hello, you just received your first call", new Dictionary&lt;string, string&gt;() { });

                Debug.WriteLine(resp.ToString());

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

Create an Application

Create an Application by visiting the Application Page and click on New Application or by using Plivo’s Application API.
Give your application a name. Let’s call it Receive Call. Enter your server URL (e.g., http://www.myvoiceapp.com/speak) 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.
Click on Create to save your application.

Assign a Plivo number to your app

Navigate to the Numbers page and select the phone number you want to use for this app.
Select Receive Call (name of the app) from the Plivo App dropdown list.
Click on Update to save.

Create Text to Speech Application

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

Test it out

When you make a call to your Plivo number, the call will be answered by Plivo and the message will be played.

Sample XML

<Response>
    <Speak>Hello, you just received your first call</Speak>
</Response>

Next Step

Learn how to forward an incoming call.

Receive an Incoming Call

Prerequisites

Set up a Web Server

Code

Create an Application

Assign a Plivo number to your app

Test it out

Sample XML

Next Step

Related Links