# 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:

- Agent. Trigger a task based on a match against your Conversation Agentstore index. To use this option you must configure an IDOL Agentstore component in your Conversation system configuration. See Configure the Conversation Agentstore.
- Regular Expressions. Trigger a task based on a text match against a regular expression pattern.
- Simple. Trigger a task based on a simple exact phrase match.

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_match` property. The following table describes the subproperties that you can set in the `simple_match` 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_match" : {
                   "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_match" : {
                   "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_match" : {
          "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_match" : {
                   "prefix" : "I want to",
                   "phrases" : [
                      "order food"
                   ]
                }
             }
          },
          {
             "id" : "BREAKFAST",
             "display_id" : "order breakfast",
             "pre" : {
                "response" : "I can help you order some lunch."
             },
             "trigger" : {
                "simple_match" : {
                   "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
       }
    }

_FT_HTML5_bannerTitle.htm