This HowTo will show how you can connect Dialogflow CX to Voximplant for inbound calling. 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 other Dialogflow tutorials:
This HowTo 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
The first step to connecting 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:
You will be prompted to specify an integration name with a language and environment:
Note that you can have multiple independent integrations with Voximplant using different parameters.
Then you will 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.
Once you signed in, you may select an existing phone number in your Voximplant account or purchase a new phone number. If using an existing phone number, make sure it is not assigned to an application.
If purchasing a new phone number, select the appropriate parameters:
Once you select your phone number, you will be directed back to the Dialogflow CX console:
From here you can use the three dots menu and choose Manage to log into the Voximplant Management console or Disconnect to destroy the connection. If you had issues or stopped during the One-click integration procedure you will 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.
Subsequent integrations with the same Dialogflow CX agent will be associated with the same application. You can always manage your numbers from inside Voximplant through the Numbers menu.
Using Dialogflow CX Telephony Integration Features
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.
To configure the no speech timeout period and enabled barge-in, you must first enable Advanced Speech Settings from the Agent Settings screen:
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-1, etc. See the Dialogflow CX Handler documentation for details. These events are triggered after the specified no speech timeout.
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 set 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.
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 will start as soon as a fulfillment message plays.
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
Using entities to identify DTMF
Optionally, you can use an Entity to identify DTMF entries using a regular expression.
The Dialogflow CX console only handles DTMF entries as parameters. Make sure the parameter type accepts numbers as well as
# if you use those DTMF keys. You will see an option to Enable DTMF under Advanced Speech Settings.
You can specify a maximum number of digits to recognize. Optionally you can also specify a finish digit.
See the Dialogflow CX parameter documentation for more information.
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 Modifying 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:
Voximplant’s Dialogflow Connector with CX telephony integration will playback these sounds with no additional VoxEngine application logic required.
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 will be 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.
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.
Then, after the PlaybackFinished event indicates any preceding synthesized speech or audio has been played, this
transfer value is checked, an outbound call is initiated with VoxEngine.callPSTN and finally, the media is connected using 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
This code can be modified to insert routing logic, place calls via SIP, start recording, and much more using the myriad of features available via VoxEngine.
Note that the default connector template assumes the call will remain attached to the Dialogflow agent. See the next section for an example of how to modify this code.
Modifying VoxEngine interaction
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 will 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.
Using 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:
Here we initiate the outbound call with
VoxEngine.callPSTN like the standard template but add an event listener that starts the
easyProcess only after that outbound call is connected.
Then we add the optional callback function to send an event using 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.
Dialogflow CX setup
In this example, we will create a distinct Live Agent page that is loaded after a transfer intent. Setup the Entry fulfillment just like the Call Transfer example above.
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.
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:
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.