Integrate Google Dialogflow CX VoiceStream

Prerequisites

To use Google Dialogflow CX virtual agentsClosed A software application that handles customer interactions in place of a live human agent. with NiCE CXone, you need:

  • A Google Cloud Platform account.

  • A Google Dialogflow CX virtual agent that's configured and trained to provide responses to your contacts'Closed The person interacting with an agent, IVR, or bot in your contact center. requests. To complete integration in NiCE CXone, you need the virtual agent name from the virtual agent's settings in the Google Dialogflow console.

  • A SIP connection with your Dialogflow CX virtual agent.

Alpha Visibility in Google

Alpha visibility is a Google program that provides Google Cloud Projects access to features that aren't otherwise available. Alpha visibility is not required to use Dialogflow CX with NiCE CXone. However, there are some cases where you may need to have alpha visibility enabled. Alpha visibility is required if you want: 

  • To have the last user utterance returned from the Dialogflow virtual agent along with the intent information. You can view this information in a script trace. If the lastUserUtterance variable is empty when it should contain data, alpha visibility may not be enabled for your project. If you require this information, your Google Cloud Project must have alpha visibility enabled.

  • To have the current page returned as part of the response's custom payload.

  • To have the Dialogflow transcript field returned as part of the response payload.

Create a Script

Required permissions: Studio Script View, Create/Edit

You need at least one Studio script to route interactions to your virtual agent. Follow the script guidelines. The supported virtual agent action for this provider is VOICEBOTSTREAM and the script must have the phone media type.

You can learn more about Studio scripting in the Fundamentals and Technical Reference Guide sections of the online help.

Custom Payload Best Practices

Follow these best practices when integrating custom payload data from Google Dialogflow CX into NiCE CXone: 

  • You can pass custom data to Dialogflow CX using JSON key-value pairs. In a Snippet action in your script, create a dynamic customPayload object and add the key-value pairs to it. For example:

    DYNAMIC customPayload
customPayload.ani = ani
customPayload.contactID = contactId
customPayload.masterContactId = masterId
customPayloadJSON = "{customPayload.asJSON()}"
  • In the VoiceBOT STREAM action in your script, configure the customPayload property with variable that has the asJSON() function in its value. You can find this variable in the customPayload object.
  • Pass the customPayload JSON to the virtual agent using the Payload property of QueryParameters. See Google documentation on QueryParameters A square with an arrow pointing from the center out from the top right corner. for Google Dialogflow CX.
  • Data passed through QueryParameters is received by a webhook in Dialogflow CX. You can write code in the Dialogflow CX console to handle the passed data.
  • Do not nest an object within the customPayload object. Nested objects are sent as literal strings.
  • To pass custom data from your Dialogflow CX virtual agent back to the script, use the Custom Payload field in the Dialogflow CX console. Make sure you're in the console for the virtual agent you're using with NiCE CXone. Map this to your script using the customPayloadVarName (out) variable in the VOICEBOT STREAM action in your script.

  • To pass custom data to Dialogflow CX from the script, use session_params in the customPayload object in a Snippet action. For example:

    DYNAMIC customPayload
customPayload.session_params.name = "Winnie le Pooh" 
customPayload.session_params.job = "Food critic" 
customPayload.session_params.location = "Hundred Acre Wood"

    Access the session parameters in the Dialogflow CX agent intent using the following syntax:

    $session.params.name = Winnie Le Pooh
$session.params.job = Food critic
$session.params.location = 100 Acre Wood

    Session parameters are only used with Dialogflow CX virtual agents. To achieve a similar result with Dialogflow ES, use contexts.

  • Configure speech context hints and a custom conversation ID to transfer the conversation to a different Dialogflow CX virtual agent in the Custom Payload snippet.

Add an App to Virtual Agent Hub

Required permissions: Connections Hub > Launch Connections Hub

Adding a configuration app to Virtual Agent Hub establishes the connection between NiCE CXone and your virtual agent provider.

  1. In NiCE CXone, click the app selector and select Other > Connection Hub and then click Virtual Agent Hub. You can also double-click the virtual agent action in your Studio script to launch Virtual Agent Hub.
  2. Click Add Bot.

  3. Enter a Virtual Agent (Bot) Name and click Dialogflow CX VoiceStream in the list of virtual agent providers.

  4. Click Next.

  5. Complete the fields in the configuration form and click Next. You can find details about this form in the Configuration Page Details section on this page.

  6. Click Next.

  7. On the Voice Integration Options page, the only option is Custom Telephony (grpc, DirectLine Voice, etc.). It's selected by default. Click Next.

  8. On the Transcript page, select the option for whether you want the conversation transcript and intent information captured. The default is Nothing. If this tab is not available, the feature is not enabled for your tenantClosed High-level organizational grouping used to manage technical support, billing, and global settings for your NiCE CXone system.. Contact your Account Representative for more information about this feature.

    Option Details
    Intent information only

    Select this option if you want to want to capture intent information only. Captured data is stored only for the duration of the interaction by default.

    This option requires custom scripting.

    Nothing Select this option if you don't want to capture conversation transcriptions or intentClosed The meaning or purpose behind what a contact says/types; what the contact wants to communicate or accomplish. information.
    Transcript and intent information

    Select this option if you want to capture both transcript and intent data. Captured data is only stored for the duration of the interaction by default.

    This option requires custom scripting.

    Transcript only Select this option if you want to capture transcript information only. Captured data is stored only for the duration of the interaction by default.

    This option requires custom scripting.

  9. Click Next.

  10. On the Add page, click Add.

Dialogflow CX VoiceStream Configuration Page Details

Use the information in the following table when completing the Configuration page. You see this page when adding an app in Virtual Agent Hub

Field

Details
Integration Version

Select the version of Virtual Agent Hub that you want to use. This option allows you to use a previous version of Virtual Agent Hub until you're ready to switch to a newly-released version. The available versions are: 

  • Version 1.0.0: This version is not available for this provider.
  • Version 2.0.0: This version is not available for this provider.
  • Version 3.0.0: This version introduced StandardBot, which standardizes how NiCE CXone communicates with virtual agent providers. The customPayload object returns as an array, as customPayloadscriptPayloads[n].xxxx. This version is available for all providers.

JSON Service Account

The service account key file you created and downloaded from your Google Cloud Console. Copy and paste the entire contents of the key file into this field, including the curly braces surrounding the key. This field is visible only if you're using your own Google Dialogflow CX account. If the field is not visible when it should be, ask your NiCE CXone account representative to review your system's settings.

The service account key is a JSON object similar to the following example:

{

"type": "service_account",
"project_id": "ic-demo2-aai-gcp",
"private_key_id": "sdv80sdf08ssd9sdf0sdf8sdfsdf90sdf8",
"private_key": "-----BEGIN PRIVATE KEY-----
nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCzgrS8vp
<private key has been truncated for this example>
----END PRIVATE KEY-----\n",
"client_email": "your@client_email-gcp.iam.gserviceaccount.com",
"client_id": "123456789",
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
"token_uri": "https://oauth2.googleapis.com/token",
"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
"client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/dialogflow-dthjop%40ic-demo2-aai-gcp.iam.gserviceaccount.com"
}

The JSON Service Account must have the Dialogflow API Admin role A square with an arrow point from the center out to the upper right corner..

Conversation Profile

Enter the ID of the Dialogflow CX conversation profile you want this Virtual Agent Hub profile to use. If you don't specify an ID, the system creates a new profile. You can find the conversation profile ID in your Google project management console.

If you change the Agent or Environment fields, the Conversation Profile field clears. This is because conversation profiles are specific to the agent and environment.

Language

The language you want this virtual agent to use. This is the language that the virtual agent understands. This is a required field.

Region

The region where the Google Dialogflow CX virtual agent you're adding to Virtual Agent Hub is located. This is a required field.

Agent

The name of the Google Dialogflow CX virtual agent you want to add to Virtual Agent Hub. You can find the name in the virtual agent's Dialogflow CX console and click Copy Name to copy it to the clipboard. This is a required field.

Environment

Enter the GUID of the environment you want this Dialogflow app to use. In Dialogflow CX, different versions of the same virtual agent are called environments. You can find the GUID for your environments in the Google Dialogflow CX console in the agent settings.

Use Custom Voice

Allows you to use an AutoML (automated machine learning) model to synthesize a custom voice for your bot. Dialogflow uses this voice instead of a TTS voice. If you use this option, enter the name of the AutoML model that you want to use in the Custom Voice Model field that appears.

TTS Voice Name

The name and language of the TTS voice you want this virtual agent to use. This option is not available if you enabled Use Custom Voice. If you're not using a custom voice, this field is required.
Model

Select the machine learning model that you want the transcription service to use when transcribing the audio. These models have been trained to recognize speech from specific audio types and sources. Configure this field for voice virtual agents only. Not all languages support every model. Refer to the Google documentation for information about language support.

Phone Call is the recommended option for most voice virtual agents.

Available options are: 

  • Command and Search: Use when transcribing shorter audio clips, such as commands or voice search. Consider using Latest Short instead.
  • Default: Use when the audio doesn't fit the other models. It can transcribe any type of audio, but results may be lower quality for some types.
  • Latest Long: Use with long-form content such as spontaneous speech or conversations.
  • Latest Short: Use when the utterances are a few seconds long, such as commands. Consider using this model instead of Command and Search.
  • Medical Conversation: Use when transcribing a conversation between a medical professional and a patient.
  • Medical Dictation: Use when transcribing notes dictated by a medical professional.
  • Phone Call: Use for transcribing the audio from a phone call.
  • Telephony: Use for higher quality audio in a phone call.
  • Telephony Short: Use for short conversations (less than ten seconds long) in a phone call.
  • Video: Use when transcribing audio that has multiple speakers, such as from video clips or podcasts. If Video isn't available in the language you need, use Latest Long instead.
Model Variant

Select the variant of the selected Model you want the virtual agent to use. Some models have an enhanced variant that provides higher quality results. The default is Best Available.

Refer to the Dialogflow documentation for more information about the models that support an enhanced variant. Enhanced models are billed at a higher rate than standard models.

For Phone Call models, the recommended variant is Enhanced.

Available options for this field are: 

  • Best Available: Select if you want Dialogflow to use the enhanced model if it's available for the selected model. If it's not, the standard model is used.
  • Enhanced:  Select to use the enhanced model. If an enhanced model isn't available for the selected Model, Dialogflow uses the standard model.
  • Standard:  Select to use the standard model even if an enhanced model is available.
  • Unspecified: Select if you aren't sure which variant to use. Dialogflow defaults to the best available variant of the selected model.
Speaking Rate

Click + or – to change how fast the TTS voice speaks. The rate can be between 0.25 and 4.0. A normal speaking rate is 1.0. A rate of 2.0 is twice as fast as normal and 0.5 is half as fast as normal. The default is 0.

Pitch

Click + or – to change the pitch of the TTS voice. Pitch is the highness or lowness of the voice. The default is 0. The maximum is 20.0 and means the voice is 20 semitones higher than the default. The minimum is -20.0 and means that the voice is 20 semitones lower than the default.

Volume Gain

Click + or – to change the volume of the TTS voice measured in decibels (dB). The default is 0. The range is 16.0 to -96.0. A gain of +6.0 plays at approximately twice the volume of the default. Do not exceed +10 dB.
Single Utterance

When enabled, the system treats the interaction as single-turn request. It listens for one complete contact utterance, sends it to Dialogflow CX, and then ends the turn. When disabled, the system treats the interaction as an ongoing, multi-turn conversation.

Assign the Dialogflow CX VoiceStream App to an Action

Required permissions: Studio Script View, Create/Edit

When the virtual agentClosed The meaning or purpose behind what a contact says/types; what the contact wants to communicate or accomplish. app is set up and configured in Virtual Agent Hub, you need to assign it to the virtual agent action in your script. This connects the action and the script to your virtual agent provider.

  1. In Studio, open the script you want to modify.
  2. Locate the VOICEBOTSTREAM action in your script. If you haven't done so already, add it from the Actions palette.
  3. Click Open Editor on the action to open Virtual Agent Hub.

  4. In the left column, locate the virtual agent profile that you want to assign to the action and click the checkmark An icon of a circle with a checkmark inside. next to it.

    An alternative to using the checkmark is to create a variable in your Studio script. Use the variable to pass the virtual agent app name into the Virtual Agent ID property of the Virtual Agent Hub action you're using.

  5. Click Close.