The Play
command plays an audio file back to the caller. The audio file may be located at any location accessible via a URL. Play
can exist as a standalone command or as a nested command. It does not allow barge-In unless nested within a GetDigits
and GetSpeech
commands. The file will always be played to completion unless nested or if it is nested and not interrupted by barge-In.
FreeClimb supports multi-channel 8 bit audio a-law/μ-law (WAV) formats with an audio sampling rate of between 1000 and 96000. The max download size is 100MB. You can convert files to this format using an audio editor. Audacity is a free, open source option:
- Import the high quality source audio
- Adjust the project rate to 8 kHz.
- Export the track using the μ-law encoding.
Play can be done on a Call when not in Conference.
Nesting Rules
No commands can be nested inside the Play
command. The Play
command can be nested inside the GetDigits
or GetSpeech
commands.
Example
This PerCL document plays a greeting repeatedly.
[
{
"Play" : {
"file" : "http://www.foo.com/greeting.wav",
"loop" : 0
}
}
]
Command Attributes
Play
supports the following attributes that modify its behavior:
Attribute | Description |
---|---|
file | URL of the audio file to be played to the caller. |
loop | Number of times the audio file is played. |
privacyMode | Indicates if the request contains sensitive information which should be hidden. |
file
REQUIREDType: absolute URL
URL of the audio file to be played to the caller. The URL can be the recordingUrl
generated from the RecordUtterance
or StartRecordCall
PerCL commands.
If attempting to use a recorded utterance that was created with
privacyMode
set totrue
, it can't be accessed by a play command.
FreeClimb will respect Cache-Control headers for this file. See Cache-Control Headers below for more details.
Cache-Control Headers
Use headers to limit repeated requests for unchanged audio. If no Cache-Control header is provided, the file will be cached for 5 seconds by default. FreeClimb supports the following headers and Cache-Control directives:
Header | Type |
---|---|
Cache-Control | General header |
Pragma | General header |
Expires | Response header |
ETag | Response header |
Last-Modified | Response header |
Cache-Control Request Directive | FreeClimb Support |
---|---|
max-age | Supported |
no-cache | Supported |
no-store | Supported |
private | Unsupported |
public | Unsupported |
must-revalidate | Unsupported |
no-transform | Unsupported |
proxy-revalidate | Unsupported |
s-maxage | Unsupported |
loop
OPTIONALType: integer >= 0
Default: 1
Number of times the audio file is played. Specifying '0' causes the Play
action to loop indefinitely. If there is a Call hangup or barge-in, a loop will end even if it has not achieved the number of times initially specified.
privacyMode
OPTIONALType: boolean
Default: false
Indicates if the request contains sensitive information which should be hidden. When set to true
, the contents of the file
attribute will be replaced with the string "xxxxx" in the logs. It's important to note that privacyMode
is set at the command level, meaning it will not be inherited by any nested commands.