Rate this page:

Dialogflow CX

This article will show how to connect Dialogflow CX to Voximplant for incoming and outgoing calling.

Dialogflow is a virtual agent that handles conversations with your end-users. It is a natural language understanding module that understands the nuances of human language.

Dialogflow CX is an advanced agent type suitable for large or very complex agents.

Here, we also highlight how to enable Dialogflow CX’s telephony integration features inside the Dialogflow CX console (as of March 2021), including:

  • No speech timeout

  • DTMF interaction

  • Playing pre-recorded messages

  • Live Agent Handoff

Dialogflow CX is Google Cloud’s newest interface for Dialogflow aimed at customer experience applications. Dialogflow ES users (formerly just Dialogflow) should refer to our Dialogflow ES guide.

Already have one-click integration and want to go straight to outgoing calling?

Scroll down to the last two sections: Outbound calling and Call lists

This article assumes you already have a Dialogflow CX agent configured. See Google Cloud’s documentation for details on using Dialogflow CX. We recommend examining Dialogflow’s Healthcare pre-built agent, which includes many telephony features.

One-click telephony integration

Copy URL

The first step to connect Dialogflow CX to Voximplant is using the One-click Telephony integration. Go to the Google Cloud Dialogflow CX console and select your agent. Then from the Manage menu, select Integrations, and click Connect on Voximplant:

Go to Google Cloud Dialogflow CX console

You are prompted to specify an integration name with a language and environment:

Create a new integration

Note that you can have multiple independent integrations with Voximplant using different parameters.

You then need to give Voximplant permission to access your Dialogflow account. If you are not already signed into Voximplant, you will be prompted to sign in or create an account.

Sign in or create an account

Once signed in, you may select an existing phone number in your Voximplant account or purchase a new phone number. If you use an existing phone number, make sure it is not assigned to an application.

If purchasing a new phone number, select the appropriate parameters:

Purchase a phone number

Once you select your phone number you are directed back to the Dialogflow CX console:

Manage the integration

From here you can use the three dots menu and choose Manage to log in to the Voximplant Management console or Disconnect to destroy the connection. If you had issues or stopped during the One-click integration procedure you also have the option to resume the integration process from where you left off.

If you click on Manage to go to the Voximplant console and click Applications or visit the Voximplant control panel - Applications directly, you will see your newly created application.

Your application

Subsequent integrations with the same Dialogflow CX agent are associated with the same application. You can always manage your numbers from inside Voximplant through the Numbers menu.

Use Dialogflow CX telephony integration features

Copy URL

The Voximplant Dialogflow CX has many telephony interaction capabilities built directly into the agent console. The VoxEngine code that is automatically created during the integration handles these interactions.

Agent settings

To configure the no speech timeout period and enabled barge-in, you must first enable Advanced Speech Settings from the Agent settings screen:

Agent settings

Once enabled, you can change these settings within each flow and route.

No speech timeout

Dialogflow CX includes several built-in event handlers for when a user does not respond to a prompt: sys.no-input-default, sys-no-input-1, etc. See the Dialogflow CX Handler documentation for details. These events are triggered after the specified no speech timeout.

Please note

The no speech timeout timer begins as soon as a prompt is returned at the beginning of speech synthesis. If the no speech timeout is too short, it can trigger before the prompt finishes playback. Make sure you set this value to a large enough number that your prompts have time to finish and your users have a chance to respond.

Barge-in

CX also supports stopping playback and new intent matching if a user interrupts a response, known as barge-in. Unlike Dialogflow ES, Dialogflow CX handles no speech detection and barge-in capabilities and does not require special handling inside VoxEngine.

If enabled, intent detection starts as soon as a fulfillment message plays.

DTMF interaction

Dialogflow CX with Voximplant’s Dialogflow Connector also handles DTMF natively without any specific VoxEngine code. Entered DTMF digits are managed as part of Dialogflow CX Parameters.

Pressed DTMF digits are passed into Dialogflow as text numbers and dtmf_digits_432* where whatever digits we pressed are added after dtmf_digits_.

Use entities to identify DTMF

Optionally, you can use an Entity to identify DTMF entries via a regular expression.

Entities

Sending events

You can send supported events from Voximplant's side for Dialogflow CX's event handler to process the event. To send the event, define sendEventin the MarkerReached. Please note, that you need to stop the outgoing media to the conversation participant in order for Dialogflow CX to receive the event. Then use the analyzeContent method to send the event as it is shown in the code example:

Sending events

Sending events

Parameter setup

The Dialogflow CX console only handles DTMF entries as parameters. Make sure the parameter type accepts numbers as well as * and # if you use those DTMF keys. Find Enable DTMF under Advanced Speech Settings.

You can specify a maximum number of digits to recognize. Optionally you can also specify a finish digit.

Parameters setup

See the Dialogflow CX parameter documentation for more information.

Please note

Currently, the DTMF implementation only works if the parameter is marked as required. For handling scenarios like “press 0 for a live agent” and more complex DTMF entry, we recommend implementing a DTMF event handler in VoxEngine to trigger a custom event. See the Modify VoxEngine interaction example further below to see how to initiate custom events.

Play a recording

The Dialogflow CX console includes an option to specify an audio URL:

Audio file to play

Voximplant’s Dialogflow Connector with CX telephony integration plays back these sounds with no additional VoxEngine application logic required.

Call transfer

Dialogflow CX console

Dialogflow CX includes a Live Agent handoff option within the routes options on each page. Simply select this value and a liveAgentHandoff value is included in the response to Voximplant that can be used to initiate the call.

Optionally you can also pass arbitrary data along with the request in JSON format. For example, you could specify a specific call center or department for proper routing within VoxEngine.

Specific call center

See the Dialogflow CX fulfillment documentation for more information.

How it works in VoxEngine

The default VoxEngine scenario created during the One-click integration contains the logic necessary to transfer the agent. You only need to enter the destination number and caller ID values.

The following snippet shows how VoxEngine recognizes a liveAgentHandoff request. The template code simply sets a global transfer variable to true.

Recognize a liveAgentHandoff request

Recognize a liveAgentHandoff request

Then, after the PlaybackFinished event indicates any preceding synthesized speech or audio has been played, this transfer value is checked, an outgoing call is initiated with VoxEngine.callPSTN and finally, the media is connected with VoxEngine.easyProcess. Make sure to enter the destination phone number - such as your call center - and one of your caller IDs as part of the callPSTN function.

Initiate a call

Initiate a call

This code can be modified to insert routing logic, place calls via SIP, start recording, and much more.

Note that the default connector template assumes the call remains attached to the Dialogflow agent. See the next section for an example of how to modify this code.

Modify VoxEngine interaction

Copy URL

As a full featured Communications Platform as a Service (CPaaS), Voximplant provides tremendous flexibility in how you can communicate with both Dialogflow and telephony networks.

In this example, we change the call transfer behavior to signal when the call transfer is successful and pass control back to Dialogflow CX in the case of a call failure.

Use VoxEngine events, callbacks, and CCAI methods

Let’s alter the CCAI.Events.Participant.PlaybackFinished code to show how we can monitor the telephony connection and send events to Dialogflow CX:

Monitor the telephony connection

Monitor the telephony connection

Here we initiate the outgoing call with VoxEngine.callPSTN like the standard template but add an event listener that starts the easyProcess only after that outgoing call is connected.

Then we add the optional callback function to send an event via the conversation object returned from the CCAI module, conversation.addParticipant, earlier in the default template. In this case, we send a TRANSFER_SUCCESS event and then use the endConversation function from the template to end the Dialogflow CX connection.

See the Dialogflow CX QueryInput documentation for options and the format for sending query input.

In addition to monitoring the CallEvents.Connected event, we also add a CallEvents.Failed handler, but this time we send a TRANSFER_FAIL event to Dialogflow.

Dialogflow CX setup

In this example, we create a distinct Live Agent page that is loaded after a transfer intent. Setup the Entry fulfillment just like the Call Transfer example above.

Create a distinct Live Agent page

Dialogflow CX allows creating custom events if you go to Event handlers on your page. Click on the plus sign next to Event handlers or Add event handler from the Event handlers frame.

Add event handler

Then click on Use custom event and enter the event name you specified in VoxEngine. Add any fulfillment and specify the transition flow or page:

Set up the event

Make sure to repeat this for each custom event you specify in VoxEngine. TRANSER_SUCCESS might transition to End Session and TRANSFER_FAILED could go to another page to handle the error or try different Live agent handoff details.

Change your agent’s voice

Copy URL

Dialogflow CX does not include a user interface for selecting your agent’s synthesized voice (unlike Dialogflow ES). However, the voice can be specified programmatically inside VoxEngine.

To change the text-to-speech voice, add a synthesizeSpeechConfig object to the replyAudioConfig within dialogflowSettings as part of the conversation.addParticipant configuration object. See the example for the object structure:

Specify the agent's voice setting

Specify the agent's voice setting

Any Google Cloud text-to-speech voice can be used, including different languages. See the list of available Google Cloud text-to-speech voices here.

If you need to use a non-Google voice for any reason, you can process the agent's response event, then read the reply to your customer using Voximplant speech synthesis engine:

Use a non-default voice

Use a non-default voice

Alternatively, you may use the VoiceList.Google constant list equivalents instead to align with other Voximplant-based speech synthesis used in your scenario – i.e. voice: { name: VoiceList.Google.en_US_Wavenet_C.voice }. See the Voximplant’s VoiceList reference documentation for the list of available Google voices.

Outbound calling

Copy URL

If you want to use this scenario with outgoing calling, you need to remove the AppEvents.CallAlerting code block and create a new AppEvents.Started block. The most important thing here is the callPSTN method that we apply to make a call when the scenario has started. Use the following logic:

AppEvents.Started code block

AppEvents.Started code block

You may wonder what to do with the old AppEvents.Started block. It’s simple: move its contents to the newly created onCallConnected function and delete the old block:

onCallConnected function code

onCallConnected function code

Everything else remains the same.

Now you just have to start the scenario. To do so, go to the Rules section and run the rule attached to your scenario:

Start the scenario

Or use the StartScenarios method of our management API. Don’t forget to specify the phone number as script custom data. Otherwise, there is no number to call.

Call lists

Copy URL

Sometimes you need to call not just one phone number, but a lot of them. This is when you use call lists. First of all, design your CSV file representing a call list. Its data is passed to the VoxEngine scenario as a JSON string that we parse. Our CSV file contains the names and phone numbers of the people we call:

first_name;last_name;phone_number
Jon;Snow;+16501234567
Daenerys;Targaryen;+16501234568

Now we can modify the scenario, so it processes every string of the file and make calls. Your AppEvents.Started block should look like this (we do not need the AppEvents.CallAlerting block here):

AppEvents.Started for call lists

AppEvents.Started for call lists

The onCallConnected function remains the same as it was for the outgoing call to one person:

onCallConnected for call lists

onCallConnected for call lists

And tell the CallList processor about a successful or unsuccessful call result:

Call results

Call results

The last thing we do is choose the Call lists section in your application menu, create a list (automatic or manual), upload the CSV file, and launch the list by running the rule if it’s manual (automatic lists are launched immediately after creation).

The call results are available in the Call history section. Learn more about call lists in the Call lists for automated calls article.