Latest Legacy

Plivo XML Overview

Your application must use Plivo XML to control a call or message synchronously. You can combine XML elements in different ways to perform complex actions, such as:

  • Playing music while a caller is on hold
  • Reading specified text to a caller
  • Requesting numeric input
  • Dialing and connecting to another number

How it works

Suppose you want to play audio to a caller when you receive an incoming call. Here’s how Plivo lets you do that.

Plivo XML Overview

Someone makes an incoming call to a Plivo number or SIP endpoint. Plivo looks up the URL configured for an application you’ve written that’s linked to the Plivo number or endpoint and makes a request to that URL. Your web application at that URL returns an XML document that provides instructions to the Plivo API on how the call should proceed.

In this example, Plivo works like an HTTP client that receives a call and requests instructions from your web application to control the call. By default, XML requests to your application are made via the HTTP POST verb, but you can configure Plivo to make XML requests to your application via GET or POST by changing a configuration parameter.

You can set configuration parameters when making outbound calls or sending messages. For incoming calls and messages, Plivo uses the configuration attached to the application that’s linked to the phone number on which your incoming call or message is received.

Controlling outbound calls

You can control outgoing calls using XML too. The initial outbound call is made through an API request; when the call gets answered, the Plivo API calls the web application specified by the answer URL, which provides instructions on how to process the call.

XML request

When Plivo makes a synchronous HTTP request to your application, the API expects an XML document in response. Plivo sends a few parameters with the HTTP request that your application can act upon before responding.

Note: The maximum allowed size of the XML document in response to an HTTP request from Plivo to your application is 100 Kb.

Voice calls

Parameters Plivo sends for voice calls

CallUUID

A unique identifier for this call.

From

The phone number of the party that initiated the call, including the country code.

If the call is inbound, then this parameter is the caller’s caller ID. If the call is outbound — initiated via a request to the API — then this is the phone number you specify as the caller ID.

To

The phone number of the called party, including the country code.

If the call is inbound, then it’s your incoming phone number. If the call is outbound, then it’s the destination phone number you provided.

ForwardedFrom

Set only when a received call is a forwarded call. Its value depends on the caller’s carrier. Not all carriers pass this information.

CallStatus

Indicates the status of the call.

The value is set to either ringing, in-progress, or completed. If the call is hung up, the CallStatus will be set to completed for inbound calls and to completed, busy, failed, timeout, or no-answer for outbound calls.

Direction

Indicates the direction of the call.

In most cases this will be inbound, and the call will be in a ringing state. If you’re using the Call API, the direction will be outbound and the call will be in an answered state.

ALegUUID

Contains a unique identifier that identifies the first leg of an outbound call.

If the call direction is inbound, this parameter will not be present.

ALegRequestUUID

Contains a unique request identifier that Plivo returns for an API request during an outbound call.

If the call direction is inbound, this parameter will not be present.

HangupCause

Contains the standard telephony hangup cause of a call (inbound and outbound).

If a call is not hung up, this parameter will not be present.

Duration

Contains the duration of the call in seconds.

If the call is not hung up, this parameter will not be present.

BillDuration

Contains the billed duration of the call in seconds.

If the call is not hung up, this parameter will not be present.

SIP headers

If you’re using a SIP endpoint and you’ve configured your SIP phone to send custom SIP headers starting with X-PH-, Plivo will send these SIP headers with the HTTP request.

Outbound calls

For outbound calls, you can set custom SIP headers while :

Inbound calls

For inbound calls, you need a SIP phone that allows custom SIP headers. If you have one, SIP headers that start with X-PH- will sent as HTTP requests.

Validation

All requests Plivo makes to your server URLs include X-Plivo-Signature-V3 and X-Plivo-Signature-V3-Nonce HTTP headers. To validate a request and to verify that it originated from Plivo, you must generate a signature at your end and check that it matches the X-Plivo-Signature-V3 parameter in the HTTP header. Read more about signature validation.

Plivo SDKs provide methods to compute and verify X-Plivo-Signature-V3.

Arguments

uri string

The callback that you want to validate. This uri can be answer_url, url (message callback), message_url, callback_url, action_url, or hangup_url.

nonce string

A randomly generated string used to verify requests. You can get the nonce from the event details posted to your callback.

X-Plivo-Signature-V3 or X-Plivo-Signature-Ma-V3 string

You can get these values from the event details posted to your callback.

auth_token string

Your account Auth Token, which you can get from the overview screen of the Plivo console.

Example Request

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
from flask import Flask, request, make_response, url_for
import plivo
from urllib.parse import urlparse, parse_qs
from plivo import utils
from plivo import plivoxml

app = Flask(__name__)

@app.route('/speak/', methods=['GET', 'POST'])
def validate_signature():
    signature = request.headers.get('X-Plivo-Signature-V3', 'signature')
    nonce = request.headers.get('X-Plivo-Signature-V3-Nonce', '12345')
    url = url_for('validate_signature', _external=True)
    auth_token = "<auth_token>"
    method = request.method
    if method == 'GET':
        valid = plivo.utils.validate_v3_signature(
            method, url, nonce, auth_token, signature)
    else:
        params = request.get_json()
        valid = plivo.utils.validate_v3_signature(
            method, url, nonce, auth_token, signature, params)
    print(valid)
    r = plivoxml.ResponseElement()
    speak_params = {
        'loop': '3'
    }
    r.add(plivoxml.SpeakElement("Hello, from Plivo", **speak_params))
    response = make_response(r.to_string())
    response.headers["Content-type"] = "text/xml"
    print(r.to_string())
    return response


if __name__ == "__main__":
    app.run(host='0.0.0.0', debug=True)

Was this code helpful

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

get '/speak/' do
	auth_token = "<auth_token>"
	signature = headers.fetch("X-Plivo-Signature-V3", "signature")
	nonce = headers.fetch("X-Plivo-Signature-V3-Nonce", "12345")
	url = request.url
	method = "GET"
	output = Plivo::Utils.valid_signatureV3?(url, nonce, signature, auth_token, method)
	puts output

	response = Response.new
	response.addSpeak("Hello, Welcome to Plivo")
	xml = PlivoXML.new(response)
	content_type 'text/xml'
	return xml.to_s
end

post '/speak/' do
	auth_token = "<auth_token>"
	signature = headers.fetch("X-Plivo-Signature-V3", "signature")
	nonce = headers.fetch("X-Plivo-Signature-V3-Nonce", "12345")
	url = request.url
	method = "POST"
	output = Plivo::Utils.valid_signatureV3?(url, nonce, signature, auth_token, method, params)
	puts output

	response = Response.new
	response.addSpeak("Hello, Welcome to Plivo")
	xml = PlivoXML.new(response)
	content_type 'text/xml'
	return xml.to_s

Was this code helpful

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
let express = require('express');
let app = express();
app.set('port', (process.env.PORT || 5000));
app.use(express.static(__dirname + '/public'));

app.all('/speak/', function (request, response) {
    let headers = request.headers;
    console.log(headers);
    let signature = request["X-Plivo-Signature-V3"];
    let nonce = request["X-Plivo-Signature-V3-Nonce"];
    if (!signature) {
        signature = "signature";
    }
    if (!nonce) {
        nonce = "12345";
    }
    let url = request.url;
    let auth_token = "<auth_token>";
    console.log(signature, nonce);
    let method = request.method;
    let validate;
    if (method == "GET") {
        validate = plivo.validateV3Signature(method, url, nonce, auth_token, signature);
    } else {
        let params = request.body;
        validate = plivo.validateV3Signature(method, url, nonce, auth_token, signature, params);
    }
    console.log(validate);

    let r = plivo.Response();
    r.addSpeak("Hello from Plivo");
    console.log(r.toXML());

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

app.listen(app.get('port'), function () {
    console.log('Node app is running on port', app.get('port'));
});

Was this code helpful

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
<?php
require 'vendor/autoload.php';
use Plivo\Exceptions\PlivoValidationException;
use Plivo\Util\v3SignatureValidation;
use Plivo\XML\Response;

if (preg_match('/speak/', $_SERVER["REQUEST_URI"])) {
    $auth_token = "<auth_token>";
    $signature = @$_SERVER["X-Plivo-Signature-V3"] ?: 'signature';
    $nonce = @$_SERVER["X-Plivo-Signature-V3-Nonce"] ?: 'nonce';
    $url = 'http' . (isset($_SERVER['HTTPS']) ? 's' : '') . '://' . "{$_SERVER['HTTP_HOST']}{$_SERVER['REQUEST_URI']}";
    $method = $_SERVER['REQUEST_METHOD'];
    $SVUtil = new v3SignatureValidation();
    if ($method == "GET") {
        try {
            $valid = $SVUtil->validateV3Signature($method, $url, $nonce, $auth_token, $signature);
        } catch (PlivoValidationException $e) {
            echo("error");
        }
    } else {
        $body = file_get_contents("php://input");
        $params = json_decode($body, true);
        try {
            $valid = $SVUtil->validateV3Signature($method, $url, $nonce, $auth_token, $signature, $params);
        } catch (PlivoValidationException $e) {
            echo("error");
        }
    }
    echo $valid;
    $body = 'Hi, Calling from Plivo';
    $attributes = array(
        'loop' => 3,
    );
    $r = new Response();
    $r->addSpeak($body, $attributes);
    echo($r->toXML());
} else {
    echo "<p>Welcome to Plivo</p>";
}

Was this code helpful

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
package plivoexample;

import java.io.IOException;
import java.net.URLDecoder;
import java.util.Iterator;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;

import com.plivo.helper.exception.PlivoException;
import com.plivo.helper.xml.elements.Message;
import com.plivo.helper.xml.elements.PlivoResponse;

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;

import com.plivo.helper.util.*;

public class validateSignature extends HttpServlet {
  private static final long serialVersionUID = 1L;
  @Override
  protected void doGet(HttpServletRequest req, HttpServletResponse resp)
    throws ServletException, IOException {
    String auth_token = "<auth_token>";
    String signature = req.getHeader("X-Plivo-Signature-V3");
    String nonce = req.getHeader("X-Plivo-Signature-V3-Nonce");
    String url = req.getRequestURL().toString();
    String method = req.getMethod();

    if(method == "GET") {
      try {
        Boolean isValid = Utils.validateSignatureV3(url, nonce, signature, auth_token, method);
        System.out.println("Valid : " + isValid);
      } catch (PlivoException e) {
        e.printStackTrace();
      }
    }
    else{
      try {
        Map<String, String> params = req.getParameterMap();
        Boolean isValid = Utils.validateSignatureV3(url, nonce, signature, auth_token, method, params);
        System.out.println("Valid : " + isValid);
      } catch (PlivoException e) {
        e.printStackTrace();
      }
    }

    PlivoResponse response = new PlivoResponse();
    Speak spk = new Speak("Hello, Welcome to Plivo");

    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  validateSignature()),"/speak");
    server.start();
    server.join();
  }
}

Was this code helpful

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
using System;
using System.Collections.Generic;
using System.Diagnostics;
using RestSharp;
using Plivo.XML;
using Plivo;
using Nancy;

namespace plivo_dotnet_app
{
    public sealed class Program : NancyModule
    {
        public Program()
        {
            Get("/speak/", x =>
            {
                string signature = Request.Headers["X-Plivo-Signature-V3"].ToString();
                string nonce = Request.Headers["X-Plivo-Signature-V3_Nonce"].ToString();
                string auth_token = "<auth_token>";
                string method = Request.Method;
                string url = Request.Url;
                bool valid;
                Dictionary<string, string> parameters = new Dictionary<string, string>();
                valid = Plivo.Utilities.XPlivoSignatureV3.VerifySignature(url, nonce, signature, auth_token, method);
                Debug.WriteLine("Valid : " + valid);

                Plivo.XML.Response resp = new Plivo.XML.Response();
                resp.AddSpeak("Hello, Welcome to Plivo", parameters);
                Debug.WriteLine(resp.ToString());

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

            Post<Response>("/speak/", x =>
            {
                string signature = Request.Headers["X-Plivo-Signature-V3"].ToString();
                string nonce = Request.Headers["X-Plivo-Signature-V3_Nonce"].ToString();
                string auth_token = "<auth_token>";
                string method = Request.Method;
                string url = Request.Url;
                bool valid;
                Dictionary<string, string> parameters = new Dictionary<string, string>();
                parameters = Request.Form;
                valid = Plivo.Utilities.XPlivoSignatureV3.VerifySignature(url, nonce, signature, auth_token, method, parameters);
                Debug.WriteLine("Valid : " + valid);

                Plivo.XML.Response resp = new Plivo.XML.Response();
                resp.AddSpeak("Hello, Welcome to Plivo", parameters);
                Debug.WriteLine(resp.ToString());

                var output = resp.ToString();
                var res = (Nancy.Response) output;
                res.ContentType = "text/xml";
                return res;
            });
        }
        
        static void Main(string[] args)
        {
            var p = new Program();
        }
    }
}

Was this code helpful

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
package main

import (
	"encoding/json"
	"fmt"
	"io/ioutil"
	"net/http"
	"reflect"
	"unsafe"

	"github.com/plivo/plivo-go/v7"
	"github.com/plivo/plivo-go/v7/xml"
	"github.com/sirupsen/logrus"
)

type Message struct {
	Id   string `json:"id"`
	Name string `json:"name"`
}

func BytesToString(b []byte) string {
	bh := (*reflect.SliceHeader)(unsafe.Pointer(&b))
	sh := reflect.StringHeader{bh.Data, bh.Len}
	return *(*string)(unsafe.Pointer(&sh))
}

func speak(w http.ResponseWriter, request *http.Request) {
	url := request.Host + request.RequestURI
	signature := request.Header.Get("X-Plivo-Signature-V3")
	nonce := request.Header.Get("X-Plivo-Signature-V3-Nonce")
	method := request.Method
	authToken := "<auth_token>"
	var valid bool
	if method == "GET" {
		valid = plivo.ValidateSignatureV3(url, nonce, method, signature, authToken)
	} else {
		parameters := make(map[string]string)
		b, err := ioutil.ReadAll(request.Body)
		defer request.Body.Close()
		if err != nil {
			http.Error(w, err.Error(), 500)
			return
		}

		var msg Message
		err = json.Unmarshal(b, &msg)
		if err != nil {
			http.Error(w, err.Error(), 500)
			return
		}

		var inInterface map[string]interface{}
		inrec, _ := json.Marshal(msg)
		json.Unmarshal(inrec, &inInterface)
		for field, val := range inInterface {
			parameters[field] = val.(string)
		}

		w.Header().Set("content-type", "text/xml")
		valid = plivo.ValidateSignatureV3(url, nonce, method, signature, authToken, parameters)
	}
	logrus.Info(valid)
	response := xml.ResponseElement{
		Contents: []interface{}{
			new(xml.SpeakElement).
				AddSpeak("Go Green, Go Plivo."),
		},
	}
	fmt.Fprintf(w, response.String())
}

func main() {
	http.HandleFunc("/speak/", speak)
	http.ListenAndServe(":5000", nil)
}

Was this code helpful

Response

  true

Call status

Plivo sends a call status to request URLs under the CallStatus key. Your application can make decisions about how to process a call based on this status.

Plivo will send one of these values under the CallStatus parameter:

List of CallStatus values

in-progress string

The call was answered and is currently in progress. Calls under this status can be explicitly terminated using the Hangup API.

completed string

The call was completed. It was either terminated using the Hangup API or ended by one of the parties in the call.

ringing string

The call is currently ringing. This status is sent to the Ring URL.

no-answer string

The call wasn’t answered by the recipient. Your application must have the logic to parse this parameter and take actions based on it.

busy string

The recipient is busy on another call. You may retry after some time.

cancel string

The call was canceled by the caller

timeout string

There was a timeout while connecting your call, caused by either an issue with one of the terminating carriers or network lag in our system.

Event

Plivo generates events when the state of a call changes to let the application know about the progress of the call.

Plivo will send one of these values under the Event parameter:

List of Event values

StartApp

The call was answered and is currently in progress. Calls with this status can be explicitly terminated using the Hangup API.

Transfer

The call was transferred using the Transfer API. This event is sent to the target URL of the XML you return from the transfer URL.

Redirect

The call was redirected using the Redirect XML element.

MachineDetection

Plivo generates this event when the machine_detection parameter is used in the Outbound Call API request. The event is sent to the machine_detection URL.

XML response

Voice calls

When your application is initiated to make a call, Plivo makes an HTTP request to the answer_url, which is one of the mandatory parameters when making an outbound call.

SMS

When your application is initiated to send a message, Plivo makes an HTTP request to the message_url, which is one of the mandatory parameters when sending a message.

Requirements

  • The answer_url or the message_url should respond with an XML document that provides instructions to control the call.
  • The Content Type of the response header, returned by the message_url, must be set to text/xml or application/xml.
  • The XML document returned should contain valid Plivo XML elements.

How to structure your XML document

The parent element

The <Response> element is the parent element of Plivo’s XML. All child elements must be nested within this element; any other structure is considered invalid.

Child elements

Child elements are Plivo’s proprietary elements and are case-sensitive. For example, using <speak> instead of <Speak> would result in an error. Attributes for child elements are also case-sensitive and “camelCased.”

When Plivo receives an XML response, it executes elements from top to bottom. For example, the XML snippet at right first announces “This is Plivo” to the caller, then plays an MP3 file, then hangs up.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Speak>This is Plivo</Speak>
  <Play>https://s3.amazonaws.com/plivocloud/Trumpet.mp3</Play>
</Response>

The MultiPartyCall element Beta

The MultiPartyCall element can add a participant to an ongoing multiparty call (MPC) or start a new multiparty call and to add a participant to it.

Note: Some of this element’s attributes apply at the MPC level, some at the participant level. For example, maxDuration and maxParticipants set the MPC’s maximum duration and maximum allowed participants, while role and coachMode update a specific participant.

Attributes

maxDurationMPC levelinteger

Sets the Max Duration (in seconds) property of the MPC resource. The MPC will end after this period.

maxDuration is counted from the call initiation time.

Allowed values: 300 (five minutes) to 28,800 (eight hours)
Defaults to 14,400 (four hours).

maxParticipantsMPC levelinteger

Sets the Max Participants property of the MPC resource.

Allowed values: 2 to 10
Defaults to 10.

waitMusicUrlMPC levelstring

The URL of an audio file to be played in a loop to participants waiting for the MPC to begin.

The URL must return an XML document with Play, Speak, and/or Wait elements only. All other elements are ignored.

Defaults to Plivo’s default wait music.

Note: If the URL is not reachable or does not return a valid XML document, no music will be played.

waitMusicMethodMPC levelstring

The HTTP verb used to invoke the URL configured as waitMusicUrl.

Allowed values: GET, POST
Defaults to GET.

agentHoldMusicUrlMPC levelstring

The URL of an audio file to be played to agents while they’re on hold. Sets the Agent Hold Music URL property of the MPC resource.

The URL must return an XML document with Play, Speak, and/or Wait elements only. All other elements are ignored.

Defaults to Plivo’s default hold music.

Note: If the URL is not reachable or does not return a valid XML document, no music will be played.

agentHoldMusicMethodMPC levelstring

The HTTP verb used to invoke the URL configured as agentHoldMusicUrl.

Allowed values: GET, POST
Defaults to GET.

customerHoldMusicUrlMPC levelstring

The URL of an audio file to be played to customers while they’re on hold. Sets the Customer Hold Music URL property of the MPC resource.

The URL must return an XML document with Play, Speak, and/or Wait elements only. All other elements are ignored.

Default is Plivo’s default hold music.

Note: If the URL is not reachable or does not return a valid XML document, no music will be played.

customerHoldMusicMethodMPC levelstring

The HTTP verb that should be used to invoke the URL configured as customerHoldMusicUrl.

Allowed values: GET, POST
Defaults to GET.

recordMPC levelboolean

Indicates whether the MPC should be recorded. Recording is initiated the first time a participant joins the MPC with record set to true.

Another participant joining with record set to false will not stop the recording.

Note: Supervisor’s voice will be present in the recording regardless of whether coach mode is on or off.

Defaults to false.

recordFileFormatMPC levelstring

Specifies the audio format for the recording.

Allowed values: mp3, wav
Defaults to mp3.

recordingCallbackUrlMPC levelstring

The URL to which MPC recording events are posted.

recordingCallbackMethodMPC levelstring

The HTTP verb that should be used to invoke the URL configured as recordingCallbackUrl.

Allowed values: GET, POST
Defaults to POST.

recordMinMemberCountMPC levelstring

Starts MPC recording when count is reached. Applies only when `record` is set to true in the MultiPartyCall element.

Allowed values: 1, 2
Defaults to 1.

When set to 1, recording will start as soon as one member has entered the MPC.

When set to 2, recording will start only when two members have joined the MPC. Recording will not start for a single member in MPC even if `record` is set to true in the MultiPartyCall element.

recordParticipantTrackBoolean

Indicates whether single-track or participant-level recording will be initiated when the participant joins the MPC bridge.

Default: false

statusCallbackUrlMPC levelstring

The URL to which MPC status change events are sent.

statusCallbackMethodMPC levelstring

The HTTP verb that should be used to invoke the URL configured as statusCallbackUrl.

Allowed values: GET, POST
Defaults to POST.

statusCallbackEventsMPC levelstring

This attribute controls which of these events, generated over the course of the multiparty call, should be pushed to the specified status_callback_url:

  • MPCInitialized
  • MPCStart
  • MPCEnd
  • ParticipantJoin
  • ParticipantExit
  • ParticipantMute
  • ParticipantUnmute
  • ParticipantHold
  • ParticipantUnhold
  • ParticipantSpeakStart
  • ParticipantSpeakStop
  • ParticipantCoachModeStart
  • ParticipantCoachModeStop
  • ParticipantDigitInput
  • AddParticipantByAPIActionInitiated
  • AddParticipantByAPIActionCompleted

Allowed values: mpc-state-changes, participant-state-changes, participant-digit-input-events, participant-speak-events, add-participant-api-events (in any order, separated by commas)

Note:
  • When mpc-state-changes is included, events for MPCInitialized, MPCStart, and MPCEnd are sent.
  • When participant-state-changes is included, events for ParticipantJoin, ParticipantExit, ParticipantMute,ParticipantUnmute, ParticipantHold, ParticipantUnhold, ParticipantCoachModeStart, ParticipantCoachModeStop are sent.
  • When participant-speak-events is included, events for ParticipantSpeakStart and ParticipantSpeakStop are sent whenever any participant begins or stops speaking.
  • When participant-digit-input-events is included, ParticipantDigitInput events are sent whenever any participant provides a DTMF input.
  • When add-participant-api-events is included, AddParticipantByAPIActionInitiated and AddParticipantByAPIActionCompleted events are sent when an Add Participant By API Action is carried out.

Defaults to mpc-state-changes,participant-state-changes.

stayAloneParticipant levelboolean

Indicates whether a participant should be removed from the call if they’re the only member remaining in the call.

Allowed values: true, false
Defaults to false.

roleParticipant levelstring

Must be one of Agent, Supervisor, or Customer.

coachModeParticipant levelboolean

Only applies to participants with the role Supervisor.

Defaults to true (by default, supervisors are in coach mode).

muteParticipant levelboolean

Indicates whether the participant should join muted.

Allowed values: true, false
Defaults to false.

holdParticipant levelboolean

Indicates whether the participant should join on hold or not.

Allowed values: true, false
Defaults to false.

startMpcOnEnterParticipant levelboolean

Indicates whether the MPC should start, if not already started, when this participant joins the call.

Allowed values: true, false
Defaults to true.

endMpcOnExitParticipant levelboolean

Indicates whether the MPC should be ended when this participant exits the call.

Allowed values: true, false
Defaults to false.

enterSoundParticipant levelstring

The sound to play on the bridge when the participant enters the MPC. Note that enterSound should never be played for supervisors entering when coach mode is set to true.

Allowed values: none, beep:1, beep:2, URL that returns an XML document with Play, Speak, and/or Wait elements only
Defaults to beep:1.

enterSoundMethodParticipant levelstring

The HTTP verb that should be used to invoke the URL configured as enterSound.

Allowed values: GET, POST
Defaults to GET.

exitSoundParticipant levelstring

The sound to play when the participant exits the MPC.

This sound should be played even if the call is hung up while in an MPC.

The exit sound should never be played for supervisors entering with coach mode set to true.

Allowed values: none, beep:1, beep:2, URL that returns an XML document with Play, Speak, and/or Wait elements only
Defaults to beep:2.

exitSoundMethodParticipant levelstring

The HTTP verb that should be used to invoke the URL configured as exitSound.

Allowed values: GET, POST
Defaults to GET.

onExitActionUrlParticipant levelstring

Action URL invoked when this participant exits the MPC. If the participant call hangs up while in the MPC or if the call is transferred to another XML document, then a request to this URL will not be invoked.

If onExitActionUrl is provided, an XML document to control the flow of the call from here on is expected in the response.

onExitActionMethodParticipant levelstring

The HTTP verb that should be used to invoke the URL configured as onExitActionUrl.

Allowed values: GET, POST
Defaults to POST.

relayDTMFInputsParticipant levelboolean

Indicates whether DTMF inputs pressed by one of the participants should be transmitted to other participants on the MPC.

Allowed values: true, false
Defaults to false.

List of events and parameters sent to the statusCallbackUrl

This information is sent to statusCallbackUrl when an event is triggered:

DigitInputstring A list of digits pressed by the participant.
EventNamestring Event that triggered this notification. This parameter will have values from the above events list.
EventTimestampstring Timestamp at which the event occurred. Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
MPCBilledAmountstring Amount charged for this call, in USD. This value is null if the MPC has not ended.
MPCBilledDurationstring Duration in seconds for which the MPC was billed. This value is null if the MPC has not ended.
MPCCreationTimestring Timestamp at which the MPC was created. Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
MPCDurationstring Total duration in seconds of the MPC. This value is null if the MPC has not ended.
MPCEndTimestring Timestamp at which the MPC ended. Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
MPCNamestring Friendly name provided during the creation of the MPC.
MPCStartTimestring Timestamp at which the MPC was started. Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
MPCTerminationCausestring Reason for MPC termination. Refer to our list of termination causes and sources. This value is null if the MPC has not ended.
MPCTerminationCauseCodestring A unique integer code for the termination cause. Refer to our list of hangup causes and sources. This value is null if the MPC has not ended.
MPCUUIDstring Unique ID of the multiparty call.
MemberAddressstring Phone number or endpoint username of the participant added to the MPC.
MemberIDstring Unique identifier of the participant whose event triggered this callback in the MPC.
ParticipantCallDirectionstring Indicates the direction of the call (inbound or outbound) through which the participant was added to the MPC.
ParticipantCallFromstring Phone number or the endpoint username of the participant that added the respective participant to MPC.
ParticipantCallTostring Phone number or the endpoint username of the participant added to the MPC.
ParticipantCallUUIDstring Call UUID of the participant’s call leg.
ParticipantCoachModestring

Indicates whether the participant is in coach mode.

Allowed values: true, false

ParticipantExitCausestring Cause of the participant’s termination from the MPC.
ParticipantExitTimestring Timestamp at which the participant was terminated from the MPC. Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
ParticipantJoinTimestring Timestamp at which the participant was added to the MPC. Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
ParticipantRolestring

Identifies the role of the participant in the MPC.

Allowed values: Agent, Supervisor, Customer

SequenceNumberstring Indicates the sequence of the callback. Helpful to sort the callback events posted to the status_callback_url.
STIRVerification string

For outbound calls: Gives details about the attestation assigned to the call by Plivo

For inbound calls: Gives details about the attestation received on the inbound call to your Plivo phone number.

Possible values:

  • Verified means the call is from a verified caller who has authorized access to the customer’s caller ID, and hence should be treated with confidence. Verified is equivalent to attestation level A.
  • Not Verified means that, for this call, either the caller is not verified, or it’s uncertain whether they have access to the caller ID used, or both. Not Verified means the call received attestation level B or C.
  • Not Applicable means STIR/SHAKEN doesn’t apply to this call, as would be the case if a call is not addressed to a US number or if it’s a cloud call (WebRTC or SIP).

Read more about STIR/SHAKEN here.

List of events and parameters sent to the recordingCallbackUrl

These events are generated:

  • MPCRecordingInitiated
  • MPCRecordingPaused
  • MPCRecordingResumed
  • MPCRecordingCompleted
  • MPCRecordingFailed

This information is sent to the URL when an event is triggered:

EventNamestringEvent that triggered this notification. This parameter will have one of the values from the list of events above.
EventTimestampstringTimestamp at which the event occurred.

Format: YYYY-MM-DD HH:mm:ss+|-hh:mm

MPCNamestringFriendly name provided during the creation of the MPC.
MPCUUIDstringUnique ID of the multiparty call.
RecordingDurationstringDuration of recording in seconds.
RecordingEndTimestringTimestamp at which the recording ended. Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
RecordingFormatstring

Format of the recording.

Allowed values: mp3, wav

RecordingResourceURLstringResource URL of the recording file. You can use this URL to fetch recording details later.
RecordingStartTimestringTimestamp at which the recording started. Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
RecordingURLstringComplete path to the recording file URL.
RecordingUUIDstringUnique identifier to identify the recording file.
SequenceNumberstringIndicates the sequence of the callback. Helpful to sort the callback events posted to the recording_callback_url.

Parameters sent to the onExitActionUrl

MPCUUIDUnique ID of the multiparty call.
MPCFriendlyNameFriendly name provided during the creation of the MPC.
MemberIDUnique identifier to identify each participant in the MPC.
ParticipantCallUUIDCall UUID of the participant’s call leg.
ParticipantJoinTimeTimestamp at which the participant was added to the MPC. Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
ParticipantEndTimeTimestamp at which the participant was terminated from the MPC. Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
ParticipantRole

Identifies the role of the participant in the MPC.

Allowed values: Agent, Supervisor, Customer

The first caller to execute this XML initializes and starts the multiparty call named My MPC. The next caller to execute this XML joins the same MPC.

Example Request

1
2
3
4
5
6
7
8
9
10
from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(
    plivoxml.MultiPartyCallElement(
        content="mpc_name", role="customer", max_duration=10000
    )
)

print(response.to_string())

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
require 'rubygems'
require 'plivo'
include Plivo::XML
include Plivo::Exceptions

begin
  response = Response.new
  response.addMultiPartyCall(
          'mpc_name',
          role: 'Agent',
          maxDuration: 10000)
  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end

Was this code helpful

1
2
3
4
5
6
7
8
9
10
var plivo = require('plivo');

var response = plivo.Response();

response.addMultiPartyCall('mpc_name', {
    role: 'customer',
    maxDuration: 10000
});

console.log(response.toXML());

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
<?php
require 'vendor/autoload.php';

use Plivo\Exceptions\PlivoXMLException;
use Plivo\Util\MPCUtils;
use Plivo\XML\Response;

$response = new Response();

$response->addMultiPartyCall("mpc_name", ["role" => "Customer", "maxDuration" => 10000]);

Header('Content-type: text/xml');
echo ($response->toXML());

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
import com.plivo.api.exceptions.PlivoValidationException;
import com.plivo.api.exceptions.PlivoXmlException;
import com.plivo.api.models.multipartycall.MultiPartyCallUtils;
import com.plivo.api.xml.MultiPartyCall;
import com.plivo.api.xml.Response;

public class Test {
    public static void main(String[] args) throws PlivoValidationException, PlivoXmlException {
        Response resp = new Response();
        resp.children(new MultiPartyCall("mpc_name", MultiPartyCallUtils.customer).maxDuration(10000));
        System.out.println(resp.toXmlString());
    }
}

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
using System;
using Plivo.Exception;
using System.Collections.Generic;

namespace PlivoExamples {
  class Program {
    static void Main(string[] args) {
      try {
        Plivo.XML.Response resp = new Plivo.XML.Response();
        resp.AddMultiPartyCall("mpc_name",
          new Dictionary < string, string > () {
            {"role","customer"},
            {"maxDuration","10000"}
          });
        Console.WriteLine(resp.ToString());
      } catch (PlivoRestException e) {
        Console.WriteLine("Exception: " + e.Message);
      }

    }
  }
}

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
package main

import "github.com/plivo/plivo-go/v7/xml"

func main() {
    response: = xml.ResponseElement {
        Contents: [] interface {} {

            new(xml.MultiPartyCallElement).
            SetRole("customer").
            SetMaxDuration(10000).
            SetContents("mpc_name"),
        },
    }
    print(response.String())
}

Was this code helpful

Response

<Response>
   <MultiPartyCall role="customer" maxDuration="10000" maxParticipants="10" waitMusicMethod="GET" agentHoldMusicMethod="GET" customerHoldMusicMethod="GET" record="false" recordFileFormat="mp3" recordingCallbackMethod="GET" statusCallbackEvents="mpc-state-changes,participant-state-changes" statusCallbackMethod="POST" stayAlone="false" coachMode="true" mute="false" hold="false" startMpcOnEnter="true" endMpcOnExit="false" enterSound="beep:1" enterSoundMethod="GET" exitSound="beep:2" exitSoundMethod="GET" onExitActionMethod="POST" relayDTMFInputs="false">mpc_name</MultiPartyCall>
</Response>

The Conference element

You can use the Conference element to start a conference call, and callers can then join to talk to others connected to that call. Conference names are mapped to a user account, which means that two accounts with same conference name will dial into different conferences. The maximum number of members in a single conference is 20.

Attributes

muted boolean

Indicates whether the conference is muted. To mute each member who joins a conference, set this attribute to true. The member will still be able to listen to the people in the conference.

Allowed values: true, false
Defaults to false.

enterSound string

The sound to be played when a member enters the conference.

You can play a single beep by using beep:1 and a double beep with beep:2. If a URL is specified, the URL is fetched with an HTTP POST request; the application at the URL must return an XML document with Play, Speak, and/or Wait elements only. All other elements are ignored.

Allowed values: “”, beep:1, beep:2, or a valid URL
Defaults to “” (empty string).

exitSound string

The sound to be played when a member exits the conference.

You can play a single beep by using beep:1 and a double beep with beep:2. If a URL is specified, the URL is fetched with an HTTP POST request; the application at the URL must return an XML document with Play, Speak, and/or Wait elements only. All other elements are ignored.

Allowed values: “”, beep:1, beep:2, or a valid URL
Defaults to “” (empty string).

startConferenceOnEnter boolean

When a member joins a conference with this attribute set to true, the conference is started if not already in progress.

When a member joins a conference with this attribute set to false, and the conference has not yet started, the member is muted and hears background music until another member joins the conference. This attribute is handy when you’re organizing moderated conferences.

Allowed values: true, false
Defaults to true.

endConferenceOnExit boolean

When a member with this attribute set to true leaves a conference, the conference ends and all other members are automatically removed from the conference. This attribute is handy when you’re organizing moderated conferences.

Allowed values: true, false
Defaults to false.

stayAlone boolean

If a conference has this attribute set to false, the conference will end if a member is alone in it.

If a member joins the conference with the stayAlone attribute set to false, the conference will end if any member is alone in it. This attribute can change from true to false if a member joins the conference with this attribute set to false.

Once this attribute changed to false, it will not be updated to true if another member joins with the value for this attribute set to true.

Allowed values: true, false
Defaults to true.

waitSound stringCallback-retry configurable

The URL of a sound file, fetched with HTTP POST request, to be played while the member is alone in the conference. The URL must return an XML document with Play, Speak and/or Wait elements only. All other elements are ignored.

Allowed values: absolute URL
Default behavior is that no music is played.

maxMembers integer

Indicates the maximum number of members that are to be allowed within a named conference. This value can be any positive integer greater than 0.

When maxMembers is reached, the conference is skipped. If the next element in the XML response is the action_url, this is also skipped and the call proceeds to the next element after the Conference element.

Allowed values: integers between 1 and 20 (inclusive)
Defaults to 20.

Note: The default number of members per conference is 20 if maxMembers is not set when starting the conference. After being set by the first member, maxMembers cannot be changed by other members.
record boolean

Indicates whether the conference should be recorded.

Allowed values: true, false
Defaults to false.

recordFileFormat string

The file format for the recording.

Allowed values: mp3, wav
Defaults to mp3.

timeLimit integer

Used to set the maximum duration of the conference in seconds.

For example, setting a time limit of 600 seconds will automatically end the conference after 10 minutes.

Allowed values: Any integer >= 0
Defaults to 86,400 seconds (24 hours).

hangupOnStar boolean

If set to true, this attribute lets the member exit from the conference by pressing the * key on their phone, without having to hang up. If specified, action URL will be invoked upon the call’s exit from the Conference.

Allowed values: true, false
Defaults to false.

action stringCallback-retry configurable

An absolute URL to which the API can send parameters. See the action request parameters table below for more information.

Allowed values: a fully qualified URL
No default value

method string

Method used to send HTTP request to the action URL.

Allowed values: GET, POST
Defaults to POST.

callbackUrl stringCallback-retry configurable

If specified, information is sent back to this URL. See the callbackUrl request parameters table below for more information.

Allowed values: a fully qualified URL
No default value.

callbackMethod string

Method used to send HTTP request to the callbackUrl.

Allowed values: GET, POST
Defaults to POST.

transcriptionType string

auto: Transcription is automated; the turnaround time is under 5 minutes which linearly increases with call duration.

Transcription charges and details are available on our pricing page.

Note:

Transcription service is available only in English, and limited to calls with a duration greater than 500 milliseconds and less than 4 hours, with a recording file size smaller than 2GB.

transcriptionUrl string

The URL to which the transcription should be posted.

Allowed values: a fully qualified URL
No default value

Note:

The transcription information will be sent to this URL via an HTTP POST callback.

digitsMatch string

A list of digits, which are sent to the callbackUrl when a user presses digits that match the digitsMatch parameter.

Allowed values: list of digits patterns separated by comma
No default value

floorEvent boolean

If set to true, send notification to callbackUrl when member is the floor-holder.

Allowed values: true, false
Defaults to false.

redirect boolean

If false, don’t redirect to action URL, only request the URL and continue to next element.

Allowed values: true, false
Defaults to true.

relayDTMF boolean

Transmit all digits except digitsMatch to all members of conference.

Allowed values: true, false
Defaults to true.

Parameters sent to the action URL

ConferenceName

The conference name.

ConferenceUUID

Unique ID of the conference.

ConferenceMemberID

Member ID in the conference.

RecordUrl

URL of the recorded file. Only available if record is set to true.

RecordingID

ID of the recorded file. Only available if record is set to true.

Parameters sent to the callbackUrl

ConferenceAction
  • enter when user enters the conference
  • exit when user leaves the conference
  • digits when user presses matching digits
  • floor if user is the floor-holder in the conference
  • record if conference has been recorded using record attribute.
ConferenceName

The conference name.

ConferenceUUID

Unique ID of the conference.

ConferenceMemberID

ID of call in the conference.

Not present if ConferenceAction is set to record value.

CallUUID

Unique identifier for this call.

Not present if ConferenceAction is set to record value.

ConferenceDigitsMatch

The digits pattern matching when call has pressed digits.

Sent if ConferenceAction is set to digits value.

RecordUrl

The URL of the recorded file.

Sent if ConferenceAction is set to record value.

RecordingID

The ID of the recorded file.

Sent if ConferenceAction is set to record value.

RecordingDuration

Duration of recording in seconds.

Sent if ConferenceAction is set to record value. If recordSession or startOnDialAnswer is true, the duration is always -1.

RecordingDurationMs

Duration of recording in milliseconds.

Sent if ConferenceAction is set to record value.

RecordingStartMs

When the recording started (epoch time UTC) in milliseconds.

Sent if ConferenceAction is set to record value.

RecordingEndMs

When the recording ended (epoch time UTC) in milliseconds.

Sent if ConferenceAction is set to record value.

Parameters sent to the transcriptionUrl

transcription_charge

The credit deducted for the transcription.

transcription

The transcribed text of the recording.

duration

The duration in seconds of the recording.

call_uuid

The call UUID of the call which was transcribed.

transcription_rate

The rate of the transcription per minute.

recording_id

Recording ID of the recording that was transcribed.

errorMay be Recording duration too long for transcription or Recording file size too large for transcription. Empty if transcription is successful.
Note: .mp3 files are smaller in size than .wav files. Consider changing the recording file format to .mp3 if you see this error.

The next few sections show code for several conferencing tasks.

Basic conference

The first caller to execute this XML joins the conference “My Room.” When a subsequent caller executes this XML, they’ll join the same conference and the conference will start.

Example Request

1
2
3
4
5
6
7
8
9
10
from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(plivoxml.ConferenceElement('My Room'))
print(response.to_string())

# Or, you can use add_conference
response = plivoxml.ResponseElement()
response.add_conference(content='My Room')
print(response.to_string())

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
require 'rubygems'
require 'plivo'

include Plivo::XML
include Plivo::Exceptions

begin
  response = Response.new

  conference_name = 'My Room'
  response.addConference(conference_name)

  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
var plivo = require('plivo');

var response = plivo.Response();

var conference_name = "My Room";
response.addConference(conference_name);

console.log(response.toXML());

/*
Sample Output
<Response>
    <Conference>My Room</Conference>
</Response>
*/

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
<?php
    require '../vendor/autoload.php';
    use Plivo\XML\Response;

    $response = new Response();

    $conference_name = "My Room";
    $response->addConference($conference_name);

    Header('Content-type: text/xml');
    echo($response->toXML());

    /*
    Sample Output

    <Response>
        <Conference>My Room</Conference>
    </Response>
    */
 ?>

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// Example for conference - basic conference
package com.plivo.api.xml.samples.conference;

import com.plivo.api.exceptions.PlivoXmlException;
import com.plivo.api.xml.Conference;
import com.plivo.api.xml.Response;


class BasicConference {
    public static void main(String[] args) throws PlivoXmlException {
        Response response = new Response()
                .children(
                        new Conference("demo")
                );
        System.out.println(response.toXmlString());
    }
}

Was this code helpful

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
using System;
using System.Collections.Generic;
using Plivo.XML;

namespace Plivo
{
	class MainClass
	{
		public static void Main(string[] args)
		{
			Plivo.XML.Response resp = new Plivo.XML.Response();
			resp.AddConference("My room", 
               new Dictionary<string, string>() { });
			var output = resp.ToString();
			Console.WriteLine(output);

		}
	}
}



//<Response>
//  <Conference>My room</Conference>
//</Response>

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// Example for conference - basic conference
package main

import "github.com/plivo/plivo-go/v7/xml"

func main() {
	response := xml.ResponseElement{
		Contents: []interface{}{

			new(xml.ConferenceElement).
				SetContents("demo"),
		},
	}
	print(response.String())
}

Was this code helpful

Response

<Response>
  <Conference>My Room</Conference>
</Response>

Moderated conference

A caller may join a conference room “My Room” and hear wait music, but the conference doesn’t start until the moderator joins the conference.

If the moderator sets endConferenceOnExit to true, then when the moderator hangs up, the conference will end and each participant will also exit the conference.

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(
    plivoxml.ConferenceElement(
        'My Room',
        start_conference_on_enter=False,
        wait_sound='https://<yourdomain>.com/waitmusic/'))

print(response.to_string())

# Next, XML for moderator with endConferenceOnExit set to true

moderator_response = plivoxml.ResponseElement()
moderator_response.add(
    plivoxml.ConferenceElement(
        'My Room', start_conference_on_enter=True, end_conference_on_exit=
        True))

print(moderator_response.to_string())

Was this code helpful

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

include Plivo::XML
include Plivo::Exceptions

begin
  response = Response.new

  params = {
    'startConferenceOnEnter' => "false",
    'waitSound' => "https://<yourdomain>.com/waitmusic/"
  }

  conference_name = "My Room"
  response.addConference(conference_name, params)

  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end

begin
  response = Response.new

  params = {
    'startConferenceOnEnter' => "true",
    'endConferenceOnExit' => "true"
  }

  conference_name = "My Room"
  response.addConference(conference_name, params)

  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end

Was this code helpful

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

var response = plivo.Response();

var params = {
    'startConferenceOnEnter': "false",
    'waitSound': "https://<yourdomain>.com/waitMusic/"
};
var conference_name = "My Room";
response.addConference(conference_name, params);

console.log(response.toXML());

/*
Sample Output
<Response>
    <Conference startConferenceOnEnter="false" waitSound="https://<yourdomain>.com/waitMusic/">My Room</Conference>
</Response>
*/


/* Code to generate XML to be returned from url at waitSound */
var plivo = require('plivo');

var response = plivo.Response();

var params = {
    'startConferenceOnEnter': "true",
    'endConferenceOnExit': "true"
};
var conference_name = "My Room";
response.addConference(conference_name, params);

console.log(response.toXML());

/*
Sample Output
<Response>
    <Conference startConferenceOnEnter="true" endConferenceOnExit="true">My Room</Conference>
</Response>
*/

Was this code helpful

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
<?php
    require '../vendor/autoload.php';
    use Plivo\XML\Response;

    $response = new Response();

    $params = array(
        'startConferenceOnEnter' => "false",
        'waitSound' => "https://<yourdomain>.com/waitmusic/"
    );

    $conference_name = "My Room";
    $response->addConference($conference_name, $params);

    Header('Content-type: text/xml');
    echo($response->toXML());

    /*
    Sample Output

    <Response>
        <Conference startConferenceOnEnter="false" waitSound="https://<yourdomain>.com/waitmusic/">My Room</Conference>
    </Response>
    */
?>

<?php
    /*Code to generate XML to be returned from url at waitSound*/

    require '../vendor/autoload.php';
    use Plivo\XML\Response;

    $response = new Response();

    $params = array(
        'startConferenceOnEnter' => "true",
        'endConferenceOnExit' => "true"
    );

    $conference_name = "My Room";
    $response->addConference($conference_name, $params);

    Header('Content-type: text/xml');
    echo($response->toXML());

    /*
    Sample Output

    <Response>
        <Conference startConferenceOnEnter="true" endConferenceOnExit="true">My Room</Conference>
    </Response>
    */
 ?>

Was this code helpful

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
// Example for conference - moderated conference
package com.plivo.api.xml.samples.conference;

import com.plivo.api.exceptions.PlivoXmlException;
import com.plivo.api.xml.Conference;
import com.plivo.api.xml.Response;
import com.plivo.api.xml.Speak;


class ModeratedConference {
    public static void main(String[] args) throws PlivoXmlException {
        Response response = new Response()
                .children(


                        new Speak("You will now be placed into a demo conference"),


                        new Conference("demo")
                                .endConferenceOnExit(true)
                                .startConferenceOnEnter(false)
                                .waitSound("https://<yourdomain>.com/waitmusic/")

                );
        System.out.println(response.toXmlString());
    }
}

Was this code helpful

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
using System;
using System.Collections.Generic;
using Plivo.XML;

namespace Plivo
{
	class MainClass
	{
		public static void Main(string[] args)
		{
			Plivo.XML.Response resp = new Plivo.XML.Response();
			resp.AddConference("My room", 
               new Dictionary<string, string>()
			{
				{"startConferenceOnEnter", "true"},
				{"endConferenceOnExit", "true"},
				{"waitSound", "https://<yourdomain>.com/waitmusic/"}
			});
			var output = resp.ToString();
			Console.WriteLine(output);

		}
	}
}



//<Response>
//    <Conference startConferenceOnEnter = "true" 
//     endConferenceOnExit="true" 
//     waitSound="https://<yourdomain>.com/waitmusic/">
//         My room
//    </Conference>
//</Response>

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// Example for conference - moderated conference
package main

import "github.com/plivo/plivo-go/v7/xml"

func main() {
	response := xml.ResponseElement{
		Contents: []interface{}{

			new(xml.SpeakElement).
				SetContents("You will now be placed into a demo conference"),

			new(xml.ConferenceElement).
				SetEndConferenceOnExit(true).
				SetStartConferenceOnEnter(false).
				SetWaitSound("https://<yourdomain>.com/waitmusic/").
				SetContents("demo"),
		},
	}
	print(response.String())
}

Was this code helpful

Response

<Response>
	<Conference startConferenceOnEnter="false" waitSound="https://<yourdomain>.com/waitmusic/">My Room</Conference>
</Response>

XML for the moderator:

<Response>
	<Conference startConferenceOnEnter="true" endConferenceOnExit="true">My Room</Conference>
</Response>

Join a conference muted

This code forces participants to join a conference muted. They can hear unmuted participants speak.

Response

<Response>
	<Conference muted="true">My Room</Conference>
</Response>

Bridge incoming calls

This code bridges two incoming calls together. With this minimal conferencing attribute setup, no sound is played, participants can speak as soon as they join, and the conference ends immediately when a participant hangs up.

Example Request

1
2
3
4
5
6
7
8
9
10
from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(
    plivoxml.ConferenceElement(
        'My Room',
        enter_sound="",
        start_conference_on_enter=True,
        end_conference_on_exit=True))
print(response.to_string())

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
require 'rubygems'
require 'plivo'

include Plivo::XML
include Plivo::Exceptions

begin
  response = Response.new

  params = {
    startConferenceOnEnter1: 'true',
    endConferenceOnExit: true
  }

  conference_name = 'My Room'
  response.addConference(conference_name, params)

  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
var plivo = require('plivo');

var response = plivo.Response();

var params = {
    'enterSound': "",
    'startConferenceOnEnter': "true",
    'endConferenceOnExit': "true"
};
var conference_name = "My Room";
response.addConference(conference_name, params);

console.log(response.toXML());

/*
Sample Output
<Response>
    <Conference enterSound="" startConferenceOnEnter="true"\ endConferenceOnExit="true">My Room</Conference>
</Response>
*/

Was this code helpful

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
<?php
    require '../vendor/autoload.php';
    use Plivo\XML\Response;

    $response = new Response();

    $params = array(
        'startConferenceOnEnter' => "true",
        'endConferenceOnExit' => "true"
    );

    $conference_name = "My Room";
    $response->addConference($conference_name, $params);

    Header('Content-type: text/xml');
    echo($response->toXML());

    /*
    Sample Output

    <Response>
        <Conference startConferenceOnEnter="true" endConferenceOnExit="true">My Room</Conference>
    </Response>
    */
?>

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// Example for conference - bridge incoming call
package com.plivo.api.xml.samples.conference;

import com.plivo.api.exceptions.PlivoXmlException;
import com.plivo.api.xml.Conference;
import com.plivo.api.xml.Response;


class BridgeIncomingCall {
    public static void main(String[] args) throws PlivoXmlException {
        Response response = new Response()
                .children(


                        new Conference("demo")
                                .endConferenceOnExit(true)
                                .enterSound("")
                                .startConferenceOnEnter(true)

                );
        System.out.println(response.toXmlString());
    }
}

Was this code helpful

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
using System;
using System.Collections.Generic;
using Plivo.XML;

namespace Plivo
{
	class MainClass
	{
		public static void Main(string[] args)
		{
			Plivo.XML.Response resp = new Plivo.XML.Response();
			resp.AddConference("My room", new Dictionary<string, string>()
			{
				{"enterSound", ""},
				{"startConferenceOnEnter", "true"},
				{"endConferenceOnExit", "true"}
			});
			var output = resp.ToString();
			Console.WriteLine(output);

		}
	}
}



//<Response>
//  <Conference enterSound = "" startConferenceOnEnter="true" 
//     endConferenceOnExit="true">
//     My room
//  </Conference>
//</Response>

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// Example for conference - bridge incoming call
package main

import "github.com/plivo/plivo-go/v7/xml"

func main() {
	response := xml.ResponseElement{
		Contents: []interface{}{

			new(xml.ConferenceElement).
				SetEndConferenceOnExit(true).
				SetEnterSound("").
				SetStartConferenceOnEnter(true).
				SetContents("demo"),
		},
	}
	print(response.String())
}

Was this code helpful

Response

<Response>
	<Conference enterSound="" startConferenceOnEnter="true" endConferenceOnExit="true">My Room</Conference>
</Response>

Waiting room

This code places the first caller into a waiting room, where the caller will hear music. It’s similar to placing a caller on hold, waiting for an agent or operator to help them.

The second XML response lets an operator join the person in the room. The conference starts when the operator enters the room, and the hold music stops. Since enterSound="", the caller won’t hear any sound when the agent answers. When the moderator hangs up, the conference ends, since the endConferenceOnExit is set to true.

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(
    plivoxml.ConferenceElement(
        'Waiting Room',
        wait_sound='https://<yourdomain>.com/waitmusic/',
        enter_sound=''))
print(response.to_string())

# Now, the XML for the operator
operator_response = plivoxml.ResponseElement()
operator_response.add(
    plivoxml.ConferenceElement(
        'Waiting Room', enter_sound='', end_conference_on_exit=True))
print(operator_response.to_string())

Was this code helpful

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

include Plivo::XML
include Plivo::Exceptions

begin
  response = Response.new

  params = {
    'waitSound' => "https://<yourdomain>.com/waitmusic/",
    'enterSound' => ""
  }

  conference_name = "Waiting Room"
  response.addConference(conference_name, params)

  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end

begin
  response = Response.new

  params = {
    'endConferenceOnExit' => "true",
    'enterSound' => ""
  }

  conference_name = "Waiting Room"
  response.addConference(conference_name, params)

  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end

Was this code helpful

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

var response = plivo.Response();

var params = {
    'waitSound': "https://<yourdomain>.com/waitMusic/"
};
var conference_name = "Waiting Room";
response.addConference(conference_name, params);

console.log(response.toXML());

/*
Sample Output
<Response>
    <Conference waitSound="https://<yourdomain>.com/waitMusic/">Waiting Room</Conference>
</Response>
*/


/* Code to generate XML to be returned from url at waitSound */
var plivo = require('plivo');

var response = plivo.Response();

var params = {
    'enterSound': "",
    'endConferenceOnExit': "true"
};
var conference_name = "Waiting Room";
response.addConference(conference_name, params);

console.log(response.toXML());

/*
Sample Output
<Response>
    <Conference enterSound="" endConferenceOnExit="true">Waiting Room</Conference>
</Response>
*/

Was this code helpful

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
<?php
    require '../vendor/autoload.php';
    use Plivo\XML\Response;

    $response = new Response();

    $params = array(
        'waitSound' => "https://<yourdomain>.com/waitmusic/"
    );

    $conference_name = "Waiting Room";
    $response->addConference($conference_name, $params);

    Header('Content-type: text/xml');
    echo($response->toXML());

    /*
    Sample Output

    <Response>
        <Conference waitSound="https://<yourdomain>.com/waitmusic/">Waiting Room</Conference>
    </Response>
    */

    $response = new Response();

    $params = array(
        'endConferenceOnExit' => "true"
    );

    $conference_name = "Waiting Room";
    $response->addConference($conference_name, $params);

    Header('Content-type: text/xml');
    echo($response->toXML());

    /*
    Sample Output

    <Response>
        <Conference endConferenceOnExit="true">Waiting Room</Conference>
    </Response>
    */
?>

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// Example for conference - waiting room
package com.plivo.api.xml.samples.conference;

import com.plivo.api.exceptions.PlivoXmlException;
import com.plivo.api.xml.Conference;
import com.plivo.api.xml.Response;


class WaitingRoom {
    public static void main(String[] args) throws PlivoXmlException {
        Response response = new Response()
                .children(


                        new Conference("Waiting Room")
                                .endConferenceOnExit(true)
                                .enterSound("")
                                .waitSound("https://<yourdomain>.com/waitmusic/")

                );
        System.out.println(response.toXmlString());
    }
}

Was this code helpful

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
using System;
using System.Collections.Generic;
using Plivo.XML;

namespace Plivo
{
	class MainClass
	{
		public static void Main(string[] args)
		{
			Plivo.XML.Response resp = new Plivo.XML.Response();
			resp.AddConference("My room", 
               new Dictionary<string, string>()
			{
				{"waitSound", "https://<yourdomain>.com/waitmusic/"},
				{"enterSound", ""}
			});
			var output = resp.ToString();
			Console.WriteLine(output);

		}
	}
}



//<Response>
//  <Conference waitSound = "https://<yourdomain>.com/waitmusic/" 
//    enterSound="">
//    My room
//  </Conference>
//</Response>

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// Example for conference - waiting room
package main

import "github.com/plivo/plivo-go/v7/xml"

func main() {
	response := xml.ResponseElement{
		Contents: []interface{}{

			new(xml.ConferenceElement).
				SetEndConferenceOnExit(true).
				SetEnterSound("").
				SetWaitSound("https://<yourdomain>.com/waitmusic/").
				SetContents("Waiting Room"),
		},
	}
	print(response.String())
}

Was this code helpful

Response

<Response>
	<Conference waitSound="https://<yourdomain>.com/waitmusic/" enterSound="">Waiting Room</Conference>
</Response>

 

XML for the operator:

<Response>
	<Conference enterSound="" endConferenceOnExit="true">Waiting Room</Conference>
</Response>

Conference with redirect

This XML code performs a few actions:

  • Sets the timeLimit attribute, after which the member will be removed from the conference.
  • Sets hangupOnStar to true, which enables the user to leave a conference by pressing the * key.
  • Specifies a Redirect element, so that after the member leaves the room, the redirect URL is invoked.

Example Request

1
2
3
4
5
6
7
8
from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(
    plivoxml.ConferenceElement('My Room', hangup_on_star=True, time_limit=30))
response.add(plivoxml.RedirectElement('https://<yourdomain>.com/redirect/'))

print(response.to_string())

Was this code helpful

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

include Plivo::XML
include Plivo::Exceptions

begin
  response = Response.new

  params = {
    hangupOnStar: true,
    timeLimit: '30'
  }

  conference_name = 'My Room'
  response.addConference(conference_name, params)

  redirect_url = 'https://<yourdomain>.com/redirect/'
  response.addRedirect(redirect_url)

  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
var plivo = require('plivo');

var response = plivo.Response();

var params = {
    'hangupOnStar': "true",
    'timeLimit': "30"
};
var conference_name = "My Room";
response.addConference(conference_name, params);

var redirect_url = "https://<yourdomain>.com/redirect/"
response.addRedirect(redirect_url);

console.log(response.toXML());

/*
Sample Output
<Response>
    <Conference hangupOnStar="true" timeLimit="30">My Room</Conference>
    <Redirect>https://<yourdomain>.com/redirect/</Redirect>
</Response>
*/

Was this code helpful

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
<?php
    require '../vendor/autoload.php';
    use Plivo\XML\Response;

    $response = new Response();

    $params = array(
        'hangupOnStar' => "true",
        'timeLimit' => "30"
    );

    $conference_name = "My Room";
    $response->addConference($conference_name, $params);

    $redirect_url = "https://<yourdomain>.com/redirect/";
    $response->addRedirect($redirect_url);

    Header('Content-type: text/xml');
    echo($response->toXML());

    /*
    Sample Output

    <Response>
        <Conference hangupOnStar="true" timeLimit="30">My Room</Conference>
        <Redirect>https://<yourdomain>.com/redirect/</Redirect>
    </Response>
    */
?>

Was this code helpful

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
// Example for conference - conference with redirect
package com.plivo.api.xml.samples.conference;

import com.plivo.api.exceptions.PlivoXmlException;
import com.plivo.api.xml.Conference;
import com.plivo.api.xml.Redirect;
import com.plivo.api.xml.Response;


class ConferenceWithRedirect {
    public static void main(String[] args) throws PlivoXmlException {
        Response response = new Response()
                .children(


                        new Conference("My Room")
                                .hangupOnStar(true)
                                .timeLimit(30),


                        new Redirect("https://<yourdomain>.com/redirect")
                );
        System.out.println(response.toXmlString());
    }
}

Was this code helpful

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
using System;
using System.Collections.Generic;
using Plivo.XML;

namespace Plivo
{
	class MainClass
	{
		public static void Main(string[] args)
		{
			Plivo.XML.Response resp = new Plivo.XML.Response();
			resp.AddConference("My room",
				 new Dictionary<string, string>()
			{
				{"hangupOnStar", "true"},
				{"timeLimit", "30"}
			});
			resp.AddRedirect("https://<yourdomain>.com/redirect/",
				 new Dictionary<string, string>() { });
			var output = resp.ToString();
			Console.WriteLine(output);

		}
	}
}



//<Response>
//  <Conference hangupOnStar = "true" 
//        timeLimit="30">My room</Conference>
//  <Redirect>https://<yourdomain>.com/redirect/</Redirect>
//</Response>

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// Example for conference - conference with redirect
package main

import "github.com/plivo/plivo-go/v7/xml"

func main() {
	response := xml.ResponseElement{
		Contents: []interface{}{

			new(xml.ConferenceElement).
				SetHangupOnStar(true).
				SetTimeLimit(30).
				SetContents("My Room"),

			new(xml.RedirectElement).
				SetContents("https://<yourdomain>.com/redirect"),
		},
	}
	print(response.String())
}

Was this code helpful

Response

<Response>
  <Conference hangupOnStar="true" timeLimit="30">My Room</Conference>
  <Redirect>https://<yourdomain>.com/redirect/</Redirect>
</Response>

Using the callback URL

When members enter and leave a conference, and when a user presses the digits that match the digitsMatch parameter, Plivo sends an HTTP POST request to the callbackUrl. See “Parameters sent to the callbackUrl” above for a list of parameters that are sent to the callback URL.

Response

<Response>
	<Conference callbackUrl="https://<yourdomain>.com/confevents/" callbackMethod="POST" digitsMatch="#0,99,000">My Room</Conference>
</Response>

The AudioStream element Beta

The audio stream element lets you receive raw audio from active calls over a WebSocket connection in near real time.

Attributes

bidirectionalboolean

Specifies whether the audio being streamed over the WebSocket is bidirectional (the service can both read and write audio over the WebSocket) or one-way (read-only).

If the bidirectional attribute is set to true, then Plivo accepts the below parameters to accept the audio stream from your application over the WebSockets.

 

Allowed values:

event: Takes playAudio as the value
media: Takes a JSON input of the key values below
contentType: audio/x-l16, audio/x-mulaw
sampleRate: 8000 and 16000
payload: Base64-encoded raw audio
audioTrackstring

The audio track (inbound or outbound) of the underlying call that Plivo will fork and stream to the WebSocket service.
Allowed values:
inbound (only audio received by Plivo from call participants is streamed over WebSocket), outbound (only audio transmitted by Plivo to call participants is streamed over WebSocket), both(both inbound and outbound audio is streamed over the WebSocket). Default is inbound.

Note: When the bidirectional value is set to true, the audioTrack value should not be set to outbound or both.
streamTimeoutinteger

The maximum duration, in seconds, for which audio will be streamed once streaming starts. At the end of the specified duration, streaming will stop. This will have no impact on the rest of the call flow.
Needs to be a positive integer if provided. Defaults to 86,400 (24 hours).

statusCallbackUrlstring

URL notified by Plivo when one of the following events occurs:

  • Audio stream is connected and audio begins streaming (first packet is sent)
  • Audio stream is stopped intentionally or when audio stream timeout is reached
  • Audio stream failed to connect or got disconnected for any reason during an ongoing call

statusCallbackMethodstring

The HTTP verb used to invoke the status_callback_url.
Allowed values:
GET, POST Defaults to POST.

contentTypestring

Preferred audio codec and sampling rate.
Allowed values: audio/x-l16;rate=8000, audio/x-l16;rate=16000, audio/x-mulaw;rate=8000 Defaults to audio/x-l16;rate=8000.

extraHeadersstring

Key-value pairs passed to the WebSocket service along with the audio stream. These extra headers will be passed with every HTTP request made by the call.
Takes string of key-value pairs as input. Example: “test1=12,test2=123”. Total length of the string being passed should be no more than 512 bytes. Only [A-Z], [a-z], and [0-9] characters are allowed in both key and value.

keepCallAliveBoolean

This parameter signifies whether the stream element should be executed alone, without proceeding to execute the subsequent elements in the XML instruction. It applies only when the bi-directional audio stream is set to true. Any elements following the stream in the XML instruction will execute only after the stream is disconnected.

Allowed values: true, false
Default: false

Parameters sent to the statusCallbackUrl

This information is sent to statusCallbackUrl when an event is triggered.

Eventstring

Allowed values:

  • StartStream: sent when audio begins streaming post connection establishment
  • StopStream: sent when the audio stream is stopped intentionally or stream timeout has been reached
  • DroppedStream: sent when the audio stream failed to connect or got disconnected due to any reason during an ongoing call
  • ClearedAudio: Transmitted when buffered audio files are cleared following the clearAudio command from your application.
  • PlayedStream: The "PlayedStream" event serves as an acknowledgment of the checkpoint event from the customer. It is emitted when all preceding media events before the checkpoint event have been successfully played back to the end user.
Note: No callback is sent when a call (rather than a stream) gets disconnected.

Errorstring

May be Could not establish connection with the remote service or Connection disconnected with the remote service.
Populated only if value of StreamAction is dropped; empty otherwise.

CallUUIDstring

Unique identifier for this call.

Fromstring

Caller number or SIP endpoint of the CallUUID sent for audio streaming.

Tostring

Destination number or SIP endpoint of the CallUUID sent for audio streaming.

ServiceURLstring

WebSocket URL to which the audio stream is connected.

ExtraHeadersstring

Key-value pairs passed as part of the audio Stream XML element.

StreamIDstring

Unique identifier for each audio stream.

Timestamptimestamp

The timestamp of when the event was generated.

Example Request

1
2
3
4
5
6
from plivo import plivoxml

response = plivoxml.ResponseElement().add(plivoxml.StreamElement('
wss://yourstream.websocket.io/audiostream'))                                         

print(response.to_string())

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
require 'rubygems'
require 'plivo'

include Plivo::XML
include Plivo::Exceptions

begin
  response = Response.new
    response.addStream('
wss://yourstream.websocket.io/audiostream')

  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end

Was this code helpful

1
2
3
4
5
6
7
var plivo = require('plivo');

const streamResponse = new Response();
var service_url = "wss://yourstream.websocket.io/audiostream";
streamResponse.addStream(service_url);

console.log(response.toXML());

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
<?php
    require './vendor/autoload.php';
    use Plivo\XML\Response;

    $response = new Response();

    $response->addStream("
wss://yourstream.websocket.io/audiostream");
    $ssml = $response->toXML(true);

    Header('Content-type: text/xml');
    echo($response->toXML());
?>

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// Example for Audio Stream XML creation
package com.plivo.examples;

import com.plivo.api.exceptions.PlivoValidationException;
import com.plivo.api.exceptions.PlivoXmlException;
import com.plivo.api.xml.Response;
import com.plivo.api.xml.Stream;

public class StreamXML {

  public static void main(String[] args) throws PlivoValidationException, PlivoXmlException {
    Response response = new Response().children(new Stream("
wss://yourstream.websocket.io/audiostream
"));
    System.out.println(response.toXmlString());
  }
}

Was this code helpful

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
using System;
using System.Collections.Generic;

namespace PlivoExamples
{
    public class MainClass
    {
        public static void Main(string[] args)
        {
            
            Dictionary<string, string> parameter  =
                new Dictionary<string, string>();
            parameter.Add("bidirectional", "False");
            parameter.Add("audioTrack", "both");
            parameter.Add("streamTimeout", "120");
            parameter.Add("statusCallbackUrl", "https://<yourdomain>.com/confevents/");
            parameter.Add("statusCallbackMethod", "POST");
            parameter.Add("contentType", "audio/x-l16;rate=16000");
            
            Plivo.XML.Stream resp1 = new Plivo.XML.Stream("
wss://yourstream.websocket.io/audiostream",parameter);

            var output = resp1.ToString();
            Console.WriteLine(output);
        }
    }
}

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
package main

import (
	"github.com/plivo/plivo-go/v7/xml"
	"html"
)

func main() {
	response := xml.ResponseElement{
		Contents: []interface{}{
			new(xml.StreamElement).SetContents("wss://www.example.com/socketserver"),
		},
	}
	print(html.UnescapeString(response.String()))
}

Was this code helpful

Response

<Response>
	<Stream bidirectional = "true" keepCallAlive="true" >wss://yourstream.websocket.io/audiostream</Stream>
</Response>

Initiate an audio stream

In this example, upon executing the audio Stream element, the audio tracks flowing in (inbound) and out (outbound) are simultaneously forked and streamed to the provided WebSocket service URL. The streaming duration is defined as 120 seconds, implying that the streaming operation will cease automatically once 120 seconds have elapsed.

Example Request

1
2
3
4
5
from plivo import plivoxml

response = plivoxml.ResponseElement().add(plivoxml.StreamElement('wss://yourstream.websocket.io/audiostream', bidirectional= "false",audioTrack="both",streamTimeout=120,statusCallbackMethod="POST",statusCallbackUrl="https://yourdomain.com/events/",contentType="audio/x-l16;rate=8000",extraHeaders="Test1=Test2,Test3=Test4"))

print(response.to_string())

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
require 'rubygems'
require 'plivo'

include Plivo::XML
include Plivo::Exceptions

begin
  response = Response.new
    response.addStream('
wss://yourstream.websocket.io/audiostream', {
        bidirectional: "false", audioTrack: 'both',
        contentType: "audio/x-l16;rate=8000",
        streamTimeout: 120,
        statusCallbackUrl: "https://<yourdomain>.com/events/",
        statusCallbackMethod: "POST",
        extraHeaders:  "Test1=Test2,Test3=Test4"
    })

  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
var plivo = require('plivo');

const streamResponse = new Response();
var service_url = "wss://yourstream.websocket.io/audiostream";
var extraHeaders = "{'Test':'test1'}";
var params = {bidirectional: "false", audioTrack: 'both',
        contentType: "audio/x-l16;rate=8000",
        streamTimeout: 120,
        statusCallbackUrl: "https://<yourdomain>.com/events/",
        statusCallbackMethod: "POST",
        extraHeaders:  "Test1=Test2,Test3=Test4"
};
streamResponse.addStream(service_url, params);

console.log(response.toXML());

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
<?php
    require './vendor/autoload.php';
    use Plivo\XML\Response;

    $response = new Response();


    $params1 = array(
        'bidirectional' => false,
        'audio_track' => "both",
        'stream_timeout' => 120,
        'content_type' => 'audio/x-l16;rate=8000',
        'status_callback_url' => 'https://<yourdomain>.com/events/',
        'status_callback_method' => 'POST',
        'extraHeaders'=>'Test1=Test2,Test3=Test4'
    );

    $response->addStream("
wss://yourstream.websocket.io/audiostream",$params1);
    $ssml = $response->toXML(true);

    Header('Content-type: text/xml');
    echo($response->toXML());
?>

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// Example for Audio Stream XML creation
package com.plivo.examples;

import com.plivo.api.exceptions.PlivoValidationException;
import com.plivo.api.exceptions.PlivoXmlException;
import com.plivo.api.xml.Response;
import com.plivo.api.xml.Stream;

public class StreamXML {

  public static void main(String[] args) throws PlivoValidationException, PlivoXmlException {
    Response response = new Response().children(new Stream("
wss://yourstream.websocket.io/audiostream
")
      .bidirectional(false)
      .streamTimeout(120)
      .audioTrack("both")
      .contentType("audio/x-l16;rate=8000")
      .statusCallbackUrl("callback-url")
      .statusCallbackMethod("POST")
      .extraHeaders("Test1=Test2,Test3=Test4"));
    System.out.println(response.toXmlString());
  }
}

Was this code helpful

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
using System;
using System.Collections.Generic;

namespace PlivoExamples
{
    public class MainClass
    {
        public static void Main(string[] args)
        {
            
            Dictionary<string, string> parameter  =
                new Dictionary<string, string>();
            parameter.Add("bidirectional", "False");
            parameter.Add("audioTrack", "both");
            parameter.Add("streamTimeout", "120");
            parameter.Add("statusCallbackUrl", "https://<yourdomain>.com/confevents/");
            parameter.Add("statusCallbackMethod", "POST");
            parameter.Add("contentType", "audio/x-l16;rate=16000");
            parameter.Add("extraHeaders", "Test1=Test2,Test3=Test4");
            
 Plivo.XML.Stream resp1 = new Plivo.XML.Stream("
wss://yourstream.websocket.io/audiostream",parameter);

            var output = resp1.ToString();
            Console.WriteLine(output);
        }
    }
}

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
package main

import (
	"github.com/plivo/plivo-go/v7/xml"
	"html"
)

func main() {
	response := xml.ResponseElement{
		Contents: []interface{}{
			new(xml.StreamElement).SetAudioTrack("both").SetContentType("audio/x-l16;rate=16000").SetBidirectional(false).SetStatusCallbackMethod("POST").SetStatusCallbackUrl("https://yourdomain.com/events").SetStreamTimeout(120).SetExtraHeaders("Test1=Test2,Test3=Test4").SetContents("wss://www.example.com/socketserver"),
		},
	}
	print(html.UnescapeString(response.String()))
}

Was this code helpful

Response

<Response>
	<Stream bidirectional="false" streamTimeout="120" audioTrack="both" statusCallbackUrl="https://<yourdomain>.com/events/" statusCallbackMethod="POST" contentType="raw">wss://yourstream.websocket.io/audiostream</Stream>
</Response>

Stream events to Plivo

You can utilize the WebSocket connection to stream events from your application to Plivo. With this connection, you can play audio, interrupt and clear buffered audio, and send a checkpoint event to indicate the completion of playback.

Play audio event

You can utilize the playAudio event to transmit audio through the WebSocket. When the bi-directional attribute is set to true, Plivo can deliver the audio transmitted from your application to the party on the call.

Attributes

event

Indicates the event type. playAudio is the value required to transmit audio over the WebSocket.

 
media

An object containing media metadata and payload

contentType

The audio codec format.
Allowed values: audio/x-l16, audio/x-mulaw

sampleRate

Sample rate of the audio transmitted.
Allowed values:
audio/x-l16: 8000, 16000
audio/x-mulaw: 8000

payload

Base64-encoded string of raw audio

Response

Request

{
  "event": "playAudio",
  "media": {
    "contentType": "audio/x-l16",
    "sampleRate": 8000,
    "payload": "base64 encoded raw audio.."
  }
}

Checkpoint event

Send a checkpoint event via WebSocket when the desired audio events are queued. Plivo will respond with playedStream, indicating that audio events buffered before the Checkpoint were successfully played out to the end user. playedStream will only be emitted if the preceding events were played successfully.

Attributes

event

Indicates the event type. checkpoint is the value expected.

 
name

Name of the checkpoint that you use to recognize upon receiving the acknowledgment.

streamId

A unique identifier generated for each audio stream.

Response

Request

{
  "event": "checkpoint",
  "streamId": "20170ada-f610-433b-8758-c02a2aab3662",
  "name": "customer greeting audio"
}

Response

{
  "event": "playedStream",
  "streamId": "20170ada-f610-433b-8758-c02a2aab3662",
  "name": "customer greeting audio"
}

Clear audio stream

The clearAudio event interrupts audio previously sent to Plivo via the playAudio event. Plivo clears all buffered media events, enabling you to initiate new playAudio events tailored to a specific use case.

You can send a clearAudio event to interrupt the audio that has been sent to Plivo. This will clear all the buffered audio.

Attributes

event

Indicates the event type. Use clearAudio to clear all the buffered audio.

 
streamId

A unique identifier generated for each audio stream.

Response

Request

{
  "event": "clearAudio",
  "streamId": "b77e037d-4119-44b5-902d-25826b654539"
}

Response

{
  "sequenceNumber": 0,
  "event": "clearedAudio",
  "streamId": "20170ada-f610-433b-8758-c02a2aab3662"
}

The Dial element

You can use the Dial element to dial one or multiple phone numbers and connect them to the current caller. If the call is picked up, then the caller and receiver will be connected and can communicate until either party hangs up. If the call is not answered, or a busy signal is received, or the phone number dialed doesn’t exist, the Dial element will end.

Upon completion of the call, Plivo makes a GET or POST request to the action URL if one is provided. Based on the value of the Redirect element, the call flow will continue using the XML received from the action URL.

Note: A Number or User element must be present and nested inside Dial for the Dial element to work.

Nesting rules

  • You must nest a Number or User element within the Dial element.
  • Specify a single Number or User value to dial a single number or a SIP user.
  • Specify multiple Number and User elements for simultaneous dialing.

Attributes

action stringCallback-retry configurable

Redirect to this URL after leaving Dial. See the table “Parameters sent to action URL” below for more information.

Allowed values: a fully qualified URL

method string

Method used to send HTTP request to the action URL.

Allowed values: GET, POST
Defaults to POST.

hangupOnStar boolean

The caller can press the * key to hang up on the called party but can continue with other operations depending on the application’s response.

Allowed values: true, false
Defaults to false.

timeLimit integer

Used to preset the duration (in seconds) of the call.

Allowed values: positive integer
Defaults to 14,400 seconds (4 hours).

Note: If timeLimit is >=86,400 seconds, calls will be disconnected after 24 hours.
timeout integer

The amount of time (in seconds) that the called party has to answer the call (pick up the phone or tap the answer button on a smart phone or SIP phone).

Allowed values: positive integer
No default value.

callerId string

If set to a string, caller number will be set to this string value.

Allowed values: valid phone number
Defaults to the current caller’s callerId.

callerName string

If set to a string, caller name will be set to this string value.

Allowed values: Any string, maximum of 50 characters
Defaults to caller’s callerName.

confirmSound stringCallback-retry configurable

A remote URL fetched with a POST HTTP request that must return an XML response with Play, Wait, and/or Speak elements only (all others are ignored). The sound indicated by the XML is played to the called party when the call is answered.

Note: This parameter must be specified for confirmKey to work.

Allowed values: a fully qualified URL

confirmTimeout string

Timeout starts after the call is answered. Entertained only if confirmSound parameter is passed without confirmKey

Note: confirmTimeout value should be greater than duration of confirmSound to auto answer the call once confirmSound is completely played.

Defaults to: 120

confirmKey string

The digit to be pressed by the called party to accept the call. Used in conjunction with confirmSound.

Allowed values: any digit, #, *

dialMusic stringCallback-retry configurable

Music to be played to the caller while the call is being connected. This is a remote URL fetched with a POST HTTP request. It must return an XML response with Play, Wait, and/or Speak elements only (all others are ignored). The sound indicated by the XML is played to the caller while the call is being connected.

Setting dialMusic to real plays the real ringtone of the called party. This is also the default behavior if dialMusic is not specified.

Allowed values: a fully qualified URL or real

callbackUrl stringCallback-retry configurable

URL to be notified when one of these events occur:

  • called party answers the call
  • called party is connected with caller
  • called party hangs up
  • caller presses any digit. See the “Parameters sent to callbackUrl” table below for more information.

Allowed values: a fully qualified URL

Configuring confirmSound and confirmKey invokes the callbackUrl after the called party answers the call and before the called party confirms the call.

callbackMethod string

Method used to notify callbackUrl.

Allowed values: GET, POST
Defaults to POST.

redirect boolean

If set to false, don’t redirect to action URL.

We expect an XML response from the action URL if this parameter is set to true. The call will be controlled based on the XML returned from the action URL.

Allowed values: true, false
Defaults to true.

digitsMatch string

A list of digits that are sent to the callbackUrl when the digits pressed by the user match the digitsMatch parameter (A leg).

Allowed values: list of digit patterns separated by a comma. Example: digitsMatch="123,456,789"

digitsMatchBLeg string

A list of digits that are sent to the callbackUrl when the digits pressed by the user match the digitsMatchBLeg parameter (B leg).

Allowed values: list of digit patterns separated by a comma. Example: digitsMatchBLeg="123,456,789"

sipHeaders string

SIP headers are always prefixed with X-PH-.

For every HTTP request called by the dialed leg, the SIP headers will be present. Only [A-Z], [a-z], and [0-9] characters are allowed for SIP header key names and values, so that you can URL-encode the values.

Allowed values: list of SIP headers to send, separated by commas. Sent as key=value pair. For example, head1=val1,head2=val2,...,headN=valN.

Parameters sent to action URL

These parameters are sent to the action URL after Dial is completed.

DialRingStatus

Indicates whether the Dial attempt rang.

Allowed values: true, false

DialHangupCause

The standard telephony hangup cause.

DialStatus

Status of the dial.

Allowed values: completed, busy, failed, cancel, timeout, no-answer

DialALegUUID

CallUUID of A leg.

DialBLegUUID

CallUUID of B leg. Empty if nobody answers.

Parameters sent to callbackUrl

These parameters are sent to the callbackUrl, if specified.

DialAction

Allowed values: answer, connected, hangup, digits

DialBLegStatus

Indicates whether B leg answered or hung up.

Allowed values: answer, connected, hangup

DialALegUUID

CallUUID of A leg.

DialBLegUUID

CallUUID of B leg. Empty if nobody answers.

DialDigitsMatch

The digits pressed by A leg and matching one digits combination set in digitsMatch attribute.

Only available when DialAction is set to digits.

DialDigitsPressedBy

Returns the leg of the call on which the digits were pressed — ALeg or BLeg.

DialBLegDuration

Dial duration in seconds from B leg. Only available when DialAction is set to hangup.

DialBLegBillDuration

Dial duration in seconds billed from B leg. Only available when DialAction is set to hangup.

DialBLegFrom

Dial caller number or SIP endpoint for B leg. Only available when DialAction is set to answer, connected, digits, or hangup.

DialBLegTo

Dial called number or SIP endpoint for B leg. Only available when DialAction is set to answer, connected, digits, or hangup.

DialBLegHangupCauseName

The reason for the B leg’s hangup. Refer to our list of hangup causes and sources.

DialBLegHangupCauseCode

A unique integer code for the hangup cause. Refer to our list of hangup causes and sources.

DialBLegHangupSource

The entity that triggered the call hangup. Possible hangup sources are: Caller, Callee, Plivo, API Request, Answer XML, Error, and Unknown

Refer to our list of hangup causes and sources.

STIRVerification string

For outbound calls: Gives details about the attestation assigned to the call by Plivo

For inbound calls: Gives details about the attestation received on the inbound call to your Plivo phone number.

Possible values:

  • Verified means the call is from a verified caller who has authorized access to the customer’s caller ID, and hence should be treated with confidence. Verified is equivalent to attestation level A.
  • Not Verified means that, for this call, either the caller is not verified, or it’s uncertain whether they have access to the caller ID used, or both. Not Verified means the call received attestation level B or C.
  • Not Applicable means STIR/SHAKEN doesn’t apply to this call, as would be the case if a call is not addressed to a US number or if it’s a cloud call (WebRTC or SIP).

Read more about STIR/SHAKEN here.

The next few sections show code for several dialing examples.

Dial status reporting

This examples uses an action URL in the Dial XML element. After the call ends, Plivo reports back the status to this URL. You can control the flow of the call by returning valid Plivo XML from the action URL and setting the redirect attribute to true.

In this example, Plivo POSTs the status of the call to https://<yourdomain>.com/dial_status/ and expects valid XML since the redirect attribute is set to true.

Response

<Response>
    <Dial action="https://<yourdomain>.com/dial_status/" method="POST" redirect="true">
        <Number>12025551111</Number>
    </Dial>
</Response>

Custom caller tone

When you make an outbound call and then connect that call to a different number using the Dial element, you can play a custom caller tone using the dialMusic attribute.

Plivo requests the dialMusic URL using the POST HTTP method for a valid Play, Speak, or Wait XML element.

To play a message on a call while it’s being connected, you should return the second XML example response.

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
13
from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(
    plivoxml.DialElement(dial_music='https://<yourdomain>.com/dial_music/').add(
        plivoxml.NumberElement('12025551111')))
print(response.to_string())

# XML to play the message
play_message_response = plivoxml.ResponseElement()
play_message_response.add(
    plivoxml.SpeakElement('Your call is being connected'))
print(play_message_response.to_string())

Was this code helpful

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

include Plivo::XML
include Plivo::Exceptions

begin
  response = Response.new

  params = {
      'dialMusic' => "https://<yourdomain>.com/dial_music/"
  }

  dial = response.addDial(params)
  first_number = "12025551111"
  dial.addNumber(first_number)

  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end

begin
  response = Response.new

  speak_body = "Your call is being connected"
  response.addSpeak(speak_body)

  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end

Was this code helpful

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

var response = plivo.Response();

var params = {
    'dialMusic': "https://<yourdomain>.com/dial_music/"
};
var dial = response.addDial(params);

var first_number = "12025551111";
dial.addNumber(first_number);

console.log(response.toXML());

/*
Sample Output
<Response>
    <Dial dialMusic="https://<yourdomain>.com/dial_music/">
        <Number>12025551111</Number>
    </Dial>
</Response>
*/


/* Code to generate XML to be returned from url at dialMusic */

var plivo = require('plivo');

var response = plivo.Response();

var speak_body = "Your call is being connected";
response.addSpeak(speak_body);

console.log(response.toXML());

/*
Sample Output
<Response>
    <Speak>Your call is being connected</Speak>
</Response>
*/

Was this code helpful

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
<?php
    require '../vendor/autoload.php';
    use Plivo\XML\Response;

    $response = new Response();

    $params = array(
        'dialMusic' => "https://<yourdomain>.com/dial_music/"
    );

    $dial = $response->addDial($params);
    $number = "12025551111";
    $dial->addNumber($number);

    Header('Content-type: text/xml');
    echo($response->toXML());

    /*
    Sample Output

    <Response>
        <Dial dialMusic="https://<yourdomain>.com/dial_music/">
            <Number>12025551111</Number>
        </Dial>
    </Response>
    */
?>

<?php
    /* XML to be returned by dialMusic */
    require '../vendor/autoload.php';
    use Plivo\XML\Response;

    $response = new Response();

    $speak_body = "Your call is being connected";
    $response->addSpeak($speak_body);

    Header('Content-type: text/xml');
    echo($response->toXML());

    /*
    Sample Output

    <Response>
        <Speak>Your call is being connected</Speak>
    </Response>
    */
?>

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// Example for dial - custom caller tone
package com.plivo.api.xml.samples.dial;

import com.plivo.api.exceptions.PlivoXmlException;
import com.plivo.api.xml.Dial;
import com.plivo.api.xml.Number;
import com.plivo.api.xml.Response;


class CustomCallerTone {
    public static void main(String[] args) throws PlivoXmlException {
        Response response = new Response()
                .children(


                        new Dial()
                                .dialMusic("https://<yourdomain>.com/dial_music/")
                                .children(
                                        new Number("12025551111")
                                )
                );
        System.out.println(response.toXmlString());
    }
}

Was this code helpful

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
using System;
using System.Collections.Generic;
using Plivo.XML;

namespace Plivo
{
	class MainClass
	{
		public static void Main(string[] args)
		{
			Plivo.XML.Response resp = new Plivo.XML.Response();
			Plivo.XML.Dial dial = new Plivo.XML.Dial(new
				Dictionary<string, string>() {
				{"dialMusic", "https://<yourdomain>.com/dial_music/"}
			});

			dial.AddNumber("12025551111",
				new Dictionary<string, string>() { });
			resp.Add(dial);

			var output = resp.ToString();
			Console.WriteLine(output);

		}
	}
}



//<Response>
//  <Dial dialMusic = "https://<yourdomain>.com/dial_music/" >
//    < Number >12025551111</ Number >
//  </ Dial >
//</ Response >

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// Example for dial - caller tone
package main

import "github.com/plivo/plivo-go/v7/xml"

func main() {
	response := xml.ResponseElement{
		Contents: []interface{}{

			new(xml.DialElement).
				SetDialMusic("https://<yourdomain>.com/dial_music/").
				SetContents(
					[]interface{}{
						new(xml.NumberElement).
							SetContents("12025551111"),
					},
				),
		},
	}
	print(response.String())
}

Was this code helpful

Response

<Response>
    <Dial dialMusic="https://<yourdomain>.com/dial_music/">
        <Number>12025551111</Number>
    </Dial>
</Response>

 

Return this XML to play the message

<Response>
    <Speak>Your call is being connected</Speak>
</Response>

Confirm to answer call

When multiple calls are fired, the first person to answer gets connected and the rest of the calls are dropped. To make sure that the call is answered by a person and not by voice mail, use the confirmKey and confirmSound attributes.

The example XML here requires the call recipient to input the digit 5 after answering the call to connect.

Plivo requests the confirmSound URL using the POST HTTP method for a valid Play, Speak, or a Wait XML element. To play a message asking the recipient to input a DTMF tone to connect the call, return the second XML example.

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(
    plivoxml.DialElement(
        confirm_key='5', confirm_sound='https://<yourdomain>.com/confirm_sound/').add(
            plivoxml.NumberElement('12025551111')).add(
                plivoxml.NumberElement('12025552222')).add(
                    plivoxml.NumberElement('12025553333')))
print(response.to_string())

# XML to play the message
play_message_response = plivoxml.ResponseElement()
play_message_response.add(
    plivoxml.SpeakElement('Enter the digit 5 to connect the call'))
print(play_message_response.to_string())

Was this code helpful

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

include Plivo::XML
include Plivo::Exceptions

begin
  response = Response.new

  params = {
      'confirmSound' => "https://<yourdomain>.com/confirm_sound/",
      'confirmKey' => "5"
  }

  dial = response.addDial(params)
  first_number = "12025551111"
  dial.addNumber(first_number)

  second_number = "12025552222"
  dial.addNumber(second_number)

  third_number = "12025553333"
  dial.addNumber(third_number)

  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end

begin
  response = Response.new

  speak_body = "Enter the digit 5 to connect the call"
  response.addSpeak(speak_body)

  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end

Was this code helpful

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

var response = plivo.Response();

var params = {
    'confirmSound': "https://<yourdomain>.com/confirm_sound/",
    'confirmKey': "5"
};
var dial = response.addDial(params);

var first_number = "12025551111";
dial.addNumber(first_number);

var second_number = "12025552222";
dial.addNumber(second_number);

var third_number = "12025553333";
dial.addNumber(third_number);

console.log(response.toXML());

/*
Sample Output
<Response>
    <Dial confirmSound="https://<yourdomain>.com/confirm_sound/" confirmKey="5">
        <Number>12025551111</Number>
        <Number>12025552222</Number>
        <Number>12025553333</Number>
    </Dial>
</Response>
*/


/* Code to generate XML to be returned from url at confirmSound */

var plivo = require('plivo');

var response = plivo.Response();

var speak_body = "Enter the digit 5 to connect the call";
response.addSpeak(speak_body);

console.log(response.toXML());

/*
Sample Output
<Response>
    <Speak>Enter the digit 5 to connect the call</Speak>
</Response>
*/

Was this code helpful

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
<?php
    require '../vendor/autoload.php';
    use Plivo\XML\Response;

    $response = new Response();

    $params = array(
        'confirmSound'=>"https://<yourdomain>.com/confirm_sound/",
        'confirmKey' => "5"
    );

    $dial = $response->addDial($params);
    $first_number = "12025551111";
    $dial->addNumber($first_number);
    $second_number = "12025552222";
    $dial->addNumber($second_number);
    $third_number = "12025553333";
    $dial->addNumber($third_number);

    Header('Content-type: text/xml');
    echo($response->toXML());

    /*
    Sample Output

    <Response>
        <Dial confirmSound = "https://<yourdomain>.com/confirm_sound/" confirmKey="5">
            <Number>12025551111</Number>
            <Number>12025552222</Number>
            <Number>12025553333</Number>
        </Dial>
    </Response>
    */
?>

<?php
    /* XML to be returned by confirmSound */
    require '../vendor/autoload.php';
    use Plivo\XML\Response;

    $response = new Response();

    $speak_body = "Enter the digit 5 to connect the call";
    $response->addSpeak($speak_body);

    Header('Content-type: text/xml');
    echo($response->toXML());

    /*
    Sample Output

    <Response>
        <Speak>Enter the digit 5 to connect the call</Speak>
    </Response>
    */
?>

Was this code helpful

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
// Example for dial - confirm to answer call
package com.plivo.api.xml.samples.dial;

import com.plivo.api.exceptions.PlivoXmlException;
import com.plivo.api.xml.Dial;
import com.plivo.api.xml.Number;
import com.plivo.api.xml.Response;


class ConfirmToAnswerCall {
    public static void main(String[] args) throws PlivoXmlException {
        Response response = new Response()
                .children(


                        new Dial()
                                .confirmKey("5")
                                .confirmSound("https://<yourdomain>.com/confirm_sound/")
                                .children(
                                        new Number("12025551111"),


                                        new Number("12025552222"),


                                        new Number("12025553333")
                                )

                );
        System.out.println(response.toXmlString());
    }
}

Was this code helpful

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 Plivo.XML;

namespace Plivo
{
	class MainClass
	{
		public static void Main(string[] args)
		{
			Plivo.XML.Response resp = new Plivo.XML.Response();
			Plivo.XML.Dial dial = new Plivo.XML.Dial(new
				Dictionary<string, string>() {
				{"confirmSound", "https://<yourdomain>.com/sound/"},
				{"confirmKey", "3"}
			});

			dial.AddNumber("12025551111",
				new Dictionary<string, string>() { });
			dial.AddNumber("12025552222",
				new Dictionary<string, string>() { });
			dial.AddNumber("12025553333",
				new Dictionary<string, string>() { });
			resp.Add(dial);

			var output = resp.ToString();
			Console.WriteLine(output);

		}
	}
}



//<Response>
//  <Dial confirmSound = "https://<yourdomain>.com/sound/" 
//    confirmKey="3">
//    <Number>12025551111</Number>
//    <Number>12025552222</Number>
//    <Number>12025553333</Number>
//  </Dial>
//</Response>

Was this code helpful

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
// Example for dial - confirm to answer call
package main

import "github.com/plivo/plivo-go/v7/xml"

func main() {
	response := xml.ResponseElement{
		Contents: []interface{}{

			new(xml.DialElement).
				SetConfirmKey("5").
				SetConfirmSound("https://<yourdomain>.com/confirm_sound/").
				SetContents([]interface{}{
					new(xml.NumberElement).
						SetContents("12025551111"),

					new(xml.NumberElement).
						SetContents("12025552222"),

					new(xml.NumberElement).
						SetContents("12025553333"),
				}),
		},
	}
	print(response.String())
}

Was this code helpful

Response

<Response>
    <Dial confirmSound="https://<yourdomain>.com/confirm_sound/" confirmKey="5">
        <Number>12025551111</Number>
        <Number>12025552222</Number>
        <Number>12025553333</Number>
    </Dial>
</Response>

 

Return the following XML to play a message.

<Response>
    <Speak>Enter the digit 5 to connect the call</Speak>
</Response>

Sequential dialing

This example calls out to two phone numbers sequentially. The first call is made to a number with a timeout value of 20 seconds. If the call is not answered within that time, Plivo will dial out to the second number.

Example Request

1
2
3
4
5
6
7
8
from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(
    plivoxml.DialElement(action='https://<yourdomain>.com/dial_action/', time_limit=20)
    .add(plivoxml.NumberElement('12025551111')))
response.add(plivoxml.DialElement().add(plivoxml.NumberElement('12025552222')))
print(response.to_string())

Was this code helpful

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 'plivo'

include Plivo::XML
include Plivo::Exceptions

begin
  response = Response.new

  params = {
      'timeout' => "20",
      'action' => "https://<yourdomain>.com/dial_status/"
  }

  first_dial = response.addDial(params)
  first_number = "12025551111"
  first_dial.addNumber(first_number)

  second_dial = response.addDial()
  second_number = "12025552222"
  second_dial.addNumber(second_number)

  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end

Was this code helpful

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

var response = plivo.Response();

var params = {
    'timeout': "20",
    'action': "https://<yourdomain>.com/dial_action/"
};
var first_dial = response.addDial(params);
var first_number = "12025551111";
first_dial.addNumber(first_number);

var second_dial = response.addDial();
var second_number = "12025552222";
second_dial.addNumber(second_number);

console.log(response.toXML());

/*
Sample Output
<Response>
    <Dial timeout="20" action="https://<yourdomain>.com/dial_action/">
        <Number>12025551111</Number>
    </Dial>
    <Dial>
        <Number>12025552222</Number>
    </Dial>
</Response>
*/

Was this code helpful

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
<?php
    require '../vendor/autoload.php';
    use Plivo\XML\Response;

    $response = new Response();

    $first_params = array(
        'timeout' => "20",
        'action' => "https://<yourdomain>.com/dial_action/"
    );

    $first_dial = $response->addDial($first_params);
    $first_number = "12025551111";
    $first_dial->addNumber($first_number);

    $second_dial = $response->addDial();
    $second_number = "12025552222";
    $second_dial->addNumber($second_number);

    Header('Content-type: text/xml');
    echo($response->toXML());

    /*
    Sample Output

    <Response>
        <Dial timeout="20" action="https://<yourdomain>.com/dial_action/">
            <Number>12025551111</Number>
        </Dial>
        <Dial>
            <Number>12025552222</Number>
        </Dial>
    </Response>
    */
?>

Was this code helpful

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
// Example for dial - sequential dialing
package com.plivo.api.xml.samples.dial;

import com.plivo.api.exceptions.PlivoXmlException;
import com.plivo.api.xml.Dial;
import com.plivo.api.xml.Number;
import com.plivo.api.xml.Response;


class SequentialDialing {
    public static void main(String[] args) throws PlivoXmlException {
        Response response = new Response()
            .children(


                new Dial()
                .children(
                    new Number("12025551111")

                ),


                new Dial()
                .children(
                    new Number("12025552222")
                )
            );
        System.out.println(response.toXmlString());
    }
}

Was this code helpful

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
using System;
using System.Collections.Generic;
using Plivo.XML;

namespace Plivo
{
	class MainClass
	{
		public static void Main(string[] args)
		{
			Plivo.XML.Response resp = new Plivo.XML.Response();
			Plivo.XML.Dial dial1 = new Plivo.XML.Dial(new
				Dictionary<string, string>() {
				{"timeout", "20"},
				{"action", "https://<yourdomain>.com/dial_action/"}
			});

			dial1.AddNumber("12025551111",
				new Dictionary<string, string>() { });

			Plivo.XML.Dial dial2 = new Plivo.XML.Dial(new
				Dictionary<string, string>()
			{ });
			dial2.AddNumber("12025552222",
				new Dictionary<string, string>() { });
			resp.Add(dial1);
			resp.Add(dial2);

			var output = resp.ToString();
			Console.WriteLine(output);

		}
	}
}



//<Response>
//  <Dial timeout = "20" 
//    action="https://<yourdomain>.com/dial_action/">
//    <Number>12025551111</Number>
//  </Dial>
//  <Dial>
//    <Number>12025552222</Number>
//  </Dial>
//</Response>

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// Example for dial - sequential dialing
package main

import "github.com/plivo/plivo-go/v7/xml"

func main() {
	response := xml.ResponseElement{
		Contents: []interface{}{

			new(xml.DialElement).
				SetContents([]interface{}{
					new(xml.NumberElement).
						SetContents("12025551111"),
				}),

			new(xml.DialElement).
				SetContents([]interface{}{
					new(xml.NumberElement).
						SetContents("12025552222"),
				}),
		},
	}
	print(response.String())
}

Was this code helpful

Response

<Response>
    <Dial timeout="20" action="https://<yourdomain>.com/dial_action/">
        <Number>12025551111</Number>
    </Dial>
    <Dial>
        <Number>12025552222</Number>
    </Dial>
</Response>

Simultaneous dialing

This example uses three User and Number elements to dial two SIP endpoints and a phone number at the same time. The first of these calls to answer will be connected to the caller, and the rest of the connection attempts will be canceled.

Note: In Simultaneous dialing, the maximum number of destinations (Endpoint or number) that can passed is 10

Example Request

1
2
3
4
5
6
7
8
from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(plivoxml.DialElement().add(
    plivoxml.UserElement('sip:alice1234@phone.plivo.com')).add(
        plivoxml.NumberElement('12025551111')).add(
            plivoxml.UserElement('sip:john1234@phone.plivo.com')))
print(response.to_string())

Was this code helpful

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 'plivo'

include Plivo::XML
include Plivo::Exceptions

begin
  response = Response.new

  dial = response.addDial()
  first_user = "sip:alice1234@phone.plivo.com"
  dial.addUser(first_user)

  number = "12025551111"
  dial.addNumber(number)

  second_user = "sip:john1234@phone.plivo.com"
  dial.addUser(second_user)

  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end

Was this code helpful

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

var response = plivo.Response();

var dial = response.addDial();

var first_user = "sip:alice1234@phone.plivo.com";
dial.addUser(first_user);

var number = "12025551111";
dial.addNumber(number);

var second_user = "sip:john1234@phone.plivo.com";
dial.addUser(second_user);

console.log(response.toXML());

/*
Sample Output
<Response>
    <Dial>
        <User>sip:alice1234@phone.plivo.com</User>
        <Number>12025551111</Number>
        <User>sip:john1234@phone.plivo.com</User>
    </Dial>
</Response>
*/

Was this code helpful

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
<?php
    require '../vendor/autoload.php';
    use Plivo\XML\Response;

    $response = new Response();

    $dial = $response->addDial();
    $first_user = "sip:alice1234@phone.plivo.com";
    $dial->addUser($first_user);

    $number = "12025551111";
    $dial->addNumber($number);

    $second_user = "sip:john1234@phone.plivo.com";
    $dial->addUser($second_user);

    Header('Content-type: text/xml');
    echo($response->toXML());

    /*
    Sample Output

    <Response>
        <Dial>
            <User>sip:alice1234@phone.plivo.com</User>
            <Number>12025551111</Number>
            <User>sip:john1234@phone.plivo.com</User>
        </Dial>
    </Response>
    */
?>

Was this code helpful

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
// Example for dial - sequential dialing
package com.plivo.api.xml.samples.dial;

import com.plivo.api.exceptions.PlivoXmlException;
import com.plivo.api.xml.Dial;
import com.plivo.api.xml.Number;
import com.plivo.api.xml.Response;


class SequentialDialing {
    public static void main(String[] args) throws PlivoXmlException {
        Response response = new Response()
            .children(


                new Dial()
                .children(
                    new Number("12025551111")

                ),


                new Dial()
                .children(
                    new Number("12025552222")
                )
            );
        System.out.println(response.toXmlString());
    }
}

Was this code helpful

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
using System;
using System.Collections.Generic;
using Plivo.XML;

namespace Plivo
{
	class MainClass
	{
		public static void Main(string[] args)
		{
			Plivo.XML.Response resp = new Plivo.XML.Response();
			Plivo.XML.Dial dial = new Plivo.XML.Dial(new
				Dictionary<string, string>() {});

			dial.AddUser("sip:alice1234@phone.plivo.com",
				new Dictionary<string, string>() { });
			dial.AddNumber("12025551111",
				new Dictionary<string, string>() { });
			dial.AddUser("sip:john1234@phone.plivo.com",
				new Dictionary<string, string>() { });
			resp.Add(dial);

			var output = resp.ToString();
			Console.WriteLine(output);

		}
	}
}



//<Response>
//  <Dial>
//    <User>sip:alice1234 @phone.plivo.com</User>
//    <Number>12025551111</Number>
//    <User>sip:john1234 @phone.plivo.com</User>
//  </Dial>
//</Response>

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// Example for dial - simultaneous dialing
package main

import "github.com/plivo/plivo-go/v7/xml"

func main() {
	response := xml.ResponseElement{
		Contents: []interface{}{

			new(xml.DialElement).
				SetContents([]interface{}{
					new(xml.UserElement).
						SetContents("sip:alice1234@phone.plivo.com"),

					new(xml.NumberElement).
						SetContents("12025551111"),

					new(xml.UserElement).
						SetContents("sip:john1234@phone.plivo.com"),
				}),
		},
	}
	print(response.String())
}

Was this code helpful

Response

<Response>
    <Dial>
      <User>sip:alice1234@phone.plivo.com</User>
      <Number>15671234567</Number>
      <User>sip:john1234@phone.plivo.com</User>
    </Dial>
</Response>

The Number element

You can use the Number element to specify a phone number to dial.

You can use multiple Number elements within a Dial element to simultaneously call multiple numbers. The first call to pick up is connected to the current call and the rest are hung up.

Use the Number element to

  • Forward an incoming call on a Plivo number to a mobile or a landline number.
  • Make an outbound call to an agent and then bridge the call to a client’s number for call center use cases.
  • Enable click to call, where you input a number on a web-based form and request a connection with another person.
Note: When dialing multiple numbers simultaneously, if confirmSound and confirmKey are specified for the Dial element, the number that confirms the key correctly is bridged and all others fail.

Attributes

sendDigits string

Tells the API to play DTMF tones when the call is answered. This is useful when dialing a phone number and an extension. The API dials the number, and when the automated system picks up, it sends DTMF tones to connect to the extension.

Allowed values: any digits and the w character. Each w character tells the Plivo API to wait 0.5 seconds.
No default value.

sendOnPreanswer boolean

If set to true, sendDigits is executed when the called party is in early media instead of answer state.

Allowed values: true, false
Defaults to false.

Dialing extensions

This code dials the extension 2410 at the number 15671234567. The Number element describes the phone number and gives it the sendDigits attribute. To dial the extension a couple of seconds after the number is dialed, we add a few leading w characters, telling Plivo to wait 0.5 seconds for each w.

Example Request

1
2
3
4
5
6
from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(plivoxml.DialElement().add(
    plivoxml.NumberElement('12025551111', send_digits='wwww2410')))
print(response.to_string())

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
require 'rubygems'
require 'plivo'

include Plivo::XML
include Plivo::Exceptions

begin
  response = Response.new

  dial = response.addDial()

  params = {
    'sendDigits' => "wwww2410"
  }

  number = "12025551111"
  dial.addNumber(number, params)

  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
var plivo = require('plivo');

var response = plivo.Response();

var dial = response.addDial();

var params = {
    'sendDigits': "wwww2410"
};
var number = "12025551111";
dial.addNumber(number, params);

console.log(response.toXML());

/*
Sample Output
<Response>
    <Dial>
        <Number sendDigits="wwww2410">12025551111</Number>
    </Dial>
</Response>
*/

Was this code helpful

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
<?php
    require '../../vendor/autoload.php';
    use Plivo\XML\Response;

    $response = new Response();

    $dial = $response->addDial();

    $params = array(
        'sendDigits' => "wwww2410",
    );

    $number = "12025551111";
    $dial->addNumber($number, $params);

    Header('Content-type: text/xml');
    echo($response->toXML());

    /*
    Sample Output

    <Response>
        <Dial>
            <Number sendDigits="wwww2410">12025551111</Number>
        </Dial>
    </Response>
    */
?>

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// Example for number - dialing extensions
package com.plivo.api.xml.samples.number;

import com.plivo.api.exceptions.PlivoXmlException;
import com.plivo.api.xml.Dial;
import com.plivo.api.xml.Number;
import com.plivo.api.xml.Response;


class DialingExtensions {
    public static void main(String[] args) throws PlivoXmlException {
        Response response = new Response()
                .children(


                        new Dial()
                                .children(
                                        new Number("12025551111")
                                                .sendDigits("wwww2410")
                                )
                );
        System.out.println(response.toXmlString());
    }
}

Was this code helpful

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
using System;
using System.Collections.Generic;
using Plivo.XML;

namespace Plivo
{
	class MainClass
	{
		public static void Main(string[] args)
		{
			Plivo.XML.Response resp = new Plivo.XML.Response();
			Plivo.XML.Dial dial = new Plivo.XML.Dial(new
				Dictionary<string, string>()
			{ });

			dial.AddNumber("12025551111",
				new Dictionary<string, string>()
			{
				{"sendDigits", "wwww2410"}
			});

			resp.Add(dial);

			var output = resp.ToString();
			Console.WriteLine(output);

		}
	}
}



//<Response>
//  <Dial>
//    <Number sendDigits = "wwww2410" > 
//        12025551111 
//    </ Number >
//  </ Dial >
//</ Response >

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// Example for number - dialing extensions
package main

import "github.com/plivo/plivo-go/v7/xml"

func main() {
	response := xml.ResponseElement{
		Contents: []interface{}{

			new(xml.DialElement).
				SetContents([]interface{}{
					new(xml.NumberElement).
						SetSendDigits("wwww2410").
						SetContents("12025551111"),
				}),
		},
	}
	print(response.String())
}

Was this code helpful

Response

<Response>
    <Dial>
        <Number sendDigits="wwww2410">15671234567</Number>
    </Dial>
</Response>

The User Element

You can use the User element to specify a SIP endpoint (user) to dial.

You can use multiple User elements within a Dial element to simultaneously call multiple SIP endpoint users. The first user to answer is connected to the current call and the rest are hung up.

Note: When dialing multiple numbers simultaneously, if confirmSound and confirmKey are specified for the Dial element, the phone that confirms the key correctly is bridged and all others fail.

Attributes

sendDigits string

Tells the API to play DTMF tones when the call is answered. This is useful when dialing a phone number and an extension. Plivo dials the number, and when the automated system picks up, it sends DTMF tones to connect to the extension.

Allowed values: any digits and the w character. Each w character tells the Plivo API to wait 0.5 seconds.
No default value.

sendOnPreanswer boolean

If set to true, sendDigits is executed when the called party is in early media instead of the answer state.

Allowed values: true, false
Defaults to false.

sipHeaders string

List of SIP headers to send, separated by commas. For example, head1=val1,head2=val2,head3=val3,...,headN=valN. The SIP headers are always prefixed with X-PH-, and are always present for each HTTP request called by the dialed leg.

Allowed values: Only [A-Z], [a-z] and [0-9] characters are allowed for SIP header names and values to ensure you can encode them in a URL.

Dialing extensions

This code calls the 2410 extension at sip:john1234@phone.plivo.com. The User element describes the SIP endpoint and gives it the attribute sendDigits. To dial the extension a couple of seconds after the number is dialed, we add a few leading w characters, telling Plivo to wait 0.5 seconds for each w.

Example Request

1
2
3
4
5
6
7
from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(plivoxml.DialElement().add(
    plivoxml.UserElement(
        'sip:john1234@phone.plivo.com', send_digits='wwww2410')))
print(response.to_string())

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
require 'rubygems'
require 'plivo'

include Plivo::XML
include Plivo::Exceptions

begin
  response = Response.new

  dial = response.addDial()

  params = {
    'sendDigits' => "wwww2410"
  }

  user = "sip:john1234@phone.plivo.com"
  dial.addUser(user, params)

  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
var plivo = require('plivo');

var response = plivo.Response();

var dial = response.addDial();

var params = {
    'sendDigits': "wwww2410",
};
var user = "sip:john1234@phone.plivo.com";
dial.addUser(user, params);

console.log(response.toXML());

/*
Sample Output
<Response>
    <Dial>
        <User>sip:john1234@phone.plivo.com</User>
    </Dial>
</Response>
*/

Was this code helpful

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
<?php
    require '../../vendor/autoload.php';
    use Plivo\XML\Response;

    $response = new Response();

    $dial = $response->addDial();

    $params = array(
        'sendDigits' => "wwww2410"
    );

    $user = "sip:john1234@phone.plivo.com";
    $dial->addUser($user, $params);

    Header('Content-type: text/xml');
    echo($response->toXML());

    /*
    Sample Output

    <Response>
        <Dial>
            <User sendDigits="wwww2410">
                sip:john1234@phone.plivo.com
            </User>
        </Dial>
    </Response>
    */
?>

Was this code helpful

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
// Example for user - dialing extensions
package com.plivo.api.xml.samples.user;

import com.plivo.api.exceptions.PlivoXmlException;
import com.plivo.api.xml.Dial;
import com.plivo.api.xml.Response;
import com.plivo.api.xml.User;


class DialingExtensions {
    public static void main(String[] args) throws PlivoXmlException {
        Response response = new Response()
                .children(


                        new Dial()
                                .children(
                                        new User("sip:john1234@phone.plivo.com")
                                                .sendDigits("wwww2410")
                                )

                );
        System.out.println(response.toXmlString());
    }
}

Was this code helpful

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
using System;
using System.Collections.Generic;
using Plivo.XML;

namespace Plivo
{
	class MainClass
	{
		public static void Main(string[] args)
		{
			Plivo.XML.Response resp = new Plivo.XML.Response();
			Plivo.XML.Dial dial = new Plivo.XML.Dial(new
				Dictionary<string, string>()
			{ });

			dial.AddUser("sip:john1234@phone.plivo.com",
				new Dictionary<string, string>()
			{
				{"sendDigits", "wwww2410"}
			});

			resp.Add(dial);

			var output = resp.ToString();
			Console.WriteLine(output);

		}
	}
}



//<Response>
//  <Dial>
//    <User sendDigits = "wwww2410" > 
//        sip:john1234@phone.plivo.com 
//    </ User >
//  </ Dial >
//</ Response >

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// Example for user - dialing extensions
package main

import "github.com/plivo/plivo-go/v7/xml"

func main() {
	response := xml.ResponseElement{
		Contents: []interface{}{

			new(xml.DialElement).
				SetContents([]interface{}{
					new(xml.UserElement).
						SetSendDigits("wwww2410").
						SetContents("\tsip:john1234@phone.plivo.com"),
				}),
		},
	}
	print(response.String())
}

Was this code helpful

Response

<Response>
    <Dial>
        <User sendDigits="wwww2410">sip:john1234@phone.plivo.com</User>
    </Dial>
</Response>

The DTMF Element

You can use the DTMF element to send digits on a live call — for instance, to automate the process of navigating through an interactive voice response (IVR) tree.

If you set the async parameter to true, Plivo will send digits in the background, so the call jumps to the next XML element when the first digit is sent. Use the character w to add a 0.5 second delay and the character W for a 1 second delay.

Allowed values: 1234567890*#wW

Attributes

async boolean

Proceed to next element after the first digit is sent.

Allowed values: true, false
Defaults to true.

Send digits

This code sends the digits 1234 on the live call.

Example Request

1
2
3
4
5
from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(plivoxml.DTMFElement('1234'))
print(response.to_string())

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
require 'rubygems'
require 'plivo'

include Plivo::XML
include Plivo::Exceptions

begin
  response = Response.new

  dtmf = "12345"
  response.addDTMF(dtmf)

  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
var plivo = require('plivo');

var response = plivo.Response();

var dtmf = "12345";
response.addDTMF(dtmf);

console.log(response.toXML());

/*
Sample Output
<Response>
    <DTMF>12345</DTMF>
</Response>
*/

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
<?php
    require '../vendor/autoload.php';
    use Plivo\XML\Response;

    $response = new Response();

    $dtmf = "12345";
    $response->addDTMF($dtmf);

    Header('Content-type: text/xml');
    echo($response->toXML());

    /*
    Sample Output

    <Response>
        <DTMF>12345</DTMF>
    </Response>
    */
?>

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// Example for xml - send digits
package com.plivo.api.xml.samples.xml;

import com.plivo.api.exceptions.PlivoXmlException;
import com.plivo.api.xml.Dtmf;
import com.plivo.api.xml.Response;
import com.plivo.api.xml.Speak;


class SendDigits {
    public static void main(String[] args) throws PlivoXmlException {
        Response response = new Response()
                .children(


                        new Speak("Sending Digits"),


                        new Dtmf("12345")

                );
        System.out.println(response.toXmlString());
    }
}

Was this code helpful

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
using System;
using System.Collections.Generic;
using Plivo.XML;

namespace Plivo
{
   class MainClas
   {
       public static void Main(string[] args)
       {
           Plivo.XML.Response resp = new Plivo.XML.Response();
           resp.AddDTMF("12345", 
             new Dictionary<string, string>() { });
			var output = resp.ToString();
           Console.WriteLine(output);

       }
   }
}



//<Response>
//  <DTMF>12345</DTMF>
//</Response>

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// Example for xml - dtmf
package main

import "github.com/plivo/plivo-go/v7/xml"

func main() {
	response := xml.ResponseElement{
		Contents: []interface{}{

			new(xml.SpeakElement).
				SetContents("Sending Digits"),

			new(xml.DTMFElement).
				SetContents("12345"),
		},
	}
	print(response.String())
}

Was this code helpful

Response

<Response>
    <DTMF>1234</DTMF>
</Response>

The GetDigits element

Note: The GetInput XML element is designed to replace Plivo’s older GetDigits XML element, which only supports the collection of digit press inputs. We recommend you use GetInput instead of GetDigits even if you only intend to collect digit press input from users.

You can use the GetDigits element to collect the digits entered by a caller. Once the caller finishes entering the digits, the API submits the data to the provided action URL using a HTTP GET or POST request.

You can play a message nested inside the GetDigits element while the digits are being received in the background, which is useful for creating an interactive voice response (IVR) tree.

Nesting rules

You can nest Speak and Play elements within the GetDigits element.

Attributes

action stringCallback-retry configurable

The URL to which the digits are sent. See the “Parameters sent to the action URL” table below for more information.

Allowed values: a full qualified URL

method string

Method used to send HTTP request to the action URL.

Allowed values: GET, POST
Defaults to POST.

timeout integer

Time in seconds to wait to receive the first digit. If the user fails to provide input within the timeout period, the next element in the response is processed.

Allowed values: any positive integer
Defaults to 5.

digitTimeout integer

Time in seconds allowed between consecutive digit inputs. If input is not provided within the digitTimeout period, digits entered until then will be processed.

Allowed values: any positive integer
Defaults to 2.

finishOnKey string

A digit that the user can press to submit digits.

Allowed values: One and only one of  0–9, *, #, <empty string>, none
Defaults to #.

If set to <empty string> or none, input capture will end based on a timeout or the numDigits attribute.

numDigits integer

Maximum number of digits to be processed in the current operation. Only the number of numDigits is captured; any additional digits entered are ignored.

Allowed values: integer >= 1
Defaults to 99.

retries integer

Indicates the number of retries the user is allowed to input digits if digits are not received within the time specified by timeout.

Allowed values: integer >= 1
Defaults to 1.

redirect boolean

Redirect to action URL if true. If false, request the URL and continue to next element.

Allowed values: true, false
Defaults to true.

playBeep boolean

Plays a beep when all Speak and Play elements finish executing.

Allowed values: true, false
Defaults to false.

validDigits string

Specifies the set of digits the user is allowed enter.

Allowed values: any digit, #, *
Defaults to 1234567890*#

invalidDigitsSound string

URL of the sound file to be played when the user enters an invalid digit.

Allowed values: Any remote sound file URL (MP3 or WAV)

log boolean

If true, Plivo logs digits entered by the caller, and you can view them in debug logs. If false, logging is disabled during GetDigits element processing.

Allowed values: true, false
Default is true.

Parameters sent to the action URL

These parameters are sent to the action URL after DTMF input is captured.

Digits

The digits input by the caller, excluding the finishOnKey digit if used.

Phone tree

In this example, after a caller enters digits on the keypad, Plivo sends them as a request to the action URL. We also include a nested Speak element, so input can be gathered at any time during the Speak element.

If the caller enters a digit during the speaking of the text, the Speak element will stop speaking and wait for digits, the finishOnKey, or a timeout.

If the GetDigits element times out without input, the Speak element will complete and the GetDigits element will exit without submitting. Plivo will then process the next element in the document, which in this case is a Speak element that informs the caller that no input was received.

For a nested phone tree, you should return a GetDigits element from the action URL. In the top example, if the caller enters a four-digit PIN, Plivo will POST the Digits to the action URL, and your application can return the second XML example to play another message and accept input.

Example Request

1
2
3
4
5
6
7
8
9
10
from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(
    plivoxml.GetDigitsElement(
        action='https://<yourdomain>.com/gather_pin/', method='POST').add(
            plivoxml.SpeakElement(
                'Enter PIN.')))
response.add(plivoxml.SpeakElement('Input not received.'))
print(response.to_string())

Was this code helpful

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

include Plivo::XML
include Plivo::Exceptions

begin
  response = Response.new

  params = {
      action: 'https://<yourdomain>.com/gather_pin/',
      method: 'POST'
  }

  get_digits = response.addGetDigits(params)
  input_received_speak = 'Enter PIN.'
  get_digits.addSpeak(input_received_speak)

  input_not_received_speak = 'Input not received.'
  response.addSpeak(input_not_received_speak)

  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end

Was this code helpful

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

var response = plivo.Response();

var params = {
    'action': "https://<yourdomain>.com/gather_pin/",
    'method': "POST"
};
var get_digits = response.addGetDigits(params);

var input_received_speak = "Enter PIN.";
get_digits.addSpeak(input_received_speak);

var input_not_received_speak = "Input not received.";
response.addSpeak(input_not_received_speak);

console.log(response.toXML());

/*
Sample Output
<Response>
    <GetDigits action="https://<yourdomain>.com/gather_pin/" method="POST">
        <Speak>Enter PIN.</Speak>
    </GetDigits>
    <Speak>Input not received.</Speak>
</Response>
*/

Was this code helpful

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
<?php
    require '../vendor/autoload.php';
    use Plivo\XML\Response;

    $response = new Response();

    $params = array(
        'action' => "https://<yourdomain>.com/gather_pin/",
        'method' => "POST"
    );

    $get_digits = $response->addGetDigits($params);
    $input_received_speak = "Enter PIN.";
    $get_digits->addSpeak($input_received_speak);

    $input_not_received_speak = "Input not received.";
    $response->addSpeak($input_not_received_speak);

    Header('Content-type: text/xml');
    echo($response->toXML());

    /*
    Sample Output

    <Response>
        <GetDigits action="https://<yourdomain>.com/gather_pin/" method="POST">
            <Speak>Enter PIN.</Speak>
        </GetDigits>
        <Speak>Input not received.</Speak>
    </Response>
    */
?>

Was this code helpful

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
// Example for getdigits - phone tree
package com.plivo.api.xml.samples.getdigits;

import com.plivo.api.exceptions.PlivoXmlException;
import com.plivo.api.xml.GetDigits;
import com.plivo.api.xml.Response;
import com.plivo.api.xml.Speak;


class PhoneTree {
    public static void main(String[] args) throws PlivoXmlException {
        Response response = new Response()
                .children(


                        new GetDigits()
                                .action("https://<yourdomain>.com/gather_pin/")
                                .method("POST")
                                .children(
                                        new Speak("Enter PIN.")
                                ),


                        new Speak("Input not received.")
                );
        System.out.println(response.toXmlString());
    }
}

Was this code helpful

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
using System;
using System.Collections.Generic;
using Plivo.XML;

namespace Plivo
{
	class MainClass
	{
		public static void Main(string[] args)
		{
			Plivo.XML.Response resp = new Plivo.XML.Response();
			Plivo.XML.GetDigits get_digits = new
				Plivo.XML.GetDigits("",
				   new Dictionary<string, string>()
			{
				{"action", "https://<yourdomain>.com/gather_pin/"},
				{ "method", "POST" }
			});
			resp.Add(get_digits);

			get_digits.AddSpeak("Enter PIN.",
				new Dictionary<string, string>() { });
			resp.AddSpeak("Input not received.",
				new Dictionary<string, string>() { });
			var output = resp.ToString();
			Console.WriteLine(output);

		}
	}
}



//<Response>
//  <GetDigits action = "https://<yourdomain>.com/gather_pin/" 
//    method="POST">
//    <Speak>Enter PIN.</Speak>
//  </GetDigits>
//  <Speak>Input not received.</Speak>
//</Response>

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// Example for getdigits - phone tree
package main

import "github.com/plivo/plivo-go/v7/xml"

func main() {
	response := xml.ResponseElement{
		Contents: []interface{}{

			new(xml.GetDigitsElement).
				SetAction("https://<yourdomain>.com/gather_pin/").
				SetMethod("POST").
				SetContents([]interface{}{

					new(xml.SpeakElement).
						AddSpeak("\tEnter PIN."),
				}),

			new(xml.SpeakElement).
				AddSpeak("Input not received."),
		},
	}
	print(response.String())
}

Was this code helpful

Response

<Response>
    <GetDigits action="https://<yourdomain>.com/gather_pin/" method="POST">
        <Speak>Enter your 4-digit pin number, followed by the hash key</Speak>
    </GetDigits>
    <Speak>Input not received</Speak>
</Response>

Return this XML to gather department:

<Response>
    <GetDigits action="https://<yourdomain>.com/gather_department/" method="POST">
        <Speak>Enter 1 for support and 2 for sales</Speak>
    </GetDigits>
</Response>

The GetInput element

You can use the GetInput XML element to collect user input through automatic speech recognition or DTMF “digit press” inputs.

When collecting speech as input, Plivo transcribes and relays a user’s speech to the specified action URL in real time.

When collecting input through digit press, Plivo relays the digits entered to the specified action URL.

The GetInput XML element supports simultaneous detection of both speech and digit press inputs.

Note: The GetInput XML element is designed to replace Plivo’s older GetDigits XML element, which only supports the collection of digit press inputs. We recommend you use GetInput instead of GetDigits even if you only intend to collect digit press input from users.

Nesting elements

You can nest Speak XML (text-to-speech) and Play XML elements inside GetInput XML to prompt users for inputs. This is useful for building interactive voice response (IVR) experiences.

Attributes

action requiredStringCallback-retry configurable

The input is sent to a specific URL. See the “parameters sent to the action URL” table below for more information.

Allowed values: a fully qualified URL

method String

The HTTP method to use when invoking the action URL.

Allowed values: GET, POST
Defaults to POST.

inputType String

The type of input(s) you expect to receive.

Allowed values: dtmf, speech, dtmf speech

When set to dtmf speech, Plivo listens for both speech and digit inputs. The input that’s detected first is relayed to the action URL.

executionTimeout integer

Maximum execution time, in seconds, for which input detection is carried out. If the user fails to provide input within the timeout period, the next element in the response will be processed. This duration is counted after nested Play/Speak elements have ended.

Allowed values: 5 to 60
Defaults to 15.

digitEndTimeout String

Time, in seconds, allowed between consecutive digit inputs. If no new digit input is provided within the digitEndTimeout period, digits entered until then will be processed.

Allowed values: 2 to 10, or auto
Defaults to auto.

This attribute is applicable to input types dtmf and dtmf speech.

speechEndTimeout String

Time, in seconds, that Plivo waits for more speech once silence is detected before it stops speech recognition. At that point, a transcription of the collected speech is relayed to the action URL.

Allowed values: 2 to 10, or auto
Defaults to auto.

This attribute is applicable to input types speech and dtmf speech.

finishOnKey String

A digit that the user can press to submit digits.

Allowed values: One and only one of  0–9, *, #, <empty string>, none
Defaults to #.

If set to <empty string> or none, input capture will end based on a timeout or the numDigits attribute.

This attribute is applicable to input types dtmf and dtmf speech.

numDigits integer The maximum number of digits to be processed in the current operation.

Plivo relays the digits to the action URL as soon as the maximum number of digits specified is collected.

Allowed values: 1 to 32
Defaults to 32.

This attribute is applicable to input types dtmf and dtmf speech.

speechModel String The automatic speech recognition (ASR) model to use for transcribing the speech.


Allowed values: default, command_and_search, phone_call.
Defaults to default.

This attribute is applicable to input types speech and dtmf speech.

Note:
  • command_and_search: Optimized for short queries such as voice commands and voice search.
  • phone_call: Optimized for transcribing audio from a phone call where the quality of the audio is slightly inconsistent.
  • telephony: telephony is an enhanced version of the phone_call model, optimized for audio typically originating from phone calls.
  • default: Optimized for audio that is not one of the specific audio models such as long-form audio.
hints String

A list of phrases to act as “hints” to the speech recognition model; these phrases can boost the probability that such words or phrases will be recognized. Phrases may be provided both as small groups of words or as single words.

Allowed values: a non-empty string of comma-separated phrases

Limits:
Phrases per request: 500
Characters per request: 10,000
Characters per phrase: 100

This attribute is applicable to input types speech and dtmf speech.

language String

Specifies the language Plivo should recognize from the user.

Allowed values: See list of supported languages
Defaults to en-US.

This attribute is applicable to input types speech and dtmf speech.

interimSpeechResultsCallback StringCallback-retry configurable

If interimSpeechResultsCallback URL is specified, requests to this URL are made in real-time as Plivo recognizes speech.

See the “parameters sent to the interimSpeechResultsCallback URL” table below for more information.

Allowed values: a fully qualified URL

This attribute is applicable to input types speech and dtmf speech.

interimSpeechResultsCallbackMethod String

The HTTP method to use when invoking the interimSpeechResultsCallback URL.

Allowed values: GET, POST
Defaults to POST.

This attribute is applicable to input types speech and dtmf speech.

log boolean

If true, Plivo will log digits or recognized speech from the caller. If false, logging will be disabled while processing the GetInput element.

Allowed values: true, false
Defaults to true.

redirect boolean

If true, redirect to action URL. If false, only request the URL and continue to the next element.

Allowed values: true, false
Defaults to true.

profanityFilter boolean

If true, filters out profane words. Words filtered out are transcribed with their first letter and asterisks for the remaining characters (e.g. f***). The profanity filter operates on single words; it doesn’t detect abusive or offensive speech that’s a phrase or a combination of words.

Allowed values: true, false
Defaults to false.

This attribute is applicable to input types speech and dtmf speech.

Parameters sent to the action URL

In addition to the standard action URL request parameters, these parameters are sent to the action URL specified.

InputType

The type of input detected.

Allowed values: dtmf, speech

Digits The digits entered by the caller, excluding the finishOnKey input, if used. This parameter will be empty if inputType is speech.
Speech The transcribed result of the caller’s speech. This parameter will be empty if inputType is dtmf.
SpeechConfidenceScore A confidence score between 0.0 and 1.0. The higher the confidence score, the more likely that the transcription is accurate.
BilledAmount The total amount billed for speech input transcription.

Parameters sent to the interimSpeechResultsCallback URL

In addition to the standard callback URL request parameters, these parameters are sent to the interim speech results callback URL.

StableSpeech The stable transcribed result of the user’s speech.
UnstableSpeech The newer unstable transcribed result of the user’s speech. This is an interim result and may change as more speech is gathered from the caller.
Stability An estimate of the likelihood that the recognizer will not change its guess about the interim result. Values range from 0.0 (completely unstable) to 1.0 (completely stable). This field only applies to unstable speech.
SequenceNumber Contains a sequence number of the interim speech callback, to help with ordering incoming callback requests.

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
from plivo import plivoxml
element = plivoxml.ResponseElement()
response = element.add(
    plivoxml.GetInputElement().
    set_action('https://<yourdomain>.com/result').
    set_method('POST').
    set_input_type('speech').
    set_execution_timeout(10).
    set_digit_end_timeout(5).
    set_speech_end_timeout(2).
    set_finish_on_key('#').
    set_num_digits(2).
    set_hints('good, bad').
    set_interim_speech_results_callback('https://<yourdomain>.com/interim_result').
    set_interim_speech_results_callback_method('POST').
    set_log(True).
    set_redirect(False).
    set_language('en-US').
    set_speech_model('default').
    add_speak(content='Tell us about your experience', voice='Polly.Salli', language='en-US', loop=2)
).to_string(False)
print(response)

Was this code helpful

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 'plivo'
require 'rspec'
require 'plivo/xml/element'
include Plivo::XML

resp = Plivo::XML::Response.new
get_input = resp.addGetInput(action:'https://<yourdomain>.com/result', digitEndTimeout: '5',
              executionTimeout:'10',
              finishOnKey:'#',
              hints:'good, bad',
              inputType:'speech',
              interimSpeechResultsCallback:'https://<yourdomain>.com/interim_result',
              interimSpeechResultsCallbackMethod:'POST',
              language:'en-US',
              log:'true',
              method:'POST',
              profanityFilter:'true',
              redirect:'false',
              speechEndTimeout:'2',
              speechModel:'default')
get_input.addSpeak('Tell us about your experience.', voice: 'Polly.Salli' language: 'en-US')
xml = Plivo::XML::PlivoXML.new(resp)
puts xml.to_xml

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
var plivo = require('plivo');
var response = new plivo.Response();
const get_input = response.addGetInput(
    {
        'action': 'https://<yourdomain>.com/result',
        "method": 'POST',
        'inputType': 'speech',
        'executionTimeout': '10',
        'digitEndTimeout': '5',
        'speechEndTimeout': '2',
        'finishOnKey': '#',
        'speechModel': 'default',
        'hints': 'good, bad',
        'language': 'en-US',
        'interimSpeechResultsCallback': 'https://<yourdomain>.com/interim_result',
        'interimSpeechResultsCallbackMethod': 'POST',
        'log': 'true',
        'redirect': 'false',
        'profanityFilter': 'true'
    });
get_input.addSpeak('Tell us about your experience');

console.log(response.toXML());

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
<?php
require 'vendor/autoload.php';
use Plivo\XML\Response;
$resp = new Response();
$get_input = $resp->addGetInput(
            [
                'action' => "https://<yourdomain>.com/result",
                'method' => "POST",
                'digitEndTimeout' => "5",
                'executionTimeout' => "10",
                'finishOnKey' => "#",
                'hints' => "good, bad",
                'inputType' => "speech",
                'interimSpeechResultsCallback' => "https://<yourdomain>.com/interim_result",
                'interimSpeechResultsCallbackMethod' => "POST",
                'language' => "en-US",
                'log' => "true",
                'profanityFilter' => "true",
                'redirect' => "false",
                'speechEndTimeout' => "2",
                'speechModel' => 'default'
            ]);
$get_input->addSpeak("Tell us about your experience.", ['language'=>"en-US", 'loop'=>"2", 'voice'=>"Polly.Salli"]);
echo($resp->toXML(true));

Was this code helpful

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
import com.plivo.api.xml.Response;
import com.plivo.api.xml.GetInput;
import com.plivo.api.xml.Speak;
import com.plivo.api.exceptions.PlivoXmlException;


class GetInputExample {
  public static void main(String [] args) throws Exception {
    Response res = new Response()
        .children (
            new GetInput()
              .action("https://<yourdomain>.com/result")
              .method("POST")
              .inputType("speech")
              .executionTimeout(10)
              .digitEndTimeout(5)
              .speechEndTimeout(2)
              .finishOnKey("#")
              .speechModel("default")
              .hints("good, bad")
              .language("en-US")
              .interimSpeechResultsCallback("https://<yourdomain>.com/interim_result")
              .interimSpeechResultsCallbackMethod("POST")
              .redirect(false)
              .log(true)
              .profanityFilter(true)
              .children(
                new Speak("Tell us about your experience")
                )
          );
    System.out.println(response.toXmlString());
  }
}

Was this code helpful

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
using System;
using System.Collections.Generic;
using Plivo.XML;

namespace Plivo
{
    public class Program
    {
        public void GetInputXml()
        {
            var resp = new Response();
            Plivo.XML.GetInput get_input = new
                Plivo.XML.GetInput("",
                    new Dictionary<string, string>()
                    {
                        {"action", "https://<yourdomain>.com/result"},
                        {"method", "POST"},
                        {"digitEndTimeout", "5"},
                        {"executionTimeout", "10"},
                        {"finishOnKey", "#"},
                        {"hints", "good, bad"},
                        {"inputType", "speech"},
                        {"interimSpeechResultsCallback", "https://<yourdomain>.com/interim_result"},
                        {"interimSpeechResultsCallbackMethod", "POST"},
                        {"language", "en-US"},
                        {"log", "true"},
                        {"profanityFilter", "true"},
                        {"redirect", "false"},
                        {"speechEndTimeout", "2"},
                        {"speechModel", "default"},
                    });
            resp.Add(get_input);
            get_input.AddSpeak("Tell us about your experience.",
                new Dictionary<string, string>() { });
            var output = resp.ToString();
            Console.WriteLine(output);
        }
    }
}

Was this code helpful

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
package main

import (
	"github.com/plivo/plivo-go/v7/xml"
)

func main() {
	println(xml.ResponseElement{
		Contents: []interface{}{
			new(xml.GetInputElement).
				SetAction("https://<yourdomain>.com/result").
				SetMethod("POST").
				SetInputType("speech").
				SetExecutionTimeout(10).
				SetDigitEndTimeout(5).
				SetSpeechEndTimeout(2).
				SetFinishOnKey("#").
				SetSpeechModel("default").
				SetLanguage("en-us").
				SetHints("good, bad").
				SetInterimSpeechResultsCallback("https://<yourdomain>.com/interim_result").
				SetInterimSpeechResultsCallbackMethod("POST").
				SetRedirect(true).
				SetLog(true).
				SetProfanityFilter(true).
				SetContents([]interface{}{new(xml.SpeakElement).
					AddSpeak("Tell us about your experience").
					SetVoice("WOMAN").
					SetLanguage("en-US").
					SetLoop(1)}),
		},
	}.String())
}

Was this code helpful

Detecting speech inputs

GetInput’s automatic speech recognition (ASR) feature is ideal for accepting both unstructured and structured speech input from users. Structured inputs, in the form of keywords and commands, are suited for use cases that have a finite set of distinct operations for users to choose from, such as interactive voice response (IVR). Adding speech detection to DTMF-driven IVR menus can improve conversions by offering users an easier alternative to navigate through menus, as in this first example.

Example

<Response>
    <GetInput inputType="dtmf speech" action="<action url>">
        <Speak>Press 1 or say New Appointment to schedule an appointment. Press 2 or say Cancel Appointment to cancel an existing appointment.</Speak>
    </GetInput>
</Response>

Real-time transcription of fuzzy inputs such as complete sentences, on the other hand, helps to build conversational AI-driven experiences.

Example

<Response>
    <GetInput inputType="speech" action="<action url>">
        <Speak>Welcome to Mary’s Hair Salon. How can I help you today?</Speak>
    </GetInput>
</Response>

An easy way to build AI conversational interfaces is by passing transcribed speech received through the GetInput XML element to AI chatbot platforms such as Google Dialogflow for NLP-based intent extraction. Also read about how the Plivo Speak XML element’s Speech Synthesis Markup Language (SSML) engine can be used to make your bot’s responses sound natural.

Supported languages

Name Language Code
English (Australia) en-AU
English (Canada) en-CA
English (United Kingdom) en-GB
English (Ireland) en-IE
English (India) en-IN
English (Philippines) en-PH
English (Singapore) en-SG
English (United States) en-US
English (South Africa) en-ZA
German (Germany) de-DE
Spanish (Spain) es-ES
Spanish (Mexico) es-MX
Spanish (United States) es-US
French (Canada) fr-CA
French (France) fr-FR
Italian (Italy) it-IT
Japanese (Japan) ja-JP
Korean (South Korea) ko-KR
Dutch (Netherlands) nl-NL
Portuguese (Brazil) pt-BR
Portuguese (Portugal) pt-PT
Russian (Russia) ru-RU
Chinese, Mandarin (Simplified, China) zh (cmn-hans-cn)
Chinese, Mandarin (Simplified, Hong Kong) zh-HK
Chinese, Mandarin (Simplified, Taiwan) zh-TW (cmn-hans-tw)
Chinese, Cantonese (Traditional, Hong Kong) yue-Hant-HK
Afrikaans (South Africa) af-ZA

Pricing for speech recognition

Speech recognition is charged based on the duration of speech analyzed in a GetInput execution.

Charges are computed based on 15-second pulses, so if speech was recognized for 35 seconds, the account would be billed for 45 seconds (15 * 3) of speech.

GetInput speech recognition charges are USD 0.02 per 15 seconds of execution.

Note that Plvio charges only for speech input detection and not DTMF input detection. If you’re using GetInput with inputType set to dtmf, you won’t be charged.

The Hangup element

You can use the Hangup element to end a call if you don’t want to answer an incoming call on your Plivo number. The application attached to the Plivo number must return the Hangup XML element along with a reason attribute to end the call.

Attributes

The Hangup element supports these attributes. You can modify the behavior of each attribute using the allowed values.

reason string

Specifies the reason for the hangup.

Allowed values: rejected, busy

schedule integer

Used to schedule a call hangup. Should be followed by an element such as Speak; if not, the call will be hung up immediately.

Allowed values: integer > 0 (in seconds)

Note:
  • When the Hangup XML element is the first element in an Answer XML element, the call is hung up with reason rejected by default if the reason attribute is not specified.
  • When Hangup XML is not the first element or if the call is already answered, the call is hung up with reason Normal Hangup if the reason attribute is not specified.

Hang up a call after a minute

This example shows how to schedule a hangup for a call after a minute while playing a message on the call.

Response

<Response>
    <Hangup schedule="60" reason="rejected" />
    <Speak loop="0">This call will be hung up after a minute</Speak>
</Response>

The Play element

You can use the Play element to play an audio file from a remote URL to a caller. Plivo supports MP3 and WAV audio file formats.

Attributes

loop integer

The number of times to play the audio file repeatedly. If you set the value to 0, the file will play indefinitely.

Allowed values: integer >= 0
Defaults to 1.

Play music

This example plays the audio file Trumpet.mp3 to the caller.

Example Request

1
2
3
4
5
from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(plivoxml.PlayElement('https://s3.amazonaws.com/Trumpet.mp3'))
print(response.to_string())

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
require 'rubygems'
require 'plivo'

include Plivo::XML
include Plivo::Exceptions

begin
  response = Response.new

  play_body = 'https://s3.amazonaws.com/plivocloud/Trumpet.mp3'
  response.addPlay(play_body)

  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
var plivo = require('plivo');

var response = plivo.Response();

var play_body = "https://s3.amazonaws.com/plivocloud/Trumpet.mp3";
response.addPlay(play_body);

console.log(response.toXML());

/*
Sample Output
<Response>
    <Play>
        https://s3.amazonaws.com/plivocloud/Trumpet.mp3 
    </Play>
</Response>
*/

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<?php
    require '../vendor/autoload.php';
    use Plivo\XML\Response;

    $response = new Response();

    $play_body = "https://s3.amazonaws.com/plivocloud/Trumpet.mp3";
    $response->addPlay($play_body);

    Header('Content-type: text/xml');
    echo($response->toXML());

    /*
    Sample Output

    <Response>
        <Play>
            https://s3.amazonaws.com/plivocloud/Trumpet.mp3
        </Play>
    </Response>
    */
?>

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// Example for xml - play music
package com.plivo.api.xml.samples.xml;

import com.plivo.api.exceptions.PlivoXmlException;
import com.plivo.api.xml.Play;
import com.plivo.api.xml.Response;


class PlayMusic {
    public static void main(String[] args) throws PlivoXmlException {
        Response response = new Response()
                .children(


                        new Play("https://s3.amazonaws.com/Trumpet.mp3")

                );
        System.out.println(response.toXmlString());
    }
}

Was this code helpful

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
using System;
using System.Collections.Generic;
using Plivo.XML;

namespace Plivo
{
	class MainClass
	{
		public static void Main(string[] args)
		{
			Plivo.XML.Response resp = new Plivo.XML.Response();
			resp.AddPlay("https://amazonaws.com/Trumpet.mp3",
					  new Dictionary<string, string>() { });

			var output = resp.ToString();
			Console.WriteLine(output);

		}
	}
}



//<Response>
//  <Play>https://amazonaws.com/Trumpet.mp3</Play>
//</Response>

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// Example for xml - play music
package main

import "github.com/plivo/plivo-go/v7/xml"

func main() {
	response := xml.ResponseElement{
		Contents: []interface{}{

			new(xml.PlayElement).
				SetContents("https://s3.amazonaws.com/Trumpet.mp3"),
		},
	}
	print(response.String())
}

Was this code helpful

Response

<Response>
    <Play>https://s3.amazonaws.com/plivocloud/Trumpet.mp3</Play>
</Response>

The PreAnswer element

The PreAnswer element answers an incoming call in early media mode. This is useful when you want to play custom caller tunes or to speak text while the call is still in an unanswered state.

Note: Not all phone numbers support this feature. Browser SDK doesn’t support early media (PreAnswer) as it’s not a part of the WebRTC specifications.

Attributes

The PreAnswer element does not have any attributes.

Nesting rules

You can nest Speak, Play, and Wait elements within the PreAnswer element.

Notify callers

This example notifies the caller that the cost of the current call is $2 a minute.

Example Request

1
2
3
4
5
6
7
from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(plivoxml.PreAnswerElement().add(
    plivoxml.SpeakElement('This call will cost you $2 a minute.')))
response.add(plivoxml.SpeakElement('Hey, thanks for dropping by.'))
print(response.to_string())

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
require 'rubygems'
require 'plivo'

include Plivo::XML
include Plivo::Exceptions

begin
  response = Response.new

  pre_answer = response.addPreAnswer()

  pre_answer_speak_body = 'This call will cost you $2 a minute.'
  pre_answer.addSpeak(pre_answer_speak_body)

  speak_body = 'Hey, thanks for dropping by.'
  response.addSpeak(speak_body)

  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
var plivo = require('plivo');

var response = plivo.Response();

var pre_answer = response.addPreAnswer();

var pre_answer_speak_body = "This call will cost you $2 a minute.";
pre_answer.addSpeak(pre_answer_speak_body);

var speak_body = "Hey, thanks for dropping by.";
response.addSpeak(speak_body);

console.log(response.toXML());

/*
Sample Output
<Response>
    <PreAnswer>
        <Speak>This call will cost you $2 a minute.</Speak>
    </PreAnswer>
    <Speak>Hey, thanks for dropping by.</Speak>
</Response>
*/

Was this code helpful

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
<?php
    require '../vendor/autoload.php';
    use Plivo\XML\Response;

    $response = new Response();

    $pre_answser = $response->addPreAnswer();

    $pre_answer_speak_body = "This call will cost you $2 a minute.";
    $pre_answser->addSpeak($pre_answer_speak_body);

    $speak_body = "Hey, thanks for dropping by.";
    $response->addSpeak($speak_body);

    Header('Content-type: text/xml');
    echo($response->toXML());

    /*
    Sample Output

    <Response>
        <PreAnswer>
            <Speak>
                This call will cost you $2 a minute.
            </Speak>
        </PreAnswer>
        <Speak>Hey, thanks for dropping by.</Speak>
    </Response>
    */
?>

Was this code helpful

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
// Example for xml - notify callers
package com.plivo.api.xml.samples.xml;

import com.plivo.api.exceptions.PlivoXmlException;
import com.plivo.api.xml.PreAnswer;
import com.plivo.api.xml.Response;
import com.plivo.api.xml.Speak;


class NotifyCallers {
    public static void main(String[] args) throws PlivoXmlException {
        Response response = new Response()
                .children(


                        new PreAnswer()
                                .children(
                                        new Speak("This call will cost you $2 a minute.")
                                ),


                        new Speak("Hey, thanks for dropping by.")
                );
        System.out.println(response.toXmlString());
    }
}

Was this code helpful

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
using System;
using System.Collections.Generic;
using Plivo.XML;

namespace Plivo
{
	class MainClass
	{
		public static void Main(string[] args)
		{
			Plivo.XML.Response resp = new Plivo.XML.Response();
			Plivo.XML.PreAnswer answer = new
				Plivo.XML.PreAnswer();
			answer.AddSpeak("This call will cost $2 a min.",
				new Dictionary<string, string>() { });
			resp.Add(answer);
			resp.AddSpeak("Thanks for dropping by.",
				new Dictionary<string, string>() { });

			var output = resp.ToString();
			Console.WriteLine(output);

		}
	}
}



//<Response>
//  <PreAnswer>
//    <Speak>This call will cost $2 a min.</Speak>
//  </PreAnswer>
//  <Speak>Thanks for dropping by.</Speak>
//</Response>

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// Example for xml - pre answer
package main

import "github.com/plivo/plivo-go/v7/xml"

func main() {
	response := xml.ResponseElement{
		Contents: []interface{}{

			new(xml.PreAnswerElement).
				SetContents([]interface{}{

					new(xml.SpeakElement).
						AddSpeak("This call will cost you $2 a minute."),
				}),

			new(xml.SpeakElement).
				AddSpeak("Hey, thanks for dropping by."),
		},
	}
	print(response.String())
}

Was this code helpful

Response

<Response>
  <PreAnswer>
    <Speak>This call will cost you $2 a minute.</Speak>
  </PreAnswer>
  <Speak>Hey, thanks for dropping by.</Speak>
</Response>

The Record element

You can use the Record element to record a call and return the URL of the recording file.

Attributes

action stringCallback-retry configurable

Submit the result of the record to this URL. See the table “Parameters sent to the action URL” below for more information.

Allowed values: a fully qualified URL

method string

Method used to send HTTP request to the action URL.

Allowed values: GET, POST
Defaults to POST.

fileFormat string

The format of the recording.

Allowed values: mp3, wav
Defaults to mp3.

redirect boolean

If false, don’t redirect to the action URL, only request the URL and continue to the next element.

Allowed values: true, false
Defaults to true.

timeout integer

Seconds of silence before considering the recording complete. Only used when recordSession and startOnDialAnswer are false.

Allowed values: positive integer
Defaults to 15.

maxLength integer

Maximum number of seconds to record.

Allowed values: integer greater than 1
Defaults to 60.

playBeep boolean

Plays a beep before recording. Only used when recordSession and startOnDialAnswer are false.

Allowed values: true, false
Defaults to true.

finishOnKey string

Stop recording when this key is pressed. Only used when recordSession and startOnDialAnswer are false.

Allowed values: any digit, #, *
Defaults to #

recordSession boolean

Record current call session in background. No beep will be played.

Allowed values: true, false
Defaults to false.

startOnDialAnswer boolean

Record call when called party answers in a Dial. No beep will be played.

Allowed values: true, false
Defaults to false.

transcriptionType string

auto: Transcription is automated; the turnaround time is under 5 minutes which linearly increases with call duration.

Transcriptions charge details are available on our pricing page.

Note:

The transcription service is available only in English, and limited to calls with a duration greater than 500 milliseconds and less than four hours with a recording file size smaller than 2GB.

transcriptionUrl stringCallback-retry configurable

The URL where the transcription is to be sent from Plivo. See the table “Parameters sent to the transcription URL” below for more information.

Allowed values: a fully qualified URL
No default value.

Note:

The transcription information will be sent to this URL via an HTTP POST callback.

callbackUrl stringCallback-retry configurable

If set, this URL is fired in the background when the recorded file is ready to be used. See the table “Parameters sent to the callback URL” below for more information.

Allowed values: a fully qualified URL

callbackMethod string

The HTTP method used to notify the callbackUrl.

Allowed values: GET, POST
Defaults to POST.

Notes:

  • If recordSession is set to true, recording will start in the background and will continue until the call is hung up or maxLength is reached.

  • If startOnDialAnswer is set to true, Plivo will record the complete conversation between both parties during the next Dial and will end when the Dial is done or maxLength is reached. This may not be legal in some countries.

  • timeout, finishOnKey, and playBeep attributes have no effect when recordSession or startOnDialAnswer is set to true.

  • The default recording time is 60 seconds if maxLength is not set.

 

Parameters sent to the action URL

RecordUrl

Complete path to the recorded file URL.

Digits

If set, the digits pressed to stop the recording.

RecordingDuration

Duration of recording in seconds.

RecordingDurationMs

Duration of recording in milliseconds.

RecordingStartMs

When the recording started (epoch time UTC) in milliseconds.

RecordingEndMs

When the recording ended (epoch time UTC) in milliseconds.

RecordingID

Recording ID of the file.

Notes:

  • If startOnDialAnswer or recordSession is set to true, an initial request is made to the action URL as soon as the recording has started. Because of this, RecordingDuration, RecordingDurationMs, RecordingStartMs, and RecordingEndMs will all be -1. No other request will be made to the action URL once the recording is completed.

  • If startOnDialAnswer and recordSession are set to false, a request is made to the action URL only when the recording is completed. This request will contain the actual values of the recording.

Parameters sent to the callback URL

RecordUrl

Complete path to the recorded file URL.

RecordingDuration

Duration of recording in seconds.

RecordingDurationMs

Duration of recording in milliseconds.

RecordingStartMs

When the recording started (epoch time UTC) in milliseconds.

RecordingEndMs

When the recording ended (epoch time UTC) in milliseconds.

RecordingID

Recording ID of the file.

Parameters sent to the transcription URL

transcription_charge

The credit deducted for the transcription.

transcription

Transcribed text of the recording.

duration

Duration in seconds of the recording.

call_uuid

Call UUID of the call that was transcribed.

transcription_rate

Rate of the transcription per minute.

recording_id

Recording ID of the recording that was transcribed.

error Can be Recording duration too long for transcription or Recording file size too large for transcription. Empty if transcription is successful.
Note: .mp3 files are smaller in size than .wav files. Consider changing the recording file format to mp3 if you see this error.

Record a voicemail

This example shows a simple voicemail recording. The caller is asked to leave a message after the beep. The Record element beeps and begins recording up to 30 seconds of audio.

If the caller remains silent, the Record element exits after a default timeout of 15 seconds, falling through to the next element — in this case, the Speak element.

After the voicemail is recorded, Plivo POSTs the recorded URL to the action URL.

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
13
from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(
    plivoxml.SpeakElement(
        "Please leave a message. Press the star key or hang up when you're done."))
response.add(
    plivoxml.RecordElement(
        action='https://<yourdomain>.com/get_recording/',
        max_length=30,
        finish_on_key='*'))
response.add(plivoxml.SpeakElement('Recording not received.'))
print(response.to_string())

Was this code helpful

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 'plivo'

include Plivo::XML
include Plivo::Exceptions

begin
  response = Response.new

  first_speak_body = "Please leave a message. Press the star key or hang up when you're done."
  response.addSpeak(first_speak_body)

  params = {
      action: 'https://<yourdomain>.com/get_recording/',
      maxLength: '30',
      finishOnKey: '*'
  }
  response.addRecord(params)

  second_speak_body = 'Recording not received.'
  response.addSpeak(second_speak_body)

  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end

Was this code helpful

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

var response = plivo.Response();

var first_speak_body ="Please leave a message. Press the star key or hang up when you're done.";
response.addSpeak(first_speak_body);

var params = {
    'action': "https://<yourdomain>.com/get_recording/",
    'maxLength': "30",
    'finishOnKey': "*"
};
response.addRecord(params);

var second_speak_body = "Recording not received.";
response.addSpeak(second_speak_body);

console.log(response.toXML());

/*
Sample Output
<Response>
    <Speak>Please leave a message. Press the star key or hang up when you're done.</Speak>
    <Record action="https://<yourdomain>.com/get_recording/" maxLength="30" finishOnKey="*"/>
    <Speak>Recording not received.</Speak>
</Response>
*/

Was this code helpful

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
<?php
    require '../vendor/autoload.php';
    use Plivo\XML\Response;

    $response = new Response();

    $first_speak_body = "Please leave a message. Press the star key or hang up when you're done.";

    $response->addSpeak($first_speak_body);

    $params = array(
        'action' => "https://<yourdomain>.com/get_recording/",
        'maxLength' => "30",
        'finishOnKey' => "*"
    );

    $response->addRecord($params);

    $second_speak_body = "Recording not received.";
    $response->addSpeak($second_speak_body);

    Header('Content-type: text/xml');
    echo($response->toXML());

    /*
    Sample Output

    <Response>
        <Speak>Please leave a message. Press the star key or hang up when you're done.</Speak>
        <Record action="https://<yourdomain>.com/get_recording/" maxLength="30" finishOnKey="*"/>
        <Speak>Recording not received.</Speak>
    </Response>
    */
?>

Was this code helpful

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
// Example for record - record a voicemail
package com.plivo.api.xml.samples.record;

import com.plivo.api.exceptions.PlivoXmlException;
import com.plivo.api.xml.Record;
import com.plivo.api.xml.Response;
import com.plivo.api.xml.Speak;


class RecordAVoicemail {
    public static void main(String[] args) throws PlivoXmlException {
        Response response = new Response()
                .children(


                        new Speak("Please leave a message. Press the star key or hang up when you're done."),


                        new Record("https://<yourdomain>.com/get_recording/")
                                .finishOnKey("*")
                                .maxLength(20),


                        new Speak("Recording not received.")

                );
        System.out.println(response.toXmlString());
    }
}

Was this code helpful

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
using System;
using System.Collections.Generic;
using Plivo.XML;

namespace Plivo
{
	class MainClass
	{
		public static void Main(string[] args)
		{
			Plivo.XML.Response resp = new Plivo.XML.Response();
			resp.AddSpeak("Please leave a message. Press the star key or hang up when you're done.",
				new Dictionary<string, string>() { });
			resp.AddRecord(new Dictionary<string, string>() {
				{"action", "https://<yourdomain>.com/get_recording/"},
				{"maxLength", "30"},
				{"finishOnKey", "*"}
			});
			resp.AddSpeak("Recording not received.",
				new Dictionary<string, string>() { });

			var output = resp.ToString();
			Console.WriteLine(output);

		}
	}
}



//<Response>
//  <Speak>Please leave a message. Press the star key or hang up when you're done.</Speak>
//  <Record action = "https://<yourdomain>.com/get_recording/" 
//    maxLength="30" finishOnKey="*" />
//  <Speak>Recording not received.</Speak>
//</Response>

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// Example for record - record voicemail
package main

import "github.com/plivo/plivo-go/v7/xml"

func main() {
	response := xml.ResponseElement{
		Contents: []interface{}{

			new(xml.SpeakElement).
				AddSpeak("Please leave a message. Press the star key or hang up when you're done"),

			new(xml.RecordElement).
				SetAction("https://<yourdomain>.com/get_recording/").
				SetFinishOnKey("*").
				SetMaxLength(20),

			new(xml.SpeakElement).
				AddSpeak("Recording not received."),
		},
	}
	print(response.String())
}

Was this code helpful

Response

<Response>
  <Speak>Please leave a message after the beep. Press the star key when done.</Speak>
  <Record action="https://<yourdomain>.com/get_recording/" finishOnKey="*" maxLength="30"></Record>
  <Speak>Recording not received.</Speak>
</Response>

Record a complete call session

To record an entire call leg from start to end, set the recordSession attribute of the Record XML element to true in the Answer XML element. recordSession="true" silently initiates a recording of the call in the background.

To record just the conversation between the A leg and the connected B leg (initiated using the Dial XML element), add a Record XML element with startOnDialAnswer="true" just before the Dial XML.

In either scenario, the call is recorded until it’s hung up or the maxLength recording duration is reached. Set maxLength to a high value based on the maximum duration you expect your calls to go on for.

  • If the maxLength value is not set, it defaults to 60 seconds.

  • If maxLength is < 1 or an invalid integer, it will trigger the error “Record ‘maxLength’ must be a positive integer” and disconnect the call.

  • If maxLength is > 1 and a valid integer, it will be set to the value.

Example Request

1
2
3
4
5
6
7
8
9
10
from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(
    plivoxml.RecordElement(
        action='https://<yourdomain>.com/get_recording/',
        start_on_dial_answer=True,
        redirect=False))
response.add(plivoxml.DialElement().add(plivoxml.NumberElement('12025551111')))
print(response.to_string())

Was this code helpful

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

include Plivo::XML
include Plivo::Exceptions

begin
  response = Response.new

  params = {
      action: 'https://<yourdomain>.com/get_recording/',
      startOnDialAnswer: 'true',
      redirect: 'false'
  }

  response.addRecord(params)

  dial = response.addDial()
  number = '12025551111'
  dial.addNumber(number)

  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end

Was this code helpful

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

var response = plivo.Response();

var params = {
    'action': "https://<yourdomain>.com/get_recording/",
    'startOnDialAnswer': "true",
    'redirect': "false"
};
response.addRecord(params);

var dial = response.addDial();
var number = "12025551111";
dial.addNumber(number);

console.log(response.toXML());

/*
Sample Output
<Response>
    <Record action="https://<yourdomain>.com/get_recording/" startOnDialAnswer="true" redirect="false"/>
    <Dial>
        <Number>12025551111</Number>
    </Dial>
</Response>
*/

Was this code helpful

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
<?php
    require '../vendor/autoload.php';
    use Plivo\XML\Response;

    $response = new Response();

    $params = array(
        'action' => "https://<yourdomain>.com/get_recording/",
        'startOnDialAnswer' => "true",
        'redirect' => "false"
    );

    $response->addRecord($params);

    $dial = $response->addDial();
    $number = "12025551111";
    $dial->addNumber($number);

    Header('Content-type: text/xml');
    echo($response->toXML());

    /*
    Sample Output

    <Response>
        <Record action="https://<yourdomain>.com/get_recording/" startOnDialAnswer="true" redirect="false"/>
        <Dial>
            <Number>12025551111</Number>
        </Dial>
    </Response>
    */
?>

Was this code helpful

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
// Example for record - record a complete call session
package com.plivo.api.xml.samples.record;

import com.plivo.api.exceptions.PlivoXmlException;
import com.plivo.api.xml.Dial;
import com.plivo.api.xml.Number;
import com.plivo.api.xml.Record;
import com.plivo.api.xml.Response;


class RecordACompleteCallSession {
    public static void main(String[] args) throws PlivoXmlException {
        Response response = new Response()
                .children(


                        new Record("https://<yourdomain>.com/get_recording/")
                                .redirect(false)
                                .startOnDialAnswer(true),


                        new Dial()
                                .children(
                                        new Number("12025551111")
                                )
                );
        System.out.println(response.toXmlString());
    }
}

Was this code helpful

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
using System;
using System.Collections.Generic;
using Plivo.XML;

namespace Plivo
{
	class MainClass
	{
		public static void Main(string[] args)
		{
			Plivo.XML.Response resp = new Plivo.XML.Response();
			resp.AddRecord(new Dictionary<string, string>() {
				{"action", "https://<yourdomain>.com/get_recording/"},
				{"startOnDialAnswer", "true"},
				{"redirect", "false"}
			});

			Plivo.XML.Dial dial = new Plivo.XML.Dial(new
				Dictionary<string, string>()
			{ });

			dial.AddNumber("12025551111",
				new Dictionary<string, string>() { });
			resp.Add(dial);

			var output = resp.ToString();
			Console.WriteLine(output);

		}
	}
}



//<Response>
//  <Record action = "https://<yourdomain>.com/get_recording/" 
//    startOnDialAnswer="true" redirect="false" />
//  <Dial>
//    <Number>12025551111</Number>
//  </Dial>
//</Response>

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// Example for record - record session
package main

import "github.com/plivo/plivo-go/v7/xml"

func main() {
	response := xml.ResponseElement{
		Contents: []interface{}{

			new(xml.RecordElement).
				SetAction("https://<yourdomain>.com/get_recording/").
				SetRedirect(false).
				SetStartOnDialAnswer(true),

			new(xml.DialElement).
				SetContents([]interface{}{
					new(xml.NumberElement).
						SetContents("12025551111"),
				}),
		},
	}
	print(response.String())
}

Was this code helpful

Response

<Response>
  <Record action="https://<yourdomain>.com/get_recording/" startOnDialAnswer="true" redirect="false" maxLength="3600" />
  <Dial>
    <Number>12025551111</Number>
  </Dial>
</Response>

The Redirect element

You can use the Redirect element to transfer control of a call to a different URL, which then starts processing the new XML response. Any elements after <Redirect> are not processed.

Attributes

method stringCallback-retry configurable

Specifies the HTTP request mode to obtain the Redirect URL.

Allowed values: GET, POST
Defaults to POST.

Parameters sent in the redirect request

From string

The phone number of the party that initiated the call, along with the country code. If the call is inbound, then this is the caller’s caller ID. If the call is outbound — initiated via a request to the API — then this is the phone number you specify as the caller ID.

To string

The phone number of the called party, with the country code. If the call is inbound, then this is your incoming phone number. If the call is outbound, then this is the phone number you provided to call.

Event string

The string Redirect.

CallUUID string

A unique identifier for the call.

CallerName string

For a SIP call, this is the name of the caller. For a PSTN call, this is the caller ID.

Direction string

Indicates the direction of the call. In most cases this will be inbound, and the call would be in a ringing state. If you’re using the Call API, the direction will be outbound, and the call will be in an answered state.

CallStatus string

Indicates the status of the call. The value may be set to ringing, in-progress, or completed. If the call is hung up, CallStatus is set to completed for inbound calls and to completed, busy, failed, timeout, or no-answer for outbound calls.

Transfer a call

In this example, we have a Redirect element after a Speak element. When the Speak element finishes, the Redirect element executes, and Plivo processes the call based on the XML returned from the Redirect element.

Example Request

1
2
3
4
5
6
7
from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(
    plivoxml.SpeakElement('Your call is being transferred.'))
response.add(plivoxml.RedirectElement('https://<yourdomain>.com/redirect/'))
print(response.to_string())

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
require 'rubygems'
require 'plivo'

include Plivo::XML
include Plivo::Exceptions

begin
  response = Response.new

  speak_body = 'Your call is being transferred.'
  response.addSpeak(speak_body)

  redirect_url = 'https://<yourdomain>.com/redirect/'
  response.addRedirect(redirect_url);

  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
var plivo = require('plivo');

var response = plivo.Response();

var speak_body = "Your call is being transferred.";
response.addSpeak(speak_body);

var redirect_url = "https://<yourdomain>.com/redirect/";
response.addRedirect(redirect_url);

console.log(response.toXML());

/*
Sample Output
<Response>
    <Speak>Your call is being transferred.</Speak>
    <Redirect>https://<yourdomain>.com/redirect/</Redirect>
</Response>
*/

Was this code helpful

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
<?php
    require '../vendor/autoload.php';
    use Plivo\XML\Response;

    $response = new Response();

    $speak_body = "Your call is being transferred.";

    $response->addSpeak($speak_body);

    $redirect_url = "https://<yourdomain>.com/redirect/";
    $response->addRedirect($redirect_url);

    Header('Content-type: text/xml');
    echo($response->toXML());

    /*
    Sample Output

    <Response>
        <Speak>Your call is being transferred.</Speak>
        <Redirect>https://<yourdomain>.com/redirect/</Redirect>
    </Response>
    */
?>

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// Example for xml - transfer a call
package com.plivo.api.xml.samples.xml;

import com.plivo.api.exceptions.PlivoXmlException;
import com.plivo.api.xml.Redirect;
import com.plivo.api.xml.Response;
import com.plivo.api.xml.Speak;


class TransferACall {
    public static void main(String[] args) throws PlivoXmlException {
        Response response = new Response()
                .children(


                        new Speak("Your call is being transferred."),


                        new Redirect("https://<yourdomain>.com/redirect/")

                );
        System.out.println(response.toXmlString());
    }
}

Was this code helpful

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
using System;
using System.Collections.Generic;
using Plivo.XML;

namespace Plivo
{
	class MainClass
	{
		public static void Main(string[] args)
		{
			Plivo.XML.Response resp = new Plivo.XML.Response();
			resp.AddSpeak("Your call is being transferred.", 
             new Dictionary<string, string>() { });
			resp.AddRedirect("https://<yourdomain>.com/redirect/", 
             new Dictionary<string, string>() { });
			var output = resp.ToString();
			Console.WriteLine(output);

		}
	}
}



//<Response>
//  <Speak>You call is being transferred.</Speak>
//  <Redirect>https://<yourdomain>.com/redirect/</Redirect>
//</Response>

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// Example for xml - transfer call
package main

import "github.com/plivo/plivo-go/v7/xml"

func main() {
	response := xml.ResponseElement{
		Contents: []interface{}{

			new(xml.SpeakElement).
				AddSpeak("Your call is being transferred."),

			new(xml.RedirectElement).
				SetContents("https://<yourdomain>.com/redirect/"),
		},
	}
	print(response.String())
}

Was this code helpful

Response

<Response>
    <Speak>Please wait while you call is being transferred.</Speak>
    <Redirect>https://<yourdomain>.com/redirect/</Redirect>
</Response>

 

To connect the incoming call to a different number, you should return the section example’s XML from the Redirect URL.

<Response>
    <Dial dialMusic="real">
        <Number>12025551111</Number>
    </Dial>
</Response>

The Speak element

You can use the Speak element to read out text as speech to the caller. It’s useful for communicating dynamic text that cannot be prerecorded.

Attributes

voice string

The tone to be used for reading out the text.

Allowed values: WOMAN, MAN
Defaults to WOMAN.

language string

Language used to read out the text.

Allowed values: See the table “Supported voices and languages” below.

Defaults to en-US.

loop integer

Specifies number of times to speak out the text. If value set to 0, speaks indefinitely.

Allowed values: integer >= 0 (0 indicates a continuous loop)
Defaults to 1.

Supported voices and languages

Danish value: da-DK
  • Woman — yes
  • Man — no
Dutch value: nl-NL
  • Woman — yes
  • Man — yes
English — Australian value: en-AU
  • Woman — yes
  • Man — yes
English — British value: en-GB
  • Woman — yes
  • Man — yes
English — USA value: en-US
  • Woman — yes
  • Man — yes
French value: fr-FR
  • Woman — yes
  • Man — yes
French — Canadian value: fr-CA
  • Woman — yes
  • Man — no
German value: de-DE
  • Woman — yes
  • Man — yes
Italian value: it-IT
  • Woman — yes
  • Man — yes
Polish value: pl-PL
  • Woman — yes
  • Man — yes
Portuguese value: pt-PT
  • Woman — no
  • Man — yes
Portuguese — Brazilian value: pt-BR
  • Woman — yes
  • Man — yes
Russian value: ru-RU
  • Woman — yes
  • Man — no
Spanish value: es-ES
  • Woman — yes
  • Man — yes
Spanish — USA value: es-US
  • Woman — yes
  • Man — yes
Swedish value: sv-SE
  • Woman — yes
  • Man — no

Play a message

In this first example, when a call is directed to this example XML document, the caller will hear “Go Green, Go Plivo” spoken once.

Example Request

1
2
3
4
5
from plivo import plivoxml

response = (plivoxml.ResponseElement()
            .add(plivoxml.SpeakElement('Go Green, Go Plivo.')))
print(response.to_string())

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
require 'rubygems'
require 'plivo'

include Plivo::XML
include Plivo::Exceptions

begin
  response = Response.new

  speak_body = 'Go Green, Go Plivo.'
  response.addSpeak(speak_body)

  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
var plivo = require('plivo');

var response = plivo.Response();

var speak_body = "Go Green, Go Plivo.";
response.addSpeak(speak_body);

console.log(response.toXML());

/*
Sample Output
<Response>
    <Speak>Go Green, Go Plivo.</Speak>
</Response>
*/

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
<?php
    require '../vendor/autoload.php';
    use Plivo\XML\Response;

    $response = new Response();

    $speak_body = "Go Green, Go Plivo.";

    $response->addSpeak($speak_body);

    Header('Content-type: text/xml');
    echo($response->toXML());

    /*
    Sample Output

    <Response>
        <Speak>Go Green, Go Plivo.</Speak>
    </Response>
    */
?>

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// Example for speak - play a message
package com.plivo.api.xml.samples.speak;

import com.plivo.api.exceptions.PlivoXmlException;
import com.plivo.api.xml.Response;
import com.plivo.api.xml.Speak;


class PlayAMessage {
    public static void main(String[] args) throws PlivoXmlException {
        Response response = new Response()
                .children(
                        new Speak("Go Green, Go Plivo.")
                );
        System.out.println(response.toXmlString());
    }
}

Was this code helpful

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
using System;
using System.Collections.Generic;
using Plivo.XML;

namespace Plivo
{
	class MainClass
	{
		public static void Main(string[] args)
		{
			Plivo.XML.Response resp = new Plivo.XML.Response();
			resp.AddSpeak("Go green, go plivo.", 
             new Dictionary<string, string>() { });
			var output = resp.ToString();
			Console.WriteLine(output);

		}
	}
}



//<Response>
//  <Speak>Go green, go plivo.</Speak>
//</Response>

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// Example for speak - play message
package main

import "github.com/plivo/plivo-go/v7/xml"

func main() {
	response := xml.ResponseElement{
		Contents: []interface{}{
			new(xml.SpeakElement).
				AddSpeak("Go Green, Go Plivo."),
		},
	}
	print(response.String())
}

Was this code helpful

Response

<Response>
    <Speak>Go Green, Go Plivo.</Speak>
</Response>

Play in a loop

This second XML example tells Plivo to say “Wow” three times.

Example Request

1
2
3
4
5
from plivo import plivoxml

response = (plivoxml.ResponseElement()
            .add(plivoxml.SpeakElement('Wow.').set_loop(3)))
print(response.to_string())

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
require 'rubygems'
require 'plivo'

include Plivo::XML
include Plivo::Exceptions

begin
  response = Response.new

  speak_body = 'Wow'
  params = {
    loop: '3'
  }
  response.addSpeak(speak_body, params)

  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
var plivo = require('plivo');

var response = plivo.Response();

var speak_body = "Wow";
var params = {
        'loop': "3"
};
response.addSpeak(speak_body, params);

console.log(response.toXML());

/*
Sample Output
<Response>
    <Speak loop="3">Wow</Speak>
</Response>
*/

Was this code helpful

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
<?php
    require '../vendor/autoload.php';
    use Plivo\XML\Response;

    $response = new Response();

    $speak_body = "Wow";

    $params = array(
        'loop' => "3"
    );

    $response->addSpeak($speak_body, $params);

    Header('Content-type: text/xml');
    echo($response->toXML());

    /*
    Sample Output

    <Response>
        <Speak loop="3">Wow</Speak>
    </Response>
    */
?>

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// Example for speak - play in a loop
package com.plivo.api.xml.samples.speak;

import com.plivo.api.exceptions.PlivoXmlException;
import com.plivo.api.xml.Response;
import com.plivo.api.xml.Speak;


class PlayInALoop {
    public static void main(String[] args) throws PlivoXmlException {
        Response response = new Response()
                .children(


                        new Speak("Wow.")
                                .loop(3)

                );
        System.out.println(response.toXmlString());
    }
}

Was this code helpful

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
using System;
using System.Collections.Generic;
using Plivo.XML;

namespace Plivo
{
	class MainClass
	{
		public static void Main(string[] args)
		{
			Plivo.XML.Response resp = new Plivo.XML.Response();
			resp.AddSpeak("Go green, go plivo.", 
             new Dictionary<string, string>()
			{
				{"loop", "3"}
			});
			var output = resp.ToString();
			Console.WriteLine(output);

		}
	}
}



//<Response>
//  <Speak loop = "3" > Go green, go plivo.</Speak>
//</Response>

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// Example for speak - play in loop
package main

import "github.com/plivo/plivo-go/v7/xml"

func main() {
	response := xml.ResponseElement{
		Contents: []interface{}{

			new(xml.SpeakElement).
				SetLoop(3).
				AddSpeak("Wow."),
		},
	}
	print(response.String())
}

Was this code helpful

Response

<Response>
    <Speak loop="3">Wow</Speak>
</Response>

SSML

Speech Synthesis Markup Language (SSML) provides a standard way to mark up text for the generation of synthesized speech. It supports 27 languages and more than 40 voices, and allows developers to control pronunciation, pitch, and volume.

For more information on SSML, see Getting Started with SSML.

Speak elements with SSML can be nested inside GetDigits and GetInput XML element tags.

Example Request

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, request, url_for
from plivo import plivoxml

app = Flask(__name__)

@app.route("/ssml/", methods=["GET", "POST"])
def ssml():
    element = plivoxml.ResponseElement()
    response = (
        element.add(
            plivoxml.SpeakElement(content="The word", voice="Polly.Joey", language="en-US")
            .add_say_as("read", interpret_as="characters")
            .add_s("may be interpreted as either the present simple form")
            .add_w("read", role="amazon:VB")
            .add_s("or the past participle form")
            .add_w("read", role="amazon:VBD")
        )
        .to_string(False)
    )
    print(response)
    return Response(response, mimetype="text/xml")

if __name__ == "__main__":
    app.run(host="0.0.0.0", debug=True)

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
class PlivoController < ApplicationController
  def ssml
    response = Plivo::XML::Response.new
    speak_elem = response.addSpeak('The word', voice: 'Polly.Joey', language: 'en-US')
    speak_elem.addSayAs('read', 'interpret-as' => 'characters')
    speak_elem.addS('may be interpreted as either the present simple form')
    speak_elem.addW('read', 'role' => 'amazon:VB')
    speak_elem.addS('or the past participle form')
    speak_elem.addW('read', 'role' => 'amazon:VBD')
    xml = Plivo::XML::PlivoXML.new(response)
    puts xml.to_xml()
    render xml: xml.to_xml
  end
end

Was this code helpful

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
var plivo = require('plivo');
var express = require('express');
var app = express();
app.set('port', (process.env.PORT || 5000));
app.use(express.static(__dirname + '/public'));

app.all('/ssml/', function (request, response) {
    if (request.method == "GET") {
        var r = new plivo.Response();
        const speakElem = r.addSpeak('The word', {
            'voice': 'Polly.Joey',
            'language': 'en-US'
        });
        speakElem.addSayAs('read', {
            'interpret-as': 'characters'
        });
        speakElem.addS('may be interpreted as either the present simple form');
        speakElem.addW('read', {
            'role': 'amazon:VB'
        });
        speakElem.addS('or the past participle form');
        speakElem.addW('read', {
            'role': 'amazon:VBD'
        });
        console.log(r.toXML());
        response.set({
            'Content-Type': 'text/xml'
        });
        response.end(r.toXML());
    }
});

app.listen(app.get('port'), function () {
    console.log('Node app is running on port', app.get('port'));
});

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
<?php

namespace App\Http\Controllers;

require '../vendor/autoload.php';
use Plivo\RestClient;
use Plivo\XML\Response;
use Illuminate\Http\Request;

class ReceivecallController extends Controller
{
    public function ssml()
    {
        $response = new Response();
        $speak_elem = $response->addSpeak('The word', ['language'=>"en-US", 'voice'=>"Polly.Joey"]);
        $speak_elem->addSayAs('read', ['interpret-as'=>"characters"]);
        $speak_elem->addS('may be interpreted as either the present simple form');
        $speak_elem->addW('read', ['role'=>"amazon:VB"]);
        $speak_elem->addS('or the past participle form');
        $speak_elem->addW('read', ['role'=>"amazon:VBD"]);
        $xml_response = $response->toXML(); 
        return response($xml_response, 200)->header('Content-Type', 'application/xml');
    }
}

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
package com.example.SsmlHandler;
import com.plivo.api.exceptions.PlivoXmlException;
import com.plivo.api.xml.*;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.*;
@SpringBootApplication
@RestController
public class SsmlApplication {
	public static void main(String[] args) {
		SpringApplication.run(SsmlHandlerApplication.class, args);
	}
	@RequestMapping(value = "/ssml/", produces = { "application/xml" }, method = { RequestMethod.GET, RequestMethod.POST })
	public Response Ssml() throws PlivoXmlException {
		Response response = new Response().children(new Speak("The word","Polly.Joey","en-US",1)
				.children(new SayAs("read", "characters"))
				.addS("may be interpreted as either the present simple form")
				.addW("read", "amazon:VB")
				.addS("or the past participle form")
				.addW("read", "amazon:VBD"));
		System.out.println(response.toXmlString());
		return response;
	}
}

Was this code helpful

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
using System.Collections.Generic;
using Plivo.XML;
using Microsoft.AspNetCore.Mvc;

namespace Voicemail.Controllers
{
    public class SsmlController : Controller
    {
        // GET: /<controller>/
        public IActionResult Index()
        {
            var resp = new Response();
            Speak speak_elem = new Speak("The word", new Dictionary<string, string>() {
                {"voice","Polly.Joey"},
                {"language","en-US"},
            });
            resp.Add(speak_elem);
            speak_elem.AddSayAs("read", new Dictionary<string, string>() {
                { "interpret-as", "characters" }
            });
            speak_elem.AddS("may be interpreted as either the present simple form");
            speak_elem.AddW("read", new Dictionary<string, string>() {
                { "role", "amazon:VB" }
            });
            speak_elem.AddS("or the past participle form");
            speak_elem.AddW("read", new Dictionary<string, string>() {
                { "role", "amazon:VBD" }
            });
            var output = resp.ToString();
            return this.Content(output, "text/xml");
        }
    }
}

Was this code helpful

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
package main

import (
	"net/http"

	"github.com/go-martini/martini"
	"github.com/plivo/plivo-go/v7/xml"
)

func main() {
	m := martini.Classic()
	m.Any("/ssml/", func(w http.ResponseWriter, r *http.Request) string {
		w.Header().Set("Content-Type", "application/xml")
		response := xml.ResponseElement{
			Contents: []interface{}{
				new(xml.SpeakElement).
					AddSpeak("The word", "Polly.Joey", "en-US", 1).
					AddSayAs("read", "characters", "").
					AddS("may be interpreted as either the present simple form").
					AddW("read", "amazon:VB").
					AddS("or the past participle form").
					AddW("read", "amazon:VBD"),
			},
		}
		return response.String()
	})

	m.Run()
}

Was this code helpful

Response

<Response>
  <Speak voice="Polly.Amy">
    <prosody rate="medium">
    Hello and welcome to the Plivo text-to-speech engine.
    <break/>
    <break/>
    We’re now testing the
    <say-as interpret-as="spell-out">SSML</say-as>
    feature.
    </prosody>
  </Speak>
</Response>
<Response>
  <GetDigits numDigits="1" playBeep="true">
  <Speak voice="Polly.Salli">
  <prosody rate="fast">
  Please press 1 to proceed.
  <break/>
  <break/>
  We’re now testing the
  <say-as interpret-as="spell-out">SSML</say-as>
  feature.
  </prosody>
  </Speak>
  </GetDigits>
</Response>

The Wait element

The Wait element waits silently for a specified number of seconds. If <Wait> is the first element in a XML document, Plivo will wait the specified number of seconds before picking up the call.

Attributes

length integer

Time to wait in seconds

Allowed values: integer greater than 0
Defaults to 1.

silenceboolean

If silence is set to true, if no voice or sound is detected for minSilence milliseconds, Plivo will end the wait and continue to the next element in the XML code immediately (effectively cutting the wait for length seconds short).

If silence is set to false, Plivo will wait for the full period of length seconds, regardless of the presence of sound or voice or the value of minSilence.

Allowed values: true or false
Defaults to false.

minSilence integer

The minimum length in milliseconds of silence that needs to be present to qualify as silence.

Only used when silence is set to true. Note that the duration of length needs to be greater than the duration of minSilence for this attribute to work as expected.

Allowed values: integer > 0
Defaults to 2,000.

beep boolean

Used to detect a voicemail machine, so an application can leave voicemail messages. Only used when silence and minSilence are false.

Allowed values: true, false
Defaults to false.

Basic wait

This first example demonstrates how to wait for seven seconds between two lines of speech.

Example Request

1
2
3
4
5
6
7
from plivo import plivoxml

response = (plivoxml.ResponseElement()
            .add(plivoxml.SpeakElement('I will wait 6 seconds starting now.'))
            .add(plivoxml.WaitElement(None).set_length(6))
            .add(plivoxml.SpeakElement('I just waited 6 seconds.')))
print(response.to_string())

Was this code helpful

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

include Plivo::XML
include Plivo::Exceptions

begin
  response = Response.new

  first_speak_body = 'I will wait 7 seconds starting now!'
  response.addSpeak(first_speak_body)

  params = {
    length: '7'
  }
  response.addWait(params)

  second_speak_body = 'I just waited 7 seconds.'
  response.addSpeak(second_speak_body)

  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end

Was this code helpful

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

var response = plivo.Response();

var first_speak_body = "I will wait 7 seconds starting now!";
response.addSpeak(first_speak_body);

var params = {
        'length': "7"
};
response.addWait(params);

var second_speak_body = "I just waited 7 seconds.";
response.addSpeak(second_speak_body);

console.log(response.toXML());

/*
Sample Output
<Response>
    <Speak>I will wait 7 seconds starting now!</Speak>
    <Wait length="7"/>
    <Speak>I just waited 7 seconds.</Speak>
</Response>
*/

Was this code helpful

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
<?php
    require '../vendor/autoload.php';
    use Plivo\XML\Response;

    $response = new Response();

    $first_speak_body = "I will wait 7 seconds starting now!";
    $response->addSpeak($first_speak_body);

    $params = array(
        'length' => "7"
    );
    $response->addWait($params);

    $second_speak_body = "I just waited 7 seconds.";
    $response->addSpeak($second_speak_body);

    Header('Content-type: text/xml');
    echo($response->toXML());

    /*
    Sample Output

    <Response>
        <Speak>I will wait 7 seconds starting now!</Speak>
        <Wait length="7"/>
        <Speak>I just waited 7 seconds.</Speak>
    </Response>
    */
?>

Was this code helpful

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
// Example for wait - basic wait
package com.plivo.api.xml.samples.wait;

import com.plivo.api.exceptions.PlivoXmlException;
import com.plivo.api.xml.Response;
import com.plivo.api.xml.Speak;
import com.plivo.api.xml.Wait;


class BasicWait {
    public static void main(String[] args) throws PlivoXmlException {
        Response response = new Response()
                .children(


                        new Speak("I will wait 6 seconds starting now."),


                        new Wait()
                                .length(6),


                        new Speak("I just waited 6 seconds.")

                );
        System.out.println(response.toXmlString());
    }
}

Was this code helpful

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
using System;
using System.Collections.Generic;
using Plivo.XML;

namespace Plivo
{
	class MainClass
	{
		public static void Main(string[] args)
		{
			Plivo.XML.Response resp = new Plivo.XML.Response();
			resp.AddSpeak("I will wait 7 seconds starting now!", 
             new Dictionary<string, string>() { });
			resp.AddWait(new Dictionary<string, string>()
			{
				{"length", "7"}
			});
			resp.AddSpeak("I just waited 7 seconds.", 
             new Dictionary<string, string>() { });
			var output = resp.ToString();
			Console.WriteLine(output);

		}
	}
}



//<Response>
//  <Speak>I will wait 7 seconds starting now!</Speak>
//  <Wait length = "7" />
//  < Speak > I just waited 7 seconds.</Speak>
//</Response>

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// Example for wait - basic wait
package main

import "github.com/plivo/plivo-go/v7/xml"

func main() {
	response := xml.ResponseElement{
		Contents: []interface{}{

			new(xml.SpeakElement).
				AddSpeak("I will wait 6 seconds starting now."),

			new(xml.WaitElement).
				SetLength(6),

			new(xml.SpeakElement).
				AddSpeak("I just waited 6 seconds."),
		},
	}
	print(response.String())
}

Was this code helpful

Response

<Response>
    <Speak>I will wait for seven seconds starting now.</Speak>
    <Wait length="7" />
    <Speak>I just waited seven seconds.</Speak>
</Response>

Beep detection

You can use the Wait element to aid leaving voice mails on answering machines by adding an extra parameter called beep and setting it to true.

Example Request

1
2
3
4
5
6
from plivo import plivoxml

response = (plivoxml.ResponseElement()
            .add(plivoxml.WaitElement(None).set_beep(True).set_length(10))
            .add(plivoxml.PlayElement('https://s3.amazonaws.com/Trumpet.mp3')))
print(response.to_string())

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
require 'rubygems'
require 'plivo'

include Plivo::XML
include Plivo::Exceptions

begin
  response = Response.new

  params = {
    length: '120',
    beep: true
  }
  response.addWait(params)

  play_url = 'https://s3.amazonaws.com/plivocloud/Trumpet.mp3'
  response.addPlay(play_url)

  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
var plivo = require('plivo');

var response = plivo.Response();

var params = {
        'length': "120",
        'beep': "true"
};
response.addWait(params);

var play_url =  "https://s3.amazonaws.com/plivocloud/Trumpet.mp3";
response.addPlay(play_url);

console.log(response.toXML());

/*
Sample Output
<Response>
    <Wait length="120" beep="true"/>
    <Play>
        https://s3.amazonaws.com/plivocloud/Trumpet.mp3
    </Play>
</Response>
*/

Was this code helpful

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
<?php
    require '../vendor/autoload.php';
    use Plivo\XML\Response;

    $response = new Response();

    $params = array(
        'length' => "120",
        'beep' => "true"
    );
    $response->addWait($params);

    $play_url = "https://s3.amazonaws.com/plivocloud/Trumpet.mp3";
    $response->addPlay($play_url);

    Header('Content-type: text/xml');
    echo($response->toXML());

    /*
    Sample Output

    <Response>
        <Wait length="120" beep="true"/>
        <Play>
            https://s3.amazonaws.com/plivocloud/Trumpet.mp3
        </Play>
    </Response>
    */
?>

Was this code helpful

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
// Example for wait - beep detection
package com.plivo.api.xml.samples.wait;

import com.plivo.api.exceptions.PlivoXmlException;
import com.plivo.api.xml.Play;
import com.plivo.api.xml.Response;
import com.plivo.api.xml.Wait;


class BeepDetection {
    public static void main(String[] args) throws PlivoXmlException {
        Response response = new Response()
                .children(


                        new Wait()
                                .beep(true)
                                .length(10),


                        new Play("https://s3.amazonaws.com/Trumpet.mp3")

                );
        System.out.println(response.toXmlString());
    }
}

Was this code helpful

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
using System;
using System.Collections.Generic;
using Plivo.XML;

namespace Plivo
{
	class MainClass
	{
		public static void Main(string[] args)
		{
			Plivo.XML.Response resp = new Plivo.XML.Response();
			resp.AddWait(new Dictionary<string, string>()
			{
				{"length", "120"}, {"beep", "true"}
			});
			resp.AddPlay("https://s3.amazonaws.com/abc.mp3", 
             new Dictionary<string, string>() { });
			var output = resp.ToString();
			Console.WriteLine(output);

		}
	}
}



//<Response>
//  <Wait length = "120" beep="true" />
//  <Play>https://s3.amazonaws.com/abc.mp3</Play>
//</Response>

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// Example for wait - beep detection
package main

import "github.com/plivo/plivo-go/v7/xml"

func main() {
	response := xml.ResponseElement{
		Contents: []interface{}{

			new(xml.WaitElement).
				SetBeep(true).
				SetLength(10),

			new(xml.PlayElement).
				SetContents("https://s3.amazonaws.com/Trumpet.mp3"),
		},
	}
	print(response.String())
}

Was this code helpful

Response

<Response>
    <Wait length="120" beep="true"/>
    <Play>https://s3.amazonaws.com/plivocloud/Trumpet.mp3</Play>
</Response>

Explanation

In this example, upon the call being answered, the Wait element waits for 120 seconds for a beep sound to be received. If a beep sound is detected before the Wait length times out, the Wait element ends and the Play verb is issued, and plays the specified MP3 file on the remote machine that sounded the beep.

If the Wait element times out after 120 seconds, the XML flow skips to the Play element.

Delayed call answer

This example demonstrates how to wait for 10 seconds before accepting a call.

Example Request

1
2
3
4
5
6
from plivo import plivoxml

response = (plivoxml.ResponseElement()
            .add(plivoxml.WaitElement(None)
                 .set_length(10)).add(plivoxml.SpeakElement('Hello')))
print(response.to_string())

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
require 'rubygems'
require 'plivo'

include Plivo::XML
include Plivo::Exceptions

begin
  response = Response.new

  params = {
    length: '10'
  }
  response.addWait(params)

  speak_body = 'Hello'
  response.addSpeak(speak_body)

  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end

Was this code helpful

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 response = plivo.Response();

var params = {
        'length': "10"
};
response.addWait(params);

var speak_body = "Hello";
response.addSpeak(speak_body);

console.log(response.toXML());

/*
Sample Output
<Response>
    <Wait length="10"/>
    <Speak>Hello</Speak>
</Response>
*/

Was this code helpful

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
<?php
    require '../vendor/autoload.php';
    use Plivo\XML\Response;

    $response = new Response();

    $params = array(
        'length' => "10"
    );
    $response->addWait($params);

    $speak_body = "Hello";
    $response->addSpeak($speak_body);

    Header('Content-type: text/xml');
    echo($response->toXML());

    /*
    Sample Output

    <Response>
        <Wait length="10"/>
        <Speak>Hello</Speak>
    </Response>
    */
?>

Was this code helpful

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
// Example for wait - delayed call answer
package com.plivo.api.xml.samples.wait;

import com.plivo.api.exceptions.PlivoXmlException;
import com.plivo.api.xml.Response;
import com.plivo.api.xml.Speak;
import com.plivo.api.xml.Wait;


class DelayedCallAnswer {
    public static void main(String[] args) throws PlivoXmlException {
        Response response = new Response()
                .children(


                        new Wait()
                                .length(10),


                        new Speak("Hello")

                );
        System.out.println(response.toXmlString());
    }
}

Was this code helpful

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
using System;
using System.Collections.Generic;
using Plivo.XML;

namespace Plivo
{
	class MainClass
	{
		public static void Main(string[] args)
		{
			Plivo.XML.Response resp = new Plivo.XML.Response();
			resp.AddWait(new Dictionary<string, string>()
			{
				{"length", "10"}
			});
			resp.AddSpeak("Hello", 
             new Dictionary<string, string>() { });
			var output = resp.ToString();
			Console.WriteLine(output);

		}
	}
}



//<Response>
//  <Wait length = "10" />
//  < Speak > Hello </ Speak >
//</ Response >

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// Example for wait - delayed answer
package main

import "github.com/plivo/plivo-go/v7/xml"

func main() {
	response := xml.ResponseElement{
		Contents: []interface{}{

			new(xml.WaitElement).
				SetLength(10),

			new(xml.SpeakElement).
				AddSpeak("Hello"),
		},
	}
	print(response.String())
}

Was this code helpful

Response

<Response>
    <Wait length="10" />
    <Speak>Hello</Speak>
</Response>

Machine detection

You can use the silence parameter in conjunction with the machine_detection feature of the Call API to enable your XML to detect whether a call is answered by voice mail. When silence is set to true, as soon as the voice mail finishes speaking, and there is silence for minSilence milliseconds, the next element in the XML is processed, without waiting for the whole period of length seconds to pass.

Example Request

1
2
3
4
5
6
from plivo import plivoxml

response = (plivoxml.ResponseElement().add(
    plivoxml.WaitElement(None).set_length(10).set_min_silence(3000)
    .set_silence(True)).add(plivoxml.SpeakElement('Hello')))
print(response.to_string())

Was this code helpful

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 'plivo'

include Plivo::XML
include Plivo::Exceptions

begin
  response = Response.new

  params = {
    length: '10',
    silence: true,
    min_silence: '3000'
  }
  response.addWait(params)

  speak_body = 'Hello, welcome to the Jungle!'
  response.addSpeak(speak_body)

  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
var plivo = require('plivo');

var response = plivo.Response();

var params = {
        'length': "10",
        'silence': "true",
        'minSilence': "3000"
};
response.addWait(params);

var speak_body = "Hello, welcome to the Jungle!";
response.addSpeak(speak_body);

console.log(response.toXML());

/*
Sample Output
<Response>
    <Wait length="10" silence="true" minSilence="3000"/>
    <Speak>Hello, welcome to the Jungle!</Speak>
</Response>
*/

Was this code helpful

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
<?php
    require '../vendor/autoload.php';
    use Plivo\XML\Response;

    $response = new Response();

    $params = array(
        'length' => "10",
        'silence' => "true",
        'minSilence' => "3000"
    );
    $response->addWait($params);

    $speak_body = "Hello, welcome to the Jungle!";
    $response->addSpeak($speak_body);

    Header('Content-type: text/xml');
    echo($response->toXML());

    /*
    Sample Output

    <Response>
        <Wait length="10" silence="true" minSilence="3000"/>
        <Speak>Hello, welcome to the Jungle!</Speak>
    </Response>
    */
?>

Was this code helpful

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
// Example for wait - machine detection
package com.plivo.api.xml.samples.wait;

import com.plivo.api.exceptions.PlivoXmlException;
import com.plivo.api.xml.Response;
import com.plivo.api.xml.Speak;
import com.plivo.api.xml.Wait;


class MachineDetection {
    public static void main(String[] args) throws PlivoXmlException {
        Response response = new Response()
                .children(


                        new Wait()
                                .length(10)
                                .minSilence(3000)
                                .silence(true),


                        new Speak("Hello")

                );
        System.out.println(response.toXmlString());
    }
}

Was this code helpful

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
using System;
using System.Collections.Generic;
using Plivo.XML;

namespace Plivo
{
	class MainClass
	{
		public static void Main(string[] args)
		{
			Plivo.XML.Response resp = new Plivo.XML.Response();
			resp.AddWait(new Dictionary<string, string>()
			{
				{"length", "10"},
             {"silence", "true"}, 
             {"minSilence", "3000"}
			});
			resp.AddSpeak("Hello, welcome to the Jungle.", 
             new Dictionary<string, string>() { });
			var output = resp.ToString();
			Console.WriteLine(output);

		}
	}
}



//<Response>
//  <Wait length = "10" silence="true" minSilence="3000" />
//  <Speak>Hello, welcome to the Jungle.</Speak>
//</Response>

Was this code helpful

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// Example for wait - machine detection
package main

import "github.com/plivo/plivo-go/v7/xml"

func main() {
	response := xml.ResponseElement{
		Contents: []interface{}{

			new(xml.WaitElement).
				SetLength(10).
				SetMinSilence(3000).
				SetSilence(true),

			new(xml.SpeakElement).
				AddSpeak("Hello"),
		},
	}
	print(response.String())
}

Was this code helpful

Response

<Response>
    <Wait length="10" silence="true" minSilence="3000" />
    <Speak>Hello, welcome to the jungle.</Speak>
</Response>