Integrate Google Dialogflow ES

Before completing the tasks on this page, be sure that the prerequisites for the integration have been met.

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 and requirements. Your script must have the phone media type A medium, such as voice, email, and chat, through which a contact connects with an intended recipient. for a voice virtual agent or the digital media type for a text virtual agent. The supported virtual agent actions for this provider are:

• VoiceBot Exchange
• TextBot Exchange

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

When your virtual agent is ready to go into production, assign the script to one or more points of contact.

Custom Payload Best Practices

Follow these best practices when integrating custom payload data Google Dialogflow ES into CXone: 

• CustomPayload is used to pass context for an intent The meaning or purpose behind what a contact says/types; what the contact wants to communicate or accomplish. Context helps the virtual agent understand the user's intent. Contexts aren't required, but they help the virtual agent match an utterance What a contact says or types. to an intent.
• In a Snippet action in your script, create a customPayload object that follows the format outlined in the Google Dialogflow ES documentation for REST Resource: projects.agent.sessions.context. The Studio online help provides additional information about dynamic data objects.
• You can also pass custom data with customPayload without contexts. To do this, include standard JSON key-value pairs in a dynamic data object.
• Speech contexts are passed in custom payload in the speech_contact parameter. You can see the contents of this parameter in Studio traces and application logs.
• The customPayload dynamic object is passed as a virtual agent parameter as JSON, as shown in the example script.

• Speech context hints can be passed with custom payload in the speechContexts parameter. The value of speechContexts.phrases must be a Google class token for the hint you want to give. The token must match the language and locale of your contacts. For example:

  DYNAMIC customPayload
  customPayload.speechContexts.phrases="$OOV_CLASS_ALPHANUMERIC_SEQUENCE"
  customPayload.speechContexts.boost=10		

Add an App to Virtual Agent Hub

Required permissions: Automation & AI > Launch Automation & AI

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

1. In CXone, click the app selector and select Other > Automation & AI 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 Google Dialogflow ES 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. If you're setting up a text virtual agent, select Text Only (No Voice Support) on the Voice page. If you're setting up a voice virtual agent, see the Configure Voice Integration Options section on this page.

8. Click Next.

9. On the Transcript page, select the option for whether you want the conversation transcript and intent information captured.

   Learn more about fields in this step

   Option	Details
   Do Not Capture or Archive Transcript or Intent Info	Select this option if you don't want to capture conversation transcriptions or intent The meaning or purpose behind what a contact says/types; what the contact wants to communicate or accomplish information.
   Capture and Archive Intent Info 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.
   Capture and Archive Transcript and Intent Info	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.

10. Click Next.

11. On the Test + Add page, you can test your bot's connection by sending voice or text prompts. If your test messages don't work, click Back to return to the Configuration page and verify the settings. You may also need to verify configurations in your virtual agent provider's management console.

12. Click Add.

Google Dialogflow ES 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 is the first version of Virtual Agent Hub. The custom payload object returns as customPayload.payload.xxxx. Version 2.0.0: This version updated the schemas used with Google Dialogflow ES. This impacts the structure of the customPayload object. Version 3.0.0: This version introduced StandardBot, which standardizes how CXone communicates with virtual agent providers. The customPayload object returns as an array, as customPayloadscriptPayloads[n].xxxx. This version is available for all providers.
Customer GCP Project ID	Your organization's Google Cloud Project ID. This is the identifier for your virtual agent. You can find it in the Google Dialogflow ES console settings. This field is visible only if you are using an OEM service account.
JSON Service Account	The service account key file you created and downloaded from your Google Cloud Console. Copy and paste the entire content of the key file into this field. This field is visible only if you're using your own Google Dialogflow ES account. 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" }
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 your Google Dialogflow ES virtual agent is located.
Environment	The name of the custom environment your virtual agent is published to. If you leave this field blank, the draft environment is used.
Perform Output TTS	Enable this option if you want to use the Google Dialogflow ES text-to-speech (TTS Allows users to enter recorded prompts as text and use a computer-generated voice to speak the content.) service. Configure the TTS output settings. If you don't to use the Google TTS service, you can use CXoneCloud TTS Hub. You configure this option on the Voice page of the configuration app wizard.
Timeout Event	Name of the Google Dialogflow ES event you want to trigger on timeout.
DTMF Break Out Pattern	Enter the characters that, when pressed during a call, cause the virtual agent to skip to the DTMFBreakout branch of the Studio script. Complete this field only if this is a voice virtual agent.
Use Google Protobuf JSON Serializer	Enable this option to use Google Protobuf Serializer. Serialized responses improve performance by reducing the size of the responses and the memory required to process them. The size reduction makes it less likely that responses will exceed 32KB, which is the general size limit for script variables. NICE CXone recommends that you enable this option. If you need to disable it for any reason, it should be re-enabled as soon as the issue is resolved. If you set up your Google Dialogflow ES integration prior to the Spring 2022 version of CXone , it's important that you check your scripts for payload parsing. Anywhere you find this, you need to replace it with parsing from the new schema before you enable this option in your integration. For example, if your script currently references something like this:  {parameters.fields.myfield.stringValue} you would change it to:  {parameters.myfield}
External Provider Timeout	Enter the number of seconds you want the script to wait for a response from Dialogflow ES . When the timeout is reached, control returns to the script, which takes the error branch.

Configure Google Dialogflow ES TTS Output

Required permissions: Automation & AI > Launch Automation & AI

Complete the steps in this section if you want to use the Google TTS service. The fields in the following image appear when you enable the Perform Output TTS option on the Dialogflow ES Configuration page in Virtual Agent Hub.

1. In Virtual Agent Hub, add a new configuration app and configure it according to the steps in Add an App to Virtual Agent Hub section on this page.
2. EnablePerform Output TTS.

3. To use a custom voice model, enable Use Custom Voice and enter the name of the AutoML model you want to use in the Custom Voice Model field.

   View image

   

   Learn more about the fields in this step

   Field	Details
   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. This field is only visible when Perform TTS Output is enabled.

4. If you want to use a Google voice model, select the TTS Voice Name from the drop-down.

5. Select the machine learning Model and Model Variant that you want the Google TTS services to use when synthesizing speech.

   Learn more about the fields in this step

   Field	Details
   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. 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. 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.

6. To add silence to the start of the virtual agent's audio response, enter the number of milliseconds of silence to add in the Add Leading Silence field. The recommended amount of silence is 500 milliseconds.

7. Enter the Speaking Rate, Pitch, and Volume Gain to configure how you want the TTS voice to sound.

   Learn more about the fields in this step

   Field	Details
   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. This field is only visible when Perform TTS Output is enabled.
   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. This field is only visible when Perform TTS Output is On.
   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. This field is only visible when Perform TTS Output is On.

8. Return to the Add an App to Virtual Agent Hub section  on this page to finish adding the configuration app.

Configure Voice Integration Options

Required permissions: Automation & AI > Launch Automation & AI

If you're setting up a text virtual agent, you can skip this section.

1. In Virtual Agent Hub, add a new configuration app and configure it according to the steps in the Add an App to Virtual Agent Hub section  on this page.

2. Click Next on the Configuration page.

3. On the Voice page under Voice Integration Options, select Turn by Turn Control (CXone Voice Bot Gateway).

4. If the form won't allow you to select Use CXone Cloud TTS, click Back to return to the Configuration page. Click the Perform Output TTS slider to Off. You can now enable Cloud TTS Hub on the Voice page.

5. Select a TTS Vendor, if you're using Cloud TTS Hub. If you're using your virtual agent provider's TTS service, this field is not visible and you can skip this step.

6. Under Transcription Options, select the option for the transcription service you want to use.

   Learn more about fields in this step

   Field

   Details

   Transcription Options

   Select the service you want to use for transcription: Use bot account transcription: Select this if your want to use your virtual agent provider's transcription service. Audio from the contact's utterances is sent to the provider before being transcribed. Use CXone transcription profile: Select this if you want to use a CXone transcription profile. You can learn more about this option on the CXone Turn-by-Turn Transcription help page.

7. If you choose to use a CXone transcription profile, click Transcription Profile to select the one you want to use. Click Add New Turn by Turn Transcription Profile to create a new profile.
8. Click Next.
9. Return to the Add an App to Virtual Agent Hub section  on this page to finish adding the configuration app.

Assign the Google Dialogflow ES App to an Action

Required permissions: Studio Script View, Create/Edit

When the virtual agent 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. If you haven't done so already, click the Tools tab, expand the Automation and AI category, and add the virtual agent action you want to use. Be sure to put it in the correct location in your script. If you don't see the action you expect, verify that your script media type is correct. For example, if you're creating a script for a voice virtual agent, the script must be a phone script.

3. Double-click the action to open Virtual Agent Hub.

   View image

   
4. In the left column, locate the virtual agent that you want to assign to the action and click the checkmark next to it.
5. Click Close.

Change the Transcription Profile

Required permissions: Automation & AI > Launch Automation & AI

A transcription profile allows you to use a different transcription service from the one the virtual agent provider offers. Each virtual agent can have one transcription profile. You only need to follow the steps in this section if you are working with a voice virtual agent and need to change the transcription profile.

1. In CXone, click the app selector and select Other > Automation & AI 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. In the list of virtual agent configuration apps on the left side of the Virtual Agent Hub page, click the one you want to modify.
3. In the center of the virtual agent app properties page, click the Voice tab.

4. Under Transcription Options, select Use CXone transcription Profile if it isn't already selected.

5. Select the Turn by Turn Transcription Profile you want this virtual agent integration to use. If the option you want to use isn't there, you can add it.

6. Click Save.
7. Test your transcription service by using the microphone option in the Test section of your virtual agent app properties page.

Test Your Virtual Agent

Required permissions: Automation & AI > Launch Automation & AI

You can test many aspects of your virtual agent to make sure everything works as intended. You can run tests from the virtual agent app's properties page in Virtual Agent Hub. When testing, you can: 

• Verify that the virtual agent app is correctly configured to communicate with the virtual agent provider.
• Add custom payload JSON to test the virtual agent's handling of custom payload data.
• Trigger a welcome intent event to test how the virtual agent begins a conversation.
• Trigger a custom intent event to test any custom events you've created for your virtual agent.
• Trigger a timeout event to test how the virtual agent responds when the contact times out.
• Test how the virtual agent handles DTMF Signaling tones that are generated when a user presses or taps a key on their telephone keypad. input.

The following image is an example of the properties page for a virtual agent app in Virtual Agent Hub. It shows the Configuration and Voice tabs and the Test pane.

1. In CXone, click the app selector and select Other > Automation & AI 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 to select the configuration app for the virtual agent you want to test from the list on the left.

3. In the Test pane, enter a test message in the Type a message field and press Enter to send it. You can also click Microphone and speak into your computer's microphone.

4. Click Start with welcome intent to start a test conversation from the beginning. The virtual agent responds with its default welcome message. You can enter test messages.

5. Click More Options to test other aspects of your virtual agent.

   Learn more about fields in this step

   Field	Details
   Add Custom Payload JSON	Select to test sending custom payload JSON to your virtual agent. Enter the custom payload in the Add Custom Payload JSON text box that appears on the Test + Add page. Press Enter after each line. Send a test message when you're ready to test the custom payload. When you're finished testing custom payload, click Close on the Add Custom Payload JSON pane.
   Trigger Welcome Intent Event	Select to test the default Welcome intent The meaning or purpose behind what a contact says/types; what the contact wants to communicate or accomplish. The virtual agent sends the welcome message. Enter a message to respond.
   Trigger Custom Intent Event	Select to test a custom intent event. Enter the Event Name in the pop-up that appears and click Trigger. The virtual agent sends the message for the intent you entered. Send a response to test the intent.
   Trigger Timeout Event	Select to view the default timeout intent. The virtual agent sends the timeout response message that it's configured with.
   DTMF Input	Select to test your voice virtual agent's response to DTMF Signaling tones that are generated when a user presses or taps a key on their telephone keypad. tones. Enter DTMF Characters and click Input to see the virtual agent's response to those characters.

6. Click Reset to start your test again.

7. If you need to make changes based on the results of your testing, you can: 

   • Modify the Studio scripts for the virtual agent.
   • Modify the configuration settings in the virtual agent's app in Virtual Agent Hub.
   • Modify the virtual agent's configuration settings in the provider's console. Click the large square button on the app properties page in Virtual Agent Hub. The example at the beginning of this section shows the Google Dialogflow CX app with the provider button. It has the icon on it to indicate that the link opens an external site.
8. Test the virtual agent thoroughly after each change to your scripts or any configuration settings.
9. When you're finished testing, click Close.