Connect Virtual Agent for Flex (Public Beta)

Public Beta
This feature is currently available as a Public Beta product and information contained in this document is subject to change. This means that some of the features are not yet implemented and others may be changed before the product is declared as Generally Available. Public Beta products are not covered by a Twilio SLA.

Not a HIPAA Eligible Service
Virtual Agent for the Conversations channel is not a HIPAA Eligible Service and should not be used in Flex workflows that are subject to HIPAA.

Studio uses Widgets to represent parts of Twilio's API. You can combine Widgets in a Studio Flow to build robust applications that require no coding on your part.

The Connect Virtual Agent Widget allows you to connect a Twilio Voice call or Conversations chat to a Google Dialogflow CX agent. You can leverage a native integration between Twilio Voice and Dialogflow CX to provide customers with conversational AI experiences for Voice and Conversations channels.

Widget with Conversations channels

This Widget is specifically for Conversations channels for Flex along with the Voice channel. If you only need to use the Voice channel for Flex, see Connect Virtual Agent Widget.

Voice channel

The integration includes live agent handoff and customer barge-in. Twilio provides the telephony aspect of the conversational IVR experience and Dialogflow CX enables agent configuration, including setting intents, sentiment analysis, speech models, and agent responses.

Conversations channels

You can use the integration to handle incoming Conversations chats and, based on the escalation intent, route them to live agents and relevant services. Agents and supervisors can also access previous messages exchanged by the Virtual Agent and customer.

The integration works with the following channels:

  • SMS
  • Webchat 3.0
  • WhatsApp
  • Google Business Messages
  • Facebook Messenger

Enable this feature

If you would like to use the Connect Virtual Agent Widget with Flex for both Conversations and Voice, contact our support team for help enabling this Beta feature.

Set up the integration between Twilio and Dialogflow CX

To use the Connect Virtual Agent Widget, you must connect your Dialogflow CX agent to Twilio in the Google Dialogflow CX cloud console. Review the prerequisites and steps for the integration in the Dialogflow CX Onboarding Guide.

After you complete the integration, Twilio automatically creates a new Studio Flow containing a Connect Virtual Agent Widget that is connected to your Dialogflow CX agent. The Incoming Call trigger is automatically attached to the Widget. To use the Widget with Conversations channels, you can adjust the trigger to Incoming Conversation.

Note: If you want to use both Voice and Conversations, you need a separate Widget for each. Make sure that you match each trigger with the corresponding Widget. For example, Incoming Call connects to the Widget using Voice.

Required configuration for the Connect Virtual Agent Widget

The Connect Virtual Agent Widget requires the connector name for the Google Dialogflow CX instance. You can find the Connector Name in the Dialogflow CX Connector in the Twilio Console after you have completed the one-click telephony integration in the step above.

Name Description Default
Connector Name The unique name configured in your Dialogflow CX connector instance. empty
Channel The channel you want to use for your widget: Voice or Conversations Voice

Editing the Connector Name within the Connect Virtual Agent Studio Widget alone will break the integration between Dialogflow and your Twilio project. If you need to update the Connector Name, you must edit it in the Dialogflow CX Connector and the Studio Widget.

Optional Configuration for Connect Virtual Agent


The Connect Virtual Agent Widget accepts a number of Voice channel configuration options that you can use to configure agent calls and analysis.

Name Description Default
Status Callback URL URL to send status callback events from Twilio empty
Status Callback Method The HTTP method to use when requesting the statusCallback URL. Accepted values are GET or POST. POST
Parameters Key-value pairs used to send custom session parameters to your virtual agent to drive personalization and/or parameterize your agent’s response empty
Configurations Key-value pairs used to override underlying connector properties (e.g. language, sentimentAnalysis, voiceName, welcomeIntent, etc.) and/or modify your virtual agent’s default behavior empty


For Conversations channels, you can configure the Connect Virtual Agent Widget with the following:

Name Description Default
Virtual Agent Timeout How long the Virtual Agent should wait for a reply from an unresponsive customer before the Timeout transition is triggered. 48 hours

Connect Virtual Agent Transitions

These events trigger transitions from this Widget to another Widget in your Flow. For more information on working with Studio transitions, see this guide.

Name Description
Completed The Dialogflow CX agent ended the connection because an intent matched the "end of the conversation" intent indicating the call completed successfully
Live Agent Handoff The Dialogflow CX agent returned a live agent handoff response indicating the call needs to be escalated to a human agent
Hangup (Voice only) The caller hung up during the Dialogflow CX agent interaction
Timeout (Conversations only) The conversation timed out because the Virtual Agent had to wait too long for a reply from a customer
Failed An error occurred during VirtualAgent processing

Connect Virtual Agent Variables

When the Connect Virtual Agent Widget executes, it will have stored the following variables for use throughout your Studio Flow (where MY_WIDGET_NAME is the name of your actual Widget). For more information on working with variables in Studio, see this guide.

Name Liquid Template Language
VirtualAgentProvider {{widgets.MY_WIDGET_NAME.VirtualAgentProvider}}
VirtualAgentStatus {{widgets.MY_WIDGET_NAME.VirtualAgentStatus}}
VirtualAgentProviderData {{widgets.MY_WIDGET_NAME.VirtualAgentProviderData}}
VirtualAgentError {{widgets.MY_WIDGET_NAME.VirtualAgentError}}
VirtualAgentErrorCode {{widgets.MY_WIDGET_NAME.VirtualAgentErrorCode}}

VirtualAgentError and VirtualAgentErrorCode will be present if status is failed (if the Widget ends through the Failed transition). VirtualAgentProviderError may also be provided if VirtualAgentErrorCode is 32601.


For Google Dialogflow CX agent, the VirtualAgentProviderData JSON object may contain the following information. Note that this variable might be empty if the Widget exited through the Failed transition.

JSON key Description
ConversationId ConversationId: Unique identifier for this conversation provided by Google
EndUserId Unique identifier for the end user participant provided by Google
AgentHandoffParameters Parameters included from the Dialogflow CX Agent if the Live Agent Handoff Transition was triggered
Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Thank you for your feedback!

Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!