Making external calls using a hook flash

This article explains how to redirect a User to another phone call or bridge a User into a conference call when a User is connected to xMatters via a Voice Device. A hook flash, also known as a "recall", simulates quickly hanging up and then picking up again. This can signal the telephone exchange to perform a function such as switching to an incoming call, or indicating a request for voice conferencing.

Note that using a hook flash is not currently supported over T-1 lines.

The following script illustrates how to code for two different tasks when a User is connected to xMatters via a Voice Device:

  • Redirecting the User to another phone call (such as directing to a Help Desk); and,
  • Bridging the User into a conference call and disconnecting the originating session once the connection is successfully completed.

For more information about the process involved, see the comments embedded within the code:

Note: A hook flash is not currently supported over T-1 lines.

# ------------------------------------------------------------  
# Three-way calling sample script showing two scenarios:  
# - Transfer a caller to a third party, such as a help desk  
# - Connect a caller to a conference call  
#  
# The flash verb is used for the transfer of the caller, and  
# requires that the phone system has 3-way calling capability.  
#  
# Three optional parameters are supported. If they are missing  
# the caller is requested to input them.  
# - thirdPartyPhoneNumber Third party number to dial.  
# - conferencePhoneNumber Conference number to dial.  
# - conferencePassword Conference password.  
# (Note that the phone numbers represents the dialstring  
# actually being dialed.)  
# ------------------------------------------------------------  
main:  
 Present menu options to select scenario  
$retry = 3  
$processed = false  
WHILE ($retry > 0)  
 @phone::clearDtmf()  
 @phone::play("phrase", "Press 1 to redirect to a third party")  
 @phone::play("phrase", "Press 2 to join a conference call")  
 @phone::play("phrase", "Press 9 to repeat the menu")  
 @phone::play("phrase", "or pound to continue")  
 $nkey = @phone::getDigits(1, 0, "")  
 @phone::clearDtmf()  
 # Process the selection  
 gosub SelectScenarioMenuSelection  
 IF ($processed)  
 $retry = 0  
 ELSE  
 $retry = $retry - 1  
 ENDIF  
ENDWHILE  
return  
# --------------------------------------  
# Process scenario select menu selection  
# --------------------------------------  
SelectScenarioMenuSelection:  
IF ($nkey == "1")  
 # Third Party Scenario  
 $processed = true  
 IF (EXISTS($event.debug))  
 @script::log("Transfering " & $content.recipient_target & " to third party...")  
 ENDIF  
 # Set number to dial  
 if (exists($event.thirdPartyPhoneNumber))  
 # number passed in with the event  
$numberToDial = $event.thirdPartyPhoneNumber  
 else  
 # get the number to dial from the user  
 @phone::clearDtmf()  
 @phone::play("phrase", "Please enter the number to dial, followed by the pound sign")  
 $numberToDial = @phone::getDigits(15, 10, "#")  
 @phone::clearDtmf()  
 endif  
 if ($numberToDial != "")  
 gosub transferToThirdParty  
 endif  
ELSE-IF ($nkey == "2")  
 # Conference Call Scenario  
 $processed = true  
 # Set number to dial  
 if (exists($event.conferencePhoneNumber))  
 # number passed in with the event  
 $numberToDial = $event.thirdPartyPhoneNumber  
 else  
 # get the number to dial from the user  
 @phone::clearDtmf()  
 @phone::play("phrase", "Please enter the conference number to dial, followed by the pound sign")  
 $numberToDial = @phone::getDigits(15, 10, "#")  
 @phone::clearDtmf()  
 endif  
 # Set the conference password  
 if (exists($event.conferencePassword))  
 $confPassword = $event.conferencePassword  
 else  
 # get the number to dial from the user  
 @phone::clearDtmf()  
 @phone::play("phrase", "Please enter the conference password, followed by the pound sign")  
 $confPassword = @phone::getDigits(15, 10, "#")  
 @phone::clearDtmf()  
 endif  
 if ($numberToDial != "")  
 gosub transferToConference  
 endif  
ELSE-IF ($nkey == "9")  
 # Repeat  
 $repeat = true  
ELSE-IF ($nkey == "#")  
 # Continue  
 $processed = true  
ENDIF  
return  
# ------------------------------  
# Transfer caller to third party  
# ------------------------------  
transferToThirdParty:  
# Contact the third party  
gosub ContactThirdParty  
# Issue another flash to get the original caller back  
@phone::flash()  
if ($thirdConnected)  
 # Caller is connected to third party, so we are done  
 @phone::clearDtmf()  
 @phone::play("phrase", "AlarmPoint transfered")  
 IF($recordingExists)  
 @phone::play("name", $targetName)  
 ELSE  
 @phone::play("phrase", $recipient.firstName)  
 @phone::play("phrase", $recipient.lastName)  
 ENDIF  
 @phone::play("phrase", "goodbye")  
 $connected = false  
 @phone::hangup()  
 exit  
else  
 # Inform the caller that the transfer failed  
 @phone::play("phrase", "Failed to transfer the call")  
 @phone::play("phrase", $callResultDesc)  
endif  
return  
# ------------------------------------  
# Transfer caller to a conference call  
# ------------------------------------  
transferToConference:  
# Contact the third party  
gosub ContactThirdParty  
# HOW TO JOIN A CONFERENCE CALL VARIES DEPENDING ON  
# THE TYPE OF CONFERENCE CALL PROVIDER  
if ($confPassword != "")  
 # Issue password  
 @phone::play("dtmf", $confPassword)  
endif  
# Wait 10 seconds  
wait(10)  
# Say the name of caller  
IF($recordingExists)  
 @phone::play("name", $targetName)  
ELSE  
 @phone::play("phrase", $recipient.firstName)  
 @phone::play("phrase", $recipient.lastName)  
ENDIF  
# Issue another flash to get the original caller back  
@phone::flash()  
if ($thirdConnected)  
 # Caller is connected to conference, so we are done  
 $connected = false  
 @phone::hangup()  
 exit  
else  
 # Inform the caller that the transfer failed  
 @phone::play("phrase", "Failed to transfer the call")  
 @phone::play("phrase", $callResultDesc)  
endif  
return  
# ---------------------  
# Contact a third party  
# ---------------------  
ContactThirdParty:  
IF (EXISTS($event.debug))  
 @script::log($event.incident_id & ": Contacting third party calling " &  
$numberToDial)  
ENDIF  
# Issue a flash  
@phone::flash()  
# Dial the third party number  
$result = @phone::makecall($numberToDial)  
gosub MakeCallResultDescription  
IF (EXISTS($event.debug))  
 @script::log("Third party call connect result: " & $callResultDesc)  
ENDIF  
$thirdConnected = false  
$voiceMail = false  
IF ( $result == "VOICE_DETECT" )  
 $thirdConnected = true  
ELSE-IF ( $result == "MACHINE_DETECT" )  
 $thirdConnected = true  
 $voiceMail = true  
ELSE  
 @script::log("Failed to connect to third party. Call result: " & $callResultDesc & ".")  
ENDIF  
return  
#------------------------------------------------  
# Translate makeCall result to a descriptive text  
#  
# CADENCE_DETECT -- cadence break detect  
# Cadence Detection analyzes the audio signal on the line to  
# detect a repeating pattern of sound and silence, such as the  
# pattern produced by a ringback or a busy signal. These patterns  
# are called audio cadences. Once a cadence has been established,  
# it can be classified as a single ring, a double ring, or a busy  
# signal by comparing the periods of sound and silence to  
# established parameters. Unless recognized as a defined cadence  
# this connect result will be returned.  
# LOOP_DETECT -- loop current drop detect  
# Loop current is established when the phone is taken off hook and  
# thereby creating a closed circuit with the Central Office. This  
# return value represents the condition when the loop current is  
# lost prematurely.  
# VOICE_DETECT -- positive voice detect  
# MACHINE_DETECT -- positive answering machine detect  
# LINE_BUSY -- busy tone detect  
# NO_ANSWER -- no answer  
# NO_RINGBACK -- no dialtone  
# OPERATOR_INTERCEPT -- operator intercept detect  
# The phone call can not be placed, and an automated operator  
# intercept message is played. Such as "The phone number can not be  
# placed as dialed" or "All circuits are currently busy".  
# ANALYSIS_STOPPED -- call progress analysis stopped  
# The call progress analysis was stopped prematurely due to errors  
# detected by the controlling tool-kit application.  
# NO_DIAL_TONE -- no dial-tone detect  
# FAX_DETECT -- fax tone detect  
# ANALYSIS_ERROR -- call progress analysis failed  
# The call progress analysis failed due to an internal error.  
#------------------------------------------------  
MakeCallResultDescription:  
if ( $result == "NO_RINGBACK" )  
 $callResultDesc = "No dialtone"  
else-if ( $result == "NO_DIAL_TONE" )  
 $callResultDesc = "No dial-tone"  
else-if ( $result == "LINE_BUSY" )  
 $callResultDesc = "Line busy"  
else-if ( $result == "NO_ANSWER" )  
 $callResultDesc = "No answer"  
else-if ( $result == "OPERATOR_INTERCEPT" )  
 $callResultDesc = "Operator intercept"  
else-if ( $result == "VOICE_DETECT" )  
 $callResultDesc = "Voice detected"  
else-if ( $result == "MACHINE_DETECT" )  
 $callResultDesc = "Answering machine detected"  
else-if ( $result == "FAX_DETECT" )  
 $callResultDesc = "Fax machine detected"  
else-if ( $result == "LOOP_DETECT" )  
 $callResultDesc = "Loop current drop detected"  
else-if ( $result == "CADENCE_DETECT" )  
 $callResultDesc = "Cadence break detected"  
else-if ( $result == "ANALYSIS_STOPPED" )  
 $callResultDesc = "Call progress analysis stopped"  
else-if ( $result == "ANALYSIS_ERROR" )  
 $callResultDesc = "Call progress analysis failed"  
else  
 $resultDesc = "Unexpected connect result"  
endif  
return  
# --------------  
# Error handlers  
# --------------  
PhoneHangupException:  
$connected = false  
IF (EXISTS($event.debug))  
 @script::log($event.incident_id & ": Phone hangup exception.")  
ENDIF  
exit  
PhoneTimeoutException:  
IF (EXISTS($event.debug))  
 @script::log($event.incident_id & ": Phone Timeout exception.")  
ENDIF  
$connected = false  
@phone::hangup()  
exit  

xMatters Reference

JDN-2031 Originally created by Don Clark

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk