Speak API

The Speak API enables you to play a message using Plivo’s text-to-speech (TTS) engine. It is most often used to play a notification (e.g., estimated hold time, number in queue, etc.) on a live call. The languages and voice supported by this API is listed here. The Speak API also enables you to stop a TTS message which is currently being played on a call.

POST https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/Speak/

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. 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.
  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 example.com. Below is a snippet to set up the route /speak_api/ on your webserver. Now when we send an HTTP request to example.com/speak_api/ this route will be invoked. This route will return an XML which will read out a message for the caller and when 1 is pressed, speak_action route is invoked. This will initiate the Speak API.

Note: For PHP, the route will be example.com/speak_api.php.

  1. Copy the relevant code below into a text file called speak_api and save it.
  2. 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
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
import plivo, plivoxml
from flask import Flask, Response, request, url_for

app = Flask(__name__)

@app.route('/speak_api/', methods=['GET', 'POST'])
def speak_api():
    response = plivoxml.Response()
    getdigits_action_url = url_for('speak_action', _external=True)
    getDigits = plivoxml.GetDigits(action=getdigits_action_url,
            method='GET', timeout=7, numDigits=1,
            retries=1, redirect='false')
    getDigits.addSpeak("Press 1 to listen to a message")
    response.add(getDigits)
    params = {
        'length' : "10"
    }
    response.addWait(**params)
    print response.to_xml()
    return Response(str(response), mimetype='text/xml')

@app.route('/speak_action/', methods=['GET', 'POST'])
def speak_action():
    auth_id = "Your_AUTH_ID"
    auth_token = "Your_AUTH_TOKEN"
    p = plivo.RestAPI(auth_id, auth_token)

    digit = request.args.get('Digits')
    call_uuid = request.args.get('CallUUID')

    print "Call UUID is : %s " % (call_uuid)
    print "Digit pressed is : %s " % (digit)

    if digit == "1":
        params = {
            'call_uuid': call_uuid, # ID of the call
            'text' : "Hello from Speak API", # Text to be played.
            'voice' : "WOMAN", # The voice to be used, can be MAN,WOMAN. Defaults to WOMAN.
            'language' : "en-GB", # The language to be used
        }
        response = p.speak(params)
    else :
        print "Wrong Input"
    print str(response)
    return Response(str(response), mimetype='text/plain')

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

# Set te caller ID using Dial XML

get '/speak_api/' do
    r = Response.new()
    getdigits_action_url = "https://example.com/speak_action/"
    params = {
        'action' => getdigits_action_url,
        'method' => 'GET',
        'timeout' => '7',
        'numDigits' => '1',
        'retries' => '1',
        'redirect' => 'false'
    }
    getDigits = r.GetDigits(params)
    getDigits.addSpeak("Press 1 to listen to a message")
    wait_params = {
        'length' => "10"
    }
    r.addWait(wait_params)

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

get '/speak_action/' do
    AUTH_ID = "Your_AUTH_ID"
    AUTH_TOKEN = "Your_AUTH_TOKEN"
    p = RestAPI.new(AUTH_ID, AUTH_TOKEN)

    digit = params[:Digits]
    call_uuid = params[:CallUUID]

    print "Digit pressed: #{digit}"
    print "Call UUID: #{call_uuid}"

    if (digit == "1")
        params = {
            'call_uuid'=> call_uuid, # ID of the call
            'text' => "Hello from Speak API", # Text to be played.
            'voice' => "WOMAN", # The voice to be used, can be MAN,WOMAN. Defaults to WOMAN.
            'language' => "en-GB" # The language to be used
        }
        response = p.speak(params)
    else
        print "Wrong Input"
        response = "Error"
    end
    return response
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
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
var express = require('express');
var app = express();
var plivo = require('plivo');

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

app.get('/speak_api/', function(request, response){
    var r = plivo.Response();
    var getdigits_action_url = "https://example.com/speak_action/";
    var params = {
        'action': getdigits_action_url,
        'method': 'GET',
        'timeout': '7',
        'numDigits': '1',
        'retries': '1',
        'redirect': 'false'
    };
    var getDigits = r.GetDigits(params);
    getDigits.addSpeak("Press 1 to listen to a message");
    var wait_params = {
        'length': "10"
    };
    r.addWait(wait_params);

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

app.get('/speak_action/', function(request, response){
    var AUTH_ID = "Your_AUTH_ID";
    var AUTH_TOKEN = "Your_AUTH_TOKEN";
    var p = plivo.RestAPI.new(AUTH_ID, AUTH_TOKEN);

    var digit = request.query.Digits || request.body.Digits;
    var call_uuid = request.query.CallUUID || request.body.CallUUID;

    console.log("Digit pressed: ", digit);
    console.log("Call UUID: ", call_uuid);

    if (digit === "1") {
        var params = {
            'call_uuid': call_uuid, // ID of the call
            'text': "Hello from Speak API", // Text to be played.
            'voice': "WOMAN", // The voice to be used, can be MAN,WOMAN. Defaults to WOMAN.
            'language' : "en-GB" // The language to be used
        };
        response = p.speak(params);
    } else {
        console.log("Wrong Input");
        response = "Error";
    }
    return response;
});

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
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
<!-- speak_api.php -->
<?php
    require 'vendor/autoload.php';
    use Plivo\Response;
    $r = new Response();
    $getdigits_action_url = "https://example.com/speak_action.php";
    $params = array(
        'action' => $getdigits_action_url,
        'method' => 'GET',
        'timeout' => '7',
        'numDigits' =>  '1',
        'retries' => '1',
        'redirect' => 'false'
    );
    $getDigits = $r->addGetDigits($params);
    $getDigits->addSpeak("Press 1 to listen to a message");
    $waitparam = array(
        'length' => '10'
    );
    $r->addWait($waitparam);
    Header('Content-type: text/xml');
    echo($r->toXML());
?>

<!--speak_action.php-->
<?php
    require 'vendor/autoload.php';
    use Plivo\RestAPI;
    
    $auth_id = "Your_AUTH_ID";
    $auth_token = "Your_AUTH_TOKEN";
    $p = new RestAPI($auth_id, $auth_token);

    $digit = $_REQUEST['Digits'];
    $call_uuid = $_REQUEST['CallUUID'];

    if ($digit == "1") {
        $params = array(
            'call_uuid' => $call_uuid, # ID of the call
            'text' => 'Hello from Speak API', # Text to be played.
            'voice' => 'WOMAN', # The voice to be used, can be MAN,WOMAN. Defaults to WOMAN.
            'language' => 'en-GB' # The language to be used
        );
        $resp = $p->speak($params);
        print_r($resp);
    } else {
        print ("Wrong Input");
    }
?>
  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
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
// speakApi.java
package plivoexample;

import java.io.IOException;
import com.plivo.helper.exception.PlivoException;
import com.plivo.helper.xml.elements.GetDigits;
import com.plivo.helper.xml.elements.PlivoResponse;
import com.plivo.helper.xml.elements.Speak;
import com.plivo.helper.xml.elements.Wait;
import org.eclipse.jetty.server.Server;
import org.eclipse.jetty.servlet.ServletContextHandler;
import org.eclipse.jetty.servlet.ServletHolder;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

public class speakApi extends HttpServlet {
    private static final long serialVersionUID = 1L;
    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp)
            throws ServletException, IOException {
        PlivoResponse response = new PlivoResponse();
        GetDigits gd = new GetDigits();
        gd.setAction("https://example.com/speak_action/");
        gd.setMethod("GET");
        gd.setTimeout(7);
        gd.setNumDigits(1);
        gd.setRetries(1);
        gd.setRedirect(false);

        Speak spk = new Speak("Press 1 to listen to a message");
        Wait wait = new Wait();
        wait.setLength(10);
        try {
            gd.append(spk);
            response.append(gd);
            response.append(wait);
            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 speakApi()),"/speak_api/");
        context.addServlet(new ServletHolder(new speakAction()),"/speak_action/");
        server.start();
        server.join();
    }
}

// speakAction.java
package plivoexample;

import java.io.IOException;
import java.util.LinkedHashMap;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import com.plivo.helper.api.client.RestAPI;
import com.plivo.helper.api.response.response.GenericResponse;
import com.plivo.helper.exception.PlivoException;

public class speakAction extends HttpServlet {
    private static final long serialVersionUID = 1L;
    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp)
            throws ServletException, IOException {
        String auth_id = "Your_AUTH_ID";
        String auth_token = "Your_AUTH_TOKEN";
        RestAPI api = new RestAPI(auth_Id, auth_Token, "v1");

        String digit = req.getParameter("Digits");
        String call_uuid = req.getParameter("CallUUID");
        System.out.println("Digit : " + digit + " Call UUID : " + call_uuid);

        if(digit.equals("1")){
            LinkedHashMap<String, String> parameters = new LinkedHashMap<String, String>();
            parameters.put("call_uuid",call_uuid); // ID of the call
            parameters.put("text","Hello from Speak Api"); // Text to be played.
            parameters.put("voice","WOMAN"); // The voice to be used, can be MAN,WOMAN. Defaults to WOMAN.
            parameters.put("language","en-GB"); // method to invoke the answer_url

            try{
                GenericResponse speak = api.speak(parameters);
                System.out.println(speak);
            }catch (PlivoException e){
                System.out.println(e.getLocalizedMessage());
            }
        }else{
            System.out.println("Wrong Input");
        }
    }
}
 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
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
using System;
using System.Collections.Generic;
using System.Diagnostics;
using RestSharp;
using Plivo.XML;
using Plivo.API;
using Nancy;

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

                String getdigits_action_url = "http://example.com/speak_action/";

                // Add GetDigits XML Tag
                GetDigits gd = new GetDigits("",new Dictionary<string, string>()
                {
                    {"action",getdigits_action_url}, // The URL to which the digits are sent.
                    {"method","GET"}, // Submit to action URL using GET or POST.
                    {"timeout","7"}, // Time in seconds to wait to receive the first digit.
                    {"retries","1"}, // Indicates the number of retries the user is allowed to input the digits,
                    {"redirect","false"} // Redirect to action URL if true. If false,only request the URL and continue to next element.
                });

                // Add GetDigits Speak XML Tag
                gd.AddSpeak("Press 1 to listen to a message",new Dictionary<string,string>());
                resp.Add(gd);

                // Add Wait XML Tag
                resp.AddWait(new Dictionary<string, string>()
                {
                    {"length","10"}
                });

                Debug.WriteLine(resp.ToString());

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

            Get["/speak_action/"] = x =>
            {
                String digits = Request.Query["Digits"];
                String uuid = Request.Query["CallUUID"];
                Debug.WriteLine("Digit pressed : {0}, Call UUID : {1}",digits, uuid );

                if (digits == "1")
                {
                    RestAPI plivo = new RestAPI("Your_AUTH_ID", "Your_AUTH_TOKEN");

                    // Call to Speak API
                    IRestResponse<GenericResponse> resp = plivo.speak(new Dictionary<string, string>()
                    {
                        { "call_uuid", uuid }, // ID of the call
                        { "text", "Hello, from Speak API" }, // Text to be played.
                        { "voice", "WOMAN" }, // The voice to be used, can be MAN,WOMAN. Defaults to WOMAN.
                        {"language","en-GB"} // The language to be used
                    });

                    Debug.WriteLine(resp.Content);
                }
                else
                {
                    Debug.WriteLine("Wrong Input");
                }
                return "Speak API";
            };
        }
    }
}

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 Speak API. Enter your server URL (e.g., http://www.example.com/speak_api) 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 Speak API 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 Speak Api (name of the app) from the Plivo App dropdown list.
  3. Click on ‘Update’ to save.

Create Speak API Application

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

Phone Number Search

Test it out

When you make a call to your Plivo number, the call will be answered by Plivo and the message “Press 1 to listen to a message” will be played. If you press 1, the Speak API is used to say “Hello from Speak API”.

Sample XML

Here is the XML returned from /speak_api/:

<Response>
    <GetDigits redirect="false" retries="1" method="GET" numDigits="1" action="http://example.com/speak_action/" timeout="7">
        <Speak>Press 1 to listen to a message</Speak>
    </GetDigits>
    <Wait length="10"/>
</Response>

Here is the response from /speak_action/:

Digit pressed: 1
Call UUID: 01d03d86-958f-11e4-a25f-c374cdd23d80 

(202, {
        u'api_id': u'0753c6a6-958f-11e4-ac1f-22000ac51de6', 
        u'message': u'speak started'
    }
)

Next Step

Learn how to use the Transfer 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