Play

Definition

The Play verb is used to play an audio file to the calling party.

There are two ways to specify the file to be played:

• pass the file URL between the Play tags;
• nest the File noun inside the Play verb and use the file_sid attribute of the File object which can be obtained using the Get Files request.

Once the file stops playing, CarrierX will make a POST or GET request to the action URL.

warning

The verbs listed after the Play verb, which has an action URL specified, will not be executed.

If no action URL is set, the call flow will move to the next verbs in the FlexML instructions.

If the Play file fails to play, a POST or GET request will be sent to the errorAction URL.

tip

Refer to our Build a FlexML Advanced Play Application quick start guide to learn more about how you can use the Play verb.

Supported Attributes

These attributes can be used to modify the Play verb. They are inserted as name-value pairs in the start-tag.

Attribute	Data Type	Description
action	string	The URL containing the executable FlexML instructions that will be requested after the Play file ends.
background	boolean	Playback occurs in the background if this value is set to true. The audio file will continue to play, but control will pass to the next verb. The default value is false.
controlSkip	integer	The amount of seconds skipped for forwardOnKey and rewindOnKey. Integers entered into this field must be greater than or equal to 1. The default value is 60.
digits	string	This attribute provides an alternate syntax for the Dtmf verb and will enter the digits provided as a string. Note that this attribute should be used alone with the Play verb, and no URL should be included between the Play tags. Other supported attributes should be used with their own Play verb.
errorAction	string	The URL containing the executable FlexML instructions that will be requested if the Play file fails.
errorMethod	string	The method used to request the errorAction URL containing the executable FlexML instructions if the Play file fails. This method can be set as either POST or GET. The default value is POST.
forwardOnKey	string	Entering the value of this field on a keypad will fast forward the recording by the number of seconds set in controlSkip. Values accepted in this field are: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, and *.
informationAudioUrl	string	The audio that will play when informationOnKey is pressed. After this file has been played once, normal playback resumes.
informationOnKey	string	If this key is pressed, audio is paused and informationAudioUrl is played. Values accepted in this field are: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, and *.
loop	integer	The number of times that the file will be played. Integers entered into this field must be greater than or equal to 1. Setting this field to 0 will make the file play repeatedly until the call is ended. The maximum value accepted in this field is 100. The default value is 1.
loopPause	integer	The number of seconds between each repetition. Integers entered into this field must be greater than or equal to 1. The maximum value accepted in this field is 300. The default value is 0, meaning that there will be no pause between repetitions.
method	string	The HTTP method used to execute the request to the action URL. This method can be set as either POST or GET. The default value is POST.
minorControlSkip	integer	The amount of seconds skipped for minorForwardOnKey and minorRewindOnKey. Integers entered into this field must be greater than or equal to 1. The default is 60.
minorForwardOnKey	string	Entering the value of this field on a keypad will fast forward the recording by the number of seconds set in minorControlSkip. Values accepted in this field are: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, and *.
minorRewindOnKey	string	Entering the value of this field on a keypad will rewind the recording by the number of seconds set in minorControlSkip. Values accepted in this field are: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, and *.
pauseAudioUrl	string	The audio to play while playback is paused by pauseOnKey. This audio is played on loop. There is a default comfort noise.
pauseOnKey	string	Used to pause the playback of the recording by pressing one of the keys. Values accepted in this field are: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, and *.
preBuffer	integer	The time in seconds that the remote file should be queued before playback is started, to avoid playback catching up with a download in progress. The default value is 0.
restartOnKey	string	Used to restart the paused playback by pressing one of the keys. Values accepted in this field are: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, and *.
rewindOnKey	string	Entering the value of this field on a keypad will rewind the recording by the number of seconds set in controlSkip. Values accepted in this field are: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, and *.
skip	integer	The time in seconds into a file that it will start playing.
stopOnKey	string	Used to stop the playback by pressing one of the keys. Values accepted in this field are: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, and *. Note that you can enter multiple values in this field. For example, if you add the 3* value, then you will be able to stop the playback by entering either 3 or *.
streaming	boolean	Allows to play the stream file defined in the URL parameter. Set the value to false if the URL is a prerecorded file, and true if the URL has a real-time recording. Note that setting the streaming value to true will disable forwardOnKey and rewindOnKey. Refer to the sections below for information about supported file formats and protocols. The default value is false.
strictForwardControl	boolean	Does not allow forwardOnKey to reach the end of the file if this value is set to true. A forward command that moves past the end of the file is ignored. The default value is false.
timeLimit	integer	The number of seconds that the recording will playback when streaming is set to true. Integers entered into this field must be greater than or equal to 1. The default value is 0, meaning that the time is not limited.
waitInitial	integer	If the initial download is slow and the initial playback cannot start before this number of seconds, waitInitialUrl will start playing.
waitInitialUrl	string	The file to play for the waitInitial attribute.
waitRepeat	integer	After waitInitial has elapsed, and if the playback does not start in this number of seconds, waitRepeatUrl will start playing. Repeat every waitRepeat seconds until Play starts.
waitRepeatUrl	string	The file to play for waitRepeat.

Example

The following example shows how to use the Play verb to play a file to the calling party.

These FlexML instructions will play the file for the maximum duration of 30 seconds.

```xml
<Response>
  <Play timeLimit="30">
    http://www.example.com/path/to/media.mp3
  </Play>
</Response>

The same result can be achieved if file_sid is used together with the File noun instead of the direct link.

<Response>
  <Play timeLimit="30">
    <File>d620ec24-acd8-4193-9249-b89f46ee3654</File>
  </Play>
</Response>

Request Data

Successful requests return a JSON response that looks like the following:

{
    "AccountSid":"",
    "ApiVersion":"2.0",
    "CallerName":"",
    "CallSid":"4695bc4a0932bcd2e99492e523db9ee2",
    "CallStatus":"completed",
    "Digits":"",
    "Direction":"inbound",
    "From":"15162065338",
    "OriginalFrom":"+15162065338",
    "OriginalTo":"15162065337",
    "PlaybackUrl":"https://storage.carrierx.com/f/5fac56c8-c9fa-4d0e-bf88-f114e0d0cfab.mp3",
    "PlayOffset":37,
    "RequestUrl":"https://sampleurl.com/example",
    "To":"15162065337"
}

Attribute	Data Type	Description
Digits	string	If the playback was stopped due to stopOnKey, this is the key that triggered the end of the playback. This value will be empty if the playback ended normally.
PlaybackUrl	string	The URL of the file that was played.
PlayOffset	integer	The position of the playback from the beginning of the file when the call ends (either played or skipped to using DTMF controls).

info

For a list of the other parameters and values to expect in action requests, refer to the FlexML Call Flow section.

Supported File Formats

These are the format types that will be able to play: aac, al/alaw, flac, g722, m3u8, mp3, mp4/mp4a, ogg, ul/ulaw, and wav

Supported Protocols

The audio streaming protocols are hls, http, https, and rtmp.

• http and https are supported when streaming is set to true or false.
• Use hls or rtmp to play streaming files only.

note

Note that streaming must be set to true when using either hls or rtmp.

File Noun

Sample Play verb that uses the File noun together with the file_sid parameter to specify the playback file

<Response>
  <Play>
    <File>d620ec24-acd8-4193-9249-b89f46ee3654</File>
  </Play>
</Response>

The File noun can be nested inside the Play verb. It uses the file_sid attribute of the File object. This attribute specifies the secure ID of the file, which will be played to the calling party. It can be obtained using the Get Files request.

Using the secure ID instead of the link allows the partners to store the files with CarrierX storage and link these files to their FlexML application without the need to set the complete path to the file.

Nesting Rules

• You can nest the File noun within the Play verb.
• You can nest the Play verb within the Gather and PreAnswer FlexML verbs.