Latest Legacy

Play audio on a call

This endpoint allows you to play an audio file during an active call. Plivo supports .mp3 and .wav audio files.

API Endpoint

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

Arguments

urls Required

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

length integer

The maximum length, in seconds, to play this audio file.

legs string

The call leg in which the audio is to be played.

Allowed values: aleg (first leg of the call), bleg (second leg of the call), or both.

Defaults to aleg.

loop boolean

When set to true, audio file plays indefinitely.

Defaults to false.

mix boolean

Used to determine the behavior of current call audio when the file is being played. If set to false, then participants cannot hear anyone speaking in the call until the play audio stops. If set to true, call audio and play audio are mixed and played.

Defaults to true.

Returns

Returns the acknowledgement that the 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('<auth_id>','<auth_token>')

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("<auth_id>","<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';
    
   // If auth id and auth token are not specified, Plivo will fetch them from the environment variables.
    var client = new plivo.Client("<auth_id>","<auth_token>");
    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("<auth_id>","<auth_token>");

try {
    $response = $client->calls->startPlaying(
        'eba53b9e-8fbd-45c1-9444-696d2172fbc8',
        [
        	'https://s3.amazonaws.com/plivocloud/Trumpet.mp3',
        	'https://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("<auth_id>","<auth_token>");
        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("<auth_id>","<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
23
24
25
26
27

// Example for Call Play create
package main

import (
	"fmt"

	"github.com/plivo/plivo-go/v7"
)

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