{"__v":0,"_id":"5845a4aa9f6fbb1b00430840","category":{"version":"5845a4a89f6fbb1b004307b7","project":"54d3007669578e0d002730c9","_id":"5845a4a89f6fbb1b004307bf","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-01-26T17:19:04.989Z","from_sync":false,"order":7,"slug":"guidelines","title":"Guidelines"},"parentDoc":null,"project":"54d3007669578e0d002730c9","user":"55a04a395730f40d001104d2","version":{"__v":1,"_id":"5845a4a89f6fbb1b004307b7","project":"54d3007669578e0d002730c9","createdAt":"2016-12-05T17:32:24.708Z","releaseDate":"2016-12-05T17:32:24.708Z","categories":["5845a4a89f6fbb1b004307b8","5845a4a89f6fbb1b004307b9","5845a4a89f6fbb1b004307ba","5845a4a89f6fbb1b004307bb","5845a4a89f6fbb1b004307bc","5845a4a89f6fbb1b004307bd","5845a4a89f6fbb1b004307be","5845a4a89f6fbb1b004307bf","5845a4a89f6fbb1b004307c0"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"25.0.0","version":"25"},"updates":["56fdb405aa7b710e007d3847"],"next":{"pages":[],"description":""},"createdAt":"2015-12-22T00:22:25.325Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"A context is a powerful tool that can help to create sophisticated voice interaction scenarios. In this post we’ll look at how you can use contexts to build dialogs.\n\nWhen a dialog is created, it’s usually the case that many branches of conversation are possible. Therefore, intents in an agent should be designed so that they follow each other in the correct order during a conversation. \n\nThe best way to demonstrate how this works is to build a conversation together, step-by-step. As an example, we’re going to create an agent for a floral shop. You can download it <a href=\"https://s3.amazonaws.com/static.api.ai/agents/Florist-Shop.zip\" target=\"_blank\">here</a> and try the instructions in your account.\n\nFirst, let’s take a quick look at how contexts operate.\n\n##1. Using contexts\n\nContexts will appear in your agent just under the intent title. You should see two fields here: input and output contexts. Corresponding input and output contexts in intents will determine whether they follow or precede one another. \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/FQWedL4URN21OoHnPves_2015-11-18-greetings.jpg\",\n        \"2015-11-18-greetings.jpg\",\n        \"1426\",\n        \"430\",\n        \"#32a1e0\",\n        \"\"\n      ],\n      \"sizing\": \"80\"\n    }\n  ]\n}\n[/block]\nTo add a context, just type its name into the field and press enter. The context will now appear as a box with a colored border.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/eZ0jVXjFSpqkJKGxAPO9_2015-11-18-context-compose.jpg\",\n        \"2015-11-18-context-compose.jpg\",\n        \"1400\",\n        \"304\",\n        \"#305a7d\",\n        \"\"\n      ],\n      \"sizing\": \"80\"\n    }\n  ]\n}\n[/block]\nHere we’ve set an **output context** for our floral shop named ‘compose’. Once this intent is matched, the context ‘compose’ will be set. So any intents that have this as an incoming context will now have top priority when matching user requests. Note that these intents will not be matched if the context is not set.\n\nAll contexts have a very important property – lifespan.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/R0qFIMCwRZEFRF2L9T5X_2015-11-18-context-compose-lifespan.jpg\",\n        \"2015-11-18-context-compose-lifespan.jpg\",\n        \"1410\",\n        \"526\",\n        \"#2e637d\",\n        \"\"\n      ],\n      \"sizing\": \"80\"\n    }\n  ]\n}\n[/block]\nBy default the lifespan value is set to five. It means that the context will last for the next five matched intents. So if you have different input/output contexts in each of the following intents, all of them will be collected in the next five stages of the dialog, like a chain of contexts. \n\nWhile this feature can be very useful, at times you may want to get rid of a context after the following intent is reached. In these situations you can simply change the lifespan to one.\n\n##2. Managing the conversation flow\n\nNow we’re ready to design the dialog we want our agent to produce. The best way to do this is to draw a scheme like the one pictured below. You can use <a href=\"https://www.lucidchart.com/\" target=\"_blank\">Lucidchart</a> for this.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/sRYqQXrSxmZExOEHuVsQ_2015-11-18-flowchart.jpg\",\n        \"2015-11-18-flowchart.jpg\",\n        \"624\",\n        \"652\",\n        \"#404d36\",\n        \"\"\n      ],\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\nFrom this scheme we can see that there are two main branches of the conversation. The first is for people who want to compose a bouquet themselves; the second provides the option to choose from one of four pre-made bouquets.\n\nIn order to manage these two branches of the conversation we’ll have to set different contexts. \n\nThe intent where fulfillment is ‘Okay! Would you like to compose a bouquet yourself?’, looks exactly as it was shown above: its name is ‘compose’ and it has an output context ‘compose’.\n\nSo we’ll have to create two different intents to match the possible answers. We’ll make one for ‘yes’:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/a8SQgDmQTaK5vT6XZHD2_2015-11-18-yes-compose.jpg\",\n        \"2015-11-18-yes-compose.jpg\",\n        \"1396\",\n        \"438\",\n        \"#349ed6\",\n        \"\"\n      ],\n      \"sizing\": \"80\"\n    }\n  ]\n}\n[/block]\nAnd one for ‘no’:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/mH50uypTe2vw6dSn1t0n_2015-11-18-no-compose.jpg\",\n        \"2015-11-18-no-compose.jpg\",\n        \"1376\",\n        \"446\",\n        \"#379ad6\",\n        \"\"\n      ],\n      \"sizing\": \"80\"\n    }\n  ]\n}\n[/block]\nIn both intents we have the same input context: ‘compose’. So after the intent ‘compose’ was matched and the context ‘compose’ was set, we can then logically only reach those intents with an input context ‘compose’. So if we say ‘yes’ we get into the ‘yes - compose’ intent; if ‘no’, then we are in the ‘no - compose’ intent.\n\nAnd now comes the most crucial point: we have to set **different** output contexts. So in order to continue choosing the flowers we have to set now ‘yes - compose’ context as output, and then as an input context to the following intents. The same goes for the other intent. In order to choose one of the pre-made floral arrangements, we have to set an output context ‘no - compose’ and then create the following intent with ‘no - compose’ as the input context.\n\nThis same logic applies along the whole dialog structure. Whenever you need to go further to a specific intent, you should set the corresponding contexts. This is especially important when you have multiple ‘yes/no’ answers in the conversation. \n\n##3. Gathering the parameters’ values\n\nThe other important function of the context is its ability to collect the parameters’ values. In our example, we’re collecting information during the dialog so we know by the end how to fill the customer’s order – how many flowers of what kind and what color we should add, or alternately, which pre-made bouquet we should choose. As long as a certain context is still alive (i.e., within its lifespan) the value we get from a parameter (if it was set in a context) is also alive.\n\nIn order to collect all the values at the end, we just have to set one context, which will appear in **every** intent, both input and output (except for the very first intent, where we set the output context only).\n\nWe just have to slightly modify what we see in the screenshots above:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/Kij1ioWDRG2nsG5dvSmv_2015-11-18-yes-compose-modified.jpg\",\n        \"2015-11-18-yes-compose-modified.jpg\",\n        \"1392\",\n        \"454\",\n        \"#3b9eca\",\n        \"\"\n      ],\n      \"sizing\": \"80\"\n    }\n  ]\n}\n[/block]\nTo retrieve the parameters from the context, write: #context_name.parameter_name:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/WVcG6ix5Rzqv0jSfHPHg_2015-11-18-parameters.jpg\",\n        \"2015-11-18-parameters.jpg\",\n        \"1380\",\n        \"626\",\n        \"#5c5c5d\",\n        \"\"\n      ],\n      \"sizing\": \"80\"\n    }\n  ]\n}\n[/block]\nThen in the dialog those values will look the same as always:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/XJZ57oYDT3uZ26BvoOG9_2015-11-18-parameter-values.jpg\",\n        \"2015-11-18-parameter-values.jpg\",\n        \"656\",\n        \"1016\",\n        \"#48787a\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nFeel free to play around with this example. You can download the agent <a href=\"https://s3.amazonaws.com/static.api.ai/agents/Florist-Shop.zip\" target=\"_blank\">here</a>.","excerpt":"","slug":"guidelines-contexts","type":"basic","title":"What are contexts and how are they used?"}

What are contexts and how are they used?


A context is a powerful tool that can help to create sophisticated voice interaction scenarios. In this post we’ll look at how you can use contexts to build dialogs. When a dialog is created, it’s usually the case that many branches of conversation are possible. Therefore, intents in an agent should be designed so that they follow each other in the correct order during a conversation. The best way to demonstrate how this works is to build a conversation together, step-by-step. As an example, we’re going to create an agent for a floral shop. You can download it <a href="https://s3.amazonaws.com/static.api.ai/agents/Florist-Shop.zip" target="_blank">here</a> and try the instructions in your account. First, let’s take a quick look at how contexts operate. ##1. Using contexts Contexts will appear in your agent just under the intent title. You should see two fields here: input and output contexts. Corresponding input and output contexts in intents will determine whether they follow or precede one another. [block:image] { "images": [ { "image": [ "https://files.readme.io/FQWedL4URN21OoHnPves_2015-11-18-greetings.jpg", "2015-11-18-greetings.jpg", "1426", "430", "#32a1e0", "" ], "sizing": "80" } ] } [/block] To add a context, just type its name into the field and press enter. The context will now appear as a box with a colored border. [block:image] { "images": [ { "image": [ "https://files.readme.io/eZ0jVXjFSpqkJKGxAPO9_2015-11-18-context-compose.jpg", "2015-11-18-context-compose.jpg", "1400", "304", "#305a7d", "" ], "sizing": "80" } ] } [/block] Here we’ve set an **output context** for our floral shop named ‘compose’. Once this intent is matched, the context ‘compose’ will be set. So any intents that have this as an incoming context will now have top priority when matching user requests. Note that these intents will not be matched if the context is not set. All contexts have a very important property – lifespan. [block:image] { "images": [ { "image": [ "https://files.readme.io/R0qFIMCwRZEFRF2L9T5X_2015-11-18-context-compose-lifespan.jpg", "2015-11-18-context-compose-lifespan.jpg", "1410", "526", "#2e637d", "" ], "sizing": "80" } ] } [/block] By default the lifespan value is set to five. It means that the context will last for the next five matched intents. So if you have different input/output contexts in each of the following intents, all of them will be collected in the next five stages of the dialog, like a chain of contexts. While this feature can be very useful, at times you may want to get rid of a context after the following intent is reached. In these situations you can simply change the lifespan to one. ##2. Managing the conversation flow Now we’re ready to design the dialog we want our agent to produce. The best way to do this is to draw a scheme like the one pictured below. You can use <a href="https://www.lucidchart.com/" target="_blank">Lucidchart</a> for this. [block:image] { "images": [ { "image": [ "https://files.readme.io/sRYqQXrSxmZExOEHuVsQ_2015-11-18-flowchart.jpg", "2015-11-18-flowchart.jpg", "624", "652", "#404d36", "" ], "sizing": "full" } ] } [/block] From this scheme we can see that there are two main branches of the conversation. The first is for people who want to compose a bouquet themselves; the second provides the option to choose from one of four pre-made bouquets. In order to manage these two branches of the conversation we’ll have to set different contexts. The intent where fulfillment is ‘Okay! Would you like to compose a bouquet yourself?’, looks exactly as it was shown above: its name is ‘compose’ and it has an output context ‘compose’. So we’ll have to create two different intents to match the possible answers. We’ll make one for ‘yes’: [block:image] { "images": [ { "image": [ "https://files.readme.io/a8SQgDmQTaK5vT6XZHD2_2015-11-18-yes-compose.jpg", "2015-11-18-yes-compose.jpg", "1396", "438", "#349ed6", "" ], "sizing": "80" } ] } [/block] And one for ‘no’: [block:image] { "images": [ { "image": [ "https://files.readme.io/mH50uypTe2vw6dSn1t0n_2015-11-18-no-compose.jpg", "2015-11-18-no-compose.jpg", "1376", "446", "#379ad6", "" ], "sizing": "80" } ] } [/block] In both intents we have the same input context: ‘compose’. So after the intent ‘compose’ was matched and the context ‘compose’ was set, we can then logically only reach those intents with an input context ‘compose’. So if we say ‘yes’ we get into the ‘yes - compose’ intent; if ‘no’, then we are in the ‘no - compose’ intent. And now comes the most crucial point: we have to set **different** output contexts. So in order to continue choosing the flowers we have to set now ‘yes - compose’ context as output, and then as an input context to the following intents. The same goes for the other intent. In order to choose one of the pre-made floral arrangements, we have to set an output context ‘no - compose’ and then create the following intent with ‘no - compose’ as the input context. This same logic applies along the whole dialog structure. Whenever you need to go further to a specific intent, you should set the corresponding contexts. This is especially important when you have multiple ‘yes/no’ answers in the conversation. ##3. Gathering the parameters’ values The other important function of the context is its ability to collect the parameters’ values. In our example, we’re collecting information during the dialog so we know by the end how to fill the customer’s order – how many flowers of what kind and what color we should add, or alternately, which pre-made bouquet we should choose. As long as a certain context is still alive (i.e., within its lifespan) the value we get from a parameter (if it was set in a context) is also alive. In order to collect all the values at the end, we just have to set one context, which will appear in **every** intent, both input and output (except for the very first intent, where we set the output context only). We just have to slightly modify what we see in the screenshots above: [block:image] { "images": [ { "image": [ "https://files.readme.io/Kij1ioWDRG2nsG5dvSmv_2015-11-18-yes-compose-modified.jpg", "2015-11-18-yes-compose-modified.jpg", "1392", "454", "#3b9eca", "" ], "sizing": "80" } ] } [/block] To retrieve the parameters from the context, write: #context_name.parameter_name: [block:image] { "images": [ { "image": [ "https://files.readme.io/WVcG6ix5Rzqv0jSfHPHg_2015-11-18-parameters.jpg", "2015-11-18-parameters.jpg", "1380", "626", "#5c5c5d", "" ], "sizing": "80" } ] } [/block] Then in the dialog those values will look the same as always: [block:image] { "images": [ { "image": [ "https://files.readme.io/XJZ57oYDT3uZ26BvoOG9_2015-11-18-parameter-values.jpg", "2015-11-18-parameter-values.jpg", "656", "1016", "#48787a", "" ] } ] } [/block] Feel free to play around with this example. You can download the agent <a href="https://s3.amazonaws.com/static.api.ai/agents/Florist-Shop.zip" target="_blank">here</a>.