@phone::play
Places a phone call by dialing the dialString.
Syntax:
@phone::play(String playType, Object playData[, Object playOption]
[, Boolean useAsync])
Parameters:
- (String) playType: represents the type of play
to perform. PlayType options are:
- PHRASE: plays a recording located in the language-specific
phrases subfolder.
- NAME: plays a User’s recorded name in the
name recordings subfolder.
- MESSAGE: plays a message located in the language-specific
subfolder.
- CHARACTERS: spells out a string of characters
using the language-specific grammar and index file.
- NUMBER: plays a number formatted as specified
by the language file using the index file for phrases.
- MONEY: plays a currency formatted as specified
by the language file using the index file for phrases.
- ORDINAL: plays ordinals formatted as specified
by the language file using the index file for phrases.
- DATE: plays a date formatted as specified
by the language file using the index file for phrases. The playOption
argument may be used to specify the format to use. If the playOption is
missing, the "Default Play/Date Format" specified on the Phone
Device Engine Details page is used. A typical format is "mm/dd hh:mm".
- DTMF: plays DTMF tones corresponding to the
characters specified. For example, "123#".
- TTS: plays a string of characters using a
text-to-speech (TTS) engine. The personality used is specified by the
"TTS Engine Personality" setting on the Phone Device Engine
Details page. It can also be dynamically specified in the script by calling
the setTtsPersonality method.
- (Object) playData: defines what to play. For example,
the name of a phrase.
- (Object) playOption: used when playing the date
or specifying the date/time format, such as "hh:mm". When playing
a phrase, name, or message, the playOption may be set to one of the following:
- tts: specifies that TTS should be used if
the recording does not exist (default setting).
- spell: specifies that the recording name should
be spelled out if it is not found.
- (Boolean) useAsync: plays the recording asynchronously
when set to true. Note that an asynchronous play statement can cause a script to hang if it is followed by one of the following methods: flash, play, playDate, record. This is due to how asynchronous play statements allow the next script line to be executed while the current play statement is processed; if the next line of the script interferes with the first play statement, the script is unable to complete.
Returns:
None
Example:
The async flag allows scripts to play a pre-recorded file asynchronously,
which allows Users to continue performing other actions while the file
is playing. This feature can be used to enchance a caller's phone experience
by minimizing processing delays, as the following examples illustrate:
Example 1 - play message synchronously
# the print statements will not be executed until the message
has
# completed.
@phone::play("phrase", "Please wait while
we retrieve your messages", false)
print("Print this message synchronously")
print("1")
print("2")
print("3")
@phone::getDigits(1)
Example 2 - play message asynchronously
# the print statements will execute right away while the
message
# is still being played.
# the getDigits statement will block waiting for the play
# statement to complete
@phone::play("phrase", "Please wait while
we retrieve your messages", true)
print("Print this message asynchronously")
print("1")
print("2")
print("3")
@phone::getDigits(1)
Best practices for playOption parameter
The following lines of code illustrate the rules used by the playOption
parameter when determining whether to play a recording, use Text-To-Speech,
or to spell out a phrase - in this example, the name of a Device.
Usage 1
@phone::play(" phrase ", $theDevice)
For this usage (which is the most common), xMatters will play the
recording if it exists. If the recording does not exist, xMatters will
use TTS. If TTS is not supported, xMatters will spell out the Device
name.
Usage 2
@phone::play( " phrase ", $theDevice, "tts")
This usage produces the same results as Usage 1.
Usage 3
@phone::play( " phrase ", $theDevice, "spell")
For this usage, xMatters will play the recording, if it exists. If
the recording does not exist, xMatters will bypass TTS and spell out
the Device name.
Note:
When spelling out phrases, xMatters uses an index file containing
phrases recorded by the same personality as the regular recordings. While
this ensures compatibility, it also precludes the possibility of using
a different voice to spell out phrases, other than re-recording all of
the phrases at a significant cost.