Rate this page:

TwiML™ Voice: <VirtualAgent>

Virtual Agent is in Public Beta. Learn more about Twilio's beta product support here.

The <VirtualAgent> TwiML noun allows you to connect a Twilio Voice call to a Dialogflow Essentials (ES) agent.

You can leverage a native integration between Twilio Voice and Google’s Dialogflow ES to provide callers with conversational experiences through their Interactive Voice Response (IVR). The integration also supports Google’s Contact Center AI (CCAI) Virtual Agent.

Google's Dialogflow Customer Experience (Dialogflow CX) is not supported with this integration. Dialogflow's Barge-in and Dual-tone multi-frequency signaling (DTMF) features are also not supported.

Twilio provides the telephony aspect of the conversational IVR experience, and Dialogflow ES manages agent configuration, including intents and responses, via the Dialogflow ES console or Dialogflow APIs.

Connect your Dialogflow ES agent to Twilio from the Dialogflow ES console. Choose the "Twilio" One-Click Telephony integration in the Integrations section of the Dialogflow ES console, and follow the prompts to complete the setup. Once the integration is complete, you can use Twilio to manage the flow of your calls and configured connections to Dialogflow ES agents.

How It Works

You can manage the Dialogflow agent via the Dialogflow ES Console or the Dialogflow API. With Twilio, you can define and manage everything else that happens on a call before and after a Dialogflow agent interaction.

Twilio will create a new Studio Flow containing a Connect Virtual Agent widget when you connect a Dialogflow ES agent to Twilio via the One-Click Integration. When a call comes in to the Twilio number you've configured for the integration, Twilio will connect the call directly to the Dialogflow ES agent. Once the Dialogflow ES agent interaction ends, the call will end.

However, you can further configure what happens before and after the Dialogflow agent interaction with TwiML or through the Studio widget.


The <VirtualAgent> TwiML noun should be nested inside the <Connect> verb. When the <Connect> runs, Twilio will connect the caller with the specified Dialogflow ES agent. When the caller starts speaking, the Dialogflow agent will match intents based on what the caller says. When the Dialogflow ES agent interaction ends, either through an "end of conversation" intent or through the caller hanging up, the <Connect> verb completes.

  <Connect action="">
    <VirtualAgent connectorName="project" statusCallback=""/>


<VirtualAgent> supports the following attributes:

Attribute Name Description Default Value
connectorName Required. Configured in Dialogflow ES connector instance in the Unique Name Field. Appears as "Unique Name" in the connector. none
language Optional. Language in which the caller will be interacting with the Dialogflow ES agent, e.g., "en-US". Learn more about Multilingual Dialogflow ES agents here. Defaults to the language provided in the connector configuration.
sentimentAnalysis Optional. Boolean, enable sentiment analysis or not. Defaults to the setting in the Dialogflow ES connector configuration.
statusCallback Optional. URL to post status callbacks from Twilio. none

<Connect> supports the following attributes related to <VirtualAgent>:

Attribute Name Description Default Value
action Optional. URL at which your app is hosted. After Dialogflow ES execution is done, Twilio will make a request to this URL to receive any further TwiML instructions for this call (ex: to connect the caller to an agent). None


              When a status change happens in Dialogflow ES, Twilio will make an HTTP POST request to the URL you specified with the statusCallback attribute with the following information:

              Parameter Description
              CallSID The Twilio CallSID
              ConversationID ID received from Google when creating the conversation profile
              EndUserID End-user participant ID provided by Google
              ResponseID The unique identifier of the response.
              VirtualAgentEvent The event triggering the callback.
              Ex: "virtual-agent-intent-received"
              VirtualAgentError If applicable, the error returned from Dialogflow ES.
              VirtualAgentErrorCode If applicable, the error code returned from Dialogflow ES.
              IntentDisplayName The name of this intent.
              Ex: "room.reservation"
              IsFallback Indicates whether this is a fallback intent.
              LiveAgentHandOff Indicates whether this intent triggers a handoff to an agent within the Dialogflow ES agent configuration.
              EndInteraction Indicates that this intent ends an interaction.
              QueryText Contains the speech recognition result. If speech recognizer produced multiple alternatives, only one is returned.
              Ex: "I want to book a room in San Francisco"
              Parameters A JSON string containing any matched parameters.
              Ex: '{"location": "San Francisco"}'
              FulfillmentText Dialogflow ES agent's response to the caller query.
              Ex: "What date is your meeting?"
              LanguageCode The language that was triggered during intent detection.
              Ex: "en-US"
              IntentDetectionConfidence The intent detection confidence. Values range from 0.0 (completely uncertain) to 1.0 (completely certain).
              SentimentAnalysisScore Sentiment score between -1.0 (negative sentiment) and 1.0 (positive sentiment).
              SentimentAnalysisMagnitude A non-negative number in the [0, +inf) range, which represents the absolute magnitude of sentiment, regardless of score (positive or negative).
              IsSpeechRecognitionFinal Boolean representing if results are final.
              SpeechRecognitionConfidence The Speech confidence between 0.0 and 1.0 for the current portion of audio.
              WebhookStatus The Dialogflow ES webhook status, if configured.

              In the TwiML example below, the caller will first hear the text in the <Say> block, and then the call will connect to the Dialogflow ES agent. After the Dialogflow ES agent ends the connection (when an intent matches the end of the conversation intent), Twilio will make an HTTP POST request to the URL specified in the action of <Connect> to determine what should happen next on the call.

              While the Dialogflow ES agent interaction is in progress, Twilio will make HTTP POST requests to the statusCallback URL when specific events occur during the agent interaction (for example, when an intent is matched).

                <Say>Hello! You will be now be connected to a virtual agent.</Say>
                <Connect action="">
                  <VirtualAgent connectorName="project" statusCallback=""/>

                    Alternatively, you can add more TwiML after the <Connect> block if you do not provide an action URL. In the example below, when the Dialogflow ES agent ends the call, the <Connect> verb is completed and the next TwiML verb, <Say>, will be executed.

                        <VirtualAgent connectorName="project" statusCallback=""/>
                      <Say>Thank you for your call. Goodbye.</Say>

                    If you provide an action URL in the <Connect> verb, Twilio will make an HTTP request to that URL immediately following the termination of the Dialogflow ES agent connection. Any remaining TwiML following the initial <Connect> will not be executed.

                    The primary way to update what happens during the Dialogflow ES agent interaction is directly in Dialogflow ES agent configuration. However, you can update a call that's in progress using TwiML at any point, including during a Dialogflow ES agent interaction. Note that updating a call in the middle of a Dialogflow ES agent interaction will end that agent interaction and begin a new set of TwiML instructions.

                    Customize your Twilio Dialogflow ES integration

                    You can change the default language and sentiment analysis settings for the Dialogflow ES integration from the Dialogflow ES Stream Connector.

                    Do not update the Unique Name, ProjectID or Conversation_Profile_ID, as this will break the integration. If you need to update the Unique Name, you must also edit the Connector Name field in the Connect Virtual Agent Studio widget.

                    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 Community Forums or browsing the Twilio tag on Stack Overflow.


                          Thank you for your feedback!

                          We are always striving to improve our documentation quality, and your feedback is valuable to us. Please select the reason(s) for your feedback or provide additional information about how we can improve:

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

                          Thanks for your feedback!

                          Refer us and get $10 in 3 simple steps!

                          Step 1

                          Get link

                          Get a free personal referral link here

                          Step 2

                          Give $10

                          Your user signs up and upgrade using link

                          Step 3

                          Get $10

                          1,250 free SMSes
                          OR 1,000 free voice mins
                          OR 12,000 chats
                          OR more