Menu

Expand
Rate this page:

TwiML™ Voice: <VirtualAgent> with Dialogflow CX

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

The <VirtualAgent> TwiML noun, used with Twilio's Google Dialogflow ES and CX Connector Add-ons, allows you to connect callers to a Google Dialogflow agent. <VirtualAgent> nests inside the <Connect> verb to direct a call to a Dialogflow agent.

This document describes how to use <VirtualAgent> with a Dialogflow CX agent. See documentation for <VirtualAgent> with Dialogflow ES here.

Set up the integration between Twilio and Dialogflow CX

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

<Connect> attributes

<VirtualAgent> is a TwiML noun that is nested within the <Connect> verb.

<Connect>'s action and method attributes allow you to execute a new set of TwiML instructions for a call after the <Connect><VirtualAgent> session ends.

Attribute Name Allowed Values Default Values
action Relative or absolute URL Current TwiML document URL
method GET, POST POST

action

The action attribute takes an absolute or relative URL as a value. After a <Connect><VirtualAgent> session ends, Twilio will send an HTTP request to this action URL and will expect a new set of TwiML instructions in the response. If you do not provide an action attribute, Twilio will request TwiML from the current TwiML document.

The following code sample is an example of using the action attribute with <Connect> and <VirtualAgent>.

        
        
        

        For Dialogflow CX, this HTTP request's body will contain additional information about the result of the <Connect><VirtualAgent> session, along with Twilio's standard request parameters. A <Connect><VirtualAgent> session ends (and thereby triggers Twilio's HTTP request to the action URL) in the following ways:

        • The Dialogflow CX agent session ends successfully and the caller did not hang up
        • The conversation with the Dialogflow CX agent requires a live agent handoff
        • The caller hangs up
        • An error occurred during the VirtualAgent session

        Twilio's request to the action URL

        The body of Twilio's request to the action URL contains properties about the <Connect><VirtualAgent> session, along with Twilio's standard request parameters. You can use this information to configure the call behavior after a <Connect><VirtualAgent> session, or to log information for analytics purposes.

        Property Description
        VirtualAgentProvider The VirtualAgent provider e.g. DialogflowCX
        VirtualAgentStatus The reason a VirtualAgent session ended (see below for more information)
        VirtualAgentProviderData JSON string containing the provider specific action callback event data (see below for more information)
        VirtualAgentErrorCode A Twilio error code. See Twilio's Error and Warning Dictionary for more information. This property will only appear if the value of the VirtualAgentStatus property is failed.
        VirtualAgentError A message describing the error that caused the VirtualAgent session to fail. This property will only appear if the value of the VirtualAgentStatus property is failed.
        VirtualAgentProviderError A Dialogflow-provided error message. This property will only appear if the value of the VirtualAgentStatus property is failed and the VirtualAgentErrorCode is 32601.
        VirtualAgentStatus

        This property describes why the VirtualAgent session ended. Possible values are:

        • completed: VirtualAgent session was terminated by one of the following:
          • The Dialogflow CX agent indicated end of conversation (by matching the end of conversation intent)
          • The caller hung up
        • live-agent-handoff: VirtualAgent returned a live agent handoff response
        • failed: An error occurred during VirtualAgent processing
        VirtualAgentProviderData

        This property is a JSON string containing Dialgfow-specific data from the agent interaction:

        • 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 agent returned a live agent handoff response

        Respond to Twilio's request to the action URL

        If you want a call to continue after a <Connect><VirtualAgent> session ends, your application should provide new TwiML instructions based on the <Connect><VirtualAgent> session.

        method

        This optional <Connect> attribute indicates the HTTP request method to be used when Twilio sends a request to the action URL. If you don't specify a method attribute in <Connect>, POST is used by default.

        The allowed values are POST and GET.

        <VirtualAgent> attributes

        The table below lists all of the <VirtualAgent> attributes with their allowed values. The Dialogflow CX integration allows additional customization of the call flow using <Parameter> and <Configuration> TwiML nouns.

        Name Allowed Values Required? Default Value
        connectorName A string Yes empty
        statusCallback An absolute URL No empty
        statusCallbackMethod GET, POST No empty

        connectorName

        The connectorName is a string, configured in Dialogflow CX connector instance in the Unique Name field. You can review your Dialogflow CX connector instances in the Twilio Console.

        statusCallback

        The statusCallback attribute is an absolute URL where Twilio will send HTTP requests. While the Dialogflow agent interaction is in progress, Twilio will send HTTP requests to this URL each time an intent matches in the Dialogflow agent's conversation.

        The body of Twilio’s requests to your statusCallback URL contains information about intents, transcripts (caller text vs. virtual agent text), sentiment analysis (if enabled), and custom parameters that were sent to Dialogflow to build custom logic.

        The body of Twilio's request to your statusCallback URL contains the following properties:

        Parameter Description Type Required?
        AccountSid Twilio Account SID string Yes
        CallSid Twilio Call SID string Yes
        Timestamp Time of the event, conformant to UTC ISO 8601 Timestamp string Yes
        StatusCallbackEvent The event type that triggered the status callback request (e.g. intent) string Yes
        VirtualAgentProvider The VirtualAgent provider (e.g. DialogflowCX) string Yes
        VirtualAgentProviderData JSON string with data from Dialogflow CX. See more information below. JSON string Yes

        VirtualAgentProviderData

        This parameter in the status callback is a JSON string containing the Dialogflow CX-specific intent event data. The JSON string can contain the following fields:

        Key Description Type Required
        ConversationId Unique identifier for this conversation provided by Google string Yes
        EndUserId Unique identifier for the end user participant provided by Google string Yes
        ResponseText The Dialogflow CX agent's response to the caller string Yes
        LanguageCode The language that was triggered during intent detection string No
        Parameters JSON object with key-value pairs containing the collected session parameters object No
        Confidence The intent detection confidence. Values range from 0.0 (completely uncertain) to 1.0 (completely certain) number No
        ResolvedInput Final text input matched against. This value may be different from the original input because of spelling correction or other processing. string No
        IntentId Intent ID provided by Google string No
        IntentDisplayName The human readable name of this intent string No
        SentimentAnalysisScore Sentiment score between -1.0 (negative sentiment) and 1.0 (positive sentiment) number No
        SentimentAnalysisMagnitude A non-negative number in the [0, +inf) range, which represents the absolute magnitude of sentiment, regardless of score (positive or negative) number No

        statusCallbackMethod

        This is the HTTP method to use when requesting the statusCallback URL. Accepted values are GET or POST, and the default value is POST.

        Custom Parameters

        You can pass custom key-value pairs to your Dialogflow CX agent by using the nested <Parameter> TwiML noun within <VirtualAgent>. The <Parameter> noun allows you to send custom session parameters to your Dialogflow CX virtual agent, which can be referenced in your agent as $session.params.parameter-name.

        <Parameter> has two attributes: name and value, both of which must be used every time you use <Parameter>.

        For example, if you want to provide the end caller with a personalized agent greeting, you can supply a nested <Parameter/> element with the customer name to the Dialogflow CX agent as in the following code sample.

        This key-value pair will be passed in as a session parameter which can be referenced under $session.params.cutomer_name at runtime in your Dialogflow CX agent.

              
              
              

              Dynamic connector configuration

              TwiML noun allows you to override your underlying Dialogflow CX Connector's configuration or pass additional parameters that change the behavior of your virtual agent. The <Config> noun is nested inside of <VirtualAgent>. <Config> has two attributes: name and value, both of which must be used every time you use <Config>.

              For each configuration option you want to override, you must include a new <Config> noun. The name attribute then corresponds to one of your Dialogflow CX Connector's configuration options, such as language, sentimentAnalysis, voiceName, and welcomeIntent.

              Additionally, there are attributes that are not present in your Dialogflow CX Connector configuration such as voiceModel, speechModel, speechModelVariant, but you can still set these attributes using <Config> noun nested inside of <VirtualAgent>.

              Below are the configuration settings supported within <Config> TwiML noun:

              Configuration Setting Description Default

              language

              Language in which the caller will be interacting with the Dialogflow CX Virtual Agent, e.g. “es-es”.

              When choosing a language, you must apply "STT" and "TTS" filters in the Dialogflow CX languages

              If not specified, this defaults to the setting in the Dialogflow CX connector configuration

              sentimentAnalysis

              Boolean indicating whether to enable sentiment analysis or not.

              If you want Dialogflow to perform sentiment analysis on the intents, you must select language that supports "Sentiment" filter in addition to STT/TTS in the Dialogflow CX languages

              If not specified, this defaults to the setting in the Dialogflow CX connector configuration

              voiceName

              The TTS voice to use for the Dialogflow CX Virtual Agent, e.g. "en-US-Standard-C"

              If not specified, this defaults to the setting in the Dialogflow CX connector configuration

              welcomeIntent

              The name of the event to trigger when connecting to the virtual agent. You would set this to the built-in system event "WELCOME" to trigger the Default Welcome Intent for your agent. However, Dialogflow CX allows you to configure custom events on your Dialogflow CX agent to programmatically denote where the flow should start.

              empty

              voiceModel

              The TTS custom voice model to use. If specified in addition to voiceName, this attribute will take precedence. This feature allows you to train a custom voice model using your own studio-quality audio recordings to create a unique voice.

              empty

              speechModel

              The STT model used in the processing of human speech. If not specified, the "default" speech-to-text transcription model is used.

              This option is not exposed in the Dialogflow CX Connector, but uses the "default" speechModel under the hood

              speechModelVariant

              The speech model variant used in speech-to-text.

              If an enhanced model variant is specified and an enhanced version of the specified model for the language does not exist, this omits an error. See the Enhanced Models guide for more information.

              This option is not exposed in the Dialogflow CX Connector and not explicitly set by Twilio. Dialogflow defaults to “USE_BEST_AVAILABLE”

              For example, if you want to customize the TTS voice and language for the virtual agent interaction, you can supply the respective configuration settings inside the <Config/> attributes as follows:

                    
                    
                    
                    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!

                          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