VoiceML: <Call>¶

The <Call> action allows you to place a call to one or more PSTN or SIP endpoints.

Attributes¶

The <Call> action supports the following attributes.

Attribute	Allowed Values	Default
CallerId	See description.	The caller ID inferred from the parent call.
MaxDurationSeconds	>= 1	`14400` (4 hours)
NextUri	absolute or relative URI	none
RingAudioUri	absolute or relative URI	none
Strategy	`linear`, `simultaneous`, `failover`	`simultaneous`
TimeoutSeconds	>= 1	none

CallerId¶

The CallerId attribute allows you to set the caller ID that the called party sees.

The allowed values vary based on the endpoints used:

For PSTN endpoints, the caller ID must be specified in +E164 format.
For SIP endpoints, the caller ID can include alphanumeric as well as the characters .-+_, up to a maximum length of 30 characters.

When terminating to SIP endpoints, the caller ID is included in the user-part of the SIP URI specified in both the From and P-Asserted-Identity headers.

The default value is the caller ID of the parent call. When the parent call is a SIP call, the default value will be the user-part of the sip or sips URI, or the value of the tel URI, of the first of the following headers:

P-Asserted-Identity
Remote-Party-ID
From

If you are calling a PSTN endpoint and the parent call is SIP, you must either:

Ensure the caller ID specified in the SIP call is a valid PSTN phone number in +E164 format.
Specify a valid PSTN phone number in +E164 format in this <Call> action.

If there is no valid +E164 formatted PSTN caller ID when placing a PSTN call, this action will fail.

You can also specify the caller ID on a per-endpoint basis using the CallerId attribute on the <Endpoint> element.

MaxDurationSeconds¶

The MaxDurationSeconds attribute specifies the maximum duration of the call in seconds.

If this time is exceeded, the call will be hung up. The maximum value is 14400 seconds (4 hours).

NextUri¶

The NextUri attribute specifies the URI where Enfonica will perform a VoiceML request after the called party hangs up or if the call does not get connected.

Enfonica will include the following parameters on the request to NextUri.

Parameter	Description
`action`	The action that has just finished executing. This will be equal to `CALL`.
`callStatus`	The status of the last call attempt. See below for permitted values.
`callEndpoint`	The endpoint that answered the call (for example, the phone number in +E164 format). Specified when `callStatus` is `COMPLETED`.

If the NextUri attribute is not specified, Enfonica will continue executing VoiceML actions after the called party hangs up or if the call does not get connected.

callStatus¶

Possible callStatus values are.

Value	Description
`COMPLETED`	The called party answered the call and the calls were bridged.
`NOT_ANSWERED`	The called party did not answer before a timeout elapsed.
`BUSY`	The called party returned a busy indication.
`FAILED`	The call attempt failed. This may happen when an invalid or not-in-service endpoint is attempted.

If multiple endpoints are being attempted, the value with the highest precedence will be returned. In the table above, values are listed from highest to lowest precedence.

RingAudioUri¶

The RingAudioUri attribute specifies the audio that should be played to the caller while the call is being attempted. A common use case is to play music to the caller while waiting. If not specified, the caller will hear ringing.

Strategy¶

The Strategy attribute specifies how multiple endpoints should be attempted. The permitted values are:

linear calls each endpoint one-by-one in order and stops when an endpoint answers.
simultaneous calls all endpoints at the same time.
failover calls endpoints in the sequence provided, and will only attempt the next endpoint if the previous endpoint fails (which does not include busy, no answer). If the last endpoint is a Cloud SIP Load Balancer which fails to connect, execution will redirect to its failover handler URIs if specified.

The default value is simultaneous.

TimeoutSeconds¶

The TimeoutSeconds attribute specifies the maximum amount of time a call attempt can run for without a call being accepted. This includes any post-dial delay. The call is not guaranteed to ring for this duration, as the endpoint that you are calling may have its own timeout which is out of our control.

If you specify more than one <Endpoint> and Strategy="linear", then this is the timeout per endpoint.

It is recommended to set this value a few seconds higher than desired, especially when using short timeouts (less than 10 seconds). The maximum value is 600 seconds, however note that many endpoints will cancel the call attempt well before this maximum.

Body¶

The body of an action is the content nested within the action. The following is supported for <Call>.

You can use plain text to call a single endpoint. For example:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Call>+61421000111</Call>
</Response>

Alternatively, you can specify one or more <Endpoint> elements. The following example is equivalent to the previous plain text example.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Call>
        <Endpoint>+61421000111</Endpoint>
    </Call>
</Response>

Using this syntax, you can call one or more endpoints simultaneously, and you can specify additional configuration for each endpoint.

<Endpoint>¶

The <Endpoint> element supports the following attributes.

Attribute	Allowed Values	Default
CallerId	See description.	The CallerId specified on the `<Call>` action.
ScreenAcceptKey	`[0-9*#]`	1
ScreenAudioUri	any URI	none
WhisperAudioUri	any URI	none

A maximum of 10 <Endpoint> elements can be defined.

CallerId¶

The CallerId attribute specifies the caller ID to use for this specific endpoint.

The caller ID defaults to the caller ID of the <Call> action.

For more information about this attribute, see the documentation of CallerId above.

ScreenAcceptKey¶

The ScreenAcceptKey attribute specifies the DTMF digit that must be pressed to accept the call. It is only used when ScreenAudioUri is specified.

ScreenAudioUri¶

The ScreenAudioUri attribute specifies the URI to audio that should be played to the called party. To connect the call, the called party must press any digit.

This can be used to allow the called party to confirm whether they want to accept the call. While this is executing, the calling party will continue to hear ringing or ring media.

WhisperAudioUri¶

The WhisperAudioUri attribute specifies the URI to audio that should be played to the called party before connecting the call.

This can be used to quickly inform the called party of the purpose of the call.

Tips and Tricks¶

If you are placing a call, be aware that voicemail will count as answering the call. This may be intended, but can be an issue in some circumstances. For example, when simultaneously calling several mobile phones, if one phone's voicemail answers, everybody else's phone will stop ringing. To counter this, you can use ScreenAudioUri to force the person answering to enter a digit before accepting the call. Because voicemail doesn't press digits, it won't answer the call.
Some of the <Endpoint> parameters execute logic on the called party before connecting the call. If specified, each will be executed in the order: WhisperAudioUri then ScreenAudioUri. It is recommend to only use one option.