{"__v":0,"_id":"5845a4a99f6fbb1b004307f4","category":{"version":"5845a4a89f6fbb1b004307b7","project":"54d3007669578e0d002730c9","_id":"5845a4a89f6fbb1b004307b9","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-07-30T06:25:25.645Z","from_sync":false,"order":1,"slug":"key-concepts","title":"Key Concepts"},"parentDoc":null,"project":"54d3007669578e0d002730c9","user":"55bafe141b0d663700781682","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":[],"next":{"pages":[],"description":""},"createdAt":"2015-08-03T14:43:44.595Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":8,"body":"* [Output Contexts](#output-contexts)\n* [Input Contexts](#input-contexts)\n* [Extracting Parameter Values from Contexts](#extracting-parameter-values-from-contexts)\n* [Related Documentation](#related-documentation)\n[block:api-header]\n{\n  \"type\": \"basic\"\n}\n[/block]\nContexts are strings that represent the current context of a user’s request. This is helpful for differentiating phrases which may be vague or have different meanings depending on the user’s preferences or geographic location, the current page in an app, or the topic of conversation.\n\nFor example, if a user is listening to a music player application and finds a band that catches their interest, they might say something like: “I want to hear more of them”. As a developer, you can include the name of the band in the context with the request, so that the API.AI agent can process it more effectively.\n\nOr let’s say you’re a manufacturer of smart home devices, and you have an app that remotely controls household appliances. A user might say, \"Turn on the front door light\", followed by “Turn it off”, and the app will understand that the second phrase is still referring to the light. Now later, if the user says, \"Turn on the coffee machine\", and follows this with “Turn it off”, it will result in different action than before, because of the new context.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Output Contexts\"\n}\n[/block]\nContexts are tied to user sessions (to a session ID that you pass in API calls). If a user expression is matched to an intent, the intent can then set an output context to be shared by this expression in the future. You can also add a context when you send the user request to your API.AI agent.\n\nIn our appliance app example, saying \"Turn on the front door light\" should set an output context to \"front-door-light\". There may be several intents with the template \"Turn it off\", each with a different input context. But if the output context is set to \"front-door-light\", then the intent \"Turn it off\" that has a matching input context of \"front-door-light\" will be executed, and all others will not.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"\",\n  \"body\": \"When naming contexts, we recommend using alphanumeric names without spaces.\"\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/x2dSnVCjShyZfE7Sjler_output-context.png\",\n        \"output-context.png\",\n        \"1180\",\n        \"517\",\n        \"#3a9fda\",\n        \"\"\n      ],\n      \"caption\": \"Output context example\"\n    }\n  ]\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"caption\": \"Input context example\",\n      \"image\": [\n        \"https://files.readme.io/TGWofPu9SxK7CM7OyBAL_input-context.png\",\n        \"input-context.png\",\n        \"1175\",\n        \"508\",\n        \"#389fda\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nBy default, contexts expire after either five requests or ten minutes from the time they were activated. Intents that renew the context will reset the counter and clock to give an additional five requests and ten minutes.\n\nYou can change the context lifespan in the settings of each context.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/1r7UBT1ASYi8kFp9rgxM_context-lifespan.png\",\n        \"context-lifespan.png\",\n        \"369\",\n        \"395\",\n        \"#e0773d\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nOr you can choose to reset the context when an intent is matched.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/DZnk10TtTXSCDbKoX82B_context-lifespan-zero.png\",\n        \"context-lifespan-zero.png\",\n        \"382\",\n        \"398\",\n        \"#e87339\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Input Contexts\"\n}\n[/block]\nInput contexts limit intents to be matched only when certain contexts are set.\n\nFor example we can create two intents for requests like “I want to hear more of them”.\n\nThe intent without context will match the user’s request when the app has no information about the artist that the user wants to listen to. So it will need to ask some follow-up questions.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/QqLXB577Rt27uMT4qLFC_intent-no-input-context.png\",\n        \"intent-no-input-context.png\",\n        \"588\",\n        \"560\",\n        \"#3a648b\",\n        \"\"\n      ],\n      \"caption\": \"Intent without input context\"\n    }\n  ]\n}\n[/block]\nYou can use the [slot filling feature](doc:dialogs#linear-dialog) for this purpose.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/3WkVJdDwS66w6jPveVBi_add-slot-filling.png\",\n        \"add-slot-filling.png\",\n        \"739\",\n        \"564\",\n        \"#3e5d84\",\n        \"\"\n      ],\n      \"caption\": \"Adding parameter for slot filling\"\n    }\n  ]\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"caption\": \"Slot filling dialog example\",\n      \"image\": [\n        \"https://files.readme.io/TWRwu9RhScPpDYuNCljA_slot-filling-dialog.gif\",\n        \"slot-filling-dialog.gif\",\n        \"346\",\n        \"604\",\n        \"#526a8e\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nThe other intent that we create has an input context, which contains information about which artist or band is meant by the user’s request. \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/Tl3ifBOJSoiGuAt1Z2Qh_intent-input-context.png\",\n        \"intent-input-context.png\",\n        \"907\",\n        \"687\",\n        \"#467a91\",\n        \"\"\n      ],\n      \"caption\": \"Using input context\"\n    }\n  ]\n}\n[/block]\nYou can set this context from intents matched to previous requests or via API calls.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/wY26jzsHSuwNkdm69EmK_intent-output-context.png\",\n        \"intent-output-context.png\",\n        \"890\",\n        \"683\",\n        \"#427da2\",\n        \"\"\n      ],\n      \"caption\": \"Setting output context\"\n    }\n  ]\n}\n[/block]\nUsing these two intents you can get the following dialog:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/ZG3uBHWBRlaioL9bINMv_no-slot-filling-dialog.gif\",\n        \"no-slot-filling-dialog.gif\",\n        \"329\",\n        \"580\",\n        \"#9d606e\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"In case of multiple input contexts defined in a single intent, *all* these contexts should be active in order for this intent to be matched.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Extracting Parameter Values from Contexts\"\n}\n[/block]\nTo refer to a parameter value that has been extracted in an intent with a defined output context, use the following format in the ‘VALUE’ column: `#context_name.parameter_name`.\n\nRead more <a href=\"https://docs.api.ai/docs/concept-actions#section-extracting-values-from-contexts\" target=\"_blank\">here</a>.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Related Documentation\"\n}\n[/block]\n- <a href=\"https://docs.api.ai/docs/guidelines-contexts\" target=\"_blank\">What are contexts and how are they used?</a>","excerpt":"","slug":"concept-contexts","type":"basic","title":"Contexts"}
* [Output Contexts](#output-contexts) * [Input Contexts](#input-contexts) * [Extracting Parameter Values from Contexts](#extracting-parameter-values-from-contexts) * [Related Documentation](#related-documentation) [block:api-header] { "type": "basic" } [/block] Contexts are strings that represent the current context of a user’s request. This is helpful for differentiating phrases which may be vague or have different meanings depending on the user’s preferences or geographic location, the current page in an app, or the topic of conversation. For example, if a user is listening to a music player application and finds a band that catches their interest, they might say something like: “I want to hear more of them”. As a developer, you can include the name of the band in the context with the request, so that the API.AI agent can process it more effectively. Or let’s say you’re a manufacturer of smart home devices, and you have an app that remotely controls household appliances. A user might say, "Turn on the front door light", followed by “Turn it off”, and the app will understand that the second phrase is still referring to the light. Now later, if the user says, "Turn on the coffee machine", and follows this with “Turn it off”, it will result in different action than before, because of the new context. [block:api-header] { "type": "basic", "title": "Output Contexts" } [/block] Contexts are tied to user sessions (to a session ID that you pass in API calls). If a user expression is matched to an intent, the intent can then set an output context to be shared by this expression in the future. You can also add a context when you send the user request to your API.AI agent. In our appliance app example, saying "Turn on the front door light" should set an output context to "front-door-light". There may be several intents with the template "Turn it off", each with a different input context. But if the output context is set to "front-door-light", then the intent "Turn it off" that has a matching input context of "front-door-light" will be executed, and all others will not. [block:callout] { "type": "info", "title": "", "body": "When naming contexts, we recommend using alphanumeric names without spaces." } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/x2dSnVCjShyZfE7Sjler_output-context.png", "output-context.png", "1180", "517", "#3a9fda", "" ], "caption": "Output context example" } ] } [/block] [block:image] { "images": [ { "caption": "Input context example", "image": [ "https://files.readme.io/TGWofPu9SxK7CM7OyBAL_input-context.png", "input-context.png", "1175", "508", "#389fda", "" ] } ] } [/block] By default, contexts expire after either five requests or ten minutes from the time they were activated. Intents that renew the context will reset the counter and clock to give an additional five requests and ten minutes. You can change the context lifespan in the settings of each context. [block:image] { "images": [ { "image": [ "https://files.readme.io/1r7UBT1ASYi8kFp9rgxM_context-lifespan.png", "context-lifespan.png", "369", "395", "#e0773d", "" ] } ] } [/block] Or you can choose to reset the context when an intent is matched. [block:image] { "images": [ { "image": [ "https://files.readme.io/DZnk10TtTXSCDbKoX82B_context-lifespan-zero.png", "context-lifespan-zero.png", "382", "398", "#e87339", "" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "Input Contexts" } [/block] Input contexts limit intents to be matched only when certain contexts are set. For example we can create two intents for requests like “I want to hear more of them”. The intent without context will match the user’s request when the app has no information about the artist that the user wants to listen to. So it will need to ask some follow-up questions. [block:image] { "images": [ { "image": [ "https://files.readme.io/QqLXB577Rt27uMT4qLFC_intent-no-input-context.png", "intent-no-input-context.png", "588", "560", "#3a648b", "" ], "caption": "Intent without input context" } ] } [/block] You can use the [slot filling feature](doc:dialogs#linear-dialog) for this purpose. [block:image] { "images": [ { "image": [ "https://files.readme.io/3WkVJdDwS66w6jPveVBi_add-slot-filling.png", "add-slot-filling.png", "739", "564", "#3e5d84", "" ], "caption": "Adding parameter for slot filling" } ] } [/block] [block:image] { "images": [ { "caption": "Slot filling dialog example", "image": [ "https://files.readme.io/TWRwu9RhScPpDYuNCljA_slot-filling-dialog.gif", "slot-filling-dialog.gif", "346", "604", "#526a8e", "" ] } ] } [/block] The other intent that we create has an input context, which contains information about which artist or band is meant by the user’s request. [block:image] { "images": [ { "image": [ "https://files.readme.io/Tl3ifBOJSoiGuAt1Z2Qh_intent-input-context.png", "intent-input-context.png", "907", "687", "#467a91", "" ], "caption": "Using input context" } ] } [/block] You can set this context from intents matched to previous requests or via API calls. [block:image] { "images": [ { "image": [ "https://files.readme.io/wY26jzsHSuwNkdm69EmK_intent-output-context.png", "intent-output-context.png", "890", "683", "#427da2", "" ], "caption": "Setting output context" } ] } [/block] Using these two intents you can get the following dialog: [block:image] { "images": [ { "image": [ "https://files.readme.io/ZG3uBHWBRlaioL9bINMv_no-slot-filling-dialog.gif", "no-slot-filling-dialog.gif", "329", "580", "#9d606e", "" ] } ] } [/block] [block:callout] { "type": "info", "body": "In case of multiple input contexts defined in a single intent, *all* these contexts should be active in order for this intent to be matched." } [/block] [block:api-header] { "type": "basic", "title": "Extracting Parameter Values from Contexts" } [/block] To refer to a parameter value that has been extracted in an intent with a defined output context, use the following format in the ‘VALUE’ column: `#context_name.parameter_name`. Read more <a href="https://docs.api.ai/docs/concept-actions#section-extracting-values-from-contexts" target="_blank">here</a>. [block:api-header] { "type": "basic", "title": "Related Documentation" } [/block] - <a href="https://docs.api.ai/docs/guidelines-contexts" target="_blank">What are contexts and how are they used?</a>