/query

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.

BaseURL

https://api.dialogflow.com/v1/

/query parameters and JSON fields

The following parameters are used as either query parameters in the URL or JSON keys in the POST body.

Name	Type	Description	Required
`contexts`	Array	Array of additional context objects. Should be sent via a POST /query request. Contexts sent in a query are activated before the query. See Contexts.	Optional.
`- lifespan`	Number	Number of requests after which the context will expire.	Optional.
`- name`	String	Context name.	Optional.
`- parameters`	Object	Object consisting of `"parameter_name":"parameter_value"` pairs.	Optional.
`entities`	Array	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 /entities endpoint.	Optional.
`event` (for POST) `e` (for GET)	Object	Object containing event name and additional data. The `"data"` parameter can be submitted only in POST requests.	Required unless a `"query"` parameter is submitted.
`- data`	Object	Object consisting of `"parameter_name":"parameter_value"` pairs.	Optional.
`- name`	String	Event name.	Required.
`lang`	String	Language tag, e.g., `en`, `es` etc. See Languages for details.	Required.
`location`	Object	Latitude and longitude values. Example:`{"latitude":37.4256293, "longitude": -122.20539}`	Optional.
`- latitude`	Number	Latitude value.	Optional.
`- longitude`	Number	Longitude value.	Optional.
`originalRequest`	Object	Full request coming from the integrated platform. (Facebook Messenger, Slack, etc.) Example: {“originalRequest”:{ “source”:”facebook”, “data”:{ … }}	Optional.
`- data`	Object	Request data.	Optional.
`- source`	String	Request source name. Possible values: `google`, `facebook`, `kik`, `slack`, `line`, `skype`, `spark`, `telegram`, `tropo`, `twilio`, `twilio-ip`, `twitter`	Optional.
`query`	String	Natural language text to be processed. Query length should not exceed 256 characters.	Required unless an `"event"`/`"e"` parameter is submitted.
`resetContexts`	Boolean	If true, all current contexts in a session will be reset before the new ones are set. False by default.	Optional.
`sessionId`	String	A string token up to 36 symbols long, used to identify the client and to manage session parameters (including contexts) per client.	Required.
`timezone`	String	Time zone from IANA Time Zone Database Examples: `America/New_York`, `Europe/Paris`	Optional.
`v`	String	Version of the protocol, e.g. `v=20150910` Warning: Do not pass the current date to the `v` parameter. See Protocol Version for more details. This parameter must be passed in the URL as a query parameter and cannot be passed in the JSON.	Required. Must be used as a URL parameter.

GET /query

Takes parameters or event name provided in URL and returns response as JSON.

GET /query sample

HTTP

GET https://api.dialogflow.com/v1/query?v=20150910&contexts=shop&lang=en&query=apple&sessionId=12345&timezone=America/New_York

Headers:
Authorization: Bearer YOUR_CLIENT_ACCESS_TOKEN

cURL

curl \
-H "Authorization: Bearer YOUR_CLIENT_ACCESS_TOKEN" \
"https://api.dialogflow.com/v1/query?v=20150910&contexts=shop&lang=en&query=apple&sessionId=12345&timezone=America/New_York"

POST /query

Takes parameters or event name in JSON format and returns response as JSON.

POST /query sample

HTTP

  POST https://api.dialogflow.com/v1/query?v=20150910

  Headers:
  Authorization: Bearer YOUR_CLIENT_ACCESS_TOKEN
  Content-Type: application/json

  POST body:
  {
    "contexts": [
      "shop"
    ],
    "lang": "en",
    "query": "I need apples",
    "sessionId": "12345",
    "timezone": "America/New_York"
  }

cURL

curl \
https://api.dialogflow.com/v1/query?v=20150910 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_CLIENT_ACCESS_TOKEN' \
-d '{
  "contexts": [
    "shop"
  ],
  "lang": "en",
  "query": "I need apples",
  "sessionId": "12345",
  "timezone": "America/New_York"
}'

GET and POST responses

Both GET and POST methods return the same JSON response.

Parameters

Name	Type	Description
`id`	String	Unique identifier of the result.
`lang`	String	Agent's language.
`result`	Object	Contains the results of the natual language processing.
`- action`	String	An action to take.
`- actionIncomplete`	Boolean	`true` if the triggered intent has required parameters and not all the required parameter values have been collected `false` if all required parameter values have been collected or if the triggered intent doesn't containt any required parameters
`- contexts`	Array	Array of context objects.
`-- lifespan`	Number	Number of requests after which the context will expire.
`-- name`	String	Context name.
`-- parameters`	Object	Object consisting of "parameter_name":"parameter_value" and "parameter_name.original":"original_parameter_value" pairs.
`- fulfillment`	Object	Data about text response(s), rich messages, response received from webhook.
`-- messages`	Array	Array of message objects
`-- source`	String	The source of the fulfillment.
`-- speech`	String	Text to be pronounced to the user / shown on the screen
`- metadata`	Object	Contains data on intents and contexts.
`-- intentId`	String	ID of the intent that produced this result.
`-- intentName`	String	Name of the intent that produced this result.
`-- webhookForSlotFillingUsed`	String	Indicates whether in the triggered intent webhook functionality is enabled for required parameters.
`-- webhookResponseTime`	Number	Webhook response time in milliseconds.
`-- webhookUsed`	String	Indicates whether webhook functionality is enabled in the triggered intent.
`- parameters`	Object	Object consisting of "parameter_name":"parameter_value" pairs.
`- resolvedQuery`	String	The query that was used to produce this result.
`- score`	Number between 0 and 1	Matching score for the intent.
`- source`	String	Source of the answer.
`sessionId`	String	Session ID.
`status`	Status Object	Contains data on how the request succeeded or failed.
`- code`	Number	The status/error code.
`- errorDetails`	String	Only shown in the event of an error - Details on the error.
`- errorType`	String	The type of error associated with the status/error code.
`timestamp`	String	Date and time of the request in UTC timezone using ISO-8601 format.

Sample

{
  "id": "3622be70-cb49-4796-a4fa-71f16f7b5600",
  "lang": "en",
  "result": {
    "action": "pickFruit",
    "actionIncomplete": false,
    "contexts": [
      "shop"
    ],
    "fulfillment": {
      "messages": [
        {
          "platform": "google",
          "textToSpeech": "Okay how many apples?",
          "type": "simple_response"
        },
        {
          "platform": "google",
          "textToSpeech": "Okay. How many apples?",
          "type": "simple_response"
        },
        {
          "speech": "Okay how many apples?",
          "type": 0
        }
      ],
      "source": "dialogflow.test.com",
      "speech": "Okay how many apples?"
    },
    "metadata": {
      "intentId": "21478be9-bea6-449b-bcca-c5f009c0a5a1",
      "intentName": "add-to-list",
      "webhookForSlotFillingUsed": "false",
      "webhookUsed": "false"
    },
    "parameters": {
      "fruit": [
        "apples"
      ]
    },
    "resolvedQuery": "I need apples",
    "score": 1,
    "source": "agent"
  },
  "sessionId": "12345",
  "status": {
    "code": 200,
    "errorType": "success"
  },
  "timestamp": "2017-09-19T21:16:44.832Z"
}