Play audio on a call

This endpoint allows you to play an audio file during an active call. The audio file formats supported are .mp3 and .wav

API Endpoint

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

Arguments

urls Required

A single URL or a list of comma separated URLs linking to an .mp3 or .wav file.

length integer

This is the maximum length to which playing this audio file should be restricted to. Length is provided in seconds.

leg string

The call leg in which the audio has to be played. This can take three values aleg (first leg of the call), bleg(second leg of the call) or both. The default value is aleg.

loop boolean

This flag when set to true will play the audio file indefinitely. By default it is set to false.

mix boolean

This flag is used to determine the behaviour of current call audio when the file is being played. If this is set to false then participants of the call would not be able to hear anyone speaking in the call until the Play is stopped. If set to true both call audio and the Play audio will be mixed and played. Defaults to true.

Returns

Returns the acknowledgement that audio file has started playing.

Response

HTTP Status Code: 202

{
  "message": "play started",
  "api_id": "07abfd94-58c0-11e1-86da-adf28403fe48"
}

Example Request

1
2
3
4
5
6
7
8
import plivo

client = plivo.RestClient()

response = client.calls.play(
    call_uuid='bc480f62-6d99-469e-b80e-090e620de824',
    urls='https://s3.amazonaws.com/plivocloud/music.mp3', )
print(response)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
#
# Example for Call Play Create
#
require 'rubygems'
require 'plivo'

include Plivo
include Plivo::Exceptions

api = RestClient.new("YOUR_AUTH_ID", "YOUR_AUTH_TOKEN")

begin
  response = api.calls.play(
    'eba53b9e-8fbd-45c1-9444-696d2172fbc8',
    ['https://s3.amazonaws.com/plivocloud/Trumpet.mp3'],
    loop: true
  )
  puts response
rescue PlivoRESTError => e
  puts 'Exception: ' + e.message
end
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// Example for Call Play create

var plivo = require('plivo');

(function main() {
    'use strict';
    
    // As the auth_id and auth_token are unspecified, Plivo will fetch them from the PLIVO_AUTH_ID and PLIVO_AUTH_TOKEN environment variables.
    var client = new plivo.Client();
    client.calls.playMusic(
        "eba53b9e-8fbd-45c1-9444-696d2172fbc8", // call uuid
        "https://s3.amazonaws.com/plivocloud/Trumpet.mp3", // urls
    ).then(function (response) {
        console.log(response);
    }, function (err) {
        console.error(err);
    });
})();
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<?php
/**
 * Example for Call Play create
 */
require 'vendor/autoload.php';
use Plivo\RestClient;
use Plivo\Exceptions\PlivoRestException;
$client = new RestClient("YOUR_AUTH_ID", "YOUR_AUTH_TOKEN");

try {
    $response = $client->calls->startPlaying(
        'eba53b9e-8fbd-45c1-9444-696d2172fbc8',
        [
        	'https://s3.amazonaws.com/plivocloud/Trumpet.mp3',
        	'http://www.ANOTHER.ONE/SOUND.MP3'
        ]
    );
    print_r($response);
}
catch (PlivoRestException $ex) {
    print_r(ex);
}
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
package com.plivo.api.samples.call.play;

import java.io.IOException;
import java.util.Collections;

import com.plivo.api.Plivo;
import com.plivo.api.exceptions.PlivoRestException;
import com.plivo.api.models.call.Call;
import com.plivo.api.models.call.actions.CallPlayCreateResponse;

/**
* Example for Call Play create
*/
class PlayCreate {
    public static void main(String [] args) {
        Plivo.init();
        try {
            CallPlayCreateResponse response = Call.player("eba53b9e-8fbd-45c1-9444-696d2172fbc8", Collections.singletonList("https://s3.amazonaws.com/plivocloud/Trumpet.mp3"))
                .play();

            System.out.println(response);
        } catch (PlivoRestException | IOException e) {
            e.printStackTrace();
        }
    }
}
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 Call Play Create
 */
using System;
using System.Collections.Generic;
using Plivo;
using Plivo.Exception;

namespace PlivoExamples
{
    internal class Program
    {
        public static void Main(string[] args)
        {
            var api = new PlivoApi("YOUR_AUTH_ID", "YOUR_AUTH_TOKEN");
            try
            {
                var response = api.Call.StartPlaying(
                    callUuid:"93b35e56-5b28-47fc-95aa-8536625d3ac1",
                    urls:new List<string>() {"https://s3.amazonaws.com/plivocloud/music.mp3"}
                );
                Console.WriteLine(response);
            }
            catch (PlivoRestException e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
    }
}
1
2
3
4
curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{"urls":"https://s3.amazonaws.com/plivocloud/Trumpet.mp3"}' \
    https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/Play/
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// Example for Call Play create
package main

import "fmt"
import "github.com/plivo/plivo-go"
 
func main() {
	client, err := plivo.NewClient("", "", &plivo.ClientOptions{})
	if err != nil {
		panic(err)
	}
	response, err := client.Calls.Play(
		"eba53b9e-8fbd-45c1-9444-696d2172fbc8",
		plivo.CallPlayParams{
			URLs: "https://s3.amazonaws.com/plivocloud/Trumpet.mp3",
		},
	)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Response: %#v\n", response)
}