Hero - Build your bot

To correctly handle an input of a user, 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:  

![flow layout](//images.ctfassets.net/2vbtnveccz5s/4g89S14PrEFzTNC3qN2IEt/99b3ea41924bf4c58acef95fe3e33018/flow_layout.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-setup](//videos.ctfassets.net/2vbtnveccz5s/116CJeTEQnJQaKtKITuyze/d112fb478a826f4e95de4a45584ecd46/1-setup.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-setup method](//videos.ctfassets.net/2vbtnveccz5s/5b9vMkKKkvJjsSMkDinq89/c1e97f15c8729685389385fdcc2b505c/2-setup_method.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 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-create flow](//videos.ctfassets.net/2vbtnveccz5s/1F1vVYME5C0eWq04D6DqwL/503a4dd8e7abd8a7df245b741c843007/3-create_flow.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. Save the listener.

![4-flow var](//videos.ctfassets.net/2vbtnveccz5s/5dIZwnyogOcn4xU8bXoC8k/651b176e6f4e14824045823c84393140/4-flow_var.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. Select the integration 'Nutrition' in the 'Add Node' section of the top ribbon.
2. In the ribbon choose 'Set start node'. This points the trigger straight to the integration.
3. Draw a line from the integration to the output node.

![5-add integration node](//videos.ctfassets.net/2vbtnveccz5s/7n6BrTWAoA7gBlvNwXajld/de865055c9a2b43b847e1df4476ed1ff/5-add_integration_node.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.
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 and give it a name like `Get calories for a drink`.
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-send receive](//videos.ctfassets.net/2vbtnveccz5s/5BRXkvBFyHtiuBPUcTTrsq/47da0a023b9b8dd7b21dd0eb5e997c24/6-send_receive.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...`.

### 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 lookup calories currently.`
5.  Give the output the name `Can't lookup calories currently`.

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

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


Add an integration

To correctly handle an input of a user, 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:  

![i-flow layout](//images.ctfassets.net/2vbtnveccz5s/3w9iF1fgL9gLlTybObfQE1/088999217ea34a9b5324aebe6cb79434/i-flow_layout.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 dashboard.
2.  Navigate to the Integration tile.
3.  Click the 'Add' button to create an integration.
4.  Name the integration `Nutrition` and add the description `Returns calories for a given drink and the walking duration required to burn the calories`.
5.  Click on Create.

![1-add integration](//videos.ctfassets.net/2vbtnveccz5s/2yYCxpImJLTwgmAOx6kb9X/a3ea9c1f83159e4f8816d361e4697c9f/1-add_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 to `Get calories`.
2. Click on the Add button in the Inputs 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'`.
3.  Now let's add an output parameter for the calories found. Click 'Add' in the Outputs panel and enter the following:
*   Name: `calories`.
*   Description: `The calories found`.
4.  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 method](//videos.ctfassets.net/2vbtnveccz5s/3V80egrlYZLgES1DGZWDbM/be82fb36062f822330194c2b15bc94c0/2-set_up_method.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 name the trigger `How many calories in 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 by clicking on the Plus icon followed by Match and Generate a draft.

![3-create flow](//videos.ctfassets.net/2vbtnveccz5s/7hIGPOLAzFOcqlsycI9URD/eda7aaee89753383c1753980f2139949/3-create_flow.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. Click on the Variables icon followed by the Plus icon to create a new flow variable.
2. Give your variable the name `mentionedCoffeeType`.
3. We will initialise this variable as an empty String, so in the field below just add `""`.

![4-flow var](//videos.ctfassets.net/2vbtnveccz5s/2rZRFng5VRu1qKMAC34iSP/6881acdfe6335bee9e8078302a5eb237/4-flow_var.mp4)

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. Click on the Listeners icon followed by the Plus icon to create a new flow listener.
2. Call your listener `Pick up coffee type`.
3. Add the following TLML Syntax condition:
`%COFFEES_SERVED.ENTITY^{ mentionedCoffeeType = lob.coffeeType }`
5. Save the listener.

![5-flow listener](//videos.ctfassets.net/2vbtnveccz5s/6Gpzngne2eALzSTSu90kJc/f4ba79a627591f4f47e1b2401f488993/5-flow_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 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 these too:
*   A flow variable called `calories` with value `""`.
*   A flow variable called `walkingDuration` that also has the value `""`.

### Add the integration to the flow

Next, we will add the Nutrition integration to our flow.

1. Click on the Plus icon above the output.
2. Select 'Continue with' followed by Integration, then choose the Nutrition integration.
3. Give it a name like `Get calories for a drink`.

![7-add integration to flow](//videos.ctfassets.net/2vbtnveccz5s/106FVrINJONuB8H2u19qHN/4a85983d3961591060b18a6a1f9fd7fd/7-add_integration_to_flow.mp4)

### 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.  Click on Add variable mapping on the integration node.
2.  In the first dropdown, select IN.
3.  Select our flow variable 'mentionedCoffeeType' in the second dropdown.
4.  Finally, select 'query' in the last dropdown.

### Receive calories and walking duration

Next, we will need to make sure tha values returned by the integrationa re stored in our flow variables __calories__ and __walkingDuration__:

1. Click on Add variable mapping in the flow node and set it to OUT.
2. Select 'calories' in the second dropdown and the flow variable __calories__ from the last dropdown.
3. Repeat the same process to add a mapping for __walkingDuration__.

![9 receive calories walkingDuration](//videos.ctfassets.net/2vbtnveccz5s/PvM9d1Vgpf0A1j0RBAzdf/0f2a8fc97cc7f35f87510ff18c461e02/9_receive_calories_walkingDuration.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...`.

### 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.  Click on 'Split Path', followed by 'transaction element' and add an Output.
4.  Add the following answer text to the new output `Unfortunately I can't lookup calories currently.`
5.  Give the output the name `Can't lookup calories currently`.

### 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 you made.
2.  Click on 'Match' and then 'TLML Syntax'.
3.  Enter the following Syntax Condition inside the editor: `{calories}`.

!!! 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).

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


Table of Contents