Play command

The Play command plays an audio file (local or downloaded from URL) when an API extension call is in progress. It is also used to play a sound to chosen parties of the conversation (caller, callee or all). It is widely used in IVR-s playing pre-recorded sounds or when a client's call is transferred and the company plays music to the client till the phone is picked up by the support staff. It can be also used to play a sound file during a conversation for example if one of the parties are low in telephone credits it could say: 'You have 1 dollar left in your phone account. Please recharge it as soon as possible!'

Request parameters

Parameter name Example value Description Mandatory
AudioFile hello.wav Wav or MP3 file to play. Here you can provide the directory path to sound file or it can be HTTP URL as well where it's downloaded and cached (based on the webserver settings). When relative path provided, it will be relative to ContentStorage\Static directory in Ozeki 10 install directory. yes
CallId 345fad34 ID of the call to play audio file. If this command is in a response to a call notification, this parameter will be the ID of that call and can be omitted. yes
Party caller Which party will hear the played audio. It's value can be 'caller', 'callee' or 'all'. yes
Repeat false Repeat audio file. no
Timeout 10 Stop playing audio file when this amount of seconds are elapsed and playing is still in progress. no
Username admin The username of the account. The username and password parameters are used to authenticate the user. yes
Password abc123 Specifies the password. The username and password parameters are used to authenticate the user. yes

Response parameters

Parameter name Example value Description Mandatory
Code 200 Returns the status code of the response. yes
Message Command successfully executed Returns th description of the response code. yes
NotificationName CallConnected Name of the notification request type. no

OzML examples

The following example plays the hello.wav file repeatedly from the ContentStorage/Static directory in Ozeki 10 install directory. The repetition of the sound file is ensured by the true value in the Repeat attribute. 

<?xml version="1.0"?>
<Response>
    <Play Repeat="true">hello.wav</Play>
</Response>

Example request and response

URL request

http://127.0.0.1:9509/api?command=Play&Party=caller&CallId=Nt3uh&AudioFile=welcome.wav&Repeat=false&Username=HTTP_User_1&Password=qwe123

Response

<?xml version="1.0"?>
<Response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Code>200</Code>
  <Message>Command successfully executed</Message>
</Response>

More information