@phone::makecall
Places a phone call by dialing the dial string and waiting for the call
to complete, and returns a call progress result.
In previous editions of this documentation, this method was
listed as @phone::makeCall. The correct usage is @phone::makecall; note
the lower case "c".
Syntax:
@phone::makecall(String dialString[, int callTimeOut])
Parameters:
- (String) dialString: the formatted
dial string using the contact person’s Country, Area/Std Code, and
Phone Number, as well as the appropriate Phone Class.
- (int) callTimeOut: number of seconds to wait after the call is connected before returning a NO_ANSWER result. Optional; if no value is specified, the default value used
is 30 seconds. Note that this default value may be too brief for international calls on some systems. If international calls are not completing, try raising this default to 60 seconds.
In some instances, voice call recipients, especially those on mobile phones, may experience 'silent' notifications when xMatters places calls over SIP lines. xMatters retries the call, but it continues to fail and the log indicates that xMatters sent a CANCEL packet to the SIP server after 30 seconds, which is the default time out value. To prevent this issue, try raising the callTimeOut value to 120 (two minutes).
Returns:
CallProgressResult
Possible CallProgressResult values are:
- CADENCE_DETECT: a ringback was detected and ended,
resulting in a successful connection, but no subsequent audio was detected.
(An audio cadence is a repeating pattern of sound and silence, such as
the pattern produced by a ringback or a busy signal. 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: a dropped loop current was detected.
(Loop current is established when the phone is taken off the hook, thereby
creating a closed circuit with the Central Office. This return value represents
the condition when the loop current is lost prematurely.)
- VOICE_DETECT: the call was answered by a person (positive voice detected).
- MACHINE_DETECT: the call was answered by an answering machine.
- LINE_BUSY: a busy signal was detected.
- NO_ANSWER: no answer was detected within the amount of time specified by the callTimeOut value.
- NO_RINGBACK: target phone is not ringing.
- OPERATOR_INTERCEPT: the call could not be placed
due to an error, and was intercepted by an automated operator.
- ANALYSIS_STOPPED: the call progress was stopped
prematurely due to an error detected before a call result was returned.
- NO_DIAL_TONE: no dial tone was detected.
- FAX_DETECT: the call was answered by a fax machine.
- ANALYSIS_ERROR: call progress analysis failed
to run, most likely due to hardware or configuration errors.
Note that not all Dialogic cards support all error messages. For example, if the call cannot detect a dial tone, you may receive an error message of "NO_RINGBACK" if the card does not support a "NO_DIAL_TONE" error.
When dialing extensions, SIP calls will return only VOICE_DETECT or MACHINE_DETECT progress results.
Example:
The following example formats
a dial string, places a phone call and waits for it to complete
$dialString = @phone::formatDialstring()
$result = @phone::makecall($dialString)