{"__v":0,"_id":"5845a4a89f6fbb1b004307c9","category":{"version":"5845a4a89f6fbb1b004307b7","project":"54d3007669578e0d002730c9","_id":"5845a4a89f6fbb1b004307ba","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-07-30T06:53:33.020Z","from_sync":false,"order":2,"slug":"api-reference","title":"API reference"},"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":["568c7fd763fefd0d00d0686e"],"next":{"pages":[],"description":""},"createdAt":"2015-08-03T22:36:37.432Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"language":"curl","code":"curl -k -F \"request={'v':'20150512', 'timezone':'America/New_York', 'lang':'en'};type=application/json\" -F \"voiceData=:::at:::hello.wav;type=audio/wav\" -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\" -H \"ocp-apim-subscription-key: YOUR_SUBSCRIPTION_KEY\" https://api.api.ai/v1/query","name":""}]},"results":{"codes":[{"status":200,"language":"json","code":"{\n  \"id\": \"81016c7e-e680-453b-a217-0abc6f7eb939\",\n  \"timestamp\": \"2014.07.24 12:22:39 UTC\",\n  \"result\": {\n    \"source\":\"agent\",\n    \"resolvedQuery\": \"Hi, Mary!\",\n    \"speech\": \"\",\n    \"action\": \"greet\",\n    \"parameters\": {\n      \"name\": \"Mary\"\n    },\n    \"fulfillment\": {\n      \"speech\":\"Hi, how are you?\"\n    }\n    \"metadata\": {\n      \"intentId\": \"979f1d1c-f189-41a8-8600-e647203b1617\",\n      \"inputContexts\": [],\n      \"contexts\": [\n        \"greeting\"\n      ],\n      \"intentName\": \"Hello\"\n    }\n  },\n  \"status\": {\n    \"code\": 200,\n    \"errorType\": \"success\"\n  }\n}","name":""}]},"settings":"","auth":"required","params":[{"_id":"55ce3532950b8e0d00f11ebd","ref":"","in":"body","required":false,"desc":"Voice requesr","default":"","type":"file","name":"voiceData"},{"_id":"55ce3532950b8e0d00f11ebc","ref":"","in":"body","required":false,"desc":"JSON request body","default":"","type":"string","name":"request"}],"url":"/query"},"isReference":false,"order":4,"body":"* [Overview](#overview)\n* [URLs](#urls)\n* [Query Parameters and JSON Fields](#query-parameters-and-json-fields)\n* [GET /query](#get-query)\n* [POST /query](#post-query)\n* [Response](#response)\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Overview\"\n}\n[/block]\nThe **query** endpoint is used to process natural language in the form of text. The query requests return structured data in JSON format with an action and parameters for that action.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"URLs\"\n}\n[/block]\nThe following URLs are available:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Method\",\n    \"h-1\": \"Definition\",\n    \"0-0\": \"[GET /query](query#get-query)\",\n    \"1-0\": \"[POST /query](query#post-query)\",\n    \"0-1\": \"Takes natural language text and information as query parameters and returns information as JSON.\",\n    \"1-1\": \"Takes natural language text and information as JSON in the POST body and returns information as JSON.\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Query Parameters and JSON Fields\"\n}\n[/block]\nThe following parameters are used as either query parameters in the URL or JSON keys in the POST body:\n[block:html]\n{\n  \"html\": \"<table>\\n<tr>\\n  <th colspan=\\\"2\\\" width=15%>Name</th>\\n  <th>Type</th> \\n  <th>Description</th>\\n  <th>Required</th>\\n</tr>\\n<tr>\\n  <td colspan=\\\"2\\\"><code>query</code></td>\\n  <td>String or array of strings</td> \\n  <td>Natural language text to be processed.<br>\\nQuery length should not exceed 256 characters.</td>\\n  <td>Required unless an <code>\\\"event\\\"</code>/<code>\\\"e\\\"</code> parameter is submitted.</td>\\n</tr>\\n<tr>\\n  <td colspan=\\\"2\\\"><code>event</code> (for POST requests)<br>or<br><code>e</code> (for GET requests)</td>\\n  <td>Object</td>\\n  <td>Object containing event name and additional data. The <code>\\\"data\\\"</code> parameter can be submitted only in POST requests.</td> \\n  <td>Required unless a <code>\\\"query\\\"</code> parameter is submitted.</td>\\n</tr>\\n<tr>\\n  <td></td>\\n  <td><code>name</code></td>\\n  <td>String</td> \\n  <td><a href=\\\"https://docs.api.ai/docs/concept-events\\\" target=\\\"_blank\\\">Event</a> name.</td>\\n  <td>Required.</td>\\n</tr>\\n<tr>\\n  <td></td>\\n  <td><code>data</code></td>\\n  <td>Object</td> \\n  <td>Object consisting of <code>\\\"parameter_name\\\":\\\"parameter_value\\\"</code> pairs.</td>\\n  <td>Optional.</td>\\n</tr>\\n<tr>\\n  <td colspan=\\\"2\\\"><code>v</code></td>\\n  <td>String</td> \\n  <td>Version of the protocol, e.g. <code>v=20150910</code><br><br>\\n<i class=\\\"fa fa-exclamation-triangle\\\" aria-hidden=\\\"true\\\"></i> Do not pass the current date to the <code>v</code> parameter. See <a href=\\\"https://docs.api.ai/docs/versioning\\\" target=\\\"_blank\\\">Versioning</a> for more details.</td>\\n  <td>Required. Must be used as a URL parameter.</td> \\n</tr>\\n<tr>\\n  <td colspan=\\\"2\\\"><code>sessionId</code></td>\\n  <td>String</td>\\n  <td>A string token up to 36 symbols long, used to identify the client and to manage session parameters (including contexts) per client.</td> \\n  <td>Required.</td>\\n</tr>\\n<tr>\\n  <td colspan=\\\"2\\\"><code>lang</code></td>\\n  <td>String</td>\\n  <td>Language tag, e.g., <code>en</code>, <code>es</code> etc.<br>\\nSee <a href=\\\"https://docs.api.ai/docs/languages\\\" target=\\\"_blank\\\">Languages</a> for details.</td> \\n  <td>Required.</td>\\n</tr>\\n<tr>\\n  <td colspan=\\\"2\\\"><code>contexts</code></td>\\n  <td>Array</td>\\n  <td>Array of additional context objects. Should be sent via a POST /query request. Contexts sent in a query are activated before the query.<br>\\nSee <a href=\\\"https://docs.api.ai/docs/concept-contexts\\\" target=\\\"_blank\\\">Contexts</a>.</td> \\n  <td>Optional.</td>\\n</tr>\\n<tr>\\n  <td></td>\\n  <td><code>name</code></td>\\n  <td>String</td> \\n  <td>Context name.</td>\\n  <td>Optional.</td>\\n</tr>\\n<tr>\\n  <td></td>\\n  <td><code>parameters</code></td>\\n  <td>Object</td> \\n  <td>Object consisting of <code>\\\"parameter_name\\\":\\\"parameter_value\\\"</code> pairs.</td>\\n  <td>Optional.</td>\\n</tr>\\n<tr>\\n  <td></td>\\n  <td><code>lifespan</code></td>\\n  <td>Number</td> \\n  <td>Number of requests after which the context will expire.</td>\\n  <td>Optional.</td>\\n</tr>\\n<tr>\\n  <td colspan=\\\"2\\\"><code>resetContexts</code></td>\\n  <td>Boolean</td>\\n  <td>If true, all current contexts in a session will be reset before the new ones are set. False by default.</td> \\n  <td>Optional.</td>\\n</tr> \\n<tr>\\n  <td colspan=\\\"2\\\"><code>entities</code></td>\\n  <td>Array</td>\\n  <td>Array of entities that replace developer defined entities for this request only. The entity(ies) need to exist in the developer console. Entities JSON format follows the format used in the <a href=\\\"https://docs.api.ai/docs/entities\\\" target=\\\"_blank\\\">/entities</a> endpoint.</td> \\n  <td>Optional.</td>\\n</tr> \\n<tr>\\n  <td colspan=\\\"2\\\"><code>timezone</code></td>\\n  <td>String</td>\\n  <td>Time zone from <a href=\\\"http://www.iana.org/time-zones\\\" target=\\\"_blank\\\">IANA Time Zone Database</a><br>\\nExamples: <code>America/New_York</code>, <code>Europe/Paris</code></td> \\n  <td>Optional.</td>\\n</tr>\\n<tr>\\n  <td colspan=\\\"2\\\"><code>location</code></td>\\n  <td>Object</td>\\n  <td>Latitude and longitude values.<br>Example:\\n<code>{\\\"latitude\\\": 37.4256293, \\\"longitude\\\": -122.20539}</code></td> \\n  <td>Optional.</td>\\n</tr>\\n<tr>\\n  <td></td>\\n  <td><code>latitude</code></td>\\n  <td>Number</td> \\n  <td>Latitude value.</td>\\n  <td>Optional.</td>\\n</tr>\\n<tr>\\n  <td></td>\\n  <td><code>longitude</code></td>\\n  <td>Number</td> \\n  <td>Longitude value.</td>\\n  <td>Optional.</td>\\n</tr>\\n<tr>\\n  <td colspan=\\\"2\\\"><code>originalRequest</code></td>\\n  <td>Object</td>\\n  <td>Full request coming from the integrated platform (Facebook Messenger, Slack, etc.) <br> Example: <code>{“originalRequest”:{“source”:”facebook”,\\t“data”:{ … }}</code></td> \\n  <td>Optional.</td>\\n</tr>\\n<tr>\\n  <td></td>\\n  <td><code>source</code></td>\\n  <td>String</td> \\n  <td>Request source name. <br> Possible values: \\\"google\\\", \\\"facebook\\\", \\\"kik\\\", \\\"slack\\\", \\\"slack_testbot\\\", \\\"line\\\", \\\"skype\\\", \\\"spark\\\", \\\"telegram\\\", \\\"tropo\\\", \\\"twilio\\\", \\\"twilio-ip\\\", \\\"twitter\\\"</td>\\n  <td>Optional.</td>\\n</tr>\\n<tr>\\n  <td></td>\\n  <td><code>data</code></td>\\n  <td>Object</td> \\n  <td>Request data.</td>\\n  <td>Optional.</td>\\n</tr>\\n</table>\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"get\",\n  \"title\": \"GET /query\"\n}\n[/block]\nTakes natural language text and information as query parameters and returns information as JSON. \n\n### GET /query Sample Request\n\nThe following query processes the word \"weather\" for the Paris time zone with the contexts of weather and Europe.\n\n    GET https://api.api.ai/v1/query?v=20150910&query=weather&timezone=Europe/Paris&lang=en&contexts=weather&contexts=europe&latitude=37.459157&longitude=-122.17926&sessionId=1234567890\n\t\n\tHeaders:\n\tAuthorization: Bearer YOUR_ACCESS_TOKEN\n\t\n### GET /query cURL Sample Request\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H \\\"Authorization: Bearer YOUR_ACCESS_TOKEN\\\" \\\"https://api.api.ai/v1/query?v=20150910&query=weather&timezone=Europe/Paris&lang=en&contexts=weather&contexts=europe&latitude=37.459157&longitude=-122.17926&sessionId=1234567890\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nYou can use the 'COPY CURL' option to copy a sample query curl request identical to the one sent from the API.AI test console.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/89b3b8e-Copy-curl.png\",\n        \"Copy-curl.png\",\n        2806,\n        446,\n        \"#2b92c7\"\n      ],\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"post\",\n  \"title\": \"POST /query\"\n}\n[/block]\nTakes natural language text and information as JSON in the POST body and returns information as JSON.\n\n### POST /query Sample Request\n\nThe following query sets the context \"weather\" and processes the phrase \"and for tomorrow\" for the America/New_York time zone for the English language.\n\n    POST https://api.api.ai/v1/query?v=20150910\n\t\n\tHeaders:\n\tAuthorization: Bearer YOUR_ACCESS_TOKEN\n\tContent-Type: application/json; charset=utf-8\n\n\tPOST body:\n    {\n    \t\"query\": [\n    \t\t\"and for tomorrow\"\n    \t],\n    \t\"contexts\": [{\n    \t\t\"name\": \"weather\",\n    \t\t\"lifespan\": 4\n    \t}],\n    \t\"location\": {\n    \t\t\"latitude\": 37.459157,\n    \t\t\"longitude\": -122.17926\n    \t},\n    \t\"timezone\": \"America/New_York\",\n    \t\"lang\": \"en\",\n    \t\"sessionId\": \"1234567890\"\n    }\n\t\n#### POST /query cURL Sample Request\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H \\\"Content-Type: application/json; charset=utf-8\\\" -H \\\"Authorization: Bearer YOUR_ACCESS_TOKEN\\\" --data \\\"{'query':'and for tomorrow', 'timezone':'GMT-5', 'lang':'en', 'contexts':[{ 'name': 'weather', 'parameters':{'city': 'London'}, 'lifespan': 4}], 'sessionId':'1234567890'}\\\" \\\"https://api.api.ai/v1/query?v=20150910\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Response\"\n}\n[/block]\nThe response will be a JSON object with the following fields:\n[block:html]\n{\n  \"html\": \"<table>\\n<tr>\\n  <th colspan=\\\"3\\\" width=20%>Name</th>\\n  <th width=15%>Type</th> \\n  <th width=65%>Description</th>\\n</tr>\\n<tr>\\n  <td colspan=\\\"3\\\">id</td>\\n  <td>String</td> \\n  <td>Unique identifier of the result.</td>\\n</tr>\\n<tr>\\n  <td colspan=\\\"3\\\">timestamp</td>\\n  <td>String</td> \\n  <td>Date and time of the request in UTC timezone using ISO-8601 format.</td>\\n</tr>\\n<tr>\\n  <td colspan=\\\"3\\\">result</td>\\n  <td></td> \\n  <td>Contains the results of the natual language processing.</td>\\n</tr>\\n<tr>\\n  <td></td>\\n  <td colspan=\\\"2\\\">source</td>\\n  <td>String</td> \\n  <td>Source of the answer. Could be \\\"agent\\\" if the response was retrieved from the agent. Or \\\"domains\\\", if <a href=\\\"https://docs.api.ai/docs/domains\\\" target=\\\"_blank\\\">Domains functionality</a> is enabled and the source is one of the domains</td>\\n</tr>\\n<tr>\\n  <td></td>\\n  <td colspan=\\\"2\\\">resolvedQuery</td>\\n  <td>String</td> \\n  <td>The query that was used to produce this result.</td>\\n</tr>\\n<tr>\\n  <td></td>\\n  <td colspan=\\\"2\\\">action</td>\\n  <td>String</td> \\n  <td>An action to take.<br/>Example: <code>turn on</code></td>\\n</tr>\\n<tr>\\n  <td></td>\\n  <td colspan=\\\"2\\\">actionIncomplete</td>\\n  <td>Boolean</td> \\n  <td><code>true</code> if the triggered intent has required parameters and not all the required parameter values have been collected<br><code>false</code> if all required parameter values have been collected or if the triggered intent doesn't containt any required parameters</td>\\n</tr>\\n<tr>\\n  <td></td>\\n  <td colspan=\\\"2\\\">parameters</td>\\n  <td>Object</td> \\n  <td>Object consisting of \\\"parameter_name\\\":\\\"parameter_value\\\" pairs. <br/>Example: <code>{\\\"device\\\": \\\"computer\\\"}</code></td>\\n</tr>\\n<tr>\\n  <td></td>\\n  <td colspan=\\\"2\\\">contexts</td>\\n  <td>Array</td> \\n  <td>Array of context objects with the fields \\\"name\\\", \\\"parameters\\\", \\\"lifespan\\\".</td>\\n</tr>\\n<tr>\\n  <td></td>\\n  <td></td>\\n  <td>name</td>\\n  <td>String</td> \\n  <td>Context name.</td>\\n</tr>\\n<tr>\\n  <td></td>\\n  <td></td>\\n  <td>parameters</td>\\n  <td>Object</td> \\n  <td>Object consisting of \\\"parameter_name\\\":\\\"parameter_value\\\" and \\\"parameter_name.original\\\":\\\"original_parameter_value\\\" pairs.</td>\\n</tr>\\n<tr>\\n  <td></td>\\n  <td></td>\\n  <td>lifespan</td>\\n  <td>Number</td> \\n  <td>Number of requests after which the context will expire.</td>\\n</tr>\\n<tr>\\n  <td></td>\\n  <td colspan=\\\"2\\\">fulfillment</td>\\n  <td></td> \\n  <td>Data about text response(s), rich messages, response received from webhook.</td>\\n</tr>\\n<tr>\\n  <td></td>\\n  <td></td>\\n  <td>speech</td>\\n  <td>String</td> \\n  <td>Text to be pronounced to the user / shown on the screen</td>\\n</tr>\\n<tr>\\n  <td></td>\\n  <td></td>\\n  <td>messages</td>\\n  <td>Array</td> \\n  <td>Array of <a href=\\\"https://docs.api.ai/docs/query#section-message-objects\\\">message objects</a></td>\\n</tr>\\n<tr>\\n  <td></td>\\n  <td colspan=\\\"2\\\">score</td>\\n  <td>Number between 0 and 1</td> \\n  <td>Matching score for the intent.</td>\\n</tr>\\n<tr>\\n  <td></td>\\n  <td colspan=\\\"2\\\">metadata</td>\\n  <td></td> \\n  <td>Contains data on intents and contexts.</td>\\n</tr>\\n<tr>\\n  <td></td>\\n  <td></td>\\n  <td>intentId</td>\\n  <td>String</td> \\n  <td>ID of the intent that produced this result.</td>\\n</tr>\\n<tr>\\n  <td></td>\\n  <td></td>\\n  <td>webhookUsed</td>\\n  <td>String</td> \\n  <td>Indicates wheather webhook functionaly is enabled in the triggered intent.</td>\\n</tr>\\n<tr>\\n  <td></td>\\n  <td></td>\\n  <td>webhookForSlotFillingUsed</td>\\n  <td>String</td> \\n  <td>Indicates wheather in the triggered intent webhook functionaly is enabled for required parameters.</td>\\n</tr>\\n<tr>\\n  <td></td>\\n  <td></td>\\n  <td>intentName</td>\\n  <td>String</td> \\n  <td>Name of the intent that produced this result.</td>\\n</tr>\\n<tr>\\n  <td colspan=\\\"3\\\">status</td>\\n  <td><a href=\\\"https://docs.api.ai/docs/status-object\\\" target=\\\"_blank\\\">Status Object</a></td> \\n  <td>Contains data on how the request succeeded or failed.</td>\\n</tr>\\n<tr>\\n  <td colspan=\\\"3\\\">sessionId</td>\\n  <td>String</td> \\n  <td>Session ID.</td>\\n</tr>\\n</table>\"\n}\n[/block]\n## Message objects\n\n### Text response message object\n[block:html]\n{\n  \"html\": \"<table>\\n<tr>\\n  <th width=20%>Name</th>\\n  <th width=15%>Type</th> \\n  <th width=65%>Description</th>\\n</tr>\\n<tr>\\n  <td>type</td>\\n  <td>Number</td> \\n  <td>Equals to 0 for the <a href=\\\"https://docs.api.ai/docs/rich-messages#text-response\\\" target=\\\"_blank\\\">Text response</a> message type.</td>\\n</tr>\\n<tr>\\n  <td>speech</td>\\n  <td>String</td> \\n  <td>Agent's text reply. Line breaks are supported for Facebook Messenger, Kik, Slack, and Telegram one-click integrations.</td>\\n</tr>\\n</table>\"\n}\n[/block]\n### Image message object\n[block:html]\n{\n  \"html\": \"<table>\\n<tr>\\n  <th width=20%>Name</th>\\n  <th width=15%>Type</th> \\n  <th width=65%>Description</th>\\n</tr>\\n<tr>\\n  <td>type</td>\\n  <td>Number</td> \\n  <td>Equals to 3 for the <a href=\\\"https://docs.api.ai/docs/rich-messages#image\\\" target=\\\"_blank\\\">Image</a> message type.</td>\\n</tr>\\n<tr>\\n  <td>imageUrl</td>\\n  <td>String</td> \\n  <td>Public URL to the image file.</td>\\n</tr>\\n</table>\"\n}\n[/block]\n### Card message object\n[block:html]\n{\n  \"html\": \"<table>\\n<tr>\\n  <th colspan=\\\"2\\\" width=20%>Name</th>\\n  <th width=15%>Type</th> \\n  <th width=65%>Description</th>\\n</tr>\\n<tr>\\n  <td colspan=\\\"2\\\">type</td>\\n  <td>Number</td> \\n  <td>Equals to 1 for the <a href=\\\"https://docs.api.ai/docs/rich-messages#card\\\" target=\\\"_blank\\\">Card</a> message type.</td>\\n</tr>\\n<tr>\\n  <td colspan=\\\"2\\\">title</td>\\n  <td>String</td> \\n  <td>Card title.</td>\\n</tr>\\n<tr>\\n  <td colspan=\\\"2\\\">subtitle</td>\\n  <td>String</td> \\n  <td>Card subtitle.</td>\\n</tr>\\n<tr>\\n  <td colspan=\\\"2\\\">buttons</td>\\n  <td>Array</td> \\n  <td>Array of objects corresponding to card buttons.</td>\\n</tr>\\n<tr>\\n  <td></td>\\n  <td>text</td>\\n  <td>String</td> \\n  <td>Button text.</td>\\n</tr>\\n<tr>\\n  <td></td>\\n  <td>postback</td>\\n  <td>String</td> \\n  <td>A text sent back to API.AI or a URL to open.</td>\\n</tr>\\n</table>\"\n}\n[/block]\n### Quick replies message object\n[block:html]\n{\n  \"html\": \"<table>\\n<tr>\\n  <th width=20%>Name</th>\\n  <th width=15%>Type</th> \\n  <th width=65%>Description</th>\\n</tr>\\n<tr>\\n  <td>type</td>\\n  <td>Number</td> \\n  <td>Equals to 2 for the <a href=\\\"https://docs.api.ai/docs/rich-messages#quick-replies\\\" target=\\\"_blank\\\">Quick replies</a> message type.</td>\\n</tr>\\n<tr>\\n  <td>title</td>\\n  <td>String</td> \\n  <td>Quick replies title. Required for the Facebook Messenger, Kik, and Telegram one-click integrations.</td>\\n</tr>\\n<tr>\\n  <td>replies</td>\\n  <td>Array</td> \\n  <td>Array of strings corresponding to quick replies.</td>\\n</tr>\\n</table>\"\n}\n[/block]\n### Custom payload message object\n[block:html]\n{\n  \"html\": \"<table>\\n<tr>\\n  <th width=20%>Name</th>\\n  <th width=15%>Type</th> \\n  <th width=65%>Description</th>\\n</tr>\\n<tr>\\n  <td>type</td>\\n  <td>Number</td> \\n  <td>Equals to 4 for the <a href=\\\"https://docs.api.ai/docs/rich-messages#custom-payload\\\" target=\\\"_blank\\\">Custom payload</a> message type.</td>\\n</tr>\\n<tr>\\n  <td>payload</td>\\n  <td>Object</td> \\n  <td>Developer defined JSON. It is sent without modifications.</td>\\n</tr>\\n</table>\"\n}\n[/block]\n### Sample Response\n\n```\n{\n  \"id\": \"170a3fc2-1596-4e0e-adf6-55a68b41991e\",\n  \"timestamp\": \"2016-11-03T14:42:13.473Z\",\n  \"result\": {\n    \"source\": \"agent\",\n    \"resolvedQuery\": \"my name is Sam and I live in Paris\",\n    \"action\": \"greetings\",\n    \"actionIncomplete\": false,\n    \"parameters\": {\n      \"city\": \"Paris\",\n      \"name\": \"Sam\"\n    },\n    \"contexts\": [\n      {\n        \"name\": \"greetings\",\n        \"parameters\": {\n          \"name.original\": \"Sam\",\n          \"city\": \"Paris\",\n          \"name\": \"Sam\",\n          \"city.original\": \"Paris\"\n        },\n        \"lifespan\": 5\n      }\n    ],\n    \"metadata\": {\n      \"intentId\": \"51ee06e9-9ff5-428b-aafd-733bbd7e9978\",\n      \"webhookUsed\": \"false\",\n      \"intentName\": \"greetings\"\n    },\n    \"fulfillment\": {\n      \"speech\": \"Hi Sam! Nice to meet you!\",\n      \"messages\": [\n        {\n          \"type\": 0,\n          \"speech\": \"Hi Sam! Nice to meet you!\"\n        }\n      ]\n    },\n    \"score\": 1\n  },\n  \"status\": {\n    \"code\": 200,\n    \"errorType\": \"success\"\n  },\n  \"sessionId\": \"0723d23f-88e0-49f8-adb3-2034a1612f81\"\n}\n```","excerpt":"","slug":"query","type":"basic","title":"/query"}
* [Overview](#overview) * [URLs](#urls) * [Query Parameters and JSON Fields](#query-parameters-and-json-fields) * [GET /query](#get-query) * [POST /query](#post-query) * [Response](#response) [block:api-header] { "type": "basic", "title": "Overview" } [/block] The **query** endpoint is used to process natural language in the form of text. The query requests return structured data in JSON format with an action and parameters for that action. [block:api-header] { "type": "basic", "title": "URLs" } [/block] The following URLs are available: [block:parameters] { "data": { "h-0": "Method", "h-1": "Definition", "0-0": "[GET /query](query#get-query)", "1-0": "[POST /query](query#post-query)", "0-1": "Takes natural language text and information as query parameters and returns information as JSON.", "1-1": "Takes natural language text and information as JSON in the POST body and returns information as JSON." }, "cols": 2, "rows": 2 } [/block] [block:api-header] { "type": "basic", "title": "Query Parameters and JSON Fields" } [/block] The following parameters are used as either query parameters in the URL or JSON keys in the POST body: [block:html] { "html": "<table>\n<tr>\n <th colspan=\"2\" width=15%>Name</th>\n <th>Type</th> \n <th>Description</th>\n <th>Required</th>\n</tr>\n<tr>\n <td colspan=\"2\"><code>query</code></td>\n <td>String or array of strings</td> \n <td>Natural language text to be processed.<br>\nQuery length should not exceed 256 characters.</td>\n <td>Required unless an <code>\"event\"</code>/<code>\"e\"</code> parameter is submitted.</td>\n</tr>\n<tr>\n <td colspan=\"2\"><code>event</code> (for POST requests)<br>or<br><code>e</code> (for GET requests)</td>\n <td>Object</td>\n <td>Object containing event name and additional data. The <code>\"data\"</code> parameter can be submitted only in POST requests.</td> \n <td>Required unless a <code>\"query\"</code> parameter is submitted.</td>\n</tr>\n<tr>\n <td></td>\n <td><code>name</code></td>\n <td>String</td> \n <td><a href=\"https://docs.api.ai/docs/concept-events\" target=\"_blank\">Event</a> name.</td>\n <td>Required.</td>\n</tr>\n<tr>\n <td></td>\n <td><code>data</code></td>\n <td>Object</td> \n <td>Object consisting of <code>\"parameter_name\":\"parameter_value\"</code> pairs.</td>\n <td>Optional.</td>\n</tr>\n<tr>\n <td colspan=\"2\"><code>v</code></td>\n <td>String</td> \n <td>Version of the protocol, e.g. <code>v=20150910</code><br><br>\n<i class=\"fa fa-exclamation-triangle\" aria-hidden=\"true\"></i> Do not pass the current date to the <code>v</code> parameter. See <a href=\"https://docs.api.ai/docs/versioning\" target=\"_blank\">Versioning</a> for more details.</td>\n <td>Required. Must be used as a URL parameter.</td> \n</tr>\n<tr>\n <td colspan=\"2\"><code>sessionId</code></td>\n <td>String</td>\n <td>A string token up to 36 symbols long, used to identify the client and to manage session parameters (including contexts) per client.</td> \n <td>Required.</td>\n</tr>\n<tr>\n <td colspan=\"2\"><code>lang</code></td>\n <td>String</td>\n <td>Language tag, e.g., <code>en</code>, <code>es</code> etc.<br>\nSee <a href=\"https://docs.api.ai/docs/languages\" target=\"_blank\">Languages</a> for details.</td> \n <td>Required.</td>\n</tr>\n<tr>\n <td colspan=\"2\"><code>contexts</code></td>\n <td>Array</td>\n <td>Array of additional context objects. Should be sent via a POST /query request. Contexts sent in a query are activated before the query.<br>\nSee <a href=\"https://docs.api.ai/docs/concept-contexts\" target=\"_blank\">Contexts</a>.</td> \n <td>Optional.</td>\n</tr>\n<tr>\n <td></td>\n <td><code>name</code></td>\n <td>String</td> \n <td>Context name.</td>\n <td>Optional.</td>\n</tr>\n<tr>\n <td></td>\n <td><code>parameters</code></td>\n <td>Object</td> \n <td>Object consisting of <code>\"parameter_name\":\"parameter_value\"</code> pairs.</td>\n <td>Optional.</td>\n</tr>\n<tr>\n <td></td>\n <td><code>lifespan</code></td>\n <td>Number</td> \n <td>Number of requests after which the context will expire.</td>\n <td>Optional.</td>\n</tr>\n<tr>\n <td colspan=\"2\"><code>resetContexts</code></td>\n <td>Boolean</td>\n <td>If true, all current contexts in a session will be reset before the new ones are set. False by default.</td> \n <td>Optional.</td>\n</tr> \n<tr>\n <td colspan=\"2\"><code>entities</code></td>\n <td>Array</td>\n <td>Array of entities that replace developer defined entities for this request only. The entity(ies) need to exist in the developer console. Entities JSON format follows the format used in the <a href=\"https://docs.api.ai/docs/entities\" target=\"_blank\">/entities</a> endpoint.</td> \n <td>Optional.</td>\n</tr> \n<tr>\n <td colspan=\"2\"><code>timezone</code></td>\n <td>String</td>\n <td>Time zone from <a href=\"http://www.iana.org/time-zones\" target=\"_blank\">IANA Time Zone Database</a><br>\nExamples: <code>America/New_York</code>, <code>Europe/Paris</code></td> \n <td>Optional.</td>\n</tr>\n<tr>\n <td colspan=\"2\"><code>location</code></td>\n <td>Object</td>\n <td>Latitude and longitude values.<br>Example:\n<code>{\"latitude\": 37.4256293, \"longitude\": -122.20539}</code></td> \n <td>Optional.</td>\n</tr>\n<tr>\n <td></td>\n <td><code>latitude</code></td>\n <td>Number</td> \n <td>Latitude value.</td>\n <td>Optional.</td>\n</tr>\n<tr>\n <td></td>\n <td><code>longitude</code></td>\n <td>Number</td> \n <td>Longitude value.</td>\n <td>Optional.</td>\n</tr>\n<tr>\n <td colspan=\"2\"><code>originalRequest</code></td>\n <td>Object</td>\n <td>Full request coming from the integrated platform (Facebook Messenger, Slack, etc.) <br> Example: <code>{“originalRequest”:{“source”:”facebook”,\t“data”:{ … }}</code></td> \n <td>Optional.</td>\n</tr>\n<tr>\n <td></td>\n <td><code>source</code></td>\n <td>String</td> \n <td>Request source name. <br> Possible values: \"google\", \"facebook\", \"kik\", \"slack\", \"slack_testbot\", \"line\", \"skype\", \"spark\", \"telegram\", \"tropo\", \"twilio\", \"twilio-ip\", \"twitter\"</td>\n <td>Optional.</td>\n</tr>\n<tr>\n <td></td>\n <td><code>data</code></td>\n <td>Object</td> \n <td>Request data.</td>\n <td>Optional.</td>\n</tr>\n</table>" } [/block] [block:api-header] { "type": "get", "title": "GET /query" } [/block] Takes natural language text and information as query parameters and returns information as JSON. ### GET /query Sample Request The following query processes the word "weather" for the Paris time zone with the contexts of weather and Europe. GET https://api.api.ai/v1/query?v=20150910&query=weather&timezone=Europe/Paris&lang=en&contexts=weather&contexts=europe&latitude=37.459157&longitude=-122.17926&sessionId=1234567890 Headers: Authorization: Bearer YOUR_ACCESS_TOKEN ### GET /query cURL Sample Request [block:code] { "codes": [ { "code": "curl -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\" \"https://api.api.ai/v1/query?v=20150910&query=weather&timezone=Europe/Paris&lang=en&contexts=weather&contexts=europe&latitude=37.459157&longitude=-122.17926&sessionId=1234567890\"", "language": "curl" } ] } [/block] You can use the 'COPY CURL' option to copy a sample query curl request identical to the one sent from the API.AI test console. [block:image] { "images": [ { "image": [ "https://files.readme.io/89b3b8e-Copy-curl.png", "Copy-curl.png", 2806, 446, "#2b92c7" ], "sizing": "full" } ] } [/block] [block:api-header] { "type": "post", "title": "POST /query" } [/block] Takes natural language text and information as JSON in the POST body and returns information as JSON. ### POST /query Sample Request The following query sets the context "weather" and processes the phrase "and for tomorrow" for the America/New_York time zone for the English language. POST https://api.api.ai/v1/query?v=20150910 Headers: Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json; charset=utf-8 POST body: { "query": [ "and for tomorrow" ], "contexts": [{ "name": "weather", "lifespan": 4 }], "location": { "latitude": 37.459157, "longitude": -122.17926 }, "timezone": "America/New_York", "lang": "en", "sessionId": "1234567890" } #### POST /query cURL Sample Request [block:code] { "codes": [ { "code": "curl -H \"Content-Type: application/json; charset=utf-8\" -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\" --data \"{'query':'and for tomorrow', 'timezone':'GMT-5', 'lang':'en', 'contexts':[{ 'name': 'weather', 'parameters':{'city': 'London'}, 'lifespan': 4}], 'sessionId':'1234567890'}\" \"https://api.api.ai/v1/query?v=20150910\"", "language": "curl" } ] } [/block] [block:api-header] { "type": "basic", "title": "Response" } [/block] The response will be a JSON object with the following fields: [block:html] { "html": "<table>\n<tr>\n <th colspan=\"3\" width=20%>Name</th>\n <th width=15%>Type</th> \n <th width=65%>Description</th>\n</tr>\n<tr>\n <td colspan=\"3\">id</td>\n <td>String</td> \n <td>Unique identifier of the result.</td>\n</tr>\n<tr>\n <td colspan=\"3\">timestamp</td>\n <td>String</td> \n <td>Date and time of the request in UTC timezone using ISO-8601 format.</td>\n</tr>\n<tr>\n <td colspan=\"3\">result</td>\n <td></td> \n <td>Contains the results of the natual language processing.</td>\n</tr>\n<tr>\n <td></td>\n <td colspan=\"2\">source</td>\n <td>String</td> \n <td>Source of the answer. Could be \"agent\" if the response was retrieved from the agent. Or \"domains\", if <a href=\"https://docs.api.ai/docs/domains\" target=\"_blank\">Domains functionality</a> is enabled and the source is one of the domains</td>\n</tr>\n<tr>\n <td></td>\n <td colspan=\"2\">resolvedQuery</td>\n <td>String</td> \n <td>The query that was used to produce this result.</td>\n</tr>\n<tr>\n <td></td>\n <td colspan=\"2\">action</td>\n <td>String</td> \n <td>An action to take.<br/>Example: <code>turn on</code></td>\n</tr>\n<tr>\n <td></td>\n <td colspan=\"2\">actionIncomplete</td>\n <td>Boolean</td> \n <td><code>true</code> if the triggered intent has required parameters and not all the required parameter values have been collected<br><code>false</code> if all required parameter values have been collected or if the triggered intent doesn't containt any required parameters</td>\n</tr>\n<tr>\n <td></td>\n <td colspan=\"2\">parameters</td>\n <td>Object</td> \n <td>Object consisting of \"parameter_name\":\"parameter_value\" pairs. <br/>Example: <code>{\"device\": \"computer\"}</code></td>\n</tr>\n<tr>\n <td></td>\n <td colspan=\"2\">contexts</td>\n <td>Array</td> \n <td>Array of context objects with the fields \"name\", \"parameters\", \"lifespan\".</td>\n</tr>\n<tr>\n <td></td>\n <td></td>\n <td>name</td>\n <td>String</td> \n <td>Context name.</td>\n</tr>\n<tr>\n <td></td>\n <td></td>\n <td>parameters</td>\n <td>Object</td> \n <td>Object consisting of \"parameter_name\":\"parameter_value\" and \"parameter_name.original\":\"original_parameter_value\" pairs.</td>\n</tr>\n<tr>\n <td></td>\n <td></td>\n <td>lifespan</td>\n <td>Number</td> \n <td>Number of requests after which the context will expire.</td>\n</tr>\n<tr>\n <td></td>\n <td colspan=\"2\">fulfillment</td>\n <td></td> \n <td>Data about text response(s), rich messages, response received from webhook.</td>\n</tr>\n<tr>\n <td></td>\n <td></td>\n <td>speech</td>\n <td>String</td> \n <td>Text to be pronounced to the user / shown on the screen</td>\n</tr>\n<tr>\n <td></td>\n <td></td>\n <td>messages</td>\n <td>Array</td> \n <td>Array of <a href=\"https://docs.api.ai/docs/query#section-message-objects\">message objects</a></td>\n</tr>\n<tr>\n <td></td>\n <td colspan=\"2\">score</td>\n <td>Number between 0 and 1</td> \n <td>Matching score for the intent.</td>\n</tr>\n<tr>\n <td></td>\n <td colspan=\"2\">metadata</td>\n <td></td> \n <td>Contains data on intents and contexts.</td>\n</tr>\n<tr>\n <td></td>\n <td></td>\n <td>intentId</td>\n <td>String</td> \n <td>ID of the intent that produced this result.</td>\n</tr>\n<tr>\n <td></td>\n <td></td>\n <td>webhookUsed</td>\n <td>String</td> \n <td>Indicates wheather webhook functionaly is enabled in the triggered intent.</td>\n</tr>\n<tr>\n <td></td>\n <td></td>\n <td>webhookForSlotFillingUsed</td>\n <td>String</td> \n <td>Indicates wheather in the triggered intent webhook functionaly is enabled for required parameters.</td>\n</tr>\n<tr>\n <td></td>\n <td></td>\n <td>intentName</td>\n <td>String</td> \n <td>Name of the intent that produced this result.</td>\n</tr>\n<tr>\n <td colspan=\"3\">status</td>\n <td><a href=\"https://docs.api.ai/docs/status-object\" target=\"_blank\">Status Object</a></td> \n <td>Contains data on how the request succeeded or failed.</td>\n</tr>\n<tr>\n <td colspan=\"3\">sessionId</td>\n <td>String</td> \n <td>Session ID.</td>\n</tr>\n</table>" } [/block] ## Message objects ### Text response message object [block:html] { "html": "<table>\n<tr>\n <th width=20%>Name</th>\n <th width=15%>Type</th> \n <th width=65%>Description</th>\n</tr>\n<tr>\n <td>type</td>\n <td>Number</td> \n <td>Equals to 0 for the <a href=\"https://docs.api.ai/docs/rich-messages#text-response\" target=\"_blank\">Text response</a> message type.</td>\n</tr>\n<tr>\n <td>speech</td>\n <td>String</td> \n <td>Agent's text reply. Line breaks are supported for Facebook Messenger, Kik, Slack, and Telegram one-click integrations.</td>\n</tr>\n</table>" } [/block] ### Image message object [block:html] { "html": "<table>\n<tr>\n <th width=20%>Name</th>\n <th width=15%>Type</th> \n <th width=65%>Description</th>\n</tr>\n<tr>\n <td>type</td>\n <td>Number</td> \n <td>Equals to 3 for the <a href=\"https://docs.api.ai/docs/rich-messages#image\" target=\"_blank\">Image</a> message type.</td>\n</tr>\n<tr>\n <td>imageUrl</td>\n <td>String</td> \n <td>Public URL to the image file.</td>\n</tr>\n</table>" } [/block] ### Card message object [block:html] { "html": "<table>\n<tr>\n <th colspan=\"2\" width=20%>Name</th>\n <th width=15%>Type</th> \n <th width=65%>Description</th>\n</tr>\n<tr>\n <td colspan=\"2\">type</td>\n <td>Number</td> \n <td>Equals to 1 for the <a href=\"https://docs.api.ai/docs/rich-messages#card\" target=\"_blank\">Card</a> message type.</td>\n</tr>\n<tr>\n <td colspan=\"2\">title</td>\n <td>String</td> \n <td>Card title.</td>\n</tr>\n<tr>\n <td colspan=\"2\">subtitle</td>\n <td>String</td> \n <td>Card subtitle.</td>\n</tr>\n<tr>\n <td colspan=\"2\">buttons</td>\n <td>Array</td> \n <td>Array of objects corresponding to card buttons.</td>\n</tr>\n<tr>\n <td></td>\n <td>text</td>\n <td>String</td> \n <td>Button text.</td>\n</tr>\n<tr>\n <td></td>\n <td>postback</td>\n <td>String</td> \n <td>A text sent back to API.AI or a URL to open.</td>\n</tr>\n</table>" } [/block] ### Quick replies message object [block:html] { "html": "<table>\n<tr>\n <th width=20%>Name</th>\n <th width=15%>Type</th> \n <th width=65%>Description</th>\n</tr>\n<tr>\n <td>type</td>\n <td>Number</td> \n <td>Equals to 2 for the <a href=\"https://docs.api.ai/docs/rich-messages#quick-replies\" target=\"_blank\">Quick replies</a> message type.</td>\n</tr>\n<tr>\n <td>title</td>\n <td>String</td> \n <td>Quick replies title. Required for the Facebook Messenger, Kik, and Telegram one-click integrations.</td>\n</tr>\n<tr>\n <td>replies</td>\n <td>Array</td> \n <td>Array of strings corresponding to quick replies.</td>\n</tr>\n</table>" } [/block] ### Custom payload message object [block:html] { "html": "<table>\n<tr>\n <th width=20%>Name</th>\n <th width=15%>Type</th> \n <th width=65%>Description</th>\n</tr>\n<tr>\n <td>type</td>\n <td>Number</td> \n <td>Equals to 4 for the <a href=\"https://docs.api.ai/docs/rich-messages#custom-payload\" target=\"_blank\">Custom payload</a> message type.</td>\n</tr>\n<tr>\n <td>payload</td>\n <td>Object</td> \n <td>Developer defined JSON. It is sent without modifications.</td>\n</tr>\n</table>" } [/block] ### Sample Response ``` { "id": "170a3fc2-1596-4e0e-adf6-55a68b41991e", "timestamp": "2016-11-03T14:42:13.473Z", "result": { "source": "agent", "resolvedQuery": "my name is Sam and I live in Paris", "action": "greetings", "actionIncomplete": false, "parameters": { "city": "Paris", "name": "Sam" }, "contexts": [ { "name": "greetings", "parameters": { "name.original": "Sam", "city": "Paris", "name": "Sam", "city.original": "Paris" }, "lifespan": 5 } ], "metadata": { "intentId": "51ee06e9-9ff5-428b-aafd-733bbd7e9978", "webhookUsed": "false", "intentName": "greetings" }, "fulfillment": { "speech": "Hi Sam! Nice to meet you!", "messages": [ { "type": 0, "speech": "Hi Sam! Nice to meet you!" } ] }, "score": 1 }, "status": { "code": 200, "errorType": "success" }, "sessionId": "0723d23f-88e0-49f8-adb3-2034a1612f81" } ```