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.
Setup
Before using <VirtualAgent>, you must complete the Dialogflow ES one-click integration.
Attributes
<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 |
statusCallback
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).
<Response>
<Say>Hello! You will be now be connected to a virtual agent.</Say>
<Connect action="https://myactionurl.com/virtualagent_ended">
<VirtualAgent connectorName="project" statusCallback="https://mycallbackurl.com"/>
</Connect>
</Response>
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.
<Response>
<Connect>
<VirtualAgent connectorName="project"/>
</Connect>
<Say>Thank you for your call. Goodbye.</Say>
</Response>
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.
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.
