Dialogflow Virtual Assistant Specifics

Dialogflow Specifics

To use a Dialogflow Virtual Assistant with VXML, a VIRTUAL_ASSISTANT_DIALOGFLOW Call Feature must be attached to the application. Information on the required parameters can be found in Parameters for VIRTUAL_ASSISTANT_DIALOGFLOW Call Feature

Dialogflow with VXML can be used with or without a separate STT engine.

All examples in this document are using the Object format for the grammar rather than the JSON plaintext inline grammar format.

Context Variables (Inbound and Outbound)

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.

Custom Variables (Inbound and Outbound)

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.

Events (Outbound)

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

Additional Parameters

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

Example Dialogflow response structure (JSON representation)

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]"
        }