To use a Dialogflow Virtual Assistant with VXML, a VIRTUAL_ASSISTANT_DIALOGFLOW_ES or VIRTUAL_ASSISTANT_DIALOGFLOW_CX Call Feature must be attached to the application. Information on the required parameters can be found in Parameters for VIRTUAL_ASSISTANT_DIALOGFLOW_ES Call Feature and Parameters for VIRTUAL_ASSISTANT_DIALOGFLOW_CX Call Feature
Dialogflow with VXML can be used with or without a separate STT engine.
Examples in this document use either the Object format for the grammar or the JSON plaintext inline grammar format. The JSON format can also be used dynamically with the srcexpr property of the grammar tag.
Contexts have a very specifc meaning in Dialogflow and the concept of a context is not simply arbitrary context variables. Each intent in Dialogflow has 0-* input contexts and output contexts. If you wish to simply send some arbitrary variables to Dialogflow, this should be done using a Custom Variables (see the "Custom Variables" section).
To set input contexts, create a "context" object structure. This can be a single context or a map containing multiple contexts. For a single context, at miminum, the name parameter must be specified. Otherwise, if specifying multiple contexts, create objects within the contexts structure. The key for the context is used as the context's name, and the value of the context must be an Object.
Example of setting a single input context:
<assign name="virtual_assistant_request_structure.context.name" expr="'my_context'"/>
<assign name="virtual_assistant_request_structure.context.lifespanCount" expr="'3'"/>
Example of setting multiple input contexts:
<assign name="virtual_assistant_request_structure.context" expr="new Object()"/>
<assign name="virtual_assistant_request_structure.context['my_context_name']" expr="new Object()"/>
<assign name="virtual_assistant_request_structure.context['my_context_name'].lifespanCount" expr="'2'"/>
<assign name="virtual_assistant_request_structure.context['my_other_context_name']" expr="new Object()"/>
<assign name="virtual_assistant_request_structure.context['my_other_context_name'].lifespanCount" expr="'3'"/>
Note that while lifespanCount is technically not considered a mandatory parameter by Dialogflow, if it is not specified it will default to 0, which will unset the context.
In Dialogflow, the custom_vars structure is sent as a payload structure to the Dialogflow session. It is a simple freeform key/value pair map.
As an example for how to set these, if using the object format:
<assign name="virtual_assistant_request_structure.custom_vars.custom_number" expr="2"/>
<assign name="virtual_assistant_request_structure.custom_vars.custom_text" expr="'donuts'"/>
<assign name="virtual_assistant_request_structure.custom_vars.custom_boolean" expr="true"/>
To get custom variables from the response, simply pull them from the shadow variable's interpretation, for example to log a custom variable my_variable:
<log>My variable is <value expr="virtual_assistant_field$.interpretation.custom_vars.my_variable"/></log>
Note that it is possible for Dialogflow to return multiple message payloads if the Dialogflow project is designed this way. If this is the case, they are all merged into the custom_vars structure. It is possible to access all payloads returned in a payloads array in the interpretation if necessary.
Dialogflow can be sent events which can be used to trigger a specific intent, rather than using text or audio input. To specify an event, set the event field. The value for this can either be just the name of the event, or an Object containing the event name and some arbitrary parameters
Setting an event with just the event name:
<assign name="virtual_assistant_request_structure.event" expr="'my_event'"/>
Setting an event with some parameters:
<assign name="virtual_assistant_request_structure.event" expr="new Object()"/>
<assign name="virtual_assistant_request_structure.event.name" expr="'my_event'"/>
<assign name="virtual_assistant_request_structure.event.parameters" expr="new Object()"/>
<assign name="virtual_assistant_request_structure.event.parameters.my_special_parm" expr="'parameter'"/>
When setting up a Dialogflow grammar in VoiceXML, you can supply parameters to alter how Google Speech To Text (STT) operates, as follows:
| stt_parms Key | Default Value | Description |
| model | phone_call | The STT model the Google engine should use for this analysis |
| single_utterance | false | Whether to use the single utterance setting for STT. This may only work with some models, see the Google STT documentation. |
| interim_results | true | Whether the model should send partial results to BVR as part of STT. |
| use_enhanced | true | Sets whether to use the enhanced versions of recognition models. May need to be set to false for some STT models, see Google STT documentation. |
| profanity_filter | false | Censors profane words in recognised text if set. |
| max_alternatives | 1 | The maximum number of different possible recognition versions to return. |
| automatic_punctuation_enabled | false | If set to true, STT will attempt to supply punctuation around the sentences it detects. |
| enable_word_time_offsets | false | If true, the top result includes a list of words and the start and end time offsets (timestamps) for those words. |
Example of how to set stt_options, in this case setting the model to 'latest_short'
<var name="virtual_assistant_request_structure" expr="new Object()"/>
<assign name="virtual_assistant_request_structure.custom_vars" expr="new Object()"/>
<assign name="virtual_assistant_request_structure.custom_vars.custom_variable" expr="'test value'"/>
<assign name="virtual_assistant_request_structure.options" expr="new Object()"/>
<assign name="virtual_assistant_request_structure.options.stt_parms" expr="new Object()"/>
<assign name="virtual_assistant_request_structure.options.stt_parms.model" expr="'latest_short'"/>
...
<grammar mode="voice" version="1.0" type="application/x-blueworx-virtual-assistant+json" srcexpr="objectToJson(virtual_assistant_request_structure)"/>
Alternatively, you can set stt_parms in an inline grammar:
<grammar mode="voice" version="1.0" type="application/x-blueworx-virtual-assistant+json">
{ "options" : { "stt_parms" : { "model" : "latest_short" } }
}
</grammar>
Additional parameters can be set in the main structure.
resetContexts (Outbound) - Resets all currently active contexts
Example:
<assign name="virtual_assistant_request_structure.resetContexts" expr="true"/>
project_id (Inbound) - The Dialogflow session's project ID
session_id (Inbound) - The Dialogflow session's session ID
This is an example of the data structure format you can expect to see from a Dialogflow response:
{
"transcript": "I need to speak to an agent",
"messages": [
{
"text": "Transferring now"
}
],
"message_text": "Transferring now",
"intents": [
{
"intent": "speak to agent",
"confidence": 1.0,
"name": "projects/[project_name]/agent/intents/[intent_id]",
"display_name": "speak to agent"
}
],
"intent": {
"intent": "speak to agent",
"confidence": 1.0,
"name": "projects/[project_name]/agent/intents/[intent_id]",
"display_name": "speak to agent"
},
"entities": [],
"context": {
"[output_context_name]": {
"lifespan_count": 1,
"name": "projects/[project_name]/agent/sessions/[session_id]/contexts/[output_context_name]",
"short_name": "[output_context_name]",
"parameters": {}
}
},
"custom_vars": {
"bw_action": "transfer",
"bw_transfer_target": "[sip_transfer_target]"
},
"raw_json": "[full_text_dialogflow_response]",
"payloads": [
{
"bw_action": "transfer",
"bw_transfer_target": "[sip_transfer_target]"
}
],
"project_id": "[project_name]",
"session_id": "[project_name]"
}