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: true

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 userData.systemID as defined in the Mix userData schema.

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 userData.userChannelID as defined in the Mix userData schema.

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.

  • Required for authentication (if enabled)

    Required for self-hosted Dialog service with the CCSS component (which is recommended).

mixSecret

The client secret.

Optional parameters:

Parameter Description
modelBaseUrl

Base path to load ASR/NLU models exported from Mix. Overrides the value of grammarBaseUrl. Speech Suite uses this value to fetch the models.

platformSessionId ID of the session on the IVR platform
reportingVariables JSON string containing variables to be written to the reporting data (client_data on StartRequest)
sessionId

Session ID for the Dialog service diagnostic logs. You can use any value, but it's a best practice to use the same value as the Speech Suite sessionId. This creates a common identifier for aligning sessions sin the call log files.

If not specified, the Connector generates a random value and passes it to the Dialog service for logging.

sessionTimeout

Session idle timeout (seconds) passed to the Dialog service. (Applies to Redis sessions/profile only; does not affect HTTP sessions. If not set, the value of application.sessionTimeout is used. Default: 900 (15 minutes)

sessionVariables

JSON string containing variables sent to the Dialog service.

version

Optional. Forces a new fetch of a grammar or prompt resource. Use this parameter to fetch updates to grammar or prompt files (instead of using previously fetched and cached versions of those files). You can specify any arbitrary value that is different from any previously fetched version (the value is not aligned to any specific file on the file system). The best practice is to increment the value whenever a fetch is desired (for example, 1.0, 1.1, 1.2 and so on).

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 External Action node in the dialog.)

  • 0 = The node uses the Success path.
  • All other values = The node uses the Failure path.

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 connection.disconnect.hangup).

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 event and eventMessage for details. For example, there was a badfetch, or the Dialog Service is not responding.

TRANSFER Mix escalation occurred

Mix dialog reached an EscalateAction node, and the client application needs to initiate a transfer. After completing the transfer, the client application should call CompleteTransfer request.

CALLER_HUNG_UP Caller disconnected during Mix dialog

Caller hung up, and the Mix dialog ended the session after processing the hang-up event.