Starting sessions
Your application container can use either HTTP or HTTPS (recommended) to communicate with VoiceXML Connector.
VoiceXML Connector exposes these endpoints to the IVR client application:
Request | Description |
---|---|
Start |
Executes a Mix dialog model. When the dialog completes, it returns status and data to the application. |
CompleteTransfer |
Performs cleanup (in the Mix dialog model) at the end of the session. |
Specify these parameters in your client applications.. For examples, see Invoking VXML Connector from applications.
Start request
Executes a Mix dialog model. When the dialog completes, it returns status and data to the application.
Parameter | Description |
---|---|
channel |
Strongly recommended. The channel modality defined in your Mix Dialog project. The default is the "default" channel. (This parameter sets the initial channel, which the Mix Dialog can change at any time during a session.) |
dialogModelRef |
Required. Pointer to the Mix dialog model on the artifact server. The value is a URN or a URL. A URN is required if using Speech Suite hybrid mode. (If URN, you must configure the actual location. See Dialog service configuration.) |
language |
Required. Language code passed to the Mix dialog model. The value determines the initial language in the dialog, which the dialog can change. |
maskSensitiveData |
Disables masking of the user's confidential data. Use this parameter during application development for debugging purposes. Do not use on production systems. By default (true), the dialog service controls masking. Default: |
systemId |
Strongly recommended. DNIS retrieved from telephony. Typically the dialed phone number (TFN or DID). The value is available to the Mix dialog model as |
ttsVoiceName |
Optional. Default text-to-speech voice name used by the Vocalizer TTS service when the Dialog service doesn't specify a TTS voice for the current language. This parameter is ignored when the Dialog service specifies a voice or when using Microsoft Neural TTS. |
userChannelId |
Strongly recommended. ANI retrieved from telephony. Typically the phone number of the caller. The value is available to the Mix dialog model as |
useDialogInputMode |
Recommended. Set to true to respect the input mode declared in the Dialog service (voice, dtmf, or both). By default, the dialog setting is ignored and Speech Suite accepts both DTMF and Voice input. |
neuralTtsUrl |
Optional. Specifies the URL of the middleware service for the neural text-to-speech solution. This parameter is relevant when the dialog uses neural TTS (see Nuance-hosted deployment). Best practice: specify this parameter in the Helm chart (to define a default neural TTS service) and add to start requests when overriding the default. For example, an override is useful when Nuance provides access to specific TTS resources such as a voice tuned for a rare language and dialect. See Microsoft Neural TTS configuration for the Helm configuration.) |
These parameters are required for the neural text-to-speech solution and whenever you enable Mix authentication. Do not pass these parameters if authentication is disabled. See Authentication configuration.
Parameter | Authentication description |
---|---|
mixClientId |
The ID of the Mix client.
|
mixSecret |
The client secret. |
Optional parameters:
Optional parameters. Typically defined in the deployment customization and not with every Start request.
Parameter | Description |
---|---|
audioBaseUrl |
Base path for loading audio files. The VoiceXML browser component of your IVR deployment uses this value to fetch audio files. |
backendBaseUrl |
Base URL for middleware calls executed from VoiceXML Connector. These client-side calls originate from data access nodes in the Mix dialog model. Typically defined in the deployment customization and not with every Start request. |
grammarBaseUrl |
Default location for grammars (.grxml and .gram files). Speech Suite fetches grammar files from this location when a grammar is specified with a relative URL. (Speech Suite prepends the base to the relative path.) This parameter is ignored when the dialog model specifies a full path. Typically defined in the deployment customization and not with every Start request. |
CompleteTransfer request
Performs cleanup (in the Mix dialog model) at the end of the session.
When the dialog returns to the client after executing the Start, it's the client's responsibility to finish the call, end the IVR session, and execute CompleteTransfer to reach closure with the dialog.
Required parameters:
Parameter | Description |
---|---|
sessionId |
Session ID associated with the call. |
returnCode |
Echoes the returnCode from the Start execution. (Originally provided by the
|
Optional parameters:
Parameter | Description |
---|---|
sessionVariables |
JSON string containing variables sent to the Dialog service. |
event |
Name of any telephony event caught by the client application during the transfer process (for example |
Connector outputs
The VoiceXML Connector returns these outputs to the IVR application:
Parameter | Description |
---|---|
sessionId | Session ID used by the Dialog service. (The same sessionId that you passed in the Start request.) |
returnCode |
Return code indicating the call status. See Return codes. |
event |
Event (if any) returned from the Connector. |
eventMessage | Event message (if any) returned from the Connector. |
sessionVariables |
Variables returned from the Dialog service as a JSON object. The Mix dialog model returns variables via the External Action node. |
sessionVariablesJson |
Variables returned from the Dialog service as a JSON string. (Variables are not returned if the Dialog service becomes unavailable for any reason.) |
Return codes
Values for the returnCode output:
Value | Set when... | Description |
---|---|---|
SUCCESS | Mix dialog ended | Mix dialog reached an End node and closed the Mix dialog session successfully. The caller is still connected (but the call might already be transferred). |
FAILURE | Mix dialog ended unexpectedly |
Mix dialog did not complete successfully. Check the |
TRANSFER | Mix escalation occurred |
Mix dialog reached an |
CALLER_HUNG_UP | Caller disconnected during Mix dialog |
Caller hung up, and the Mix dialog ended the session after processing the hang-up event. |