The Greeting message flow is the first flow to trigger when a user begins a dialog with your bot. This is the place where a bot should introduce itself and lay down the scope of the conversation. The Dialogue Resources are delivered with a pre-built greeting located in the top-level folder Greeting Message. The flow contains standard greeting responses, which you can adjust to match your use case. If you did not load solution with the Teneo Dialogue Resources template into your solution, you will need to create your own Greeting Message flow.

### Greeting style
The greeting message holds the first words users hear from your bot, so you should try and make the most out of this introduction. Be sure to write something that encourages users to engage with your system.

This greeting would not be very effective in a business setting:

> **Bot:** Say something.

But this greeting clearly guides user expectations:

> **Bot:** Hi, my name is Botname of Artificial Solutions. I'm here to answer all your questions about ordering coffee online. How may I help you?

In other words, an effective way to begin the conversation is to:

1.  Introduce the system (use the bot's name, if it has one).
2.  Mention the company's name.
3.  Tell users what they can ask.

!!! Remember, this is the one flow that users will definitely see, so be sure to put some thought into its preparation. These are stored as [Global Variables](/studio/flows/concepts/variables#create-a-global-variable) in the Teneo Dialogue Resources and can be changed upon editing the value.

## Trigger condition
The greeting flow uses a trigger with a TLML Syntax Match whose Syntax condition queries specific [system annotations](/studio/reference/annotations-reference#system-annotations):

![Init condition annotated](//images.ctfassets.net/2vbtnveccz5s/2mosatMXJqkj0f7Gm4wcCb/fb32b2238cfbfad15c667ea60388f2d1/Init_condition_annotated.png?classes=w60)

__%$_INIT__ represents the event of the input being the first in a conversation. __%$_EMPTY__ means that the user input does not contain any text. Together, these two conditions say: give the greeting message if the user did not start the conversation with a question. If the user has sent a question as the first input, we skip the greeting message and allow the input to be processed by the first best flow.

## Build a Greeting message flow
The Greeting message is an important part of a solution, as it is typically the first thing the user sees of the solution. The following steps detail how to build your own Greeting message flow.

!!! The [Dialogue Resources](/studio/language-understanding/concepts/languages#dialogue-resources) come with a pre-built Greeting message flow. You can find it in the 'Greeting Message' folder. For solutions in languages without available Dialogue Resources, it is useful to add your own Greeting message flow using the following instructions and localizing to the language in question.

### Create a new flow
Remember that this flow is a flow like any other in your bot. The condition is what sets it apart from other flows. But since it does have a unique purpose, we advise you to keep the flow in a special folder, make sure it's easy to find, and give it a meaningful name.

1. Click on the 'Flow' icon in the top ribbon.
2. Name the flow `Greeting message`.
3. Click the arrow in the top left corner to go to the main flow window.

### Create a TLML Syntax Match
Next, add a TLML Syntax Match to your newly created flow:
1. Select the trigger and name it `Greeting message`.
2. Scroll down to the Match section and click on the 'Add' button. This will toggle a dropdown list of different Match requirements to select.
3. Select 'TLML Syntax' and then paste in the following condition: `%$_INIT & %$_EMPTY`.

!!! If you need a way to manually trigger the flow, for example from another system such as an IVR, you can add a trigger word to the condition, one that users will not enter by accident: `(%$_INIT & %$_EMPTY) / TRIGGER_GREETING_MESSAGE`

### Assign an order group
Make sure to assign the trigger to a high priority [order group](/studio/conversations/concepts/ordering).

### Add a greeting message to the output node
As this message is the first one the user will see, it is important to choose it carefully. Feel free to use the following example, which makes use of the global variable holding the bot name, or write your own message.
1. Select the output node and give it a name like `Answer to Greeting message`.
2. Set the answer to `Hello and welcome! My name is ${Lib_sBotName} and I'm here to answer your questions.`.

## Activate in Tryout
You can trigger the greeting flow in Tryout by following these steps:

1. Click the __Restart__ button to begin a new conversation.
2. Click the __Send__ button, leaving the input field blank.

![trigger-greeting](//videos.ctfassets.net/2vbtnveccz5s/ar1XzJexZ8ERhmcXJQKCb/bc36658cac67feaa94d6e39725ac29fa/trigger-greeting.mp4)

Build - Greeting message

Greeting message

Sometimes your bot will not understand what the user says. It is thus important that your solution contains a fallback flow that deals with user inputs that are not understood. In Teneo, we call this flow a Safetynet flow.

## Matches anything and is tested last
The Safetynet flow consists of a trigger with a star (__*__) and __%$_QUESTION__ as a language condition. The reason for this is that the Safetynet flow needs to be true for any input. To work as intended, Teneo must test all other triggers before falling back to the Safetynet trigger. The Safetynet trigger must thus be placed at the bottom of the trigger [ordering](/studio/conversations/concepts/ordering).   

![safetynet-script](//images.ctfassets.net/2vbtnveccz5s/7cZGpZG0y4RozcTd34GdvM/ee0fcda280b7af93daf08c13cf9c3378/safetynet-script.png?classes=w40)

## A flow like any other flow
Apart from having a very generous language condition, a Safetynet flow is like any other flow. It may be triggered when there is no other active flow in process, or in the middle of some other flow as in the following example:

>**User**: I'd like to order a coffee.       
>**Bot**: Ok, what coffee would you like?   

>**User**: ajkfhh  (*the coffee order flow is interrupted and the Safetynet is triggered*)    
>**Bot**:  I'm sorry but I didn't get that. (*Safetynet response is given*)

>**Bot**: Let's continue with your order. Which coffee would you like? (*the coffee order flow is resumed*)  

The same Safetynet flow may thus cater to non-understood inputs in all sorts of different contexts!

## Activate in Tryout
You can trigger the Safetynet flow in Tryout by following these steps:

1. Click on the Tryout to start a conversation.
2. Write something nonsensical, like: `ajkfhh`.

![trigger-safetynet](//videos.ctfassets.net/2vbtnveccz5s/7nJHpV1tgIz1tfawuDS519/980c63af2239c4a35481fdba9f379fbb/trigger-safetynet.mp4)

## Build a Safetynet flow
The Safetynet fallback flow is crucial for every solution. This flow can be built using the following steps.

!!! The [Dialogue Resources](/studio/language-understanding/concepts/languages#dialogue-resources) come with a pre-built Safetynet flow. You can find it in the 'Safetynet' folder. For solutions in languages without available Dialogue Resources, it is useful to add your own Safetynet flow using the following instructions and localizing to the language in question.

### Create a Safetynet order group
The Safetynet is always located at the bottom of the [order](/studio/conversations/concepts/ordering#order-groups) groups. This is because the Safetynet is built to trigger on every single input, catching the inputs that are not covered inside the solution. In order for the Safetynet to not steal any of the inputs, it is important to create an order group specifically for the Safetynet and place it at the lowest level.

!!! More on how to create your own custom order group can be found here: [Create a custom order group](/studio/conversations/how-to/create-a-custom-order-group#create-the-order-group).

### Create a Safetynet Flow
To begin with, create your flow by doing the following:

1. Click on the 'Flow' icon in the top ribbon.
2. Name the flow `Safetynet`.
3. Click the arrow in the top left corner of the window to go to the main flow window.

#### Create a TLML Syntax Match
As mentioned above, the Safetynet flow uses one [TLML Syntax Match](/studio/flows/concepts/triggers#condition). You can now go ahead and create that:

1. Select the trigger and name it `Safetynet`.
2. Scroll down to the 'Match' section and click on the 'Add' button. This will toggle a dropdown list of different Match requirements to select.
3. Select 'TLML Syntax' and then paste in the following condition: `* / %$_QUESTION`.
4. Lastly, change the ordering by locating the Triggering section and selecting the Order Group we created in the steps above, __Safetynet__. This will change the flows trigger ordering.

#### Add answer texts to the output
As the Safetynet fallback flow is one of the most triggered flows, it is important to add a wide range of answer texts inside the output node. 

Output nodes can contain multiple answer variations to make the conversation more dynamic. 

Teneo will choose any of these answers randomly and return it to the user. User has also the option to 'Set order' for the outputs to show.
1. Select the output node and paste in the following answers:
* `I'm sorry but I didn't get that.`
* `I'm not sure I know what you mean?`
* `Can you help me understand that?`
* `Can you say that again using different words?`
* `I didn't get that.`
* `I'm afraid I have no answer for you.`
* `I don't have a good answer to that.`
* `Sorry, can you rephrase that for me?`
* `I don't think I got that.`
2. Save the flow.

## Create an area Safetynet flow
An area Safetynet captures ambiguous inputs, but instead of giving a standard answer it recognizes what topic the user mentioned and tries to redirect the conversation towards that goal. 

For example, if a user mentions the word 'coffee' without any other context, the bot might respond like this:

> **User**: coffees       
> **Bot**: I understand you would like to talk about coffee. Can you be more specific? Did you want to order a coffee or see our selection of coffees?       
>       
> **User**: your selection       
> **Bot**: We offer a variety of handcrafted coffee drinks - from espressos to macchiatos to flat whites and more.       

A practical example of how to build an area Safetynet can be found [here](/studio/conversations/how-to/handle-ambiguous-inputs).

Build - Safetynet fallback flow

Safetynet

When Teneo tests a user input against your solution's triggers and transitions, it stops at the first match. It is thus crucial in which *order* the triggers and transitions are tested. Teneo allows you to define and modify their order. This concept is called *ordering*.

## Active flows first

When searching for a matching trigger, Teneo always gives priority to the flow that is currently being processed. Thus, each input is first tested against the transitions at the current point of the active flow. The order in which these transitions are tested is [indicated in the flow graph](/studio/flows/concepts/transitions#order).  
Only if there is no active flow or if none of the transitions in the active flow match the user input, Teneo will go on and test the input against other flow triggers of the solution.

## Order groups

If there is no active flow, or no matching transition in the active flow, Teneo will go through all other flows of the solution to find a matching trigger. The order in which the triggers are tested is determined by the triggers' order group. To get an overview of the order groups of your solution, simply select the 'Intent Trigger' icon in the 'Ordering' section of the top ribbon.

![ordering-trigger](//images.ctfassets.net/2vbtnveccz5s/1R08aN0pHqaN60hCfYqL8y/04b825f470809f8f05c4fe07dc79c8c7/ordering-trigger.png)

This opens an overview of the existing order groups in your solution. When searching for a matching trigger, Teneo will start at the top and work its way down until it finds a matching trigger.

![Trigger picture](//images.ctfassets.net/2vbtnveccz5s/2837QNBhkzFnXjZ4f0IwXH/52d68129deeb64ff0852e1b131ebcb38/Trigger_picture.PNG)

The order groups displayed above are the groups that come with Teneo Dialogue Resources (which you can use as a template when creating a new solution). Let's have a quick look at all of these groups:

1.  **Default** - group to store default triggers. Because this is marked as 'default', triggers you add to your solution will automatically be assigned to this group
2.  **TDR - Top** - contains triggers from Teneo's Dialogue Resource template solution, which are very specific.
3.  **TDR - Middle** - this is the group you should assign triggers which are in between 'Top' and 'Low'.
4.  **TDR - Low** - contains the triggers from Teneo's Dialogue Resource template solution that are less specific.
5.  **TDR - Safetynet** - this group contains the [Safetynet](/studio/conversations/concepts/safetynet) that comes with Teneo's Dialogue Resource template solution.

These pre-defined groups should take you a long way. However, should you discover that you need to add more order groups to your solution, you can easily do so by moving over to the 'Groups' tab of the 'Intent Trigger Ordering' window. There, you may also move triggers from one group to another, if necessary. But before you add order groups or start moving triggers, you may want to try whether 'Relative Ordering' does the job. You can read more on how to create a custom order group [here](/studio/conversations/how-to/create-a-custom-order-group).

### Managing order groups
The tools needed to manage order groups can be found under the Groups tab. Here, we can add, move, and delete groups.

![managing order groups](//images.ctfassets.net/2vbtnveccz5s/5hoDrE1zUIlz0tFltI2xkM/42bdc025b62cc3bd98f094356772ded9/managing_order_groups.png)

In the View group in the ribbon bar there are buttons to toggle the visibility of disabled triggers. To select multiple groups, hold down the Ctrl key while clicking on group names.

## Relative ordering

In some cases, multiple triggers within one order group might be competing for inputs. This can be solved easily by defining relations between those triggers. Trigger relations are defined by arrows that can be drawn between any two triggers in the same order group by simply clicking on one trigger and dragging an arrow to a second one.

This relative ordering clarifies the order in which the triggers should be tested. Just like with order groups, the more specific triggers should be put before the less specific ones; otherwise, the most specific triggers would never be tested.

Relative ordering between triggers can be defined in the Intent Trigger Ordering window. Here, we can click on an order group to see exactly which triggers are included in that group.

![ordering window](//images.ctfassets.net/2vbtnveccz5s/6TotRLlTl17txw5ljqI5h5/cb99ce21653a1ff82b22a2d9dee633f9/ordering_window.png)

Triggers and relations are treated as separate types of objects. For example, in this image, there are three different objects that can be selected: two triggers, and one relation.

![triggers and relations](//images.ctfassets.net/2vbtnveccz5s/2FPxUMkSBuuHYLX5AtUuyh/d4be3218799e1bdd2a20a0fe56705e7c/triggers_and_relations.png?classes=w60)

Triggers and relations have their own groups in the Home tab of the ribbon bar.

![trigger relations groups](//images.ctfassets.net/2vbtnveccz5s/7l0o1IgqspXwU7k96x9y07/fad496f7b2ec9cb45b2098fab6790ccb/trigger_relations_groups.png)

## Prompt triggers

We have so far seen how to order Intent triggers, which make up for the majority of triggers in our solution. Prompt triggers are ordered separately from the intent triggers, but their ordering follows the same general principle: more specific triggers should be tested before less specific ones. To view or change the ordering of prompt triggers, simply select the 'Prompt Trigger' icon in the Ordering section of the top ribbon.

Build - Trigger Ordering

Ordering

Users sometimes communicate using incomplete inputs making it harder to interpret what they want. In our system we might expect ambiguous inputs mentioning one of our relevant products, such as __coffee__ or __flat white__. We would have the same trouble understanding if someone spoke to us this way. Do they want to order? Do they want the calorie count? Something else? On this page, we will create a flow with a syntax trigger to deal with these kinds of inputs. We will also create a custom order group to hold the flow's trigger and others like it. We will order the group just before the class intents because we don't want this specialized situation to be second-guessed by machine learning when we already know that it's ambiguous.

!!! In our experience, users do this for a variety of reasons. A likely reason is that the user believes the bot to be either very primitive or a search engine and that communication through keywords is the best way to get to the right answers.

This is the first part of solving the problem of recognizing ambiguity without overtriggering. After working through this how-to, we suggest to have a look at how to [Handle Ambiguous Inputs](/studio/conversations/how-to/handle-ambiguous-inputs) to give a satisfying resolution to the problem.

Before our implementation, we have a conversation which looks something like this:

> **User:** coffee  
> **Bot:** I'm sorry but I didn't get that.
> 
> **User:** espresso  
> **Bot:** I'm not sure I know what you mean?

These kinds of responses do not result in a satisfying user experience. But after we're finished, we'll have responses that add more direction to the conversation:

> **User:** coffee  
> **Bot:** I understand you would like to talk about coffee. Can you be more specific?
> 
> **User:** what are the coffees you have  
> **Bot:** We offer a variety of handcrafted coffee drinks - from espressos to macchiatos to flat whites and more.

In the first part of the exercise, we will create an order group called __Project - Less Exact__ for syntax triggers responding to ambiguous inputs. In the second part, we will create a flow to respond to ambiguous mentions of the word coffee or any of its synonyms.

## Create a custom order group

Since you've based this solution on the template solution with the Teneo Dialogue Resources, you'll notice that you already have a set of order groups in your solution. After we're finished defining our custom order group, the ordering will look like this.

![intent ordering window](//images.ctfassets.net/2vbtnveccz5s/5Q0YfHirvO4sykHJdlY3oY/7fc4678934458eae462add7053052035/intent_ordering_window.png)

### Create the order group

First we'll create the order group:
1. Open your solution.
2. Click __Intent Triggers__ in the __Ordering__ section to open trigger ordering window.
3. In the __Intent Trigger Ordering__ window, navigate to the __Groups__ tab.
4. In the Groups tab click __Add__ to add a new group (it appears at the bottom of the list of groups).

### Adjust the group ordering

Our group was added at the bottom of the ordering, but we want it to be up higher. In these steps, we will move our group to a more optimal location in the ordering.
1.  Select the new order group (it will have a default name like __Order Group 1__) and while selected, copy this name `Project - Low` into the name field.
2.  With the order group still selected, click the Up arrow in the Ribbon to move the group to just above the group of __TDR - Low__.
3.  Save and close the Intent Trigger Ordering window.

![1-create group](//videos.ctfassets.net/2vbtnveccz5s/5VGqYitsH7l8S3XxSyyV29/4b24d163bada2d6b712a7f2cbbc3edf7/1-create_group.mp4)

## Create a flow for partial understanding

In this section we'll create a flow for partial understanding. It will use a syntax trigger ordered into the __Project - Low__ group which we just created. When finished, our flow should look like this:  

![final flow](//images.ctfassets.net/2vbtnveccz5s/4a5rR4k8zZaq5QxP9C5lgk/b3f74853a5f50638baa23909faed9499/final_flow.png)

### Create a new flow and add a Match Requirement for a Language Object
1.  Create a new flow and call it `Partial understanding: Coffee`.
2.  Name the trigger `User mentioned Coffee` and add the following positive intent examples:
```example-inputs
cappuccino    
coffee
espresso
```
3.  Add a 'Language Object' Match with the following condition:`COFFEE.NN.SYN`.
4.  In the __Triggering__ section, select the __Order Group__ we created in the steps above: __Project - Low__. This will change its ordering.

![2-create flow](//videos.ctfassets.net/2vbtnveccz5s/7zJb0mhLYvMF3ueuwgu59H/29e80fc3876114637b6105708b3eb19a/2-create_flow.mp4)

### Populate the Output node and Save

1. Select the output node and give it a name like `Respond to single synonym: Coffee`.
2. Paste the response `I understand you would like to talk about coffee. Can you be more specific?`.
3. Add a few more output variations to make your bot look smarter:
*   `I'm not sure what you wanted to ask about coffee. Could you please help clarify?`
*   `You're talking about coffee. Would you please tell me what you wanted exactly?`
4.  Hit the 'Save' button.

![3-populate output](//videos.ctfassets.net/2vbtnveccz5s/5aMq623f8bKmQaT71Enld1/bc79fcc9350082435e1db91619ef730d/3-populate_output.mp4)

## Try it out!
That's it! Now go ahead and give it a try in Tryout!

!!! Because you've assigned your trigger to a different order group, there will be a message at the bottom of the tryout panel that says 'A reload of the engine is required to apply your recent changes'. Click __Reload now__ before you start testing.

> **User:** coffee  
> **Bot:** I understand you would like to talk about coffee. Can you be more specific?


Build - Create a custom order group

Create a custom order group

A good dialogue system is able to get the conversation back on track if the user makes an ambiguous request. On this page we'll look at the flow we built in [create a custom order group](/studio/conversations/how-to/create-a-custom-order-group) and expand it to help users find the correct answer to their question. We'll do this using flow links, which allow us to send the user to a flow meant to answer the question. In the __Partial understanding: coffee__ flow we'll first present users with likely options of what the question might have been, and allow users to give a clarifying response.

Before our changes we would have a conversation like this:

> **User:** coffees  
> **Bot:** I'm not sure what you wanted to ask about coffee. Could you please help clarify?
> 
> **User:** your selection  
> **Bot:** I'm sorry but I didn't get that.

After our modifications, it will look like this:

> **User:** coffees  
> **Bot:** I understand you would like to talk about coffee. Can you be more specific? Did you want to order a coffee or see our selection of coffees?
> 
> **User:** your selection  
> **Bot:** We offer a variety of handcrafted coffee drinks - from espressos to macchiatos to flat whites and more.
> 
> **User:** espresso  
> **Bot:** You're talking about coffee. Would you please tell me what you wanted exactly? Did you want to order a coffee or see our selection coffees?
> 
> **User:** order  
> **Bot:** Ok, what coffee would you like?

To achieve this, we'll enhance the [Partial understanding: coffee](/studio/conversations/how-to/create-a-custom-order-group) flow by following these steps:

*   Add an additional output to ask if the user wants to order a coffee or see the selection.
*   Add links to flows User wants to order a coffee and User asks about coffees we offer
*   Make sure we send the user to the correct flow depending on the user's response (order or selection)

When we're finished, our flow will look like this:  

![final flow](//images.ctfassets.net/2vbtnveccz5s/4zrlVnGwN0N0RjEuKERLHP/4abe5784aca6921925a49565048ec4f0/final_flow.png)

## Add a new output

Let's first expand the current prompt to offer the user several possibilities.

1. Open the flow 'Partial understanding: Coffee' in edit mode.
2. Select the Plus icon under 'Respond to single synonym: Coffee', followed by 'Continue with' transaction element' and 'output'.
3. Select the new transition and make sure the __Get input before continuing__ checkbox are unchecked and the __User Intent__ is removed. 
4. Select the Output below, name it `Ask user what was meant` and add the following answer text: `Did you want to order a coffee or see our selection of coffees?`.

![1-add output](//videos.ctfassets.net/2vbtnveccz5s/2lpHIv36Yw723HmAaLZdHW/bec780c7ac2f89f125ef23df0f688cf8/1-add_output.mp4)

## Add the first flow link

Now it's time to add a flow link if the user wants to order a coffee.

1. Select the Plus icon below the output 'Ask user what was meant', hover over 'Continue with' and select __Flow link__.
2. Select the transition and name it `Order`.
3. Make sure 'Get input before continuing' is selected.
4. Add the positive intent `Order` and generate a 'Match'.
5. Navigate to the new flow node and name it `User wants to order a coffee`.
6. Add the __User wants to order a coffee__ flow via the __Flow Link__ panel using the __Browse__ button in the Target section.

![2-add first flow link](//videos.ctfassets.net/2vbtnveccz5s/NLrZwETpcllM64mPzBR7i/052d95b1bddfd7819912a5fbf7edefe6/2-add_first_flow_link.mp4)

## Add the second flow link
Now that we've covered the order flow link. It's time to add one more if the user wants to see the coffee selection.

1. Select the Plus icon below the 'Ask user what was meant', followed up with 'Split path' and Flow link. 
2. Name the new flow node `User wants to see the selection`.
3. Add the __User asks about coffees we offer__ flow via the __Flow Link__ panel using the __Browse__ button in the Target section.
5. Navigate to the transition above name it `Selection`.
6. Make sure 'Get input before continuing' is selected.
7. Add the positive intent `Selection` and generate a Match.
9. Hit the 'Save' button.

![3-add second flow link](//videos.ctfassets.net/2vbtnveccz5s/7MFN84QuAHQ0VGKXw8X7IT/e8762397bae109c933df3d18a0aef370/3-add_second_flow_link.mp4)

## Test in Tryout

> **User:** coffees  
> **Bot:** I understand you would like to talk about coffee. Can you be more specific? Did you want to order a coffee or see our selection of coffees?
> 
> **User:** your selection  
> **Bot:** We offer a variety of handcrafted coffee drinks - from espressos to macchiatos to flat whites and more.
> 
> **User:** espresso  
> **Bot:** You're talking about coffee. Would you please tell me what you wanted exactly? Did you want to order a coffee or see our selection coffees?
> 
> **User:** order  
> **Bot:** Ok, what coffee would you like?


Build - Handle ambiguous inputs

Handle ambiguous inputs

Listeners help your bot pick up relevant pieces of information from user inputs, even when these have not been explicitly prompted for. You can think of a listener as a fly on the wall, silently listening and registering things.



## Global listener

Global listeners listen to any input, independent of the flow.

Just like flow listeners, global listeners help your bot pick up relevant pieces of information from user inputs, even when these things have not been explicitly prompted for. You can think of a listener as a fly on the wall, silently listening and registering things. However, global listeners listen to any input in a conversation, whereas flow listeners only listen to inputs that trigger or pass through a particular flow.

### When to use a global listener

It can be very tempting to use a global listener any time you want to pick something up from an input. For example, you could create a global listener that stores the name of a user in a global variable 'userName' whenever a name is encountered in an input. However, this is generally not a good practice. Because the global listener operates on each input, it might accidentally overwrite 'userName' with any name, like the name of the user's sister for example. In general, it is best to use a flow listener for the flow where you specifically anticipate receiving a particular detail and only use global listeners to listen for things that transcend flows.

### Components

Global listeners are made up of the same parts as flow listeners: a __TLML Syntax__ condition and an __Execution Script__. The Syntax condition determines what patterns should be listened for, e.g. a positive sentiment. The Execution Script defines what should happen when the Syntax condition is met, for example updating a counter or adding an annotation. An example of a global listener that counts the number inputs in a conversation that express a positive sentiment could look like this:

![1-listener](//images.ctfassets.net/2vbtnveccz5s/2mB8OQuOoaeGh9SW21ZPlY/e7bad27cadd8580be43ffe51df254084/1-listener.PNG?classes=w50)

You manage global listeners in the Globals area of your solution:

![global-listener](//images.ctfassets.net/2vbtnveccz5s/4AEivOiveEknqRs2uFReXY/a6ad4add5dd9cf7d5033ffba88a46a64/global-listener.PNG)

### Pre or post matching

There are two types of global listeners, *pre* matching listeners and *post* matching listeners.

*   **Pre listeners** - Pre matching listeners listen to inputs *before* Teneo tries to match the input to a trigger or transition. This makes them best suited when you want to do things that are important during matching. For example, you can use them to add annotations that can then influence if a particular trigger or transitions should match. For example, a pre matching listener can annotate a postal code in an input and a language condition might say 'you should only match if a postal code is present in the input'. Because the annotation is added before Teneo tries to match the language conditions, the annotation will be taken into account.
*   **Post listeners** - Post matching listeners act on inputs *directly after* Teneo finds a matching trigger or a transition waiting for a new input. You can't use these to do things that are important during the matching process, because by the time the post listeners are executed, the matching process is already completed. You can use them, for example, to check if the currently triggered flow was stored in a particular folder, like the 'Flows' folder. If true, the listener would then perform the task specified in the listener's operation.

You can find more details about the order in which Teneo executes listeners (and other tasks) in the [Input processing path reference](/studio/reference/input-processing-path).

## Flow listener

In addition to global listeners, Teneo allows listeners on a flow level too. Listeners are often used to extract entities from user inputs.

### Types

When you add a listener to a flow, you can choose to make it listen to all inputs that trigger or pass through the flow or to make it only listen for a particular trigger or transition.

| Type | Description | How to add |
| --- | --- | --- |
| **Flow listener** | Listens to all inputs that pass through a flow including inputs that trigger the flow. | Open your flow in edit mode. Go to the 'Flow' tab and select 'Listeners'. |
| **Trigger / transition listener** | Is defined in relation to a specific point of a flow; will only kick in for inputs of the trigger or transition where the listener was added. | Open your flow in edit mode. Select the trigger or transition. Click on 'Add' in the 'After Match' section to add a listener. |

### Components of a listener

A listener is made up of two parts: a __TLML Syntax__ condition and an optional __Execution Script__. The Syntax condition determines what patterns should be listened for, e.g. the name of a city. The operation defines what should happen when the condition is met, e.g. setting a variable or updating a counter.

![2-flow listener](//images.ctfassets.net/2vbtnveccz5s/7DICiC3UyxeOMpDxQoY5Y8/87653bbdd22f58f569579f73b7c887cb/2-flow_listener.png?classes=w40)

Sometimes you can extract the information you want in the TLML Syntax condition itself. In that case, you don't need to specify a script. In the example below, the listener extracts the destination mentioned in the user input. Read more on how to extract data from inputs [here](/studio/language-understanding/concepts/attached-scripts).

![3-flow listener tlml](//images.ctfassets.net/2vbtnveccz5s/4hqcPETWI7iPRFIFZSUVJ6/b103b88dbe88ba8285407071db1c451f/3-flow_listener_tlml.PNG?classes=w40)

If you need additional programmatic logic, for example to further process what you have extracted, you can add it to the script field:

![4-flow listener script](//images.ctfassets.net/2vbtnveccz5s/7yLYa4ed3R6f24ulOTpBKX/bb7b9d72a4fb430237b3f13bb0765e06/4-flow_listener_script.PNG?classes=w40)

### Use cases
*   **Flow listeners** are defined for a flow and listen to all inputs that trigger or pass through a flow. They are generally used when your bot should pick up certain pieces of information wherever they are mentioned in the flow dialogue. [Slot filling flows](/getting-started/build-a-slot-filling-flow) typically make use of flow listeners.
*   **Trigger/transition listeners** are attached to a specific trigger or transition of a flow. A trigger/transition listener can be the best solution when you need to pick up something that can be interpreted differently depending on where you are in the flow. For example, if a flow should pick up two dates from a user (like an *arrival* and *departure* date for a holiday), you can add a listener to the transition where the user is asked for the arrival date and another listener to the transition for the departure date.

!!! If you find yourself creating the same listener on multiple triggers or transitions, you might want to check if you can use a flow listener instead.

## Listeners vs After Match
[After Match](/getting-started/data-actions) are great if you know exactly:
* What you want to extract from the user input
* When that information is present in the user input

However, the above conditions will not always be met. There will also be cases where the user input contains information that the bot has not yet asked for. Consider also a case in which we want to use a Global Listener to extract information. In cases like these, we can use Flow Listeners combined with propagation scripts in order to add programmatic extraction logic. This enables us to extract the information we need at any point in the conversation, rather than just when we are expecting it, and to propagate the value to a Global Listener.

Build - Listeners

Listeners

[Listeners](/studio/conversations/concepts/listeners) can be used in multiple ways in Teneo. For this example, we will demonstrate one way of using a listener inside a flow. In the previous page on how to [handle ambigous inputs](/studio/conversations/how-to/create-a-custom-order-group#create-a-flow-for-partial-understanding), we demonstrated a way to handle partial understanding and catch keywords. Adding on to that, we will now add a [listener](/studio/conversations/concepts/listeners) to recognize if a coffee type is mentioned and the user wants to order it. 

Before our changes, we would have a conversation like this:

> **User:** espresso    
> **Bot:** You're talking about coffee. Would you please tell me what you wanted exactly? Did you want to order a coffee or see our selection coffees?  
> 
> **User:** order    
> **Bot:** Ok, what coffee would you like?     

After our modifications, it will look like this:

> **User:** espresso    
> **Bot:** You're talking about coffee. Would you please tell me what you wanted exactly? Did you want to order a coffee or see our selection coffees?  
> 
> **User:** order    
> **Bot:** Ok, a **espresso** will be ready for pickup in 5 minutes.     

To achieve this we need to do the following: 
* Create a [flow variable](/studio/flows/concepts/variables#flow-variable).
* Add a [flow listener](/studio/conversations/concepts/listeners#flow-listener).
* Modify the flow link to include the mentioned coffee type.

## Create a flow variable
Let us start off by opening the [Partial Understanding: Coffee](/studio/conversations/how-to/create-a-custom-order-group#create-a-flow-for-partial-understanding) flow and creating a new flow variable to store the coffee type mentioned by the user. 
1. Open the [Partial Understanding: Coffee](/studio/conversations/how-to/create-a-custom-order-group#create-a-flow-for-partial-understanding) flow in edit mode.
2. While inside the flow, navigate to 'Flow' tab located.
3. Click on 'Variables' add a new variable that has the name `coffeeType` and the value `""`.    

![1-add flow variable](//videos.ctfassets.net/2vbtnveccz5s/4ud2hLpHrvhVD36rkdqOHS/2913b7b9a34ffe220db6273b9e1fd4be/1-add_flow_variable.mp4)

## Create a flow listener
Now it is time to add a flow listener to listen for the coffee type. We will also use the previously created [COFFEES_SERVED.ENTITY](/getting-started/create-custom-entities#create-a-coffees-served-entity) for the condition.
1. While inside the 'Variables' section, switch over to 'Listeners'. 
2. Click on the 'Add' button. This will open up a new flow listener.
3. Name the listener `Listen for coffee types`.
4. In the TLML Syntax field, paste in the following: `%COFFEES_SERVED.ENTITY^{coffeeType = lob.coffeeType}`.
5. Click on 'Ok'.
6. Click on the back arrow in the menu to return to the Home tab of the flow.

![2-add listener](//videos.ctfassets.net/2vbtnveccz5s/1vQrhLkOQYygTUSOtQ8tky/b68e664327f6e70bba8dadb7794f4a07/2-add_listener.mp4)

!!! This can also be done by adding an [Entity Match](/studio/flows/concepts/triggers#match-requirements) to the intent trigger.

## Modify the flow link
The next step is to modify the flow link to send over the flow variable that stores the mentioned coffee type to the 'User wants to order a coffee' flow. 
1. While inside the flow, select the flow node 'User wants to order a coffee'. 
2. Navigate to the 'Target' section and select the drop-down menu right beside 'orderedCoffeeType'.
3. From the drop-down menu, select the previously created flow variable 'coffeeType'. This will send the value from this flow variable to the 'orderedCoffeeType' flow variable inside 'User wants to order a coffee'.
4. Save the flow.

![3-modify flow link](//videos.ctfassets.net/2vbtnveccz5s/4JrQxy3gXOSjuNwZ5WZh5k/701d968e9140e321116ab962564b8636/3-modify_flow_link.mp4)

## Try it out
Let's go ahead and test the modified flow by mentioning a coffee type:    
> **User:** `espresso`    
> **Bot:** You're talking about coffee. Would you please tell me what you wanted exactly? Did you want to order a coffee or see our selection coffees?  
> 
> **User:** `order`    
> **Bot:** Ok, a **espresso** will be ready for pickup in 5 minutes.     


Build - Use Listeners

Use Listeners

Throughout the lifetime of your bot, you may need to execute scripts and code. For example, at the start of the conversation you might want to retrieve and store the timezone of the user, so you can personalize the greeting message and also use the timezone in other flows. Or inside a flow, you might want to run a script to check if a user provided a valid account number.

## Groovy

Scripts in Teneo are written in Groovy or Java code. Apache Groovy is similar to Java but with an easier-to-learn syntax. More details on Groovy can be found here: [http://groovy-lang.org](http://groovy-lang.org).

For a quick overview of basic Groovy scripts that come in handy when using Teneo, see the [Groovy basics](/studio/scripting/concepts/groovy) page. If you're looking for something more like a tutorial, we quite like this one: [https://www.timroes.de/2015/06/27/groovy-tutorial-for-java-developers/](https://www.timroes.de/2015/06/27/groovy-tutorial-for-java-developers/).

## Teneo engine scripting API

In many cases, you may need to access the internal engine and request data in your scripts. You may, for example, want to use the user's input in a script or store a request parameter in a global variable. The Teneo engine scripting API provides access for scripts to internal engine data as well as request parameters. For more details, please refer to the [Engine scripting API Reference](/studio/reference/engine-scripting-api).

## Where to add your code?

You can add scripts to various places in a solution, depending on when you want the script to be executed. Some places have already been covered:

*   [Script nodes](/studio/flows/how-to/add-a-script-to-your-flow#add-a-script-node) in flows
*   Scripts that are executed as operations in [listeners](/studio/flows/concepts/listeners)
*   Scripts that are part of [scripted contexts](/studio/conversations/concepts/context)
*   [Script conditions](/studio/reference/condition-syntax#script-condition) in triggers and transitions


Scripting

Integrations are a reusable set of scripts that can be written once and used many times within flows throughout the solution. Most commonly, they are used to connect to external services. For example, your bot may want to provide weather information and use an integration to connect to a weather service.

Integrations are added at the solution level by clicking on the 'Solution' button in the top left, selecting 'Resources', and choosing 'Integrations'.

![1-integration script](//images.ctfassets.net/2vbtnveccz5s/3cnjJXED8VO96FwDfjqTnz/6dd89b3c61a27b2fe4c93e71d42158ab/1-integration_script.PNG)

## Methods

Every integration can contain one or more methods. For example, a weather integration might have two methods; 'Get current weather' and 'Get weather forecast'.  

Each method has a name and an optional description. Additionally, each method can contain input and output parameters and a script.

### Input parameters

Input parameters allow your method to receive information from a flow. The ‘Get current weather’ method for a weather integration could, for example, have an input parameter ‘city’. A ‘Get weather’ flow extracts the city from the user’s input and passes it on to the integration via an input parameter. The input parameters can be strings, lists, objects, etc. The type depends on the type of the variable that was transferred by the flow. Input parameters are optional. Their names cannot contain spaces.

### Output parameters

Output parameters allow your method to send information back to a flow. The ‘Get current weather’ method could, for example, have two output parameters ‘weatherTemperature’ and ‘weatherDescription’ which can be used by the ‘Get weather’ flow in the final answer. Just as input parameters, output parameters can be strings, lists, objects, etc. Output parameters are optional and their names cannot contain spaces.

### Script

This is the script that will be executed when the integration is called by a flow. Both the integration's input parameters and the solution's global variables are available inside the script. For example, the script node of a 'Get current weather' method might receive a location as an input parameter and use a global variable to determine the user's preference for Fahrenheit or Celsius. A method's script can populate its output parameters as well as global variables.

!!! Integrations are widely used while creating Backend Connectors. Please see [Resources](/resources) for more examples.

## Adding an integration to a flow

Once the integration is saved, it is available in the ribbon when a flow is opened in Edit mode. From there, it can be used in a flow where the required method can be selected and the relevant flow variables can be assigned to input and output parameters.

For an example of how to add an integration to your solution and use it in a flow, see [How to add an integration](/studio/scripting/how-to/add-an-integration).


Integration manager

To correctly handle a user's input, a bot may need to connect to external services. For example, you may want to provide weather information or your bot may need to initiate a reset password process. In Teneo these calls to external services and the handling of their responses are carried out by *Integrations*. You add an integration to your solution once, and after that it's available for any flow in that solution.

In this example, we will create a flow that uses an integration that provides the number of calories in a coffee, like this:

> **User:** How many calories in a Cappuccino?  
> **Bot:** One flat white contains about 120 calories, a walk of about 30 minutes should be enough to burn them.

To make this possible, we are first going to set up an integration and then create a flow that makes use of the integration. The final result will look like this:  

![final flow](//images.ctfassets.net/2vbtnveccz5s/2GIWYjwxJoZfzhkaqpyUO2/0149718f000ce5702ebe12953040993d/final_flow.png)

## Set up the nutrition integration

First we are going to set up the integration. These are the steps to add an integration in Teneo:

1.  Open the 'Solution' tab in the solution's main window and select 'Resources'.
2.  Navigate to 'Integration' at the top.
3.  Click the 'Add' button to create an integration.
4.  Name the integration `Nutrition`.
5.  Click the 'back button' in the top left to leave the integration's backstage view so that you enter the main integration view.

![1-create integration](//videos.ctfassets.net/2vbtnveccz5s/6607V5tGG80o17na4eXhdK/9d4ff4d06f976d9a666ecb15fdeeb6de/1-create_integration.mp4)

### Set up a method

An integration can contain multiple methods. A method is a block of code that only runs when it is called. You can pass data into the method and after executing the code, the method returns the results. Here we want to create a method that returns the calories and walking duration to burn these calories for the coffee drink that was passed into the method.

When you created the integration, a 'Default Method' was automatically created. Let's give it a proper name and add an input parameter we will use to pass data into the method and add two output parameters that we will use to return the results:

1.  Re-name the method by replacing 'Default Method' in the 'Name' field with `Get calories` and add the description `Returns calories for a given drink and the walking duration required to burn the calories`.
2. On the right, click on the ‘Inputs’ and the ’Outputs’ tab to see the input and output parameters (if not yet visible already).
3. Click 'Add' in the input parameters pane and give the input a name and a description:
*   Name the input parameter `query`.
*   Add the description: `The coffee drink to find the calories for. For example: 'cappuccino' or 'espresso'`.
4.  Now let's add an output parameter for the calories found. Click 'Add' in the output parameters panel and enter the following:
*   Name: `calories`.
*   Description: `The calories found`.
5.  Finally, add the last output parameter for the walking duration:
*   Name: `walkingDuration`.
*   Description `Walk duration in minutes to burn the calories`.

### Add the script to the method

To complete the method, let's add the script which will be executed when the integration is called by the flow and save the method:

```groovy
def caloriesPerDrink = [
    "americano": 9,
    "cappuccino": 120,
    "cortado" : 34,
    "espresso": 3,
    "frappuccino": 408,
    "latte": 189,
    "lungo": 3,
    "macchiato": 8,
    "ristretto": 5,
    "flat white": 223,
    "brewed coffee": 2
]

// populate output param 'calories' with calories found
calories = caloriesPerDrink[query]

// calculate walking duration
def durationMinutes = (int)Math.ceil((calories/4))

// populate output param 'walkingDuration'
walkingDuration = (durationMinutes == 1 ? durationMinutes + " minute" : durationMinutes + " minutes")
```

Finally, save the integration.

![2-set up integration](//videos.ctfassets.net/2vbtnveccz5s/6OKeSk1UUdAW6NG7rPBiFZ/f44969fc1a18f262144adbed5be4aefc/2-set_up_integration.mp4)

!!! For simplicity, the script above *simulates* a query to a nutrition API. If you prefer to use a real API, you can replace the script above with the contents of this file: [nutritionix integration example script](//assets.ctfassets.net/2vbtnveccz5s/7pghiHjMVHeZogIadJtNhV/177d9a9b8980f493faf3f744f8a5c809/nutritionix_integration_example_script.txt). However, make sure that you add the appropriate 'appId' and 'appKey' which you can obtain here: [developer.nutritionix.com](https://developer.nutritionix.com/).

## Create the nutrition flow

1.  Create a new flow and give it the name `User asks about calories in a drink`, then select the trigger and call it `How many calories in a flat white`. Give the trigger these Intent inputs:

```example-inputs
How many calories in a flat white
Number of calories in an espresso
Whats the calorie count in a macchiato
How many calories is there in a lungo?
How many calories in a latte?
What's the calorie count in a ristretto?
Tell me the calories in an cortado
What is the number of calories in a brewed coffe
What's the calories in a frappuccino
Could you tell me about the calorie count in an americano
How many calories in a cappuccino
Number of calories in a macchiato
```

2. Generate a Match.

![3-populate trigger](//videos.ctfassets.net/2vbtnveccz5s/67yoNkV9hvCmizUIW8JYM/9af0e263b39093155c0f2fc478ba82dc/3-populate_trigger.mp4)

### Add a flow variable and a flow listener to recognize and store the coffee type

We will need to pick up the type of coffee that the user mentioned, like espresso or cappuccino, so we can use it later to look up the number of calories. First, let's add a flow variable in which we can store the coffee type. Go ahead and add a flow variable:

1. Select the 'FLOW' tab.
2. Click 'Variables' on the left.
3. Click the 'Add' button and give your variable a name by replacing 'Variable1' with `mentionedCoffeeType`.
4. We will initialise this variable as an empty String, so in the field below just add `""`.

Now that we have an empty flow variable for __mentionedCoffeeType__, we can use a [flow listener](/article/build/conversations/concepts/listeners) to set it whenever a coffee type is mentioned in the flow.

1. Select 'Listeners' to the left.
2. Click on the 'Add' button.
3. Call your listener `Pick up coffee type`.
4. Add the following TLML Syntax condition:
`%COFFEES_SERVED.ENTITY^{ mentionedCoffeeType = lob.coffeeType }`
5. Click on 'OK' to create the listener.

![4-refilm add var and listener](//videos.ctfassets.net/2vbtnveccz5s/2lUjOlFZg0tkvnXcgatGwu/a5190b54a8544ca44b3923c4a34af33d/4-refilm_add_var_and_listener.mp4)

As you can see, the TLML Syntax condition above uses the entity __COFFEES_SERVED.ENTITY__ that we made when we [created custom entities](/getting-started/create-custom-entities). The [propagating script](/studio/language-understanding/concepts/attached-scripts) __^{ mentionedCoffeeType = lob.coffeeType }__ stores the coffee drink mentioned by the user in our flow variable __mentionedCoffeeType__.

![explain propagation script](//images.ctfassets.net/2vbtnveccz5s/2LAmwYj0lHKgwf9jwszb5T/6422f19bc3bcf23c6810f13b476d523d/explain_propagation_script.png?classes=mediumimg)

### Add the integration to the flow

Next, we will add the Nutrition integration to our flow. The integration appears as 'Nutrition' in the ribbon. Make sure nothing is selected in your flow by clicking anywhere in the white area around your flow nodes. Then simply click the Nutrition icon in the ribbon.

Currently, the integration is dangling and not connected to any of the other elements in the flow. However, we want our integration to be executed immediately after the flow is triggered, and right before an answer is given to the user. To put the integration in its place we need to follow these steps:

1. Click on the Plus icon above the output node, followed by 'Continue with' and 'Integration'.
2. Select the Nutrition integration.

![5-add integration to flow](//videos.ctfassets.net/2vbtnveccz5s/4UgZYU6VA9r0bMWjkFPFRH/7be3a5617852d735acb3e64a168a9c83/5-add_integration_to_flow.mp4)

### Add flow variables to store integration results

Now it is time to receive information returned by the integration. In our case, the integration returns two fields: __calories__ and __walkingDuration__. We need to store these values somewhere, so you will need to add two flow variables for this too:
*   A flow variable called `calories` with value `""`.
*   A flow variable called `walkingDuration` that also has the value `""`.

### Send the mentionedCoffeeType to the integration

Now that we have put the integration in its place, we can specify which variables should be transferred back and forth. In our case we will send the __mentionedCoffeeType__ variable to the integration so it can use it to lookup the calories. Follow these steps to achieve that:

1.  Select the integration in your flow and give it a name like `Get calories for a drink`.
2.  For the field 'query' in the Send section, select our flow variable 'mentionedCoffeeType' from the dropdown.

### Receive calories and walking duration

Now that we have added the variables __calories__ and __walkingDuration__, we will need to make sure that the values returned by the integration are actually stored in them:

1.  Select the integration in your flow.
2.  For 'calories' in the Receive section, select the flow variable __calories__ from the dropdown.
3.  For 'walkingDuration' in the Receive section, select the flow variable __walkingDuration__ from the dropdown.

![6-receive calories and walking duration](//videos.ctfassets.net/2vbtnveccz5s/1De4OuPWEVbUfhI1LXHV6X/3c2936fdc99b6c61ad4eef8dcab9256a/6-receive_calories_and_walking_duration.mp4)

The integration is now properly included. The coffee type that was picked up from the input is sent to it and after the integration is executed our flow will receive the calories and the time one needs to walk to burn the calories. The received values are stored in the flow variables calories and walkingDuration.

### Populate the output

When we reach the output we want to provide the calories and the time it takes to burn them to the user. Add the following answer text to your output:
* `One ${mentionedCoffeeType} contains about ${calories} calories. A walk of about ${walkingDuration} should be enough to burn them.`

Make sure you give your output a name like `One flat white contains about 223 calories, a walk of about...`.

![7-populate output](//videos.ctfassets.net/2vbtnveccz5s/6hAbF8mbqufNuGRkIUrrY4/889cb360f15b4d1f0283edb797500228/7-populate_output.mp4)

### Add a fallback output node

There may be cases where the integration fails to provide a proper response, for example when the api that provides the details is down. It is good practice to add an output for that too:

1.  Select the Plus icon under the integration.
2.  Hover over 'Split Path', followed by 'transaction element' and add an Output.
4.  Add the following answer text to the new output `Unfortunately, I can't look up calories currently.`
5.  Give the output the name `Can't look up calories currently`.

![8-add fallback node](//videos.ctfassets.net/2vbtnveccz5s/2gwDs8E75EiuzYmKT1q8l2/aaa9d3393c887b069c7ded2ea4f79ec2/8-add_fallback_node.mp4)

### Add a condition to your transition

You now have two outputs, one that should be shown when we found calories and one in case something went wrong and we could not find the calories. We will have to make sure that Teneo only shows the first output when calories were found.

1.  Select the Plus icon that points to the first output (the transition should have the [transition order](/studio/flows/concepts/transitions#order) 1).
2.  Hover over 'Match' and click on 'TLML Syntax'.
3.  Enter the following Syntax Condition inside the editor: `{calories}`.
4.  Give the transition a name, like `Results found`.

!!! Please note that you can also add a Flow Variable Match to achieve same results.

The condition we added is a Groovy script, because it is surrounded by curly brackets __{}__. The expression returns true if the flow variable __calories__ is not empty. For more details on how Groovy decides if an expression is true, read about the [Groovy Truth](http://docs.groovy-lang.org/next/html/documentation/core-semantics.html#Groovy-Truth).

If you like, you can give the second transition the name `Results not found`, but this is not required.

![9-add condition to transition](//videos.ctfassets.net/2vbtnveccz5s/2Im0ujev9Uvrw6zPjkSBnI/f5c77d7a1295abb390d0f18eeca31786/9-add_condition_to_transition.mp4)

## Save and test your flow

That's it! Save your flow and give it a go in Tryout.

> **User:** How many calories in a Cappuccino?  
> **Bot:** One flat white contains about 120 calories, a walk of about 30 minutes should be enough to burn them.
> 
> **User:** How many calories in a flat white?  
> **Bot:** One flat white contains about 223 calories, a walk of about 56 minutes should be enough to burn them.


Advanced Concepts

Groovy

Teneo engine scripting API

Where to add your code?

Next page