Conversation Triggers

A conversation trigger defines when to run a particular conversation task. When you start a conversation session, or when a user provides text, Answer Server finds the conversation trigger that matches the input, and runs the appropriate task.

You can use several different types of triggers:

You can configure different tasks with different types of triggers.

TIP:

When a user sends some text that matches more than one trigger, Answer Server returns a disambiguation prompt. This prompt uses the display_id in your tasks to display the options to the user. See Task Disambiguation.

Not all tasks require a conversation trigger. For example, the tasks that you configure as the initial task and fallback task might not need a trigger (see Default Tasks). Similarly, you might have tasks that run only when called by explicit routing from another task.

The number of tasks that you add triggers to depends on your conversation structure and routing.

To configure a trigger, you set the trigger property in the configuration object for an individual task, which contains different properties depending on the type of trigger you use.

The following sections describe the types of conversation triggers in more detail, and provide examples of how to configure them.

Agent Triggers

NOTE:

To use agent triggers, you must configure an IDOL Agentstore component in your Conversation system configuration.

Agent triggers use IDOL agent search to find matching triggers. In agent search, you send plain text or a document to the Agentstore, which returns any agents that match the input text. In the case of agent triggers, Answer Server sends the user input text to the Agentstore, which returns any matching agent triggers.

You link the value of an Agentstore field in the trigger agent (usually the document reference) to a task in your task configuration JSON file. When the user text matches a particular agent trigger, Answer Server runs the corresponding task for that agent.

TIP:

By default, Answer Server uses the document reference field in your agents as the task ID. You can set the AgentstoreReferenceField configuration parameter in your Conversation system configuration to change the field that Answer Server uses as the task ID.

Agent triggers use IDOL text search to match user text. For example, it includes IDOL stemming to allow more flexible term matching, and you can use term weighting to influence how triggers match. For more information, refer to the IDOL Server Administration Guide.

To configure an agent trigger, you add a trigger object with the agent property, set to the document reference for the agent that triggers the task.

For example:

The following IDX document represents a simple agent trigger, which you index into the Conversation Agentstore:

#DREREFERENCE LunchConversationTrigger
#DREDATE 2017/07/01
#DRETITLE
Lunch
#DRECONTENT
food lunch sandwich
#DREDBNAME MyAgentDB
#DREENDDOC

The following JSON shows a task that uses this agent as a trigger.

{
   "tasks" : [
      {

         "id" : "LUNCH",
         "pre" : {
            "response" : "I can help you order some lunch."
         },
         "trigger" : {
            "agent" : "LunchConversationTrigger"
         }
      }
   ]
}

This task runs when a user sends any text that matches the terms food, lunch, or sandwich in IDOL text matching.

Regular Expressions Triggers

Regular expressions triggers match user text against a regular expression pattern that you provide in the task configuration. Answer Server runs the task when the user input text matches your regex.

To configure a regular expressions trigger, you add a trigger object with the regex property. The regex property contains a pattern subproperty, which you must set to a regular expression pattern in ECMAScript regular expression format.

For example:

{
   "tasks" : [
      {
         "id" : "LUNCH",
         "display_id" : "order lunch",
         "pre" : {
            "response" : "I can help you order some lunch."
         },
         "trigger" : {
            "regex" : {
               "pattern" : "(Book|order) .* lunch"
            }
         }
      }
   ]
}

You can also provide a weight for the trigger by setting the weight property in the trigger object. The weight value is a number between one and 100. The default value is 100. Answer Server uses this weight to determine the best triggers to return in a disambiguation response. See Trigger Options.

The weight value is constant for a particular trigger. You can assign a higher weight to triggers that have more restrictive trigger conditions. For example, if a user must match a more complex regular expression to trigger a task, it is more likely to be the task that they want, and so you assign a higher weight.

For example:

 "trigger" : {
   "regex" : {
      "pattern" : "(Book|order) .* lunch"
   },
   "weight" : 80
}

Simple Triggers

Simple triggers match user text against a list of phrases that you provide in the task configuration. Answer Server runs the task when the user input text matches one of the phrases you provide.

In a simple trigger, you must provide a list of phrases. You can optionally also provide a required prefix and suffix. By default, matches are case sensitive, but you can also use a property in your configuration to specify that matches must be case insensitive.

To configure a simple trigger, you add a trigger object with the simple property. The following table describes the subproperties that you can set in the simple object.

Property Type Description
phrases array, strings (Required) A list of phrases that you want to match. The task runs if the user input text matches at least one of the specified strings. The array must have at least one item.
prefix string (Optional) A string that must occur at the start of the user input text for this trigger to match.
suffix string (Optional) A string that must occur at the end of the user input text for this trigger to match.
case_insensitive Boolean (Optional) Set to true to match user text case insensitively. The default value is false (case sensitive matching).

For example:

{
   "tasks" : [
      {
         "id" : "LUNCH",
         "display_id" : "order lunch",
         "pre" : {
            "response" : "I can help you order some lunch."
         },
         "trigger" : {
            "simple" : {
               "prefix" : "I want to",
               "phrases" : [ 
                  "order some lunch",
                  "buy a sandwich",
                  "book a table for lunch",
                  "order food"
               ]
            }
         }
      },
      {
         "id" : "BREAKFAST",
         "display_id" : "order breakfast",
         "pre" : {
            "response" : "I can help you order some breakfast."
         },
         "trigger" : {
            "simple" : {
               "phrases" : [ 
                  "get breakfast",
                  "order breakfast",
                  "eat breakfast",
                  "buy breakfast"
               ],
               "case_insensitive" : true
            }
         }
      }
   ]
}

The first of these example tasks matches user text that starts with I want to and continues with one of the listed phrases, such as I want to order some lunch, or I want to order a sandwich. The matching for this task is case sensitive.

The second task matches user text that contains any of the listed phrases, and matches case insensitively.

You can also provide a weight for the trigger by setting the weight property in the trigger object. The weight value is a number between one and 100. The default value is 100. Answer Server uses this weight to determine the best triggers to return in a disambiguation response. See Trigger Options.

The weight value is constant for a particular trigger. You can assign a higher weight to triggers that have more restrictive trigger conditions. For example, if a user must supply more matching keywords to trigger a task, it is more likely to be the task that they want, and so you assign a higher weight.

For example:

"trigger" : {
   "simple" : {
      "phrases" : [
         "get breakfast",
         "order breakfast",
         "eat breakfast",
         "buy breakfast"
         ],
      "case_insensitive" : true
   },
   "weight": 90
}

Task Disambiguation

In some cases, the user might provide text that matches the trigger for more than one task. In this case, Answer Server returns a disambiguation prompt, which allows the user to select the appropriate option from a list of tasks that match their input.

Answer Server uses the task display_id property in the prompt that it displays to the user. If you do not specify a display_id, it uses the id property.

For example:

{
   "tasks" : [
      {
         "id" : "LUNCH",
         "display_id" : "order lunch",
         "pre" : {
            "response" : "I can help you order some lunch."
         },
         "trigger" : {
            "simple" : {
               "prefix" : "I want to",
               "phrases" : [ 
                  "order food"
               ]
            }
         }
      },
      {
         "id" : "BREAKFAST",
         "display_id" : "order breakfast",
         "pre" : {
            "response" : "I can help you order some lunch."
         },
         "trigger" : {
            "simple" : {
               "phrases" : [ 
                  "get breakfast",
                  "order breakfast",
                  "eat breakfast",
                  "buy breakfast",
                  "order food"
               ]
            }
         }
      }
   ]
}

If a user sends the text I want to order food, both of these task triggers match. Answer Server then returns the text Which of the following did you mean: order lunch, or order breakfast? (you can modify this message, if required. See Default Messages).

After the user selects the appropriate task, Answer Server processes the selected task. It sends the original text that activated the disambiguation prompt to the new task, so that the new task can use it for automatic requirement gathering, where appropriate (see Automatic Requirement Gathering).

You can define the maximum number of triggered tasks that return in a disambiguation message by using the trigger_options configuration. See Trigger Options.

Trigger Options

The trigger_options object allows you to set additional properties that define how your task triggers work. You can optionally add this object at the top level of your task configuration file. The settings apply to all your tasks.

The following table describes the properties that you can set in the trigger_options object.

Property Type Description
max_triggers integer (Optional) The maximum number of triggers that the conversation task can return in a disambiguation response. Answer Server sorts the triggers by weight and returns up to max_triggers options with the highest weight. The default value is 6.

For non-agent triggers, you define the weight property in the trigger configuration object. For agent triggers, Answer Server uses the returned autn:weight value when it queries for matching agent triggers. Answer Server considers triggers with zero weight only if there are no matches with non-zero weights.

weight_range number(0-100) (Optional) The weight range for task triggers to allow in task disambiguation. When Answer Server returns a disambiguation response, it does not return any triggers that have a weight that is more than weight_range below the highest weight. By default, there is no limit.

For example:

{
"tasks" : ...   "trigger_options": { "max_triggers": 5, "weight_range": 50 } }

_HP_HTML5_bannerTitle.htm