VoIP Drupal
Public Member Functions | Static Public Member Functions | Data Fields | Protected Member Functions | Protected Attributes
VoipScript Class Reference

Public Member Functions

 __construct ($name, $variables=array())
 getName ()
 getVar ($name)
 setVar ($name, $value)
 unsetVar ($name)
 setLanguage ($language)
 getLanguage ()
 setVoice ($voice)
 getVoice ()
 getNextCommand ()
 resetIndex ()
 evalString ($string)
 isError ()
 getErrorMessage ()
 addBeep ()
 addDial ($number='', $timeout=30, $hangup_on_star=false, $time_limit=3600, $caller_id='')
 addGetInput ($prompt='', $num_digits=NULL, $end_key='#', $timeout=5)
 addGosub ($script_name, $options=array())
 addGoto ($label_name)
 addGotoIf ($label_name, $condition)
 addHangup ($hangup_mode='end_session')
 addJoinConference ($room, $muted=FALSE, $hangup_on_star=true)
 addLabel ($label_name)
 addLog ($input, $name=NULL)
 addRunIvrMenu ($prompt='', $input_options=NULL, $invalid_msg='', $no_input_msg='', $max_attempts=3, $timeout=5)
 addRecord ($prompt='', $timeout=5, $end_key='#', $max_length=3600, $format='mp3', $play_beep=TRUE)
 addReject ($reason=VoipScript::REJECT_INVALID)
 addReturn ()
 addSay ($prompt, $loop=1)
 addSendText ($text, $to='', $network='SMS', $caller_id='')
 addSet ($var_name, $var_value)
 addSetLanguage ($language='en')
 addSetVoice ($voice='man')
 addUnset ($var_name)
 addWait ($time_limit=60)
 runGosub ($script_name, $options=NULL)
 runGoto ($label_name)
 runIvrMenu ($options)
 runLoad ($script_name, $params=NULL)
 runLog ($input, $name=NULL)
 runReturn ()
 getStackLevel ()

Static Public Member Functions

static getScriptNames ()
static loadScript ($script_name, $params=NULL)

Data Fields

const ERROR = 'processing_error'
const DIAL_COMPLETED = 'dial_completed'
const DIAL_BUSY = 'dial_busy'
const DIAL_NO_ANSWER = 'dial_no_answer'
const DIAL_FAILED = 'dial_failed'
const DIAL_CANCELED = 'dial_canceled'
const REJECT_INVALID = 'reject_invalid'
const REJECT_BUSY = 'reject_busy'

Protected Member Functions

 getCommands ()
 getVariables ()
 addCommand ($command)

Protected Attributes

 $is_error
 $error_message

Constructor & Destructor Documentation

__construct ( name,
variables = array() 
)

VoipScript constructor

Parameters:
$nameA string containing the name of the new script
$variablesAn array with the initial value of the script variables
Returns:
The new script created

Member Function Documentation

addBeep ( )

Adds a beep command to the script.

addCommand ( command) [protected]
addDial ( number = '',
timeout = 30,
hangup_on_star = false,
time_limit = 3600,
caller_id = '' 
)

Adds a "dial" command to the script.

When executed, the 'dial' command connects the current caller to another phone. If the called party picks up, the two parties are connected and can communicate until one hangs up. If the called party does not pick up, or if a busy signal is received, or the number doesn't exist, the dial command will finish.

Parameters:
$numberString with a valid number to be dialed
$timeoutInteger with the number of seconds to wait for the called party to answer the call
$hangup_on_starIf TRUE, lets the calling party hang up on the called party by pressing the '*' key on his phone. This feature allows the calling party to hang up on the called party without having to hang up the phone and end the session. When the caller presses '*' Voip Drupal will hang up on the called party and will move on to execute the next command in the script.
$time_limitInteger with the maximum duration of the call in seconds
$caller_idString with the caller id to be used for the call. By default, this is the caller id defined in the 'default call configuration' settings
Returns:
The 'dial' command sets the script variable dial_status with the outcomes of the call:

If the call was successful, the variable dial_duration gets set with the number of seconds that the call lasted for.

addGetInput ( prompt = '',
num_digits = NULL,
end_key = '#',
timeout = 5 
)

Adds a 'get input' command to the script.

When executed, the 'get input' command reads user input from the phone keypad. The system stops reading the input whenever there is a timeout, the user presses a predefined key, or the users presses the maximum number of digits expected.

Parameters:
$promptMixed. Can be any of the following
  • an executable string to be processed into a prompt string, a VoipPrompt instance, or an array of VoipPrompt instances
  • a prompt string combining text and audio URLs to be played to the user prompting him/her to type something
  • a VoipPrompt instance
  • an array of VoipPrompt instances to be processed
$timeoutInteger specifying the maximum number of seconds to wait in between digits
$end_keyKey used to end the data input. The allowed values are the numbers 0-9, # , * and the empty string.
$num_digitsInteger with the number of digits that are expected.
Returns:
The 'get input' command sets the script variable input_digits to the input received. In case nothing is typed, input_digits gets set to ''
addGosub ( script_name,
options = array() 
)

Adds a "gosub" command to the script.

When executed, the 'gosub' command saves the state of the current script into the local stack and loads the commands and variables of specified script.

Parameters:
$script_nameThe name of the script to be loaded
$optionsAn array with options to be passed to the function that generates the required script
See also:
VoipScript::addReturn()
addGoto ( label_name)

Adds a "go to" command to the script.

When ran, the 'go to' command updates the index of the script and skips the script execution to the command that follows the specified label.

Parameters:
$label_nameString with the name of the label to go to.
See also:
VoipScript::addLabel()
VoipScript::addGotoIf()
addGotoIf ( label_name,
condition 
)

Adds a 'goto if' command to the script.

This command is similar to VoipScript:addGoto(). However, it only goes to the specified label in case the specified condition evaluates to TRUE.

Parameters:
$label_nameString with the name of the label to go to.
$conditionIf TRUE, skips script execution to the specified label.
See also:
VoipScript::addLabel()
VoipScript::addGoto()
addHangup ( hangup_mode = 'end_session')

Adds a 'hangup' command to the script

Parameters:
$hangup_modeString with one of the following options:
  • "end_session", to end the session and leave the script index as is
  • "reset", to keep the session alive, but resetting both the stack and the command index to their initial values
  • "resume", to keep the session alive, maintaining both the stack and the command index with their present values
addJoinConference ( room,
muted = FALSE,
hangup_on_star = true 
)

Adds a 'join conference' command to the script.

When executed, the 'join conference' command connects the current call to the specified conference room.

Parameters:
$roomString with the name of the conference call room
$mutedBoolean indicating whether the participant can speak on the conference
$hangup_on_starIf TRUE, allows participants to leave the conference by pressing '*'
Returns:
The 'join conference' command sets the script variable dial_status with the outcomes of the conference call:
addLabel ( label_name)

Adds a label to the script.

See also:
VoipScript::addGoto()
VoipScript::addGotoIf()
addLog ( input,
name = NULL 
)

Adds a log command to the script.

addRecord ( prompt = '',
timeout = 5,
end_key = '#',
max_length = 3600,
format = 'mp3',
play_beep = TRUE 
)

Adds a 'record' command to the script.

When executed, the 'record' command records audio input from the phone. The system stops recording whenever there is a timeout, the user presses the predefined 'end' key, or the maximum length of the recording is reached.

Parameters:
$promptMixed. Can be any of the following
  • an executable string to be processed into a prompt string, a VoipPrompt instance, or an array of VoipPrompt instances
  • a prompt string combining text and audio URLs to be played to the user prompting him/her to start recording
  • a VoipPrompt instance
  • an array of VoipPrompt instances to be processed
$timeoutInteger specifying the maximum number of seconds of silence to wait before ending the recording.
$end_keyKey used to end the recording. The allowed values are the numbers 0-9, # , * and the empty string.
$max_lengthInteger with the maximum number of seconds allowed for the recording
$formatThe format in which to record. By default, servers should support at least the 'mp3' format
$play_beepBoolean indicating whether or not to play a beep before the recording begins It's set to TRUE by default.
Returns:
The execution of the 'record' command sets the following script variables:
  • recording_path, with the local location of the file recorded
  • recording_public_url, with the remote location of the file recorded if available, otherwise will store local location.
  • recording_duration, with the duration in seconds of the recording
  • recording_digits, the key (if any) pressed to end the recording
  • recording_fid, with the fid of the file recorded

NOTE: If the call is hang up in the middle of a recording, the variable "recording_digits" will be set to "hangup" and the other variables will be set to their appropriate values.

addReject ( reason = VoipScript::REJECT_INVALID)

Adds a 'reject' command to the script.

Rejects an incoming call without billing you. Has to be the first command to be executed for an incoming call.

addReturn ( )

Add a 'return' command to the script.

Returns call control to the previous script in the script stack.

addRunIvrMenu ( prompt = '',
input_options = NULL,
invalid_msg = '',
no_input_msg = '',
max_attempts = 3,
timeout = 5 
)

Adds a "run IVR menu" command to the script

When executed, the "run IVR menu" command presents the user with a set of options and expects for an input to be typed in.

Parameters:
$promptMixed element presenting the different menu items available ('For x, press 1. For y, press 2...'). If empty (''), the default message will be used: 'Press any key from the telephone keypad.' Can be any of the following
  • an executable string to be processed into a prompt string, a VoipPrompt instance, or an array of VoipPrompt instances
  • a prompt string combining text and audio URLs to be played to the user
  • a VoipPrompt instance
  • an array of VoipPrompt instances to be processed
$input_optionsArray whose associating keys pressed with a respective script label. The indexes of the array are the keys allowed for the IVR. The contents are the script labels associated with each of those keys. For instance, $options[1] = 'story_playback' would associate the 1 with the 'story_playback' label of the script. By default, $input_options is set to the following: $input_options = Array ( 0 => 'option_0', 1 => 'option_1', 2 => 'option_2', 3 => 'option_3', 4 => 'option_4', 5 => 'option_5', '*' => 'option_star', '#' => 'option_hash', 't' => 'no_input_received', // used to report timeout situations 'i' => 'invalid_option' ) If the option 't' is not provided, it will be set to 'no_input_received' by default. Similarly, by default 'i' will be set to 'invalid_option'.
input$invalid_msgMixed. The message to be played in case an invalid option is selected. If empty (''), the default message will be used: 'Invalid option selected.' Similar to the $prompt parameter, might be either a string, a VoipPrompt instance, or an array of VoipPrompt instances.
%no_input_msgMixed. The message to be played in case no input is received. If empty, will use the same message as $invalid_msg. Similar to the $prompt parameter, might be either a string, a VoipPrompt instance, or an array of VoipPrompt instances.
$max_attemptsString with the maximum number of attempts allowed. Default is 3.
$timeoutString with the number of seconds to wait for an input digit to be pressed. The default is 5
Returns:
Set the ivr_option_selected script variable with the label associated with the option selected.
addSay ( prompt,
loop = 1 
)

Add a 'say' command to the script.

Says the given prompt the specified number of times in the given voice.

Parameters:
$promptString combining text to be converted to speech and audio URLs to be played. Mixed. Can be any of the following
  • an executable string to be processed into a prompt string, a VoipPrompt instance, or an array of VoipPrompt instances
  • a prompt string combining text to be converted to speech and audio URLs to be played to the user
  • a VoipPrompt instance
  • an array of VoipPrompt instances to be processed
$loopInteger with the number of times that the prompt should be repeated
Returns:
The execution of the 'say' command does not return anything.
addSendText ( text,
to = '',
network = 'SMS',
caller_id = '' 
)

Adds a "send text" command to the script.

When ran, this command sends the given text message to the specified phone number.

VoipScript::$variables

Parameters:
$textString with the text to be sent
$toThe destination of the text message. For instance, for messages sent via the SMS channel, $to contains the SMS number; for AIM messages, it contains the AIM username. When sending text as part of an inbound call, 'to' defaults to the caller. When sending text on an outbound call, 'to' defaults to the called party.
$networkString with the network to be used. The default the network is 'sms'. Different VoIP servers might support other options such as 'aim', 'msn', 'jabber', 'yahoo', 'gtalk', etc.
$caller_idString with the caller id to be used. Depending on the network, it can be a phone number, a IM username, etc. When sending on an inbound call, 'caller_id' defaults to the called party. When sending on an outbound call, 'caller id' defaults to the calling party.
Returns:
The execution of the 'send text' command sets the script variable 'send_text_status' to any of the following values:
  • VoipCall::TEXT_FAILED
  • VoipCall::TEXT_INVALID
  • VoipCall::TEXT_SENDING
  • VoipCall::TEXT_SENT
addSet ( var_name,
var_value 
)

Set the value of the specified script variable

addSetLanguage ( language = 'en')

Set the current language of the script

addSetVoice ( voice = 'man')

Set the current voice of the script

addUnset ( var_name)

Unset the specified script variable

addWait ( time_limit = 60)

Adds a 'wait' command to the script.

Parameters:
$time_limitNumber of seconds the script should wait before moving to the next command
evalString ( string)

Evaluates the given string based on the current value of script variables.

Parameters:
$stringThe string (or array of strings) to be evaluated
Returns:
The result of the evaluation
See also:
_voipscript_expand_variables() for the actual syntax allowed in the string to be evaluated
getCommands ( ) [protected]

Protected methods

getErrorMessage ( )

Retuns the message associated with a script error.

getLanguage ( )

Returns the current language of the script

getName ( )

Returns the script name

getNextCommand ( )

Returns the next script command to be executed

static getScriptNames ( ) [static]

Returns the name of all the scripts available in the system

Returns:
Array with the script names sorted alphabetically
getStackLevel ( )

Returns the number of scripts in the stack.

getVar ( name)

Returns the value of the specified script variable

NOTE: This method is only to be used inside VoIP Drupal server modules. To retrieve the value of a variable from inside the script execution, use the variable_name notation as in addSay("You typed: %input"). In this case, input is going to be replaced by the value of the script variable 'input'

getVariables ( ) [protected]
getVoice ( )

Returns the current voice of the script

isError ( )

Returns TRUE in case a script processing error has been detected

static loadScript ( script_name,
params = NULL 
) [static]

Returns a new instance of an already-existing script

Parameters:
$script_nameString containing the name of the script to be loaded
array$paramsArray with the value pairs to be passed to hook_voipscript_load_script()
Returns:
The new script instance, or NULL in case of invalid script name
resetIndex ( )

Resets the script index

runGosub ( script_name,
options = NULL 
)

Executes the specified script and then returns to the current script

runGoto ( label_name)

Jumps script execution to the command associated with the specified label

runIvrMenu ( options)

Runs the specified IVR menu

runLoad ( script_name,
params = NULL 
)

Loads the specified script

Parameters:
$script_namestring, name of script to be loaded
$paramsarray, optional parameters to be passed to implementations of hook_voipscript_load_script
runLog ( input,
name = NULL 
)

Logs the given message

runReturn ( )

Returns to the script that has originally issued the Gosub that started the present script

setLanguage ( language)

Sets the current language of the script

setVar ( name,
value 
)

Sets the value of the specified script variable

NOTE: This method is only to be used inside VoIP Drupal server modules. VoIP Scripts should use the addSet() method

setVoice ( voice)

Sets the current voice of the script

unsetVar ( name)

Unsets the specified script variable


Field Documentation

$error_message [protected]

Script error message

$is_error [protected]

Flag indicating script execution error

const DIAL_BUSY = 'dial_busy'
const DIAL_CANCELED = 'dial_canceled'
const DIAL_COMPLETED = 'dial_completed'

Values associated with the dial command results

const DIAL_FAILED = 'dial_failed'
const DIAL_NO_ANSWER = 'dial_no_answer'
const ERROR = 'processing_error'

Constants Error code

const REJECT_BUSY = 'reject_busy'
const REJECT_INVALID = 'reject_invalid'

'Reject' command options


The documentation for this class was generated from the following file:
 All Data Structures Files Functions Variables