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
    
    // Example for Call Play create
    package main
    
    import "fmt"
    import "github.com/plivo/plivo-go"
     
    func main() {
    	client, err := plivo.NewClient("<auth_id>","<auth_token>", &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)
    }