When you make a call with the Voice Broadcast API, the script you want to be read aloud goes in the TextToSay parameter. This page summarizes the commands you can use in your call scripts.
Text-To-Speech
No special command is required to use text-to-speech (TTS). Just enter the text that you want for your message.
Example:
Hello, John Doe, your account is past due. Please call Jerry at 757-555-5555 to settle your account.
If you want to adjust the voices, speech rate, pitch, and other attributes of text-to-speech, refer to the Speech Control Commands page.
Playing a sound file
You can upload WAV files by using the UploadSoundFile method. To use the sound file in a message, put tildes (~) around its name and start it with a caret (^).
This example would play the sound file named “intro,” then read the text “John Doe,” then play the sound file named “end”:
~^intro~ John Doe ~^end~
Advanced Commands
Our Voice Broadcast API includes commands that let you customize your call scripts far beyond simple text-to-speech or sound files. Variables can be used in many of these commands. (Note that the system converts all variable names to lowercase. It also truncates variable values over 500 characters.)
ActOnDigitPress
Disables/enables Message Interruption for digit commands (such as pressing 1 to repeat the message). For example, if your user is told to enter his ZIP Code, you can use this method to prevent the Dial Plan from changing location while he enters the digits of his ZIP Code.
~ActOnDigitPress(false)~
ActOnFeature
Disables/enables Answering Machine Detection (AMD), Fax Detection, and Ring Detection. This is useful if you do not wish the message to restart when these tones are detected.
~ActOnFeature(false)~
AssignDTMF
Assigns a digit to a label. When the user presses the specified digit, the message will jump to the label. (Note that 1 is set to repeat the message by default, but this can be overridden.)
This example makes it so that pressing 1 will take the user to MyLabel:
~AssignDTMF(1|MyLabel)~
Beep
Plays a standard beep tone. It is typically used right before a record command (RecordAndSaveAs or RecordWithUniqueID).
~Beep()~
ChangeVoiceID
Changes the reading voice used for text-to-speech. See TextToSay Voices for a list of available voices.
~ChangeVoiceID(VOICE_ID)~
ClearDTMF
Clears all actions associated with DTMF commands. (This will also remove the default DTMF command of pressing 1 to repeat the message.)
~ClearDTMF()~
Conference
Provides a way to conference multiple calls together. The first call to issue this command will trigger a ConfKey variable to be posted to the URL specified in StatusChangePostURL. Additional calls can then join the room: invoke ~SetVar(ConfKey|THE_CONFKEY)~ at the top of scripts for the joining calls.
~Conference()~
DialDTMF
Dials a number in DTMF tones.
~DialDTMF(NUMBER_TO_DIAL)~
ErrorEmail
Sends an email when errors occur. See Debugging and Error Reporting for more information.
~ErrorEmail(EMAIL_ADDRESS)~
EndCall
Ends the call immediately.
~EndCall()~
GetDigits
Saves digits entered by the user to a variable. This command gives the user five seconds to enter digits, or optionally you can specify how long to wait. The call script will continue after the user presses the “#” key, at which point the digits will be saved to the specified variable. You can also specify the maximum number of digits to accept; this will turn off the “#” feature. You should typically set ActOnDigitPress to false before using GetDigits.
~GetDigits(VARIABLE_NAME)~
~GetDigits(VARIABLE_NAME|WAIT_IN_SECONDS)~
~GetDigits(VARIABLE_NAME|WAIT_IN_SECONDS|NUMBER_OF_DIGITS)~
This example will pause up to six seconds while waiting for a five-digit number:
~GetDigits(ZipCode|6|5)~
GetVariableLength
Saves the length of an input variable to an output variable.
~GetVariableLength(INPUT_VARIABLE|OUTPUT_VARIABLE)~
Goto
Goes to a label defined by the Label command.
~Goto(MyLabel)~
GotoIf
Goes to a label, but only if the specified variable is equal to a given value.
~GotoIf(VARIABLE_NAME|VALUE|LABEL)~
This example goes to MyLabel if the value of MyVariable is true:
~GotoIf(MyVariable|true|MyLabel)~
IncreaseVariable
Increases a variable by the amount specified. The number may be negative, in which case the variable is decreased. If the variable is not a number, the system will ignore this command and move on.
~IncreaseVariable(VARIABLE_NAME|NUMBER)~
Label
Defines a label within the message. You can let the user jump to a label using the AssignDTMF command. You can also force your message jump to a label by using the Goto or GotoIf commands.
~Label(MyLabel)~
MaxRingTime
Sets the maximum ring time in seconds for an outgoing call. If used, you must put this at the top of your call script. Note that some phones don’t ring for the first few seconds of “ring time.” (This can be the case, for example, with call blocking applications.)
~MaxRingTime(MAX_RING_TIME_IN_SECONDS)~
Special Labels
If you include them in your call script, the system will jump to these special labels in specific circumstances.
- Start – Start of a call.
- Ring – Where to go if a ring is detected in the call.
- Amd – Where to go if an answering machine is detected.
PlayAlphaNumeric
Reads out alphanumeric characters in a clear voice that uses the Phonetic Alphabet. Variables are not currently supported with this command.
~PlayAlphaNumeric(k9b52)~
PlayAmount
Reads out money values in a clear voice. Variables are not currently supported with this command.
~PlayAmount(29.95)~
PlaySpecialSoundFile
This command is mainly used by Esendex for global sound files, such as recording sound files.
~PlaySpecialSoundFile(SOUND_FILE)~
Some predefined sound files:
- BEA78757-BE32-4670-A8F7-D7E03AAFFB95 – Hello, please record sound file for id…
- AAA31398-AED0-4854-B745-95D174AAFE37 – After the tone record the message and press # to hang up or stop speaking when you are finished.
- C8F07A8C-E130-4E54-BE55-8079B8BB64E5 – Press 1 to accept, Press 2 to rerecord the sound file.
- B8B80319-0308-4E9A-80D8-D3A3D1E3CF51 – Thank you for using the Sound Record Service.
PlaySilence
Inserts a pause at any part of a message. This is useful if you need to wait for a user action. The value is in seconds.
~PlaySilence(3)~
~PlaySilence(3.75)~
QueryExternalServer
Saves the value returned from the specified URL to a variable. Note that special characters such as ~ ^ ( ) | are not allowed in the URL.
Your server has five seconds to respond. If your URL does not respond by then, the call script will continue from where it left off. This command may convert the URL into lowercase.
~QueryExternalServer(URL|RETURNED_VALUE)~
You can inject variables into the URL by surrounding them with brackets. Example: ~QueryExternalServer(http://null.esendex.us/manage_appt.cgi?action=cancel&queueid=[queueid]|Result)~
QuickStart
Use this command to play the message as soon as possible. This command bypasses “hello” detection. Therefore, you may want to follow this command with ~WaitForSilence(.5)~, or similar. If used, this must be the very first command in your Dial Plan.
~QuickStart()~
RecordAndSaveAs
Records and saves a WAV file to a variable.
~RecordAndSaveAs(VARIABLE_NAME)~
RecordWithUniqueID
Records a WAV file, saves it with an automatically generated Sound ID, and saves that ID to a variable.
~RecordWithUniqueID(VARIABLE_NAME)~
SetVar
Sets a variable with the value specified. Values might be converted to lowercase.
~SetVar(VARIABLE_NAME|VALUE)~
System Variables
You can set these variables at any time during a call:
maxrecordseconds– Sets the maximum recording length in seconds. This example sets the max to 30 seconds:~SetVar(maxrecordseconds|30)~maxcallseconds– Sets the maximum call length in seconds. (You must set this at the beginning of the call.)transfercallerid– Sets the CallerID which is used on the phone to be transferred to.transfercalleridname– Sets the CallerID name which is used on the phone to be transferred to.maxtransfertime– Sets the maximum duration, in minutes, for the transferred call.saverecordingonhangup– Sets whether the recording will be saved when a user hangs up on a call (defaults tofalse).transfersoundfileid– Sets the transfer message played to the user while waiting for a transferred call to be picked up.transferwhispersound– Sets a message played to the transfer line before the transfer is connected. Example:Incoming Sales Call.
The system may set these variables at any time during a call:
incoming– Containstrueif the call is an incoming call.machinedetection– Contains the status of the AMD detection routines. This can be FAX, MACHINE, HUMAN, or UNKNOWN.transferredto– Contains the number that a call was transferred to during a call.transfererror– Contains the error experienced within a transfer if an error occurs.
The system sets these variables at the beginning of a call and removes them at the end of the call (you can use these in your scripts):
queueid– Contains the QueueID number for the call. (Incoming calls also support QueueID).phonenumber– Contains the phone number that was dialed. (On incoming calls this is the incoming number.)callerid– Contains the CallerID number. (On an incoming call script this is the person who called.)calleridname– Contains the CallerID name. (On an incoming call script this is the person who called.)extension– Contains the extension dialed, if specified. (This is empty on incoming calls.)
The system sets these variables at the end of a call:
digitsdialed– Contains all the digits dialed during a call (pipe-delimited).AC– Contains a status code. This is for advanced problem solving with Tech Support.TransferErrorAC– Contains a status code. This is for advanced problem solving with Tech Support.
SoundPausing
Our system pauses when loud background noise are detected. This is intended to assist in the answering machine detection (AMD) of where the beep is. However, talking over the answering machine will sometimes cause the beep to corrupt and therefore cause the system to miss it. If you would like to turn off the sound pausing feature of AMD, use this command.
~SoundPausing(false)~
StatusChangePostURL
Posts information about the call to the specified URL. This useful method is highly recommended, as long as you have a server to postback to on the web. The POST_URL must be in lowercase.
~StatusChangePostURL(POST_URL)~
This command will post these values:
QueueID– The ID of the call.ResponseCode– 1 = Call answered. 2 or more = Call unanswered.StartTime– Start time in Universal Time (UTC).EndTime– End time in Universal Time (UTC).Duration– Call length in seconds.machinedetection– HUMAN, MACHINE, or FAX. (This value might change at any time during the call, since answering machine detection can happen at any time.)AC– Contains a status code. This is for advanced problem solving with Tech Support.digitsdialed– Contains all the digits dialed during a call.incoming– Containstrueif the call was an incoming call.- [Additional variables] – Any other variables that you collected or set during the call.
Note that the NotifyPhoneAdvanced and NotifyMultiplePhoneAdvanced methods also let you set the postback URL.
TransferTo
Immediately transfers the call to the number specified.
~TransferTo(17575551000)~
VariableToTTS
Reads a variable as text-to-speech. (Note that the variable gets sent to the TTS Server Farm for conversion. This is usually very quick, but please try to limit the size of these; otherwise, the listener might experience excessive dead air.)
~VariableToTTS(MY_VARIABLE)~
WaitForDTMF
Waits the specified number of seconds for a DTMF command. WaitForDTMF differs from GetDigits in that it accepts only one digit. Make sure that ActOnDigitPress is set to true (the default).
~WaitForDTMF(5)~
WaitForSilence
Waits for silence the specified number of seconds. (The maximum is 10 seconds.)
~WaitForSilence(3)~
Debugging Commands
See Debugging and Error Reporting for commands you can use to debug your Dial Plans.