{"__v":0,"_id":"5845a4a99f6fbb1b004307f2","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":"55bf6cdcad601c2b00762d13","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":["578a0d2f7b06020e00aa4b45"],"next":{"pages":[],"description":""},"createdAt":"2016-04-22T03:39:01.744Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":5,"body":"* [Action Overview](#action-overview)\n* [Parameter Table Management](#parameter-table-management)\n * [Automatic Parameter Definition](#section-automatic-parameter-definition)\n * [Deleting Parameters](#section-deleting-parameters)\n * [Defining Parameters Manually](#section-defining-parameters-manually)\n     + [Parameters with Constant Values](#section-parameters-with-constant-values)\n     + [Extracting Original Value](#section-extracting-original-value)\n     + [Extracting Values from Composite Entities](#section-extracting-values-from-composite-entities)\n     + [Extracting Values from Contexts](#section-extracting-values-from-contexts)\n     + [Defining Default Value](#section-defining-default-value)\n * [Required Parameters](#section-required-parameters)\n * [Parameters with List Values](#section-parameters-with-list-values)\n     + [Returning Parameter Values as Lists](#section-returning-parameter-values-as-lists)\n     + [List Parameter Values for Composite Entities](#section-list-parameter-values-for-composite-entities)\n     + [Referencing List Values in Text Response](#section-referencing-list-values-in-text-response)\n * [Parameter Values for :::at:::sys.date](#section-parameter-values-for-sys-date)\n     + [Incomplete Dates with Value in the Future](#section-incomplete-dates-with-value-in-the-future)\n     + [Incomplete Dates with Value in the Past](#section-incomplete-dates-with-value-in-the-past)\n     + [Incomplete Dates with Partial Value](#section-incomplete-dates-with-partial-value)\n* [Managing Parameters in Templates](#managing-parameters-in-templates)\n* [Referring to Parameter Values in ‘Text Response’](#referring-to-parameter-values-in-text-response)\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Action Overview\"\n}\n[/block]\nAn action corresponds to the step your application will take when a specific <a href=\"https://docs.api.ai/docs/concept-intents\" target=\"_blank\">intent</a> has been triggered by a user input.\n\nActions can have parameters for extracting information from user inputs.\n\nIn a JSON response to a query, the data appears in the following format:\n```\n{“action”:“action_name”}\n{“parameter_name”:“parameter_value”}\n```\nThe action name and its parameters are defined in the ‘Action’ section in an intent.\n\nFor example, if you are building an application for sending messages, the ‘Action’ section could look like this:\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/f5KwTJt7TiwkZtc6cgx5_action-overview.png\",\n        \"action-overview.png\",\n        \"1398\",\n        \"486\",\n        \"#f0f1f1\",\n        \"\"\n      ],\n      \"sizing\": \"80\"\n    }\n  ]\n}\n[/block]\nParameters and their values can be defined automatically from the examples you provide in the <a href=\"https://docs.api.ai/docs/concept-intents#user-says\" target=\"_blank\">‘User says’ section</a>, or you can insert them in the parameter table manually. \n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"In <a href=\\\"https://docs.api.ai/docs/domains\\\" target=\\\"_blank\\\">Domains</a>, action and parameter names are pre-defined. If you are developing your own intents to expand the domains provided by API.AI, make sure to use the same action and parameter names.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Parameter Table Management\"\n}\n[/block]\n## Automatic Parameter Definition\n\nWhen you enter an <a href=\"https://docs.api.ai/docs/concept-intents#section-example-and-template-modes\" target=\"_blank\">example</a> containing words that correspond to system or developer entities, these words will be highlighted, and parameters will automatically appear in the parameter table. In this case, the parameter name and value will correlate with the entity name:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/MY3VoFAsR2aUKykqUptu_param-auto-detection.gif\",\n        \"param-auto-detection.gif\",\n        \"791\",\n        \"401\",\n        \"#1c9fea\",\n        \"\"\n      ],\n      \"sizing\": \"80\"\n    }\n  ]\n}\n[/block]\nIf you want to change the parameter name, you can click on the highlighted word and change the name in the parameter review window. The name and the value in the parameter table will be automatically synchronized:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/eNir2gTVQXyTFDejovfD_param-number-to-age.gif\",\n        \"param-number-to-age.gif\",\n        \"791\",\n        \"481\",\n        \"#39769e\",\n        \"\"\n      ],\n      \"sizing\": \"80\"\n    }\n  ]\n}\n[/block]\nIf you need to alter the parameter name in all examples, you can do it directly from the parameter table. It will be synchronized with the parameter name that you see in the parameter review windows for each example:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/7ba338a-Incomplete-dates_partial-value.png\",\n        \"Incomplete-dates_partial-value.png\",\n        1510,\n        958,\n        \"#edefea\"\n      ],\n      \"sizing\": \"80\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Synchronization applies only to the parameters defined **automatically** from ‘User says’ examples.\"\n}\n[/block]\n## Deleting Parameters\n\nYou can delete the association between a word and an entity by removing the annotation from a single example. It will affect only this particular example.\n\nIf you need to delete such an association in the entire intent, you can opt for deleting the corresponding parameter row from the parameter table. To do this, hover the mouse over the respective row and click the three-dots menu button on the right.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/OtE4BoqfRd6njmfA0dv3_deleting-params.png\",\n        \"deleting-params.png\",\n        \"1662\",\n        \"1138\",\n        \"#1a9f79\",\n        \"\"\n      ],\n      \"sizing\": \"80\"\n    }\n  ]\n}\n[/block]\n## Defining Parameters Manually\n\nThere are some cases when you may need to define parameters and their values manually in the parameter table.\n\n###Parameters with Constant Values\n\nDepending on your application, you may need to define parameters with fixed values.\n\nFor example, if you want to make your robot rotate 360 degrees clockwise when given the command “Dance!”, you can define action and parameter values explicitly for its performance:\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/efZukZPSTqyIBd3cia8S_param-constant-values.png\",\n        \"param-constant-values.png\",\n        \"1474\",\n        \"906\",\n        \"#17a16f\",\n        \"\"\n      ],\n      \"sizing\": \"80\"\n    }\n  ]\n}\n[/block]\n### Extracting Original Value\n\n**Original value** is the part of the user input that was matched by a particular entity.\n\nTo extract the original value, you’ll need to add a new parameter to the parameter table and define its value in the ‘VALUE’ column in the following format: `$parameter_name.original`.\n\nYou may want to extract original values for your agent to give a grammatically correct response. \n\nFor example, when talking to a shopping assistant agent, a user may ask for one or more items and will use singular or plural form respectively (“*I want one hamburger*” vs. “*I want five hamburgers*”). To maintain these forms in the Text Response, define a new parameter with the original value and reference it in the Text Response. \n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/pHnLTkyLSzWPZRGnnf7d_original-value.png\",\n        \"original-value.png\",\n        \"1999\",\n        \"1165\",\n        \"#23a081\",\n        \"\"\n      ],\n      \"sizing\": \"80\"\n    }\n  ]\n}\n[/block]\n###Extracting Values from Composite Entities\n\nBy default, <a href=\"https://docs.api.ai/docs/concept-entities#section-developer-composite-entities\" target=\"_blank\">composite entities</a> return object-type values. \n\nIn order to extract string values from “inner” entities, you’ll need to define parameters manually with the help of “inner” aliases. \n\nHere’s an example of a composite entity that matches phrases like “*four steps to the left*”:\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/0BM8yDgsRyCwrqgnFX6v_move-composite.png\",\n        \"move-composite.png\",\n        \"1516\",\n        \"432\",\n        \"#189f97\",\n        \"\"\n      ],\n      \"sizing\": \"80\"\n    }\n  ]\n}\n[/block]\nWhen adding examples containing such phrases to an intent, the parameter “move” will be defined in the parameter table automatically. \n\nIn order to get string and number values corresponding to the number of steps and direction,  we’ll add new parameters called “steps” and “direction” and define their values in the format `$parameter_name.inner_alias`.\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/ilheWMDQfubCGPLKPoHu_strings-from-composite.png\",\n        \"strings-from-composite.png\",\n        \"1464\",\n        \"1280\",\n        \"#12a160\",\n        \"\"\n      ],\n      \"sizing\": \"80\"\n    }\n  ]\n}\n[/block]\nHere are the parameter values received for the “*Move two steps forward*” user input.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/p9RJDyOiRyin49ncRBPh_testing-strings-from-composite.png\",\n        \"testing-strings-from-composite.png\",\n        \"696\",\n        \"1248\",\n        \"#1b9f6c\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n### Extracting Values from Contexts\n\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\nFor example, you can define the output context in the intent that collects a user name. \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/0xwUC7SuSM2NTBrVRSJH_context-stores-value.png\",\n        \"context-stores-value.png\",\n        \"1580\",\n        \"1310\",\n        \"#1da191\",\n        \"\"\n      ],\n      \"sizing\": \"80\"\n    }\n  ]\n}\n[/block]\nIf you want to reference the “name” value in some other intents within the same agent, you’ll need to add a new parameter with the value #greetings.name to those intents. To keep the context active, you’ll have to add the output context “greetings” in **all** agent’s intents. \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/kGOo0l4QhONTgV7sorPW_value-from-context.png\",\n        \"value-from-context.png\",\n        \"1576\",\n        \"1402\",\n        \"#18a17e\",\n        \"\"\n      ],\n      \"sizing\": \"80\"\n    }\n  ]\n}\n[/block]\n**Related Topic:**\n\n- <a href=\"https://docs.api.ai/docs/guidelines-contexts\" target=\"_blank\">What are contexts and how are they used?</a>\n\n### Defining Default Value\n\nTo define a default parameter value, hover the mouse over a parameter row, click on the menu button on the right, and select ‘Default value’. \n\nFor example, in a shopping assistant agent, you can define the default number of items for the situations when this number is not provided by a user, as in phrases with an indefinite article: “*I want to order a hamburger*.”\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/VpArO8PpSJSFPlukHDYz_default-value.gif\",\n        \"default-value.gif\",\n        \"906\",\n        \"674\",\n        \"#3d8bc0\",\n        \"\"\n      ],\n      \"sizing\": \"80\"\n    }\n  ]\n}\n[/block]\nIn this case, if a user says “*I want to order an ice cream*”, the returned parameters will look like this:\n\n     \"resolvedQuery\": \"I want to order an ice cream\",\n        \"parameters\": {\n          \"item\": \"ice cream\",\n          \"item-original\": \"ice cream\",\n          \"number\": \"1\"\n        },\n        \"fulfillment\": {\n          \"speech\": \"I've added 1 ice cream to your shopping cart.\"\n        }\n\n## Required Parameters\n\nYou can mark a parameter as required if the action defined in the intent cannot be performed without this parameter value. For required parameters, it’s mandatory to indicate the corresponding entity in the ‘Entity’ column. Read the <a href=\"https://docs.api.ai/docs/guidelines-slot-filling\" target=\"_blank\">Slot Filling documentation</a> to learn more.\n\n## Parameters with List Values\n\nBy default, parameter values can be strings, numbers, or – in the case of <a href=\"https://docs.api.ai/docs/concept-entities#section-developer-composite-entities\" target=\"_blank\">composite entities</a> – objects. For some use cases, it is convenient to receive parameter values in the JSON response as a list. \n\nFor example, if user inputs contain an enumeration like *“I want apples, bananas, and plums.”* developers may want to get the following JSON response format:\n```\n{\n   \"parameters\": {\n      \"fruit\": [\n         \"apples\",\n         \"bananas\",\n         \"plums\"\n      ]\n   }\n}\n```\n\nOr for inputs like *“I need 3 t-shirts and 2 pairs of pants.”* it would be convenient to get the following:\n```\n{\n   \"parameters\": {\n      \"order\": [\n         {\n            \"item\": \"t-shirt\",\n            \"number\": 3\n         },\n         {\n            \"item\": \"pants\",\n            \"number\": 2\n         }\n      ]\n   }\n}\n```\n\n### Returning Parameter Values as Lists\n\nTo return parameter values as lists:\n1. Provide example user expressions in the ‘User says’ section.\n2. Check the ‘IS LIST’ checkbox in the parameter table in the respective row, as the following example shows:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/4fee58c-List-param-values-check.png\",\n        \"List-param-values-check.png\",\n        1994,\n        1258,\n        \"#f8f8f8\"\n      ],\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\nIf an example contains multiple words/phrases that should be returned as list elements for the same parameter value, use the same entity and parameter name for annotation of those words/phrases, as the following example shows:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/3bf7614-Incomplete-dates_recent.png\",\n        \"Incomplete-dates_recent.png\",\n        1512,\n        1092,\n        \"#edeeeb\"\n      ],\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\nLists can contain an indefinite number of elements. Be sure to define a simple example so that more complex inputs can also be matched.\n\nFor example, if you expect users to say *“I like blue, green, yellow”* or *“I like blue, red”*, you can add an example “I like black”. Annotate the word “black” as `@sys.color` and check the ‘IS LIST’ checkbox in the parameter table for the “color” parameter.\n\n\nIf you expect more diverse user inputs, be sure to add as many examples as you can.\n\n### List Parameter Values for Composite Entities\n\nTo get lists for inputs like *“I want 2 apples and 3 bananas”*, create a <a href=\"https://docs.api.ai/docs/concept-entities#section-developer-composite-entities\" target=\"_blank\">composite entity</a> that matches “2 apples” and “3 bananas”. \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/85423ad-List-param-values-fruit-number-entity.png\",\n        \"List-param-values-fruit-number-entity.png\",\n        2046,\n        528,\n        \"#2e8cc9\"\n      ],\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\nThen, just use this entity in example annotations and check ‘IS LIST’ in the parameter table.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/5d9e1e0-List-param-values-fruit-number-intent.png\",\n        \"List-param-values-fruit-number-intent.png\",\n        1994,\n        1310,\n        \"#f7f8f8\"\n      ],\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\nIn this case, you’ll get the following in the JSON response:\n\n```\n   \"resolvedQuery\": \"I want 2 apples and 3 bananas\",\n    \"action\": \"fruit_number\",\n    \"actionIncomplete\": false,\n    \"parameters\": {\n      \"fruit_number\": [\n        {\n          \"number\": 2,\n          \"fruit\": \"apple\"\n        },\n        {\n          \"number\": 3,\n          \"fruit\": \"banana\"\n        }\n      ]\n    }\n```\n\n### Referencing List Values in Text Response\n\nYou can reference the entire list in the 'Text response' field by using the format `$parameter_name`. The list will be shown as strings, separated by commas, corresponding to the list elements.\n\nTo reference a specific list element, use the format `$parameter_name[<number>]`, where `<number>` is the element number in the list (the count starts from 0).\n\n## Parameter Values for @sys.date\n\nThe `@sys.date` entity allows to extract dates in the ISO-8601 format. \n\nIf a user provides full information about the date, there is no ambiguity about the returned value. \n\nIn case of incomplete information about the date, API.AI allows you to extract different types of value depending on what fits best your use case.\n\nYou can set the value type in the parameter table so that it returns either of these:\n[block:html]\n{\n  \"html\": \"<table>\\n  <tr>\\n    <th>Value type to set</th>\\n    <th>Description</th>\\n  </tr>\\n  <tr>\\n    <td><code>$date</code></td>\\n    <td>The nearest date in the future for incomplete dates.</td>\\n  </tr>\\n  <tr>\\n    <td><code>$date.recent</code></td>\\n    <td>The most recent date in the past.</td>\\n  </tr>\\n  <tr>\\n    <td><code>$date.partial</code></td>\\n    <td>Incomplete date without the year value.</td>\\n  </tr>\\n</table>\"\n}\n[/block]\nTo change the type, click on the value and select a desired type from the drop-down. \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/a731de3-date-value.gif\",\n        \"date-value.gif\",\n        783,\n        388,\n        \"#edeeed\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"This feature is currently supported for English.\"\n}\n[/block]\n### Incomplete Dates with Value in the Future\n\nBy default, when you add an example containing a date, it gets annotated as `@sys.date` and the value in the parameter table is automatically defined as `$date`.\n\nIf a user provides an incomplete date (e.g., “*Monday*”, “*July 8th*”), the system returns a corresponding date in the nearest future. It fits perfectly such use cases as booking, scheduling etc.\n\nHere’s a simplified example of how an intent for a booking service may look like:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/e44fa93-Incomplete-dates_booking.png\",\n        \"Incomplete-dates_booking.png\",\n        1496,\n        968,\n        \"#eeefeb\"\n      ]\n    }\n  ]\n}\n[/block]\nFor such intents, in case of incomplete information about the date, the system will return the nearest date in the future. If today is December 2nd, 2016, the user query \"*Book a ticket for Monday*\" will return` \"date\": \"2016-12-05\"`.\n\n```\n    \"resolvedQuery\": \"Book a ticket for Monday\",\n    \"action\": \"book_tickets\",\n    \"actionIncomplete\": false,\n    \"parameters\": {\n      \"date\": \"2016-12-05\"\n    }\n```\n\n### Incomplete Dates with Value in the Past\n\nSome use cases require that the date is returned in the past. To determine this type of value, choose the `$date.recent` format.\n\nHere’s an example of the intent for a service that searches for messages sent on a specific date.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/85af5ed-Incomplete-dates_recent.png\",\n        \"Incomplete-dates_recent.png\",\n        1512,\n        1092,\n        \"#edeeeb\"\n      ]\n    }\n  ]\n}\n[/block]\nIn this case, for incomplete dates, JSON response will contain the corresponding most recent date in the past. Here’s what you’ll get for “*Find messages sent on April 1st*” when testing, for example, on the December 5th, 2016:\n\n```\n    \"resolvedQuery\": \"Find messages sent on April 1st\",\n    \"action\": \"find_messages_by_date\",\n    \"actionIncomplete\": false,\n    \"parameters\": {\n      \"date\": \"2016-04-01\"\n    }\n```\n\n### Incomplete Dates with Partial Value\n\nIn some cases, incomplete dates might not be understood unambiguously. For example, in a calendar search service, a user may want to search for future or for past dates. In this case, It might be convenient to return a partial date and handle it in your business logic. To determine this type of value, choose the `$date.partial` format.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/26a5d4d-Incomplete-dates_partial-value.png\",\n        \"Incomplete-dates_partial-value.png\",\n        1510,\n        958,\n        \"#edefea\"\n      ]\n    }\n  ]\n}\n[/block]\nHere’s what you will get for “*Search my calendar for events on April 23*” query:\n\n```\n    \"resolvedQuery\": \"Search my calendar for events on April 23\",\n    \"action\": \"search-calendar_date\",\n    \"actionIncomplete\": false,\n    \"parameters\": {\n      \"date\": \"UUUU-04-23\"\n    }\n```\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"`$date.partial` doesn’t work with days of week.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Managing Parameters in Templates\"\n}\n[/block]\nIn some rare cases, you may want to use the <a href=\"https://docs.api.ai/docs/concept-intents#section-example-and-template-modes\" target=\"_blank\">template mode</a> (indicated with the `@` icon at the beginning of the line) instead of the example mode in the ‘User says’ section.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"We recommend using examples rather than templates, because it’s easier and Machine Learning learns better this way.\"\n}\n[/block]\nIn templates, entities should be referenced by their names and prefixed with the `@` sign, and can be used with or without aliases: `@entity:alias` or `@entity` respectively.\n\nAlias corresponds to the parameter name. The parameter corresponding to the alias is defined automatically in the parameter table. \n\nIf you use an entity without an alias, no corresponding parameter will be defined in the parameter table or returned in the JSON response.\n\nParameters defined from templates can be modified in the following ways:\n\nIn a single template:\n\n- by editing or deleting the alias\n- by editing the parameter name in the parameter review window\n\nIn the entire intent:\n\n- by modifying or deleting parameter names in the parameter table \n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Synchronization applies only to the parameters defined automatically from the ‘User says’ templates.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Referring to Parameter Values in ‘Text Response’\"\n}\n[/block]\nTo reference parameter values in the ‘Text Response’ field, use the following format: `$parameter_name`. <a href=\"https://docs.api.ai/docs/concept-intents#speech-response\" target=\"_blank\">Read more</a>.","excerpt":"","slug":"concept-actions","type":"basic","title":"Actions and Parameters"}

Actions and Parameters


* [Action Overview](#action-overview) * [Parameter Table Management](#parameter-table-management) * [Automatic Parameter Definition](#section-automatic-parameter-definition) * [Deleting Parameters](#section-deleting-parameters) * [Defining Parameters Manually](#section-defining-parameters-manually) + [Parameters with Constant Values](#section-parameters-with-constant-values) + [Extracting Original Value](#section-extracting-original-value) + [Extracting Values from Composite Entities](#section-extracting-values-from-composite-entities) + [Extracting Values from Contexts](#section-extracting-values-from-contexts) + [Defining Default Value](#section-defining-default-value) * [Required Parameters](#section-required-parameters) * [Parameters with List Values](#section-parameters-with-list-values) + [Returning Parameter Values as Lists](#section-returning-parameter-values-as-lists) + [List Parameter Values for Composite Entities](#section-list-parameter-values-for-composite-entities) + [Referencing List Values in Text Response](#section-referencing-list-values-in-text-response) * [Parameter Values for @sys.date](#section-parameter-values-for-sys-date) + [Incomplete Dates with Value in the Future](#section-incomplete-dates-with-value-in-the-future) + [Incomplete Dates with Value in the Past](#section-incomplete-dates-with-value-in-the-past) + [Incomplete Dates with Partial Value](#section-incomplete-dates-with-partial-value) * [Managing Parameters in Templates](#managing-parameters-in-templates) * [Referring to Parameter Values in ‘Text Response’](#referring-to-parameter-values-in-text-response) [block:api-header] { "type": "basic", "title": "Action Overview" } [/block] An action corresponds to the step your application will take when a specific <a href="https://docs.api.ai/docs/concept-intents" target="_blank">intent</a> has been triggered by a user input. Actions can have parameters for extracting information from user inputs. In a JSON response to a query, the data appears in the following format: ``` {“action”:“action_name”} {“parameter_name”:“parameter_value”} ``` The action name and its parameters are defined in the ‘Action’ section in an intent. For example, if you are building an application for sending messages, the ‘Action’ section could look like this: [block:image] { "images": [ { "image": [ "https://files.readme.io/f5KwTJt7TiwkZtc6cgx5_action-overview.png", "action-overview.png", "1398", "486", "#f0f1f1", "" ], "sizing": "80" } ] } [/block] Parameters and their values can be defined automatically from the examples you provide in the <a href="https://docs.api.ai/docs/concept-intents#user-says" target="_blank">‘User says’ section</a>, or you can insert them in the parameter table manually. [block:callout] { "type": "info", "body": "In <a href=\"https://docs.api.ai/docs/domains\" target=\"_blank\">Domains</a>, action and parameter names are pre-defined. If you are developing your own intents to expand the domains provided by API.AI, make sure to use the same action and parameter names." } [/block] [block:api-header] { "type": "basic", "title": "Parameter Table Management" } [/block] ## Automatic Parameter Definition When you enter an <a href="https://docs.api.ai/docs/concept-intents#section-example-and-template-modes" target="_blank">example</a> containing words that correspond to system or developer entities, these words will be highlighted, and parameters will automatically appear in the parameter table. In this case, the parameter name and value will correlate with the entity name: [block:image] { "images": [ { "image": [ "https://files.readme.io/MY3VoFAsR2aUKykqUptu_param-auto-detection.gif", "param-auto-detection.gif", "791", "401", "#1c9fea", "" ], "sizing": "80" } ] } [/block] If you want to change the parameter name, you can click on the highlighted word and change the name in the parameter review window. The name and the value in the parameter table will be automatically synchronized: [block:image] { "images": [ { "image": [ "https://files.readme.io/eNir2gTVQXyTFDejovfD_param-number-to-age.gif", "param-number-to-age.gif", "791", "481", "#39769e", "" ], "sizing": "80" } ] } [/block] If you need to alter the parameter name in all examples, you can do it directly from the parameter table. It will be synchronized with the parameter name that you see in the parameter review windows for each example: [block:image] { "images": [ { "image": [ "https://files.readme.io/7ba338a-Incomplete-dates_partial-value.png", "Incomplete-dates_partial-value.png", 1510, 958, "#edefea" ], "sizing": "80" } ] } [/block] [block:callout] { "type": "info", "body": "Synchronization applies only to the parameters defined **automatically** from ‘User says’ examples." } [/block] ## Deleting Parameters You can delete the association between a word and an entity by removing the annotation from a single example. It will affect only this particular example. If you need to delete such an association in the entire intent, you can opt for deleting the corresponding parameter row from the parameter table. To do this, hover the mouse over the respective row and click the three-dots menu button on the right. [block:image] { "images": [ { "image": [ "https://files.readme.io/OtE4BoqfRd6njmfA0dv3_deleting-params.png", "deleting-params.png", "1662", "1138", "#1a9f79", "" ], "sizing": "80" } ] } [/block] ## Defining Parameters Manually There are some cases when you may need to define parameters and their values manually in the parameter table. ###Parameters with Constant Values Depending on your application, you may need to define parameters with fixed values. For example, if you want to make your robot rotate 360 degrees clockwise when given the command “Dance!”, you can define action and parameter values explicitly for its performance: [block:image] { "images": [ { "image": [ "https://files.readme.io/efZukZPSTqyIBd3cia8S_param-constant-values.png", "param-constant-values.png", "1474", "906", "#17a16f", "" ], "sizing": "80" } ] } [/block] ### Extracting Original Value **Original value** is the part of the user input that was matched by a particular entity. To extract the original value, you’ll need to add a new parameter to the parameter table and define its value in the ‘VALUE’ column in the following format: `$parameter_name.original`. You may want to extract original values for your agent to give a grammatically correct response. For example, when talking to a shopping assistant agent, a user may ask for one or more items and will use singular or plural form respectively (“*I want one hamburger*” vs. “*I want five hamburgers*”). To maintain these forms in the Text Response, define a new parameter with the original value and reference it in the Text Response. [block:image] { "images": [ { "image": [ "https://files.readme.io/pHnLTkyLSzWPZRGnnf7d_original-value.png", "original-value.png", "1999", "1165", "#23a081", "" ], "sizing": "80" } ] } [/block] ###Extracting Values from Composite Entities By default, <a href="https://docs.api.ai/docs/concept-entities#section-developer-composite-entities" target="_blank">composite entities</a> return object-type values. In order to extract string values from “inner” entities, you’ll need to define parameters manually with the help of “inner” aliases. Here’s an example of a composite entity that matches phrases like “*four steps to the left*”: [block:image] { "images": [ { "image": [ "https://files.readme.io/0BM8yDgsRyCwrqgnFX6v_move-composite.png", "move-composite.png", "1516", "432", "#189f97", "" ], "sizing": "80" } ] } [/block] When adding examples containing such phrases to an intent, the parameter “move” will be defined in the parameter table automatically. In order to get string and number values corresponding to the number of steps and direction, we’ll add new parameters called “steps” and “direction” and define their values in the format `$parameter_name.inner_alias`. [block:image] { "images": [ { "image": [ "https://files.readme.io/ilheWMDQfubCGPLKPoHu_strings-from-composite.png", "strings-from-composite.png", "1464", "1280", "#12a160", "" ], "sizing": "80" } ] } [/block] Here are the parameter values received for the “*Move two steps forward*” user input. [block:image] { "images": [ { "image": [ "https://files.readme.io/p9RJDyOiRyin49ncRBPh_testing-strings-from-composite.png", "testing-strings-from-composite.png", "696", "1248", "#1b9f6c", "" ] } ] } [/block] ### Extracting Values from Contexts 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`. For example, you can define the output context in the intent that collects a user name. [block:image] { "images": [ { "image": [ "https://files.readme.io/0xwUC7SuSM2NTBrVRSJH_context-stores-value.png", "context-stores-value.png", "1580", "1310", "#1da191", "" ], "sizing": "80" } ] } [/block] If you want to reference the “name” value in some other intents within the same agent, you’ll need to add a new parameter with the value #greetings.name to those intents. To keep the context active, you’ll have to add the output context “greetings” in **all** agent’s intents. [block:image] { "images": [ { "image": [ "https://files.readme.io/kGOo0l4QhONTgV7sorPW_value-from-context.png", "value-from-context.png", "1576", "1402", "#18a17e", "" ], "sizing": "80" } ] } [/block] **Related Topic:** - <a href="https://docs.api.ai/docs/guidelines-contexts" target="_blank">What are contexts and how are they used?</a> ### Defining Default Value To define a default parameter value, hover the mouse over a parameter row, click on the menu button on the right, and select ‘Default value’. For example, in a shopping assistant agent, you can define the default number of items for the situations when this number is not provided by a user, as in phrases with an indefinite article: “*I want to order a hamburger*.” [block:image] { "images": [ { "image": [ "https://files.readme.io/VpArO8PpSJSFPlukHDYz_default-value.gif", "default-value.gif", "906", "674", "#3d8bc0", "" ], "sizing": "80" } ] } [/block] In this case, if a user says “*I want to order an ice cream*”, the returned parameters will look like this: "resolvedQuery": "I want to order an ice cream", "parameters": { "item": "ice cream", "item-original": "ice cream", "number": "1" }, "fulfillment": { "speech": "I've added 1 ice cream to your shopping cart." } ## Required Parameters You can mark a parameter as required if the action defined in the intent cannot be performed without this parameter value. For required parameters, it’s mandatory to indicate the corresponding entity in the ‘Entity’ column. Read the <a href="https://docs.api.ai/docs/guidelines-slot-filling" target="_blank">Slot Filling documentation</a> to learn more. ## Parameters with List Values By default, parameter values can be strings, numbers, or – in the case of <a href="https://docs.api.ai/docs/concept-entities#section-developer-composite-entities" target="_blank">composite entities</a> – objects. For some use cases, it is convenient to receive parameter values in the JSON response as a list. For example, if user inputs contain an enumeration like *“I want apples, bananas, and plums.”* developers may want to get the following JSON response format: ``` { "parameters": { "fruit": [ "apples", "bananas", "plums" ] } } ``` Or for inputs like *“I need 3 t-shirts and 2 pairs of pants.”* it would be convenient to get the following: ``` { "parameters": { "order": [ { "item": "t-shirt", "number": 3 }, { "item": "pants", "number": 2 } ] } } ``` ### Returning Parameter Values as Lists To return parameter values as lists: 1. Provide example user expressions in the ‘User says’ section. 2. Check the ‘IS LIST’ checkbox in the parameter table in the respective row, as the following example shows: [block:image] { "images": [ { "image": [ "https://files.readme.io/4fee58c-List-param-values-check.png", "List-param-values-check.png", 1994, 1258, "#f8f8f8" ], "sizing": "full" } ] } [/block] If an example contains multiple words/phrases that should be returned as list elements for the same parameter value, use the same entity and parameter name for annotation of those words/phrases, as the following example shows: [block:image] { "images": [ { "image": [ "https://files.readme.io/3bf7614-Incomplete-dates_recent.png", "Incomplete-dates_recent.png", 1512, 1092, "#edeeeb" ], "sizing": "full" } ] } [/block] Lists can contain an indefinite number of elements. Be sure to define a simple example so that more complex inputs can also be matched. For example, if you expect users to say *“I like blue, green, yellow”* or *“I like blue, red”*, you can add an example “I like black”. Annotate the word “black” as `@sys.color` and check the ‘IS LIST’ checkbox in the parameter table for the “color” parameter. If you expect more diverse user inputs, be sure to add as many examples as you can. ### List Parameter Values for Composite Entities To get lists for inputs like *“I want 2 apples and 3 bananas”*, create a <a href="https://docs.api.ai/docs/concept-entities#section-developer-composite-entities" target="_blank">composite entity</a> that matches “2 apples” and “3 bananas”. [block:image] { "images": [ { "image": [ "https://files.readme.io/85423ad-List-param-values-fruit-number-entity.png", "List-param-values-fruit-number-entity.png", 2046, 528, "#2e8cc9" ], "sizing": "full" } ] } [/block] Then, just use this entity in example annotations and check ‘IS LIST’ in the parameter table. [block:image] { "images": [ { "image": [ "https://files.readme.io/5d9e1e0-List-param-values-fruit-number-intent.png", "List-param-values-fruit-number-intent.png", 1994, 1310, "#f7f8f8" ], "sizing": "full" } ] } [/block] In this case, you’ll get the following in the JSON response: ``` "resolvedQuery": "I want 2 apples and 3 bananas", "action": "fruit_number", "actionIncomplete": false, "parameters": { "fruit_number": [ { "number": 2, "fruit": "apple" }, { "number": 3, "fruit": "banana" } ] } ``` ### Referencing List Values in Text Response You can reference the entire list in the 'Text response' field by using the format `$parameter_name`. The list will be shown as strings, separated by commas, corresponding to the list elements. To reference a specific list element, use the format `$parameter_name[<number>]`, where `<number>` is the element number in the list (the count starts from 0). ## Parameter Values for @sys.date The `@sys.date` entity allows to extract dates in the ISO-8601 format. If a user provides full information about the date, there is no ambiguity about the returned value. In case of incomplete information about the date, API.AI allows you to extract different types of value depending on what fits best your use case. You can set the value type in the parameter table so that it returns either of these: [block:html] { "html": "<table>\n <tr>\n <th>Value type to set</th>\n <th>Description</th>\n </tr>\n <tr>\n <td><code>$date</code></td>\n <td>The nearest date in the future for incomplete dates.</td>\n </tr>\n <tr>\n <td><code>$date.recent</code></td>\n <td>The most recent date in the past.</td>\n </tr>\n <tr>\n <td><code>$date.partial</code></td>\n <td>Incomplete date without the year value.</td>\n </tr>\n</table>" } [/block] To change the type, click on the value and select a desired type from the drop-down. [block:image] { "images": [ { "image": [ "https://files.readme.io/a731de3-date-value.gif", "date-value.gif", 783, 388, "#edeeed" ] } ] } [/block] [block:callout] { "type": "info", "body": "This feature is currently supported for English." } [/block] ### Incomplete Dates with Value in the Future By default, when you add an example containing a date, it gets annotated as `@sys.date` and the value in the parameter table is automatically defined as `$date`. If a user provides an incomplete date (e.g., “*Monday*”, “*July 8th*”), the system returns a corresponding date in the nearest future. It fits perfectly such use cases as booking, scheduling etc. Here’s a simplified example of how an intent for a booking service may look like: [block:image] { "images": [ { "image": [ "https://files.readme.io/e44fa93-Incomplete-dates_booking.png", "Incomplete-dates_booking.png", 1496, 968, "#eeefeb" ] } ] } [/block] For such intents, in case of incomplete information about the date, the system will return the nearest date in the future. If today is December 2nd, 2016, the user query "*Book a ticket for Monday*" will return` "date": "2016-12-05"`. ``` "resolvedQuery": "Book a ticket for Monday", "action": "book_tickets", "actionIncomplete": false, "parameters": { "date": "2016-12-05" } ``` ### Incomplete Dates with Value in the Past Some use cases require that the date is returned in the past. To determine this type of value, choose the `$date.recent` format. Here’s an example of the intent for a service that searches for messages sent on a specific date. [block:image] { "images": [ { "image": [ "https://files.readme.io/85af5ed-Incomplete-dates_recent.png", "Incomplete-dates_recent.png", 1512, 1092, "#edeeeb" ] } ] } [/block] In this case, for incomplete dates, JSON response will contain the corresponding most recent date in the past. Here’s what you’ll get for “*Find messages sent on April 1st*” when testing, for example, on the December 5th, 2016: ``` "resolvedQuery": "Find messages sent on April 1st", "action": "find_messages_by_date", "actionIncomplete": false, "parameters": { "date": "2016-04-01" } ``` ### Incomplete Dates with Partial Value In some cases, incomplete dates might not be understood unambiguously. For example, in a calendar search service, a user may want to search for future or for past dates. In this case, It might be convenient to return a partial date and handle it in your business logic. To determine this type of value, choose the `$date.partial` format. [block:image] { "images": [ { "image": [ "https://files.readme.io/26a5d4d-Incomplete-dates_partial-value.png", "Incomplete-dates_partial-value.png", 1510, 958, "#edefea" ] } ] } [/block] Here’s what you will get for “*Search my calendar for events on April 23*” query: ``` "resolvedQuery": "Search my calendar for events on April 23", "action": "search-calendar_date", "actionIncomplete": false, "parameters": { "date": "UUUU-04-23" } ``` [block:callout] { "type": "info", "body": "`$date.partial` doesn’t work with days of week." } [/block] [block:api-header] { "type": "basic", "title": "Managing Parameters in Templates" } [/block] In some rare cases, you may want to use the <a href="https://docs.api.ai/docs/concept-intents#section-example-and-template-modes" target="_blank">template mode</a> (indicated with the `@` icon at the beginning of the line) instead of the example mode in the ‘User says’ section. [block:callout] { "type": "info", "body": "We recommend using examples rather than templates, because it’s easier and Machine Learning learns better this way." } [/block] In templates, entities should be referenced by their names and prefixed with the `@` sign, and can be used with or without aliases: `@entity:alias` or `@entity` respectively. Alias corresponds to the parameter name. The parameter corresponding to the alias is defined automatically in the parameter table. If you use an entity without an alias, no corresponding parameter will be defined in the parameter table or returned in the JSON response. Parameters defined from templates can be modified in the following ways: In a single template: - by editing or deleting the alias - by editing the parameter name in the parameter review window In the entire intent: - by modifying or deleting parameter names in the parameter table [block:callout] { "type": "info", "body": "Synchronization applies only to the parameters defined automatically from the ‘User says’ templates." } [/block] [block:api-header] { "type": "basic", "title": "Referring to Parameter Values in ‘Text Response’" } [/block] To reference parameter values in the ‘Text Response’ field, use the following format: `$parameter_name`. <a href="https://docs.api.ai/docs/concept-intents#speech-response" target="_blank">Read more</a>.