Rate this page:

TwiML™ Voice: <VirtualAgent> with Dialogflow ES

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).

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.

<VirtualAgent> also supports Dialogflow CX agents. See the documentation for the Dialogflow CX integration here.

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 a Programmable Voice call to a Dialogflow ES agent


        Before using <VirtualAgent>, you must complete the Dialogflow ES one-click integration.


        <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

              Change the Dialogflow ES Agent language


                    Enable Sentiment Analysis for a Dialogflow ES agent call


                    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=""/>

                          Say a message before connecting a Programmable Voice call to a Dialogflow ES agent

                          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"/>
                              <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 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!